@leemour/cli-core 0.1.2 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ keyring behind a testable seam, and injectable clocks.
 Extracted from [`brazecli`](https://github.com/leemour/brazecli), where each piece earned its
 shape, and shared with [`max-cli`](https://github.com/leemour/max-cli).
 
-**Status: 0.1.2.** Published on npm, used by `max-cli`. Both extraction steps have landed: the
+**Status: 0.3.0.** Published on npm, used by `max-cli`. Both extraction steps have landed: the
 files that move unchanged, and the ones that needed a parameter threaded through. 75 tests.
 
 ## The rule this package exists to keep
@@ -43,6 +43,8 @@ streams.stderr // []
 | `logging` | a Pino adapter writing JSON lines with secrets redacted by field name; a file that cannot be written is reported to `onError`, never thrown |
 | `retry` | full-jitter backoff, and the distinction between "no answer came" and "safe to repeat" |
 | `/testing` | `captureStreams`, `memoryKeyring`, `brokenKeyring`, `fakeClock` |
+| `/commands` | the command registry: `describeProgram`, `annotate`, `flatten` — see below |
+| `/completion` | shell completion over the registry: `suggest`, `formatSuggestions` — see below |
 
 **Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
 seam live in `@leemour/cli-core/http`, so a CLI that speaks a socket never depends on a stack it
@@ -52,6 +54,40 @@ does not call:
 import { providerWaitMs, statusToCode } from "@leemour/cli-core/http"
 ```
 
+**The command registry is `@leemour/cli-core/commands`** — the whole command tree as data, like
+`rails routes`, for an agent to read instead of `--help` and for generated documentation. It walks
+the live [Commander](https://github.com/tj/commander.js) tree, so a command built in a loop from a
+catalog appears exactly like a handwritten one; `annotate` adds what the tree cannot say. Commander
+is a type here, not a runtime dependency — an optional peer, 15 or newer.
+
+```ts
+import { annotate, describeProgram } from "@leemour/cli-core/commands"
+
+annotate(program.command("send"), { mutates: true, examples: ["max messages send 42 hi"] })
+annotate(generated, { origin: "generated", operationId: "campaigns.list" })
+
+describeProgram(program) // [{ path: ["send"], usage, origin, mutates, options: [...], commands: [...] }]
+```
+
+Each option says whether it `takesValue` and, separately, whether it is `mandatory` — not
+Commander's `required`, which means "takes a value when given" — plus its choices, default,
+environment variable, the options it `conflicts` with and the values it `implies`.
+
+**Shell completion is `@leemour/cli-core/completion`**, built on the registry. `suggest` takes the
+words typed so far and answers what may come next: a command, an action, an option, one of its
+values, or an argument's values from a source the CLI hands in — a local cache, never the network,
+because a shell calls it on every Tab. `formatSuggestions` writes the answer in the protocol of the
+shell scripts [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab) generates, so the CLI prints
+those scripts with tab and answers `<cli> complete -- <words>` with this; cli-core itself does not
+depend on tab.
+
+```ts
+import { formatSuggestions, suggest } from "@leemour/cli-core/completion"
+
+const words = argv.slice(argv.indexOf("--") + 1)
+streams.data(formatSuggestions(suggest({ commands, globalOptions, words, sources: { arguments: { chat: chatNames } } })))
+```
+
 **Two traps worth knowing before you use the credential store.** The OS keyring is global: an entry
 is addressed by service and account and knows nothing about which config directory asked for it, so
 a throwaway config directory silently overwrites the real secret unless you pass `isolated: true`.

package/dist/commands/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The command registry: the whole command tree of a CLI as data, however each command came to be.
+ *
+ * It walks the live Commander tree rather than a list written by hand, so a command built in a
+ * loop from a catalog shows up exactly like one written in a file. What the tree cannot say — where
+ * a command came from, whether it changes anything, whether it is on its way out — is attached with
+ * `annotate`.
+ *
+ * Behind its own entry point for the same reason `/http` is: Commander is only a type here, and the
+ * root of this package stays free of any command-line framework.
+ */
+import type { Command } from "commander";
+export type Origin = "handwritten" | "generated";
+export type CommandState = "beta" | "deprecated";
+export interface CommandMeta {
+    origin?: Origin;
+    /** The catalog operation a generated command was made from. */
+    operationId?: string;
+    /** True when running the command changes something outside this machine. */
+    mutates?: boolean;
+    state?: CommandState;
+    examples?: readonly string[];
+}
+export interface ArgumentInfo {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    description: string;
+    choices?: readonly string[];
+    default?: unknown;
+}
+export interface OptionInfo {
+    flags: string;
+    description: string;
+    /** False for a plain switch like `--json`, so an agent knows not to look for a value. */
+    takesValue: boolean;
+    /**
+     * Whether the option itself must be given. Deliberately not Commander's `required`, which means
+     * "takes a value when present" — reading that as "you must pass this" is the obvious misreading.
+     */
+    mandatory: boolean;
+    choices?: readonly string[];
+    default?: unknown;
+    env?: string;
+    /** Options that may not be given together with this one. */
+    conflicts?: readonly string[];
+    /** Values this option sets on others when they are not given. */
+    implies?: Readonly<Record<string, unknown>>;
+}
+export interface CommandInfo {
+    /** What to pass to the CLI, already split: `["runs", "list"]`. */
+    path: readonly string[];
+    name: string;
+    summary?: string;
+    description: string;
+    usage: string;
+    origin: Origin;
+    operationId?: string;
+    mutates?: boolean;
+    state?: CommandState;
+    examples?: readonly string[];
+    arguments: readonly ArgumentInfo[];
+    options: readonly OptionInfo[];
+    commands: readonly CommandInfo[];
+}
+/** Attaches what the tree cannot say. Repeated calls merge; the command is returned for chaining. */
+export declare const annotate: <T extends Command>(command: T, meta: CommandMeta) => T;
+export declare const metaOf: (command: Command) => CommandMeta;
+export declare const describeProgram: (root: Command) => CommandInfo[];
+export declare const describeOptions: (command: Command) => OptionInfo[];
+export declare const flatten: (commands: readonly CommandInfo[]) => CommandInfo[];
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAY,OAAO,EAAU,MAAM,WAAW,CAAA;AAE1D,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,WAAW,CAAA;AAChD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,CAAA;AAEhD,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,yFAAyF;IACzF,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,iEAAiE;IACjE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,SAAS,EAAE,SAAS,YAAY,EAAE,CAAA;IAClC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IAC9B,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CACjC;AAID,qGAAqG;AACrG,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,WAAW,KAAG,CAG3E,CAAA;AAED,eAAO,MAAM,MAAM,GAAI,SAAS,OAAO,KAAG,WAAwC,CAAA;AAElF,eAAO,MAAM,eAAe,GAAI,MAAM,OAAO,KAAG,WAAW,EACK,CAAA;AAEhE,eAAO,MAAM,eAAe,GAAI,SAAS,OAAO,KAAG,UAAU,EACW,CAAA;AAExE,eAAO,MAAM,OAAO,GAAI,UAAU,SAAS,WAAW,EAAE,KAAG,WAAW,EACE,CAAA"}

package/dist/commands/index.js

@@ -0,0 +1,61 @@
+const labels = new WeakMap();
+/** Attaches what the tree cannot say. Repeated calls merge; the command is returned for chaining. */
+export const annotate = (command, meta) => {
+    labels.set(command, { ...labels.get(command), ...meta });
+    return command;
+};
+export const metaOf = (command) => labels.get(command) ?? {};
+export const describeProgram = (root) => visible(root).map((child) => describe(child, root.name(), []));
+export const describeOptions = (command) => command.options.filter((option) => !option.hidden).map(describeOption);
+export const flatten = (commands) => commands.flatMap((command) => [command, ...flatten(command.commands)]);
+const describe = (command, cli, parents) => {
+    const path = [...parents, command.name()];
+    const args = command.registeredArguments.map(describeArgument);
+    const options = describeOptions(command);
+    const { origin = "handwritten", ...meta } = metaOf(command);
+    const usage = [
+        cli,
+        ...path,
+        ...args.map((argument) => (argument.required ? `<${argument.name}>` : `[${argument.name}]`)),
+        options.length > 0 ? "[options]" : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return {
+        path,
+        name: command.name(),
+        ...(command.summary() ? { summary: command.summary() } : {}),
+        description: command.description(),
+        usage,
+        origin,
+        ...meta,
+        arguments: args,
+        options,
+        commands: visible(command).map((child) => describe(child, cli, path)),
+    };
+};
+// `addCommand(command, { hidden: true })` sets only this; Commander has no public getter for it.
+const visible = (command) => command.commands.filter((child) => !child._hidden);
+const describeArgument = (argument) => ({
+    name: argument.name(),
+    required: argument.required,
+    variadic: argument.variadic,
+    description: argument.description,
+    ...(argument.argChoices ? { choices: argument.argChoices } : {}),
+    ...(argument.defaultValue === undefined ? {} : { default: argument.defaultValue }),
+});
+const describeOption = (option) => {
+    const { conflictsWith = [], implied } = option;
+    return {
+        flags: option.flags,
+        description: option.description,
+        takesValue: option.required || option.optional,
+        mandatory: option.mandatory,
+        ...(option.argChoices ? { choices: option.argChoices } : {}),
+        ...(option.defaultValue === undefined ? {} : { default: option.defaultValue }),
+        ...(option.envVar ? { env: option.envVar } : {}),
+        ...(conflictsWith.length > 0 ? { conflicts: conflictsWith } : {}),
+        ...(implied ? { implies: implied } : {}),
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"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"}

package/dist/completion/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shell completion over the command registry: which word may come next, as data.
+ *
+ * It speaks the protocol of the shell scripts `@bomb.sh/tab` generates — the shell runs
+ * `<cli> complete -- <words>` and reads `value<TAB>description` lines ending in `:<directive>` —
+ * so a CLI prints those scripts with tab and answers the requests with this. Nothing here reads a
+ * terminal, a file or the network: the words come in, the suggestions go out, and where values come
+ * from (a local cache, a config file) is the CLI's business, handed in as `sources`.
+ */
+import type { CommandInfo, OptionInfo } from "../commands/index.js";
+export interface Suggestion {
+    value: string;
+    description: string;
+}
+/** Values for one argument or option. Called on every Tab, so it must be cheap and must not connect anywhere. */
+export type Values = () => readonly (string | Suggestion)[];
+export interface CompletionSources {
+    /** By argument name, as registered: `chat`, `person`. */
+    arguments?: Readonly<Record<string, Values>>;
+    /** By long option name without dashes: `chat` for `--chat <id>`. */
+    options?: Readonly<Record<string, Values>>;
+    /** Offered alongside the top-level commands — a profile name that may come first, say. */
+    firstWord?: Values;
+}
+export interface CompletionRequest {
+    commands: readonly CommandInfo[];
+    globalOptions?: readonly OptionInfo[];
+    /** Everything after `complete --`; the last word is the one being typed, `""` for a fresh one. */
+    words: readonly string[];
+    sources?: CompletionSources;
+}
+/** Tells the shell not to fall back to file names when nothing matched. */
+export declare const NO_FILE_COMPLETION = 4;
+export declare const suggest: ({ commands, globalOptions, words, sources }: CompletionRequest) => Suggestion[];
+/** The answer in the form the shell script reads. */
+export declare const formatSuggestions: (suggestions: readonly Suggestion[]) => string;
+//# sourceMappingURL=index.d.ts.map

package/dist/completion/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/completion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAgB,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,iHAAiH;AACjH,MAAM,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAA;AAE3D,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5C,oEAAoE;IACpE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1C,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;IAChC,aAAa,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,kGAAkG;IAClG,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAC5B;AAED,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,eAAO,MAAM,OAAO,GAAI,6CAAuD,iBAAiB,KAAG,UAAU,EA2C5G,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,GAAI,aAAa,SAAS,UAAU,EAAE,KAAG,MAC4C,CAAA"}

package/dist/completion/index.js

@@ -0,0 +1,87 @@
+/** Tells the shell not to fall back to file names when nothing matched. */
+export const NO_FILE_COMPLETION = 4;
+export const suggest = ({ commands, globalOptions = [], words, sources = {} }) => {
+    const typed = words.at(-1) ?? "";
+    const before = words.slice(0, -1);
+    let level = commands;
+    let current;
+    let positional = 0;
+    let pending;
+    for (const word of before) {
+        if (pending) {
+            pending = undefined;
+            continue;
+        }
+        if (word.startsWith("-")) {
+            const option = findOption(word, current, globalOptions);
+            if (option?.takesValue && !word.includes("="))
+                pending = option;
+            continue;
+        }
+        const child = level.find((command) => command.name === word);
+        if (child) {
+            current = child;
+            level = child.commands;
+            positional = 0;
+        }
+        else {
+            positional += 1;
+        }
+    }
+    const candidates = pending
+        ? optionValues(pending, sources)
+        : typed.startsWith("-")
+            ? typed.includes("=")
+                ? valuesAfterEquals(typed, current, globalOptions, sources)
+                : optionNames(current, globalOptions)
+            : [
+                ...level.filter((command) => command.state !== "deprecated").map(asSuggestion),
+                ...(current ? argumentValues(current.arguments, positional, sources) : []),
+                ...(current ? [] : resolve(sources.firstWord)),
+            ];
+    const unique = new Map(candidates.map((candidate) => [candidate.value, candidate]));
+    return [...unique.values()].filter(({ value }) => value.startsWith(typed));
+};
+/** The answer in the form the shell script reads. */
+export const formatSuggestions = (suggestions) => [...suggestions.map(({ value, description }) => `${value}\t${description}`), `:${NO_FILE_COMPLETION}`].join("\n");
+const asSuggestion = (command) => ({
+    value: command.name,
+    description: command.summary ?? command.description,
+});
+const longName = (option) => option.flags.match(/--([\w-]+)/)?.[1];
+const findOption = (word, current, globals) => {
+    const name = word.replace(/^-+/, "").split("=")[0];
+    const matches = (option) => longName(option) === name || option.flags.split(/[ ,]+/).includes(`-${name}`);
+    return [...(current?.options ?? []), ...globals].find(matches);
+};
+const optionNames = (current, globals) => [...(current?.options ?? []), ...globals].flatMap((option) => {
+    const name = longName(option);
+    return name ? [{ value: `--${name}`, description: option.description }] : [];
+});
+/** `--kind <dialog|group|channel>`: Commander does not know these as choices, but the flags say them. */
+const inlineChoices = (flags) => flags.match(/<([^>]*\|[^>]*)>/)?.[1]?.split("|") ?? [];
+const optionValues = (option, sources) => {
+    const name = longName(option);
+    return [
+        ...[...(option.choices ?? []), ...inlineChoices(option.flags)].map((value) => ({ value, description: "" })),
+        ...resolve(name ? sources.options?.[name] : undefined),
+    ];
+};
+const valuesAfterEquals = (typed, current, globals, sources) => {
+    const [flag] = typed.split("=");
+    const option = findOption(flag ?? "", current, globals);
+    if (!option?.takesValue)
+        return [];
+    return optionValues(option, sources).map(({ value, description }) => ({ value: `${flag}=${value}`, description }));
+};
+const argumentValues = (args, position, sources) => {
+    const argument = args[position] ?? (args.at(-1)?.variadic ? args.at(-1) : undefined);
+    if (!argument)
+        return [];
+    return [
+        ...(argument.choices ?? []).map((value) => ({ value, description: "" })),
+        ...resolve(sources.arguments?.[argument.name]),
+    ];
+};
+const resolve = (values) => (values?.() ?? []).map((value) => (typeof value === "string" ? { value, description: "" } : value));
+//# sourceMappingURL=index.js.map

package/dist/completion/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/completion/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leemour/cli-core",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "MIT",
   "author": "Viacheslav Ptsarev",
@@ -30,6 +30,14 @@
     "./http": {
       "types": "./dist/http/index.d.ts",
       "default": "./dist/http/index.js"
+    },
+    "./commands": {
+      "types": "./dist/commands/index.d.ts",
+      "default": "./dist/commands/index.js"
+    },
+    "./completion": {
+      "types": "./dist/completion/index.d.ts",
+      "default": "./dist/completion/index.js"
     }
   },
   "scripts": {
@@ -46,8 +54,8 @@
   },
   "dependencies": {
     "cli-table3": "^0.6.5",
-    "picocolors": "^1.1.1",
     "env-paths": "^4.0.0",
+    "picocolors": "^1.1.1",
     "pino": "^10.3.1",
     "valibot": "^1.5.0"
   },
@@ -57,11 +65,20 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
     "@types/node": "^22.10.2",
+    "commander": "^15.0.0",
+    "lefthook": "^2.1.8",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
-    "lefthook": "^2.1.8"
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "commander": ">=15"
+  },
+  "peerDependenciesMeta": {
+    "commander": {
+      "optional": true
+    }
   }
 }