@leemour/cli-core 0.1.1 → 0.2.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.1.** Published on npm, used by `max-cli`. Both extraction steps have landed: the
+**Status: 0.2.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,7 @@ 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 |
 
 **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 +53,25 @@ 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`.
+
 **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`.
@@ -109,10 +129,18 @@ Raise `version` in `package.json` through a pull request, merge it, then on `mai
 bin/release
 ```
 
-It refuses a dirty tree, a branch other than `main` and a version npm already has, runs every
-check, publishes with the npm token from the keyring (`secret-tool`, service `npm`, account
-`leemour`) without printing it, and tags `v<version>` only once npm shows the new version. The
-token must be allowed to write `@leemour/cli-core`, not only `@leemour/max-cli`.
+It refuses a dirty tree, a branch other than `main`, a `main` that is not pushed and a version npm
+already has, then starts [`release.yml`](.github/workflows/release.yml) and follows it. The workflow
+runs every check, publishes through npm's
+[trusted publishing](https://docs.npmjs.com/trusted-publishers/) — no npm token in GitHub, and npm
+attaches provenance — and tags `v<version>` only once npm shows the new version.
+
+npm trusts the workflow **by file name**: the package's Trusted Publisher settings on npmjs.com name
+`leemour` / `cli-core` / `release.yml`. Rename the file and publishing stops until they are updated.
+
+`bin/release --local` is the fallback: it runs the same checks here and publishes with the npm token
+from the keyring (`secret-tool`, service `npm`, account `leemour`) without printing it. The token
+must be allowed to write `@leemour/cli-core`, not only `@leemour/max-cli`.
 
 ## Licence
 

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,59 @@
+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) => root.commands.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: command.commands.map((child) => describe(child, cli, path)),
+    };
+};
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leemour/cli-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "MIT",
   "author": "Viacheslav Ptsarev",
@@ -12,6 +12,7 @@
   "engines": {
     "node": ">=22"
   },
+  "packageManager": "pnpm@11.20.0",
   "files": [
     "dist",
     "README.md",
@@ -29,12 +30,28 @@
     "./http": {
       "types": "./dist/http/index.d.ts",
       "default": "./dist/http/index.js"
+    },
+    "./commands": {
+      "types": "./dist/commands/index.d.ts",
+      "default": "./dist/commands/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --force --emitDeclarationOnly",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke:bun": "bun run scripts/smoke.ts",
+    "prepare": "lefthook install || true",
+    "secrets:scan": "gitleaks git --no-banner --redact .",
+    "prepublishOnly": "pnpm build"
+  },
   "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"
   },
@@ -44,21 +61,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"
   },
-  "scripts": {
-    "build": "tsc --build",
-    "typecheck": "tsc --build --force --emitDeclarationOnly",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "smoke:bun": "bun run scripts/smoke.ts",
-    "secrets:scan": "gitleaks git --no-banner --redact ."
+  "peerDependencies": {
+    "commander": ">=15"
+  },
+  "peerDependenciesMeta": {
+    "commander": {
+      "optional": true
+    }
   }
-}
+}