@hardfin/cli 0.1.1-dev.49 → 0.1.1-dev.51

package/README.md

@@ -129,6 +129,35 @@ An agent branches on `code`. A code is never renamed and never changes meaning,
 message may be reworded at any time. `hardfin agent-guide` lists every code with what it
 means, and `src/output/failure.ts` defines them.
 
+### Reading the commands from a program
+
+`hardfin agent-guide` describes the CLI to an agent, as Markdown or as JSON. Name a command to
+get that command alone, which is a few kilobytes where the whole guide is two hundred.
+
+```sh
+hardfin agent-guide                              # every command, as Markdown
+hardfin agent-guide --json                       # every command, as JSON
+hardfin agent-guide --json customer create       # one command, and what is nested under it
+hardfin agent-guide --json customer create | jq -r '.commands[0].flags[] | select(.required) | .name'
+```
+
+The JSON holds `cli`, `apiVersion`, `exitCodes`, `errorCodes`, `globalFlags` and `commands`.
+Each command names its `path`, its `endpoint`, whether it `runs`, and its flags.
+
+| A flag's     | Holds                                                                       |
+| ------------ | --------------------------------------------------------------------------- |
+| `required`   | Present when the command fails without it                                   |
+| `schema`     | The `type`, and the `enum`, `format`, `minimum` or `maximum` that narrow it |
+| `sends`      | The query parameter, or the path of the body field, the value goes to       |
+| `clearable`  | Present when `--unset` can clear the field                                  |
+| `repeatable` | Present when the flag is given once per value                               |
+| `negatable`  | Present when a boolean also takes a `--no-` form                            |
+| `element`    | The fields one value carries as `key=value`, for an array of objects        |
+| `default`    | The value used when the flag is not given                                   |
+
+A part that is absent means no. The description is read from the same declarations the parser
+enforces, so it cannot say one thing while the command does another.
+
 ### Overrides
 
 Two endpoints sometimes want one name. `DELETE /asset/{assetKey}/ownership` and
@@ -480,6 +509,10 @@ Nothing secret is printed. An API key and a refresh token are each reported as a
 `sha256:` fingerprint, which identifies a credential across two machines without disclosing
 it.
 
+`authorizationServer.scopesOffered` is every scope the server can grant to anyone. The scopes
+this sign in was granted are `api.accessTokenScopes`, and `api.identity.scopes` is what the
+API says the credential holds.
+
 `api.authenticated` is `true` only when the API answered who the credential is. A 401 or a
 403 makes it `false`, and `hardfin status` then exits with code 4. It is `null` when the API
 could not be asked, because no answer says nothing about the credential.

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6c054d7b-a0a8-526c-90d7-5bbec53675dd")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d68fe726-8a0c-5521-8d64-6a70ad73fa4f")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,7 +14,7 @@ process.on("unhandledRejection", (error) => void toCrash(error));
 try {
 	const answer = await toQuickAnswer(process.argv.slice(2));
 	if (answer === void 0) {
-		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-Da7dZSnW.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-CXKDQ-E9.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	const isJSON = process.argv.includes("--json") || !process.stdout.isTTY;
 	try {
-		const { toReported, writeCrash } = await import("./program-Da7dZSnW.js");
+		const { toReported, writeCrash } = await import("./program-CXKDQ-E9.js");
 		writeCrash(error, isJSON);
 		await toReported(error, isJSON, void 0, "fatal");
 	} catch {
@@ -54,4 +54,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=6c054d7b-a0a8-526c-90d7-5bbec53675dd
+//# debugId=d68fe726-8a0c-5521-8d64-6a70ad73fa4f

package/dist/completion-tree.json

@@ -2610,10 +2610,14 @@
       "flags": [
         {
           "name": "json",
-          "description": "Print the command registry as JSON instead of Markdown"
+          "description": "Print every command as JSON, with what each flag takes, instead of Markdown"
+        }
+      ],
+      "arguments": [
+        {
+          "variadic": true
         }
       ],
-      "arguments": [],
       "subcommands": []
     },
     {

package/dist/{program-Da7dZSnW.js → program-CXKDQ-E9.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e0ad2183-1cb1-5831-b5d1-b96dcf795d93")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f3469c6b-5453-551f-9090-b9d18cbba487")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BZ0egWxC.js";
 import { n as toAnswer$1, r as toCompletion, t as PATH_VALUES } from "./completion-tree-DLC6ARLR.js";
 import { createRequire } from "node:module";
@@ -1296,23 +1296,47 @@ const agentGuideCommand = defineCommand({
 	name: "agent-guide",
 	summary: "Print instructions an agent can follow to use this CLI",
 	description: "Writes Markdown describing every command, its flags, and its exit codes. Save it as a skill file, an AGENTS.md section, or paste it into a system prompt.",
-	arguments: [],
+	arguments: [{
+		name: "command",
+		description: "The words of one command, such as customer create, to describe it and what is nested under it alone",
+		required: false,
+		variadic: true
+	}],
 	flags: [{
 		name: "json",
-		description: "Print the command registry as JSON instead of Markdown",
+		description: "Print every command as JSON, with what each flag takes, instead of Markdown",
 		schema: z.boolean().optional()
 	}],
-	examples: [{
-		description: "Write a skill file",
-		command: "hardfin agent-guide > SKILL.md"
-	}, {
-		description: "Inspect the registry",
-		command: "hardfin agent-guide --json"
-	}],
+	examples: [
+		{
+			description: "Write a skill file",
+			command: "hardfin agent-guide > SKILL.md"
+		},
+		{
+			description: "Read what every flag takes",
+			command: "hardfin agent-guide --json"
+		},
+		{
+			description: "Read what one command takes, and nothing else",
+			command: "hardfin agent-guide --json customer create"
+		},
+		{
+			description: "List the flags one command needs",
+			command: "hardfin agent-guide --json customer create | jq -r '.commands[0].flags[] | select(.required) | .name'"
+		}
+	],
 	run: runAgentGuide
 });
+/** EXIT_CODES is what each exit code means, which both forms of the guide print. */
+const EXIT_CODES = {
+	[ExitCode.OK]: "The command succeeded",
+	[ExitCode.ERROR]: "The command failed",
+	[ExitCode.USAGE]: "The command was called wrongly",
+	[ExitCode.NOT_AUTHENTICATED]: "No usable credential",
+	[ExitCode.INTERRUPTED]: "The person pressed Ctrl-C"
+};
 /** toGuide renders the registry as the Markdown an agent reads. */
-function toGuide(commands, version) {
+function toGuide(commands, version, parents = []) {
 	const lines = [
 		"# Hardfin CLI",
 		"",
@@ -1330,11 +1354,7 @@ function toGuide(commands, version) {
 		"",
 		"| Code | Means |",
 		"| --- | --- |",
-		"| 0 | The command succeeded |",
-		"| 1 | The command failed |",
-		"| 2 | The command was called wrongly |",
-		"| 4 | No usable credential |",
-		"| 130 | The person pressed Ctrl-C |",
+		...Object.entries(EXIT_CODES).map(([code, meaning]) => `| ${code} | ${meaning} |`),
 		"",
 		"## Error codes",
 		"",
@@ -1347,7 +1367,7 @@ function toGuide(commands, version) {
 		"## Commands",
 		""
 	];
-	for (const command of commands.filter((command) => !command.hidden)) lines.push(...toCommandLines(command, []));
+	for (const command of commands.filter((command) => !command.hidden)) lines.push(...toCommandLines(command, parents));
 	return lines.join("\n");
 }
 /** toCommandLines describes one command and everything nested under it. */
@@ -1365,10 +1385,11 @@ function toCommandLines(command, parents) {
 		lines.push("");
 	}
 	if (command.flags.length > 0) {
-		lines.push("| Flag | Takes | Does |", "| --- | --- | --- |");
+		lines.push("| Flag | Required | Takes | Does |", "| --- | --- | --- | --- |");
 		for (const flag of command.flags) {
 			const name = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
-			lines.push(`| \`${name}\` | ${flag.valueName ?? "nothing"} | ${flag.description} |`);
+			const described = toDescribed(flag);
+			lines.push(`| \`${name}\` | ${described.required ? "yes" : "no"} | ${toTaken(described)} | ${flag.description} |`);
 		}
 		lines.push("");
 	}
@@ -1376,29 +1397,111 @@ function toCommandLines(command, parents) {
 	for (const subcommand of command.subcommands ?? []) lines.push(...toCommandLines(subcommand, path));
 	return lines;
 }
+/** toTaken says in a few words what a flag takes, naming the values when only some are allowed. */
+function toTaken(flag) {
+	const values = flag.schema.enum ?? flag.schema.items?.enum;
+	if (values) return `one of ${values.map((value) => `\`${value}\``).join(", ")}`;
+	if (flag.element) return flag.element.map((field) => `${field}=`).join(",");
+	return flag.valueName ?? "nothing";
+}
 async function runAgentGuide(input) {
+	const found = toNamed(input.commands, input.args);
+	if (found === void 0) {
+		writeFailure("invalid_arguments", `no command is called ${input.args.join(" ")}. Run hardfin --help for the list`, input.isJSON);
+		return ExitCode.USAGE;
+	}
 	if (input.flags["json"] === true) {
-		writeData(input.commands.filter((command) => !command.hidden).map(toSummary));
+		writeData(toDescription$1(found.commands, version$1, found.parents));
 		return ExitCode.OK;
 	}
-	writeData(toGuide(input.commands, version$1));
+	writeData(toGuide(found.commands, version$1, found.parents));
 	return ExitCode.OK;
 }
-function toSummary(command) {
+/** toNamed finds the one command a caller named by its words, or every command when none was named. */
+function toNamed(commands, words) {
+	let level = commands.filter((command) => !command.hidden);
+	let found;
+	for (const word of words) {
+		found = level.find((command) => command.name === word);
+		if (!found) return;
+		level = (found.subcommands ?? []).filter((command) => !command.hidden);
+	}
+	return found ? {
+		commands: [found],
+		parents: words.slice(0, -1)
+	} : {
+		commands: level,
+		parents: []
+	};
+}
+/** toDescribed reads one flag from its declaration, which is also what the parser enforces. */
+function toDescribed(flag) {
+	const sent = flag;
+	const described = {
+		name: flag.name,
+		short: flag.short,
+		description: flag.description,
+		valueName: flag.valueName,
+		required: sent.required === true,
+		repeatable: flag.repeatable === true,
+		negatable: flag.negatable === true,
+		clearable: sent.nullable === true,
+		default: flag.defaultValue,
+		schema: toFlagSchema(flag),
+		sends: sent.queryName !== void 0 ? { query: sent.queryName } : sent.jsonPath !== void 0 ? { body: sent.jsonPath } : void 0,
+		element: sent.element
+	};
+	return Object.fromEntries(Object.entries(described).filter(([, value]) => value !== void 0 && value !== false));
+}
+/** The bounds zod states for any whole number, which say nothing about a particular flag. */
+const ANY_INTEGER = [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER];
+/** toFlagSchema states what a value must be, keeping only the parts that narrow it. */
+function toFlagSchema(flag) {
+	try {
+		return toNarrowed(z.toJSONSchema(flag.schema, {
+			io: "output",
+			unrepresentable: "any"
+		}));
+	} catch {
+		return {};
+	}
+}
+function toNarrowed(schema) {
+	const narrowed = {};
+	if (typeof schema["type"] === "string") narrowed.type = schema["type"];
+	if (typeof schema["format"] === "string") narrowed.format = schema["format"];
+	if (Array.isArray(schema["enum"])) narrowed.enum = schema["enum"].map(String);
+	for (const bound of ["minimum", "maximum"]) {
+		const value = schema[bound];
+		if (typeof value === "number" && !ANY_INTEGER.includes(value)) narrowed[bound] = value;
+	}
+	if (typeof schema["items"] === "object" && schema["items"] !== null) narrowed.items = toNarrowed(schema["items"]);
+	return narrowed;
+}
+/** toDescription is the whole CLI as data: the codes, and every command with what it takes. */
+function toDescription$1(commands, version, parents = []) {
+	return {
+		cli: version,
+		apiVersion: API_VERSION,
+		exitCodes: EXIT_CODES,
+		errorCodes: FAILURE_CODES,
+		globalFlags: GLOBAL_FLAGS.map(toDescribed),
+		commands: commands.filter((command) => !command.hidden).map((command) => toSummary(command, parents))
+	};
+}
+function toSummary(command, parents) {
+	const path = [...parents, command.name];
 	return {
 		name: command.name,
+		path,
 		summary: command.summary,
 		description: command.description ?? command.summary,
+		runs: command.run !== void 0,
+		endpoint: command.endpoint ?? null,
 		arguments: command.arguments,
-		flags: command.flags.map((flag) => ({
-			name: flag.name,
-			short: flag.short ?? null,
-			description: flag.description,
-			valueName: flag.valueName ?? null,
-			repeatable: flag.repeatable ?? false
-		})),
+		flags: command.flags.map(toDescribed),
 		examples: command.examples,
-		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map(toSummary)
+		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map((entry) => toSummary(entry, path))
 	};
 }
 //#endregion
@@ -3456,8 +3559,8 @@ function toServerReport(metadata) {
 		tokenEndpoint: metadata.token_endpoint,
 		revocationEndpoint: metadata.revocation_endpoint ?? null,
 		deviceEndpoint: metadata.device_authorization_endpoint ?? null,
-		grantTypes: metadata.grant_types_supported ?? [],
-		scopes: metadata.scopes_supported ?? []
+		grantTypesOffered: metadata.grant_types_supported ?? [],
+		scopesOffered: metadata.scopes_supported ?? []
 	};
 }
 /** The statuses the API answers when it will not take the credential. */
@@ -6934,5 +7037,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted, writeCrash };
 
-//# sourceMappingURL=program-Da7dZSnW.js.map
-//# debugId=e0ad2183-1cb1-5831-b5d1-b96dcf795d93
+//# sourceMappingURL=program-CXKDQ-E9.js.map
+//# debugId=f3469c6b-5453-551f-9090-b9d18cbba487

package/package.json

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

package/skills/hardfin-cli/SKILL.md

@@ -55,6 +55,7 @@ hardfin --help                    # the nouns
 hardfin asset --help              # what you can do with assets
 hardfin asset create --help       # every flag that command takes
 hardfin agent-guide               # every command, flag, exit code and error code, as Markdown
+hardfin agent-guide --json asset create   # one command as JSON: required flags, allowed values, the endpoint
 ```
 
 | Noun               | Holds                                                                              |