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

package/dist/cli.js

@@ -21,6 +21,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. */
@@ -970,7 +982,8 @@ const completionCommand = defineCommand({
 	arguments: [{
 		name: "shell",
 		description: `The shell to write for: ${SHELLS.join(", ")}`,
-		required: true
+		required: true,
+		values: [...SHELLS]
 	}],
 	flags: [],
 	examples: [
@@ -1007,43 +1020,168 @@ const completeCommand = defineCommand({
 	}],
 	examples: [],
 	run: async (input) => {
-		writeData(toCandidates(input.commands, input.args).join("\n"));
+		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");
+}
 /**
-* 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.
+* 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 toCandidates(commands, words) {
+function toCompletion(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));
+	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 = walked.command ? walked.command.subcommands ?? [] : commands;
+	if (subcommands.length > 0) return {
+		candidates: subcommands.filter((command) => !command.hidden && command.name.startsWith(partial)).map((command) => ({
+			value: command.name,
+			description: command.summary
+		})),
+		isFile: false
+	};
+	return toArgumentValues(walked, partial);
 }
 function toWalked(commands, words) {
-	let remaining = commands;
-	let command;
+	let walked = {
+		flags: [
+			...GLOBAL_FLAGS,
+			VERSION_FLAG,
+			HELP_FLAG
+		],
+		used: /* @__PURE__ */ new Set(),
+		positionals: 0,
+		isUnknown: false
+	};
 	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,
+		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 = (walked.command ? walked.command.subcommands ?? [] : commands).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
 		};
-		command = found;
-		remaining = found.subcommands ?? [];
+	}
+	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 {
-		command,
-		remaining,
-		isUnknown: false
+		candidates: [],
+		isFile: PATH_VALUES.has(flag.valueName ?? "")
+	};
+}
+function toArgumentValues(walked, partial) {
+	const declared = walked.command?.arguments ?? [];
+	const last = declared[declared.length - 1];
+	return {
+		candidates: ((walked.positionals < declared.length ? declared[walked.positionals] : last?.variadic ? last : void 0)?.values ?? []).filter((value) => value.startsWith(partial)).map((value) => ({ value })),
+		isFile: false
 	};
 }
-function toFlagNames(command) {
-	return [...(command?.flags ?? []).map((flag) => `--${flag.name}`), "--help"];
+/** 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] ?? "";
@@ -1087,14 +1225,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,12 +1258,40 @@ _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 _hardfin_complete hardfin`,
@@ -1120,7 +1300,21 @@ 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,14 +1333,24 @@ 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 }))
   }
 }`
 };
@@ -5201,7 +5405,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.23",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",