Module cli_tool 

Put an app’s bundled command-line tool on the user’s PATH, the way editors offer an “Install command” menu item.

The tool ships inside the app (on macOS <App>.app/Contents/Helpers/<name>). Installing makes a symbolic link <bin dir>/<name> → that file, so updating the app updates the tool:

1. The link goes in /usr/local/bin (created when missing).
2. When that folder isn’t writable, the OS asks for an administrator password (macOS: the standard do shell script … with administrator privileges prompt).
3. When that is declined (or no prompt is available), the link goes in ~/.local/bin and the result carries the line to add to the shell profile.

A file or link that isn’t this app’s tool is never replaced unless the caller passes replace (and the result names what was replaced). A link left behind after the app moved (it points at a missing …/Contents/Helpers/<name>) is repaired without asking. A folder is never replaced.

ENV_BIN_DIR and ENV_FALLBACK_DIR point both folders elsewhere for tests; while either is set the administrator prompt is never shown.

commands are the matching command specs (app.installCommandLineTool, app.uninstallCommandLineTool, app.commandLineToolStatus) for any host that implements CliToolHost; run runs the same three for apps with their own command router.

Structs

CliTool

One app’s bundled command-line tool and where to install it.

Installed

What CliTool::install did.

Removed

What CliTool::uninstall did.

Status

Where the tool is installed, if anywhere.

Enums

CliToolError

Why installing or removing the tool did not happen.

Elevated

The answer to an administrator prompt.

Elevation

How to get administrator rights when the system folder isn’t writable.

LinkState

What one location holds.

Constants

ENV_BIN_DIR

Install into this folder instead of SYSTEM_BIN_DIR (tests); disables the admin prompt.

ENV_FALLBACK_DIR

Fall back to this folder instead of ~/.local/bin (tests); disables the admin prompt.

INSTALL

Command ids registered by commands.

STATUS

SYSTEM_BIN_DIR

Where the link goes by default: on every macOS PATH (/etc/paths).

UNINSTALL

Traits

CliToolHost

A command host that can hand out its app’s CliTool (None in a development build with no bundled tool: the commands are then disabled with a reason).

Functions

bundled_helper

The bundled tool’s path for the running app: <exe dir>/../Helpers/<name>, which on macOS is <App>.app/Contents/Helpers/<name>.

check_name

A tool name: lowercase ASCII letters, digits, -, _, .; not starting with - or ..

commands

app.installCommandLineTool and app.uninstallCommandLineTool in menu (macOS: the app menu, &["<App name>"]), and the menu-less query app.commandLineToolStatus. Each returns the outcome as JSON with a message for a toast.

run

Run INSTALL (param replace), UNINSTALL or STATUS on tool, for apps that route commands themselves instead of through a ashlar_command::Registry. The result is the outcome as JSON with a message for a toast; None when id is none of the three.

sh_quote

p as one single-quoted /bin/sh word. Refuses non-UTF-8 and control characters.

Type Aliases

Elevator

Runs a /bin/sh script with administrator rights. The script is built by this module from fixed commands and single-quoted paths.