@hardfin/cli 0.1.0-dev.22 → 0.1.0-dev.24

package/README.md

@@ -224,13 +224,37 @@ environment, so `hardfin login` works out of the box.
 ## Completing commands in your shell
 
 ```sh
-source <(hardfin completion zsh)     # this shell, now
-hardfin completion zsh >> ~/.zshrc   # every shell after this one
+hardfin completion install   # every shell after this one
 ```
 
-`bash`, `zsh`, `fish` and `powershell` each get a script. The script asks the CLI what may
-follow what you have typed, so completions never fall behind the commands, including the ones
-generated from the API document.
+`install` finds your shell from `$SHELL`, shows what it will change, and asks before changing
+it. Name the shell to install for another one, and pass `--yes` to skip the question.
+
+| Shell      | The script is written to                  | And loaded from                            |
+| ---------- | ----------------------------------------- | ------------------------------------------ |
+| bash       | `~/.local/share/hardfin/completion.bash`  | `~/.bashrc`, or `~/.bash_profile` on macOS |
+| zsh        | `~/.local/share/hardfin/completion.zsh`   | `~/.zshrc`                                 |
+| fish       | `~/.config/fish/completions/hardfin.fish` | fish, by itself                            |
+| PowerShell | `~/.local/share/hardfin/completion.ps1`   | the profile PowerShell reports             |
+
+The lines added to a startup file sit between `# >>> hardfin completion >>>` and
+`# <<< hardfin completion <<<`. Installing again replaces them, and
+`hardfin completion uninstall` removes them with the script. Install again after upgrading, so
+the script matches the CLI.
+
+To complete in the current shell without installing anything:
+
+```sh
+source <(hardfin completion zsh)
+```
+
+The script asks the CLI what may follow what you have typed, so completions never fall behind
+the commands, including the ones generated from the API document. It offers commands, flags,
+the values a flag accepts, and file paths where a flag takes one. zsh, fish and PowerShell
+show a description beside each.
+
+The script calls `hardfin` by name, so it needs `hardfin` on your `PATH`. Running
+`node dist/cli.js` from a checkout leaves nothing for it to call, and `npm link` fixes that.
 
 ## Serving an agent
 

package/dist/cli.js

@@ -2,13 +2,14 @@
 import { createRequire } from "node:module";
 import { Command, Option } from "commander";
 import { z } from "zod";
-import { chmodSync, closeSync, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 import { createServer } from "node:http";
-import { createInterface } from "node:readline";
+import { createInterface as createInterface$1 } from "node:readline";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
 const ExitCode = {
@@ -21,6 +22,18 @@ const ExitCode = {
 function defineCommand(command) {
 	return command;
 }
+/** GLOBAL_FLAGS are the options the CLI takes before any command. */
+const GLOBAL_FLAGS = [{
+	name: "api-url",
+	description: "The API to call, whose host also holds the authorization server",
+	valueName: "url",
+	schema: z.string()
+}, {
+	name: "issuer-url",
+	description: "The authorization server, when it does not sit at the API's host",
+	valueName: "url",
+	schema: z.string()
+}];
 //#endregion
 //#region src/config/settings.ts
 /** The API version this build was written against, sent on every request. */
@@ -956,104 +969,54 @@ function toBody$1(source) {
 	}
 }
 //#endregion
-//#region src/command/completion.ts
+//#region src/auth/browser.ts
+/** isWSL reports whether this Linux is running under Windows. */
+function isWSL() {
+	return existsSync("/proc/sys/fs/binfmt_misc/WSLInterop");
+}
+/**
+* toOpeners lists the ways to open a URL here, best first. WSL needs Windows to do it,
+* because the browser the person is looking at is the Windows one, and xdg-open reaches
+* nothing outside the distribution.
+*/
+function toOpeners(url) {
+	if (process.platform === "darwin") return [["open", [url]]];
+	if (process.platform === "win32") return [["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]]];
+	if (isWSL()) return [
+		["wslview", [url]],
+		["powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"Start-Process",
+			`'${url}'`
+		]],
+		["explorer.exe", [url]]
+	];
+	return [["xdg-open", [url]]];
+}
+/** openBrowser asks the desktop to show a URL, and reports whether anything took it. */
+function openBrowser(url, launch = spawnSync) {
+	for (const [command, args] of toOpeners(url)) if (launch(command, args, {
+		stdio: "ignore",
+		cwd: command.endsWith(".exe") ? "/mnt/c" : void 0,
+		timeout: 1e4
+	}).error === void 0) return true;
+	return false;
+}
+//#endregion
+//#region src/command/completion-scripts.ts
 const SHELLS = [
 	"bash",
 	"zsh",
 	"fish",
 	"powershell"
 ];
-const completionCommand = defineCommand({
-	name: "completion",
-	summary: "Print the shell script that completes hardfin commands",
-	description: "Writes a script for your shell. The script asks this CLI what may follow what you have typed, so completions never fall behind the commands.",
-	arguments: [{
-		name: "shell",
-		description: `The shell to write for: ${SHELLS.join(", ")}`,
-		required: true
-	}],
-	flags: [],
-	examples: [
-		{
-			description: "Complete in this shell, now",
-			command: "source <(hardfin completion zsh)"
-		},
-		{
-			description: "Complete in every new shell",
-			command: "hardfin completion zsh > ~/.hardfin-completion.zsh"
-		},
-		{
-			description: "Complete in bash",
-			command: "source <(hardfin completion bash)"
-		}
-	],
-	run: runCompletion
-});
-/** The hidden command a completion script asks, which keeps one implementation for every shell. */
-const completeCommand = defineCommand({
-	name: "__complete",
-	summary: "Answer what may follow the words typed so far",
-	hidden: true,
-	arguments: [{
-		name: "words",
-		description: "The words typed so far",
-		required: false,
-		variadic: true
-	}],
-	flags: [{
-		name: "json",
-		description: "Accepted for consistency, and ignored",
-		schema: z.boolean()
-	}],
-	examples: [],
-	run: async (input) => {
-		writeData(toCandidates(input.commands, input.args).join("\n"));
-		return ExitCode.OK;
-	}
-});
-/**
-* toCandidates answers what may follow the words typed so far. A word starting with a dash
-* asks for the current command's flags, and anything else asks for its subcommands.
-*/
-function toCandidates(commands, words) {
-	const partial = words[words.length - 1] ?? "";
-	const walked = toWalked(commands, words.slice(0, -1));
-	if (partial.startsWith("-")) return toFlagNames(walked.command).filter((name) => name.startsWith(partial));
-	if (walked.isUnknown) return [];
-	return (walked.command?.subcommands ?? walked.remaining).map((command) => command.name).filter((name) => !name.startsWith("__")).filter((name) => name.startsWith(partial));
-}
-function toWalked(commands, words) {
-	let remaining = commands;
-	let command;
-	for (const word of words) {
-		if (word.startsWith("-") || command?.arguments.length) continue;
-		const found = remaining.find((entry) => entry.name === word);
-		if (!found) return {
-			command,
-			remaining,
-			isUnknown: true
-		};
-		command = found;
-		remaining = found.subcommands ?? [];
-	}
-	return {
-		command,
-		remaining,
-		isUnknown: false
-	};
-}
-function toFlagNames(command) {
-	return [...(command?.flags ?? []).map((flag) => `--${flag.name}`), "--help"];
-}
-async function runCompletion(input) {
-	const shell = input.args[0] ?? "";
-	if (!SHELLS.includes(shell)) {
-		writeFailure(`${shell || "no shell"} is not one this CLI writes for. Choose ${SHELLS.join(", ")}`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	writeData(toScript(shell));
-	return ExitCode.OK;
-}
 /** toScript writes a shell's completion, each one asking __complete for the candidates. */
 function toScript(shell) {
 	return SCRIPTS[shell];
@@ -1087,14 +1050,28 @@ _hardfin_words() {
 }
 
 _hardfin_complete() {
-  local _hardfin_line_words candidate current prefix breaks
+  local _hardfin_line_words line directive current prefix breaks
   _hardfin_words
   COMPREPLY=()
 
-  while IFS= read -r candidate; do
-    COMPREPLY+=("$candidate")
+  # Each line is a candidate with its description after a tab, which bash cannot show, and
+  # the last line is the directive.
+  while IFS= read -r line; do
+    if [[ $line == :* ]]; then
+      directive=$line
+    else
+      COMPREPLY+=("\${line%%$'\\t'*}")
+    fi
   done < <(hardfin __complete -- "\${_hardfin_line_words[@]:1}" 2>/dev/null)
 
+  # A path is left to readline, which completes it from the file system.
+  if [[ $directive == :1 ]]; then
+    compopt -o default 2>/dev/null
+    COMPREPLY=()
+
+    return
+  fi
+
   # Readline replaces only the text after the last = or : in the word, so a candidate
   # loses what comes before it or the line would repeat that part.
   current=\${_hardfin_line_words[\${#_hardfin_line_words[@]} - 1]}
@@ -1106,21 +1083,68 @@ _hardfin_complete() {
   fi
 }
 
-complete -F _hardfin_complete hardfin`,
+# Bash before 4.0 has no compopt, so files are offered whenever no candidate is.
+if type compopt >/dev/null 2>&1; then
+  complete -F _hardfin_complete hardfin
+else
+  complete -o default -F _hardfin_complete hardfin
+fi`,
 	zsh: `# hardfin completion for zsh
 _hardfin_complete() {
-  local -a candidates
-  candidates=(\${(f)"$(hardfin __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)"})
-  compadd -a candidates
+  local -a lines described
+  local line name directive
+  lines=(\${(f)"$(hardfin __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)"})
+  directive=\${lines[-1]}
+  lines=(\${lines[1,-2]})
+
+  if [[ $directive == :1 ]]; then
+    _files
+
+    return
+  fi
+
+  # Each line is a candidate with its description after a tab, and _describe separates the
+  # two with a colon, so a colon in the candidate is escaped.
+  for line in $lines; do
+    name=\${line%%$'\\t'*}
+    name=\${name//:/\\\\:}
+
+    if [[ $line == *$'\\t'* ]]; then
+      described+=("$name:\${line#*$'\\t'}")
+    else
+      described+=("$name")
+    fi
+  done
+
+  _describe 'hardfin' described -M 'm:{a-zA-Z}={A-Za-z}'
 }
 
+# compdef comes from compinit, which a startup file without completion never runs.
+if ! (( $+functions[compdef] )); then
+  autoload -Uz compinit && compinit
+fi
+
 compdef _hardfin_complete hardfin`,
 	fish: `# hardfin completion for fish
 function __hardfin_complete
     # Older fish lacks -x, which replaced -o, so it falls back to the older option.
     set -l words (commandline -xpc 2>/dev/null; or commandline -opc)
     set -l current (commandline -ct)
-    hardfin __complete -- $words[2..-1] "$current" 2>/dev/null
+    set -l lines (hardfin __complete -- $words[2..-1] "$current" 2>/dev/null)
+    set -l directive $lines[-1]
+
+    if set -q lines[1]
+        set -e lines[-1]
+    end
+
+    if test "$directive" = ":1"
+        __fish_complete_path "$current"
+
+        return
+    end
+
+    # Fish shows what follows a tab as the description, so candidates pass through as they are.
+    string join \\n -- $lines
 end
 
 complete -c hardfin -f -a "(__hardfin_complete)"`,
@@ -1139,18 +1163,488 @@ Register-ArgumentCompleter -Native -CommandName hardfin -ScriptBlock {
     $words += if ($isLegacy) { '""' } else { '' }
   }
 
-  hardfin __complete -- @words 2>$null | ForEach-Object {
-    $text = $_
+  $lines = @(hardfin __complete -- @words 2>$null)
+
+  # Returning nothing makes PowerShell complete paths, which is what the last line asks for
+  # when it is :1.
+  if ($lines.Count -eq 0 -or $lines[-1] -eq ':1') {
+    return
+  }
+
+  # Each line is a candidate with its description after a tab.
+  $lines | Select-Object -SkipLast 1 | ForEach-Object {
+    $value, $description = $_ -split "\`t", 2
+    $text = $value
 
     if ($text -match '[\\s#@$;,''{}()"\`|<>&]') {
       $text = "'" + ($text -replace "'", "''") + "'"
     }
 
-    [System.Management.Automation.CompletionResult]::new($text, $_, 'ParameterValue', $_)
+    [System.Management.Automation.CompletionResult]::new($text, $value, 'ParameterValue', $(if ($description) { $description } else { $value }))
   }
 }`
 };
 //#endregion
+//#region src/command/completion-install.ts
+const BLOCK_START = "# >>> hardfin completion >>>";
+const BLOCK_END = "# <<< hardfin completion <<<";
+const SHELL_ARGUMENT = {
+	name: "shell",
+	description: `The shell to install for, found from $SHELL when not given: ${SHELLS.join(", ")}`,
+	required: false,
+	values: [...SHELLS]
+};
+const YES_FLAG = {
+	name: "yes",
+	short: "y",
+	description: "Make the change without asking",
+	schema: z.boolean()
+};
+const JSON_FLAG$1 = {
+	name: "json",
+	description: "Print machine-readable output, which is the default when stdout is not a terminal",
+	schema: z.boolean()
+};
+const installCommand = defineCommand({
+	name: "install",
+	summary: "Set up completion in your shell",
+	description: "Writes the completion script under your data directory and loads it from your shell's startup file, between two marked lines. Fish loads it from its completions directory, so no startup file changes. Run it again after upgrading, so the script matches the CLI.",
+	arguments: [SHELL_ARGUMENT],
+	flags: [YES_FLAG, JSON_FLAG$1],
+	examples: [{
+		description: "Install for the shell you are using",
+		command: "hardfin completion install"
+	}, {
+		description: "Install for zsh without being asked",
+		command: "hardfin completion install zsh --yes"
+	}],
+	run: (input) => runChange(input, "install")
+});
+const uninstallCommand = defineCommand({
+	name: "uninstall",
+	summary: "Remove completion from your shell",
+	description: "Removes the script install wrote, and the marked lines it added to your shell's startup file.",
+	arguments: [SHELL_ARGUMENT],
+	flags: [YES_FLAG, JSON_FLAG$1],
+	examples: [{
+		description: "Remove completion from zsh",
+		command: "hardfin completion uninstall zsh"
+	}],
+	run: (input) => runChange(input, "uninstall")
+});
+/**
+* toPlan decides where a shell's completion goes. Fish loads a file from its completions
+* directory by itself, and every other shell is told to load the script from its startup
+* file, because not every bash has bash-completion to load it lazily.
+*/
+function toPlan(shell, place) {
+	const content = `${toScript(shell)}\n`;
+	if (shell === "fish") {
+		const config = place.env["XDG_CONFIG_HOME"] || join(place.home, ".config");
+		return {
+			shell,
+			script: {
+				path: join(config, "fish", "completions", "hardfin.fish"),
+				content
+			}
+		};
+	}
+	const data = toDataDirectory(place);
+	const extension = {
+		bash: "bash",
+		zsh: "zsh",
+		powershell: "ps1"
+	}[shell];
+	const path = join(data, `completion.${extension}`);
+	if (shell === "powershell") {
+		const profile = place.toProfile();
+		const block = `if (Test-Path '${path}') { . '${path}' }`;
+		return {
+			shell,
+			script: {
+				path,
+				content
+			},
+			startup: profile ? {
+				path: profile,
+				block
+			} : void 0
+		};
+	}
+	const block = `[ -f '${path}' ] && . '${path}'`;
+	return {
+		shell,
+		script: {
+			path,
+			content
+		},
+		startup: {
+			path: toStartupFile(shell, place),
+			block
+		}
+	};
+}
+/** toDataDirectory is where hardfin keeps files that are not settings or credentials. */
+function toDataDirectory(place) {
+	if (place.platform === "win32") return join(place.env["LOCALAPPDATA"] || join(place.home, "AppData", "Local"), "hardfin");
+	return join(place.env["XDG_DATA_HOME"] || join(place.home, ".local", "share"), "hardfin");
+}
+/**
+* toStartupFile names the file a shell reads when a person opens one. A terminal on macOS
+* starts bash as a login shell, which reads .bash_profile and never .bashrc.
+*/
+function toStartupFile(shell, place) {
+	if (shell === "zsh") return join(place.env["ZDOTDIR"] || place.home, ".zshrc");
+	return join(place.home, place.platform === "darwin" ? ".bash_profile" : ".bashrc");
+}
+/** withBlock answers a startup file holding the marked block once, replacing any earlier copy. */
+function withBlock(text, block) {
+	const marked = `${BLOCK_START}\n${block}\n${BLOCK_END}`;
+	const without = withoutBlock(text);
+	if (without === "") return `${marked}\n`;
+	return `${without.endsWith("\n") ? without : `${without}\n`}\n${marked}\n`;
+}
+/** withoutBlock answers a startup file with the marked block removed, and the blank line before it. */
+function withoutBlock(text) {
+	const start = text.indexOf(BLOCK_START);
+	const end = text.indexOf(BLOCK_END, start);
+	if (start === -1 || end === -1) return text;
+	return text.slice(0, start).replace(/\n\n$/, "\n") + text.slice(end + 28).replace(/^\n/, "");
+}
+/** toShell finds the shell a person is using, from what the environment says. */
+function toShell(place) {
+	const name = basename(place.env["SHELL"] ?? "").replace(/\.exe$/, "");
+	if (SHELLS.includes(name)) return name;
+	if (name === "pwsh") return "powershell";
+	if (place.platform === "win32") return "powershell";
+}
+/** isInstalled answers whether install has written a script for any shell. */
+function isInstalled(place = toPlace()) {
+	return SHELLS.some((shell) => existsSync(toPlan(shell, {
+		...place,
+		toProfile: () => void 0
+	}).script.path));
+}
+function toPlace() {
+	return {
+		home: homedir(),
+		platform: process.platform,
+		env: process.env,
+		toProfile: toPowerShellProfile
+	};
+}
+/** toPowerShellProfile asks PowerShell where its profile is, because it moves between versions. */
+function toPowerShellProfile() {
+	for (const program of ["pwsh", "powershell"]) {
+		const result = spawnSync(program, [
+			"-NoProfile",
+			"-NoLogo",
+			"-Command",
+			"$PROFILE.CurrentUserAllHosts"
+		], { encoding: "utf8" });
+		const profile = result.status === 0 ? result.stdout.trim() : "";
+		if (profile !== "") return profile;
+	}
+}
+async function runChange(input, change) {
+	const place = toPlace();
+	const shell = input.args[0] ?? toShell(place);
+	if (!shell || !SHELLS.includes(shell)) {
+		writeFailure(`name the shell to ${change} for: ${SHELLS.join(", ")}`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const plan = toPlan(shell, place);
+	if (change === "install" && shell === "powershell" && !plan.startup) {
+		writeFailure("PowerShell did not report its profile, so there is nowhere to load the script from", input.isJSON);
+		return ExitCode.ERROR;
+	}
+	process.stderr.write(toDescription(plan, change));
+	if (!await isConfirmed(input.flags["yes"] === true)) {
+		writeFailure(process.stdin.isTTY ? "nothing was changed" : "nothing was changed. Pass --yes to change it without a terminal", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	if (change === "install") {
+		mkdirSync(dirname(plan.script.path), { recursive: true });
+		writeFileSync(plan.script.path, plan.script.content);
+		if (plan.startup) {
+			const text = existsSync(plan.startup.path) ? readFileSync(plan.startup.path, "utf8") : "";
+			mkdirSync(dirname(plan.startup.path), { recursive: true });
+			writeFileSync(plan.startup.path, withBlock(text, plan.startup.block));
+		}
+		for (const warning of toWarnings(place)) process.stderr.write(`warning: ${warning}\n`);
+	} else {
+		rmSync(plan.script.path, { force: true });
+		if (plan.startup && existsSync(plan.startup.path)) writeFileSync(plan.startup.path, withoutBlock(readFileSync(plan.startup.path, "utf8")));
+	}
+	writeData({
+		shell,
+		[change === "install" ? "installed" : "uninstalled"]: true,
+		script: plan.script.path,
+		startupFile: plan.startup?.path ?? null,
+		next: change === "install" ? "Open a new shell to complete hardfin commands with Tab" : "Open a new shell to stop completing hardfin commands"
+	});
+	return ExitCode.OK;
+}
+function toDescription(plan, change) {
+	const lines = change === "install" ? [`This writes the ${plan.shell} completion script to ${plan.script.path}`] : [`This removes the ${plan.shell} completion script at ${plan.script.path}`];
+	if (plan.startup) lines.push(change === "install" ? `and adds these lines to ${plan.startup.path}:\n\n${BLOCK_START}\n${plan.startup.block}\n${BLOCK_END}\n` : `and the lines between the hardfin completion markers in ${plan.startup.path}`);
+	return `${lines.join("\n")}\n`;
+}
+/** isConfirmed asks before changing a person's files, unless they already said yes. */
+async function isConfirmed(isYes) {
+	if (isYes) return true;
+	if (!process.stdin.isTTY) return false;
+	const reader = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		const answer = await reader.question("Continue? [y/N] ");
+		return /^y(es)?$/i.test(answer.trim());
+	} finally {
+		reader.close();
+	}
+}
+/**
+* toWarnings names what would stop the script from working once installed. The script
+* calls hardfin by name, so a CLI run from a checkout has nothing for it to call.
+*/
+function toWarnings(place, find = (name) => toOnPath(name, place), isInsideWSL = isWSL) {
+	const found = find(place.platform === "win32" ? "hardfin.cmd" : "hardfin");
+	if (!found) return ["hardfin is not on your PATH, and the script calls it by name. Install it with npm install -g @hardfin/cli, or npm link in a checkout"];
+	if (place.platform === "linux" && found.startsWith("/mnt/") && isInsideWSL()) return [`the hardfin on your PATH is the Windows one at ${found}. Install it inside WSL, so each Tab runs the Linux one`];
+	return [];
+}
+function toOnPath(name, place) {
+	return (place.env["PATH"] ?? "").split(delimiter).filter((directory) => directory !== "").map((directory) => join(directory, name)).find(isExecutable);
+}
+function isExecutable(path) {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/command/completion.ts
+const completionCommand = defineCommand({
+	name: "completion",
+	summary: "Complete hardfin commands in your shell",
+	description: "Prints the completion script for a shell. The script asks this CLI what may follow what you have typed, so completions never fall behind the commands. Run hardfin completion install to load it in every new shell.",
+	arguments: [{
+		name: "shell",
+		description: `The shell to write for: ${SHELLS.join(", ")}`,
+		required: true,
+		values: [...SHELLS]
+	}],
+	flags: [],
+	examples: [{
+		description: "Complete in every new shell",
+		command: "hardfin completion install"
+	}, {
+		description: "Complete in this shell, now",
+		command: "source <(hardfin completion zsh)"
+	}],
+	subcommands: [installCommand, uninstallCommand],
+	run: runCompletion
+});
+/** The hidden command a completion script asks, which keeps one implementation for every shell. */
+const completeCommand = defineCommand({
+	name: "__complete",
+	summary: "Answer what may follow the words typed so far",
+	hidden: true,
+	arguments: [{
+		name: "words",
+		description: "The words typed so far",
+		required: false,
+		variadic: true
+	}],
+	flags: [{
+		name: "json",
+		description: "Accepted for consistency, and ignored",
+		schema: z.boolean()
+	}],
+	examples: [],
+	run: async (input) => {
+		writeData(toAnswer$1(toCompletion(input.commands, input.args)));
+		return ExitCode.OK;
+	}
+});
+/** Directive is the last line of an answer, which tells the script what to do beyond the candidates. */
+const Directive = {
+	NONE: ":0",
+	FILES: ":1"
+};
+const HELP_FLAG = {
+	name: "help",
+	short: "h",
+	description: "Print help for the command",
+	schema: z.boolean()
+};
+const VERSION_FLAG = {
+	name: "version",
+	short: "v",
+	description: "Print the version",
+	schema: z.boolean()
+};
+/** The value names that mean a path, so the shell offers files for them. */
+const PATH_VALUES = /* @__PURE__ */ new Set(["path", "file"]);
+const NOTHING = {
+	candidates: [],
+	isFile: false
+};
+/**
+* toAnswer writes a completion as a script reads it. Each line is a candidate, with its
+* description after a tab, and the last line is the directive.
+*/
+function toAnswer$1(completion) {
+	return [...completion.candidates.map((candidate) => candidate.description ? `${candidate.value}\t${toLine(candidate.description)}` : candidate.value), completion.isFile ? Directive.FILES : Directive.NONE].join("\n");
+}
+/**
+* toCompletion answers what may follow the words typed so far. The last word is what is
+* being typed, and it is empty when the cursor sits after a space, which asks what may come
+* next rather than how to finish the word before it.
+*/
+function toCompletion(commands, words) {
+	const partial = words[words.length - 1] ?? "";
+	const walked = toWalked(commands, words.slice(0, -1));
+	if (walked.isUnknown) return NOTHING;
+	if (walked.pending) return toValues(walked.pending, partial, "");
+	const assigned = /^(--?[^=]+)=(.*)$/.exec(partial);
+	if (assigned?.[1] !== void 0 && assigned[2] !== void 0) {
+		const flag = toFlag(walked.flags, assigned[1]);
+		return flag?.valueName ? {
+			candidates: toValues(flag, assigned[2], `${assigned[1]}=`).candidates,
+			isFile: false
+		} : NOTHING;
+	}
+	if (partial.startsWith("-")) return {
+		candidates: toFlagCandidates(walked).filter((candidate) => candidate.value.startsWith(partial)),
+		isFile: false
+	};
+	const subcommands = toSubcommands(commands, walked).filter((command) => !command.hidden && command.name.startsWith(partial)).map((command) => ({
+		value: command.name,
+		description: command.summary
+	}));
+	if (walked.command && walked.command.subcommands?.length && !walked.command.run) return {
+		candidates: subcommands,
+		isFile: false
+	};
+	return {
+		candidates: [...subcommands, ...toArgumentValues(walked, partial)],
+		isFile: false
+	};
+}
+/** toSubcommands lists the commands the next word may name. */
+function toSubcommands(commands, walked) {
+	if (!walked.command) return commands;
+	return walked.positionals === 0 ? walked.command.subcommands ?? [] : [];
+}
+function toWalked(commands, words) {
+	let walked = {
+		flags: [
+			...GLOBAL_FLAGS,
+			VERSION_FLAG,
+			HELP_FLAG
+		],
+		used: /* @__PURE__ */ new Set(),
+		positionals: 0,
+		isUnknown: false
+	};
+	for (const word of words) {
+		if (walked.pending) {
+			walked.pending = void 0;
+			continue;
+		}
+		if (word.startsWith("-")) {
+			const flag = toFlag(walked.flags, word.split("=")[0] ?? word);
+			if (flag) walked.used.add(flag.name);
+			if (flag?.valueName && !word.includes("=")) walked.pending = flag;
+			continue;
+		}
+		const found = toSubcommands(commands, walked).find((entry) => entry.name === word);
+		if (found) {
+			walked = {
+				command: found,
+				flags: [...found.flags, HELP_FLAG],
+				used: /* @__PURE__ */ new Set(),
+				positionals: 0,
+				isUnknown: false
+			};
+			continue;
+		}
+		if (walked.command?.arguments.length) {
+			walked.positionals += 1;
+			continue;
+		}
+		return {
+			...walked,
+			isUnknown: true
+		};
+	}
+	return walked;
+}
+/** toFlag finds the flag a word names, whether long, short, or the --no- form of a boolean. */
+function toFlag(flags, word) {
+	if (word.startsWith("--")) {
+		const name = word.slice(2);
+		return flags.find((flag) => flag.name === name || flag.negatable && `no-${flag.name}` === name);
+	}
+	return flags.find((flag) => flag.short !== void 0 && `-${flag.short}` === word);
+}
+function toFlagCandidates(walked) {
+	return walked.flags.filter((flag) => flag.repeatable || !walked.used.has(flag.name)).flatMap((flag) => {
+		const candidate = {
+			value: `--${flag.name}`,
+			description: flag.description
+		};
+		return flag.negatable ? [candidate, {
+			value: `--no-${flag.name}`,
+			description: `${flag.description}, turned off`
+		}] : [candidate];
+	});
+}
+/** toValues offers the values a flag takes, each written after the prefix the word already has. */
+function toValues(flag, partial, prefix) {
+	const values = toSchemaValues(flag.schema);
+	if (values) {
+		const typed = partial.toLowerCase();
+		return {
+			candidates: values.filter((value) => value.toLowerCase().startsWith(typed)).map((value) => ({ value: `${prefix}${value}` })),
+			isFile: false
+		};
+	}
+	return {
+		candidates: [],
+		isFile: PATH_VALUES.has(flag.valueName ?? "")
+	};
+}
+function toArgumentValues(walked, partial) {
+	const declared = walked.command?.arguments ?? [];
+	const last = declared[declared.length - 1];
+	return ((walked.positionals < declared.length ? declared[walked.positionals] : last?.variadic ? last : void 0)?.values ?? []).filter((value) => value.startsWith(partial)).map((value) => ({ value }));
+}
+/** toSchemaValues reads the values a schema allows, when it allows only a fixed set. */
+function toSchemaValues(schema) {
+	if (schema instanceof z.ZodEnum) return schema.options.map(String);
+	if (schema instanceof z.ZodPipe) return toSchemaValues(schema.out);
+	if (schema instanceof z.ZodOptional || schema instanceof z.ZodDefault) return toSchemaValues(schema.unwrap());
+}
+/** toLine keeps a description on one line, because a newline would start another candidate. */
+function toLine(description) {
+	return description.replace(/\s+/g, " ").trim();
+}
+async function runCompletion(input) {
+	const shell = input.args[0] ?? "";
+	if (!SHELLS.includes(shell)) {
+		writeFailure(`${shell || "no shell"} is not one this CLI writes for. Choose ${SHELLS.join(", ")}`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	writeData(toScript(shell));
+	return ExitCode.OK;
+}
+//#endregion
 //#region src/command/config.ts
 const configCommand = defineCommand({
 	name: "config",
@@ -1201,47 +1695,6 @@ async function runConfig(input) {
 	return ExitCode.OK;
 }
 //#endregion
-//#region src/auth/browser.ts
-/** isWSL reports whether this Linux is running under Windows. */
-function isWSL() {
-	return existsSync("/proc/sys/fs/binfmt_misc/WSLInterop");
-}
-/**
-* toOpeners lists the ways to open a URL here, best first. WSL needs Windows to do it,
-* because the browser the person is looking at is the Windows one, and xdg-open reaches
-* nothing outside the distribution.
-*/
-function toOpeners(url) {
-	if (process.platform === "darwin") return [["open", [url]]];
-	if (process.platform === "win32") return [["cmd", [
-		"/c",
-		"start",
-		"",
-		url
-	]]];
-	if (isWSL()) return [
-		["wslview", [url]],
-		["powershell.exe", [
-			"-NoProfile",
-			"-NonInteractive",
-			"-Command",
-			"Start-Process",
-			`'${url}'`
-		]],
-		["explorer.exe", [url]]
-	];
-	return [["xdg-open", [url]]];
-}
-/** openBrowser asks the desktop to show a URL, and reports whether anything took it. */
-function openBrowser(url, launch = spawnSync) {
-	for (const [command, args] of toOpeners(url)) if (launch(command, args, {
-		stdio: "ignore",
-		cwd: command.endsWith(".exe") ? "/mnt/c" : void 0,
-		timeout: 1e4
-	}).error === void 0) return true;
-	return false;
-}
-//#endregion
 //#region src/auth/device.ts
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 /** The interval a server gives is in seconds, and five more are added on a slow_down. */
@@ -1653,7 +2106,8 @@ async function toSignedIn(input, metadata, tokens) {
 		`Scope     ${tokens.scope ?? "as granted"}`,
 		`Stored in ${stored}`,
 		"",
-		"Run hardfin status to see what this CLI is using"
+		"Run hardfin status to see what this CLI is using",
+		...isInstalled() ? [] : ["Run hardfin completion install to complete commands with Tab"]
 	].join("\n"));
 	return ExitCode.OK;
 }
@@ -1947,7 +2401,7 @@ function toCliRunner() {
 }
 /** serve answers requests on stdin until the client closes it. */
 async function serve(commands, run = toCliRunner()) {
-	const lines = createInterface({ input: process.stdin });
+	const lines = createInterface$1({ input: process.stdin });
 	const answering = /* @__PURE__ */ new Set();
 	for await (const line of lines) {
 		if (line.trim() === "") continue;
@@ -5201,7 +5655,8 @@ function toRejectedFlag(command, flags) {
 /** toCli builds the parser from the registry, which is what every surface reads. */
 function toCli(entries = commands) {
 	const program = new Command();
-	program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").option("--api-url <url>", "The API to call, whose host also holds the authorization server").option("--issuer-url <url>", "The authorization server, when it does not sit at the API's host").showHelpAfterError().enablePositionalOptions();
+	program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").showHelpAfterError().enablePositionalOptions();
+	for (const flag of GLOBAL_FLAGS) program.option(`--${flag.name} <${flag.valueName}>`, flag.description);
 	for (const command of entries) program.addCommand(toProgram(program, command), { hidden: command.hidden });
 	return program;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.0-dev.22",
+    "version": "0.1.0-dev.24",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",