@wirecat/cli-base 0.21.0 → 0.23.0

package/README.md

@@ -46,16 +46,17 @@ streams.stderr // []
 | `paths` | config, state and cache in the XDG layout on Linux and macOS (`~/.config`, `~/.local/share`, `~/.cache`) and the `AppData` one on Windows, each overridable by environment variable; `migrateLegacyMacPaths` moves an older release's `~/Library` folders once |
 | `config` | JSON config loading that names the bad field, and an atomic write that locks the directory down |
 | `credentials` | environment → keyring → file, warning once and falling through when the keyring refuses |
-| `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 |
+| `logging` | `createRecordLog`: one `LogRecord` per JSON line (OpenTelemetry field names, flat), secrets redacted by field name at any depth; 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 |
+| `/commands` | the command registry: `describeProgram`, `annotate`, `flatten`, `refuseJoinedPath`, and `commandsDocument` — the one `commands --json` shape, with its schema — see below |
 | `/completion` | shell completion over the registry: `suggest`, `formatSuggestions` — see below |
 | `/update` | keeping an install current: `installerOf`, `updateCommand`, `latestVersion`, `mayNotify`, `updateNotice`, `runUpdate` — see below |
 | `/codegen` | build time: an official API description → types, Valibot schemas, an operation manifest and a coverage page — see below |
 | `/release` | release time: `releaseCheck` and the checks it runs — changelog shape, links, package contents, version in step — see below |
 | `/skill` | the CLI's SKILL.md for coding agents: `skillCommand` (`show`, `install`), `skillHint`, `skillResource` — see below |
 | `/mcp` | local stdio MCP setup for Codex and Claude Code, plus a read-only handshake and tool-list probe |
+| `/standards` | the registries the standard is made of — vocabulary, output envelope, error object and reasons, next steps, log record, lint rules — as Valibot schemas that also emit JSON Schema 2020-12 |
 
 **Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
 seam live in `@wirecat/cli-base/http`, so a CLI that speaks a socket never depends on a stack it
@@ -112,6 +113,11 @@ Each option says whether it `takesValue` and, separately, whether it is `mandato
 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`.
 
+`refuseJoinedPath(program, args)` throws a `validation_error` when a command path arrived as one
+argument (`"projects add" --help`, what a zsh loop over `$c` passes), naming the words to type.
+Commander would print the root help instead; call it on the words before `parseAsync`, after a
+leading profile word if the CLI takes one.
+
 **Shell completion is `@wirecat/cli-base/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,
@@ -304,6 +310,14 @@ extends:
 | `scripts/docs-check.ts` | `cli-dev docs-check --rules scripts/release/checks.ts`, or `--ids CLI,MAX` with the English defaults |
 | `scripts/test-matrix.ts` | `cli-dev test-matrix --program dist/program.js --untested scripts/test-matrix-untested.ts --name max [--check]` |
 
+| — | `cli-dev lint --cli dist/bin.js` (or `--commands <file>`): the command tree against the standard |
+
+`cli-dev lint` reads `<cli> commands --json`, refuses a document not in `commandsDocument`'s shape, and
+judges it by `LINT_RULES` and `VOCABULARY` from `/standards`. Known violations live in
+`lint/baseline/<rule-id>.json`, one file per rule, and may only shrink: an entry with no violation left
+fails the run. `--write-baseline` rewrites those files to today's violations. Permanent exceptions go in
+`lint/overrides.json` — `[{ "rule", "target", "reason" }]` — and more than `--budget` (10) of them fails.
+
 `--rules` names a module exporting `CHANGELOG` and `docsRules(root)`; `--program` one exporting
 `createProgram`; `--untested` one exporting `UNTESTED`. A TypeScript module loads on Node 24 as it is.
 

package/dist/commands/document.d.ts

@@ -0,0 +1,72 @@
+import type { Command } from "commander";
+import * as v from "valibot";
+import { type CommandInfo, type OptionInfo } from "./index.js";
+/**
+ * What `<cli> commands --json` prints, in every CLI on cli-base. `scope` and `inheritedOptions` are
+ * there only when one command path was asked for. Nothing else at the top: `cli-dev lint` refuses it.
+ */
+export declare const commandsDocumentSchema: v.StrictObjectSchema<{
+    readonly cli: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>]>;
+    readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>]>;
+    /** The major version of the JSON the CLI's commands print. */
+    readonly contract: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly description: v.StringSchema<undefined>;
+    readonly globalOptions: v.ArraySchema<v.ObjectSchema<{
+        readonly flags: v.StringSchema<undefined>;
+        readonly description: v.StringSchema<undefined>;
+        readonly takesValue: v.BooleanSchema<undefined>;
+        readonly mandatory: v.BooleanSchema<undefined>;
+        readonly choices: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly default: v.OptionalSchema<v.UnknownSchema, undefined>;
+        readonly env: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly conflicts: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly implies: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly scope: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly inheritedOptions: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly path: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        readonly options: v.ArraySchema<v.ObjectSchema<{
+            readonly flags: v.StringSchema<undefined>;
+            readonly description: v.StringSchema<undefined>;
+            readonly takesValue: v.BooleanSchema<undefined>;
+            readonly mandatory: v.BooleanSchema<undefined>;
+            readonly choices: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly default: v.OptionalSchema<v.UnknownSchema, undefined>;
+            readonly env: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly conflicts: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly implies: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
+    readonly commands: v.ArraySchema<v.GenericSchema<CommandInfo>, undefined>;
+    readonly exitCodes: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>, undefined>;
+}, undefined>;
+export interface CommandsDocument {
+    cli: string;
+    version: string;
+    contract: number;
+    description: string;
+    globalOptions: OptionInfo[];
+    scope?: string[];
+    inheritedOptions?: {
+        path: string[];
+        options: OptionInfo[];
+    }[];
+    commands: CommandInfo[];
+    exitCodes: Record<string, number>;
+}
+export declare const commandsDocumentJsonSchema: () => import("@valibot/to-json-schema").JsonSchema;
+export declare const parseCommandsDocument: (value: unknown) => {
+    document: CommandsDocument;
+    problems?: undefined;
+} | {
+    document?: undefined;
+    problems: string[];
+};
+export interface CommandsDocumentAbout {
+    cli: string;
+    version: string;
+    contract: number;
+}
+/** The whole tree; a CLI that answers `commands <path>` adds `scope` and `inheritedOptions` itself. */
+export declare const commandsDocument: (root: Command, about: CommandsDocumentAbout) => CommandsDocument;
+//# sourceMappingURL=document.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/commands/document.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAG5B,OAAO,EAAE,KAAK,WAAW,EAAoC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAwChG;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;IAGjC,8DAA8D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAQ9D,CAAA;AAEF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,UAAU,EAAE,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,gBAAgB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,EAAE,CAAA;IAC9D,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED,eAAO,MAAM,0BAA0B,oDAA6E,CAAA;AAEpH,eAAO,MAAM,qBAAqB,UACzB,OAAO,KACb;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAGnG,CAAA;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,uGAAuG;AACvG,eAAO,MAAM,gBAAgB,SAAU,OAAO,SAAS,qBAAqB,KAAG,gBAQ7E,CAAA"}

package/dist/commands/document.js

@@ -0,0 +1,71 @@
+import * as v from "valibot";
+import { EXIT_CODES, GENERIC_FAILURE } from "../exit-codes.js";
+import { issuesOf, jsonSchemaOf } from "../standards/registry.js";
+import { describeOptions, describeProgram } from "./index.js";
+const argumentInfoSchema = v.object({
+    name: v.string(),
+    required: v.boolean(),
+    variadic: v.boolean(),
+    description: v.string(),
+    choices: v.optional(v.array(v.string())),
+    default: v.optional(v.unknown()),
+});
+const optionInfoSchema = v.object({
+    flags: v.string(),
+    description: v.string(),
+    takesValue: v.boolean(),
+    mandatory: v.boolean(),
+    choices: v.optional(v.array(v.string())),
+    default: v.optional(v.unknown()),
+    env: v.optional(v.string()),
+    conflicts: v.optional(v.array(v.string())),
+    implies: v.optional(v.record(v.string(), v.unknown())),
+});
+const commandInfoSchema = v.object({
+    path: v.array(v.string()),
+    name: v.string(),
+    summary: v.optional(v.string()),
+    description: v.string(),
+    usage: v.string(),
+    origin: v.picklist(["handwritten", "generated"]),
+    operationId: v.optional(v.string()),
+    mutates: v.optional(v.boolean()),
+    local: v.optional(v.boolean()),
+    state: v.optional(v.picklist(["beta", "deprecated"])),
+    examples: v.optional(v.array(v.string())),
+    arguments: v.array(argumentInfoSchema),
+    options: v.array(optionInfoSchema),
+    commands: v.array(v.lazy(() => commandInfoSchema)),
+});
+/**
+ * What `<cli> commands --json` prints, in every CLI on cli-base. `scope` and `inheritedOptions` are
+ * there only when one command path was asked for. Nothing else at the top: `cli-dev lint` refuses it.
+ */
+export const commandsDocumentSchema = v.strictObject({
+    cli: v.pipe(v.string(), v.nonEmpty()),
+    version: v.pipe(v.string(), v.nonEmpty()),
+    /** The major version of the JSON the CLI's commands print. */
+    contract: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    description: v.string(),
+    globalOptions: v.array(optionInfoSchema),
+    scope: v.optional(v.array(v.string())),
+    inheritedOptions: v.optional(v.array(v.object({ path: v.array(v.string()), options: v.array(optionInfoSchema) }))),
+    commands: v.array(commandInfoSchema),
+    exitCodes: v.record(v.string(), v.pipe(v.number(), v.integer())),
+});
+export const commandsDocumentJsonSchema = () => jsonSchemaOf(commandsDocumentSchema, { command: commandInfoSchema });
+export const parseCommandsDocument = (value) => {
+    const parsed = v.safeParse(commandsDocumentSchema, value);
+    return parsed.success ? { document: parsed.output } : { problems: issuesOf(parsed.issues) };
+};
+/** The whole tree; a CLI that answers `commands <path>` adds `scope` and `inheritedOptions` itself. */
+export const commandsDocument = (root, about) => ({
+    cli: about.cli,
+    version: about.version,
+    contract: about.contract,
+    description: root.description(),
+    globalOptions: describeOptions(root),
+    commands: describeProgram(root),
+    exitCodes: { ok: 0, generic_failure: GENERIC_FAILURE, ...EXIT_CODES },
+});
+//# sourceMappingURL=document.js.map

package/dist/commands/document.js.map

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

package/dist/commands/index.d.ts

@@ -72,5 +72,12 @@ 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[];
+export { type CommandsDocument, type CommandsDocumentAbout, commandsDocument, commandsDocumentJsonSchema, commandsDocumentSchema, parseCommandsDocument, } from "./document.js";
 export { COMMANDS_PAGE_LABELS, type CommandsPage, type CommandsPageLabels, type CommandsPageText, commandsPage, } from "./page.js";
+/**
+ * Refuses a command path that arrived as one argument — `"projects add" --help`, what a zsh loop over
+ * `$c` passes. Commander settles `--help` for an unknown word before any hook runs and prints the root
+ * help, so the words are checked before parsing. Pass the words after a leading profile, if any.
+ */
+export declare const refuseJoinedPath: (root: Command, args: readonly string[]) => void;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yGAAyG;IACzG,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,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,OAAO,CAAA;IACf,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,WAAW,CAAC,QAAQ,WAAW,KAAG,CAG3E,CAAA;AAED,eAAO,MAAM,MAAM,YAAa,OAAO,KAAG,WAAwC,CAAA;AAElF,eAAO,MAAM,eAAe,SAAU,OAAO,KAAG,WAAW,EACK,CAAA;AAEhE,eAAO,MAAM,eAAe,YAAa,OAAO,KAAG,UAAU,EACW,CAAA;AAExE,eAAO,MAAM,OAAO,aAAc,SAAS,WAAW,EAAE,KAAG,WAAW,EACE,CAAA;AA8DxE,OAAO,EACL,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,YAAY,GACb,MAAM,WAAW,CAAA"}
+{"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;AAG1D,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,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yGAAyG;IACzG,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,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,OAAO,CAAA;IACf,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,WAAW,CAAC,QAAQ,WAAW,KAAG,CAG3E,CAAA;AAED,eAAO,MAAM,MAAM,YAAa,OAAO,KAAG,WAAwC,CAAA;AAElF,eAAO,MAAM,eAAe,SAAU,OAAO,KAAG,WAAW,EACK,CAAA;AAEhE,eAAO,MAAM,eAAe,YAAa,OAAO,KAAG,UAAU,EACW,CAAA;AAExE,eAAO,MAAM,OAAO,aAAc,SAAS,WAAW,EAAE,KAAG,WAAW,EACE,CAAA;AA8DxE,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,YAAY,GACb,MAAM,WAAW,CAAA;AAElB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,SAAU,OAAO,QAAQ,SAAS,MAAM,EAAE,KAAG,IAgBzE,CAAA"}

package/dist/commands/index.js

@@ -1,3 +1,4 @@
+import { CliError } from "../errors.js";
 const labels = new WeakMap();
 /** Attaches what the tree cannot say. Repeated calls merge; the command is returned for chaining. */
 export const annotate = (command, meta) => {
@@ -58,5 +59,27 @@ const describeOption = (option) => {
         ...(implied ? { implies: implied } : {}),
     };
 };
+export { commandsDocument, commandsDocumentJsonSchema, commandsDocumentSchema, parseCommandsDocument, } from "./document.js";
 export { COMMANDS_PAGE_LABELS, commandsPage, } from "./page.js";
+/**
+ * Refuses a command path that arrived as one argument — `"projects add" --help`, what a zsh loop over
+ * `$c` passes. Commander settles `--help` for an unknown word before any hook runs and prints the root
+ * help, so the words are checked before parsing. Pass the words after a leading profile, if any.
+ */
+export const refuseJoinedPath = (root, args) => {
+    let command = root;
+    const path = [];
+    for (const arg of args) {
+        if (arg.startsWith("-"))
+            return;
+        const [first = "", ...rest] = arg.trim().split(/\s+/);
+        const next = command.commands.find((child) => child.name() === first || child.aliases().includes(first));
+        if (next === undefined)
+            return;
+        if (rest.length > 0)
+            throw new CliError("validation_error", `"${arg}" was given as one argument; run: ${[root.name(), ...path, first, ...rest].join(" ")}`);
+        path.push(first);
+        command = next;
+    }
+};
 //# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

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

package/dist/deadline.js

@@ -1,4 +1,4 @@
-import { CliError } from "./errors.js";
+import { CliError, isCliError } from "./errors.js";
 import { realSleep } from "./time.js";
 export const createDeadline = ({ timeoutMs, signal, sleep = realSleep } = {}) => {
     if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 2147483647))
@@ -13,13 +13,13 @@ export const createDeadline = ({ timeoutMs, signal, sleep = realSleep } = {}) =>
         timer.abort();
         signal?.removeEventListener("abort", onAbort);
     };
-    const onAbort = () => abort(signal?.reason instanceof CliError ? signal.reason : new CliError("cancelled", "command cancelled"));
+    const onAbort = () => abort(isCliError(signal?.reason) ? signal.reason : new CliError("cancelled", "command cancelled"));
     if (signal?.aborted)
         onAbort();
     else
         signal?.addEventListener("abort", onAbort, { once: true });
     const expire = () => abort(new CliError("timeout", "the command did not finish before its deadline", {
-        reason: "command_timeout",
+        reason: "command.timed-out",
         timeoutMs,
         retryable: false,
     }));
@@ -68,7 +68,7 @@ export const createDeadline = ({ timeoutMs, signal, sleep = realSleep } = {}) =>
                     await running.catch((reason) => {
                         settled = reason;
                     });
-                    if (settled instanceof CliError && settled.code === "outcome_unknown")
+                    if (isCliError(settled) && settled.code === "outcome_unknown")
                         throw settled;
                     throw controller.signal.reason;
                 }

package/dist/deadline.js.map

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

package/dist/dev/lint.d.ts

@@ -0,0 +1,33 @@
+import type { CommandsDocument } from "../commands/document.js";
+import { type LintRule, type Override } from "../standards/lint.js";
+import type { Vocabulary } from "../standards/vocabulary.js";
+export interface Violation {
+    rule: string;
+    /** What the baseline and overrides name: `chats list`, `chats show <chat>`, `chats list --limit`, `--until`. */
+    target: string;
+    message: string;
+}
+/** Splits an example the way a shell would for the quoting examples use: '…', "…" and a backslash. */
+export declare const exampleWords: (line: string) => string[];
+export declare const lintRuleIds: () => string[];
+/** Every violation, one per rule and target, sorted. Generated commands keep the names of the API they mirror. */
+export declare const lintCommands: (document: CommandsDocument, vocabulary: Vocabulary, rules?: readonly LintRule[]) => Violation[];
+export interface Judgement {
+    /** Not in the baseline and not overridden: these fail the run. */
+    fresh: Violation[];
+    baselined: number;
+    overridden: number;
+    /** Baseline or override entries with no violation left: the list only shrinks, so these fail too. */
+    stale: {
+        rule: string;
+        target: string;
+        in: "baseline" | "overrides";
+    }[];
+    /** Rule ids named by a baseline file or an override that no rule has. */
+    unknownRules: string[];
+    overBudget: boolean;
+}
+export declare const judge: (violations: readonly Violation[], baseline: Readonly<Record<string, readonly string[]>>, overrides: readonly Override[], budget: number, rules?: readonly LintRule[]) => Judgement;
+/** What `--write-baseline` writes: per rule, the targets no override covers. A rule with none gets no file. */
+export declare const baselineOf: (violations: readonly Violation[], overrides: readonly Override[], rules?: readonly LintRule[]) => Record<string, string[]>;
+//# sourceMappingURL=lint.d.ts.map

package/dist/dev/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/dev/lint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE/D,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAE5D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,gHAAgH;IAChH,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AA+BD,sGAAsG;AACtG,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAM,EAM/C,CAAA;AAmMH,eAAO,MAAM,WAAW,QAAO,MAAM,EAAyB,CAAA;AAE9D,kHAAkH;AAClH,eAAO,MAAM,YAAY,aACb,gBAAgB,cACd,UAAU,UACf,SAAS,QAAQ,EAAE,KACzB,SAAS,EAUX,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,qGAAqG;IACrG,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,UAAU,GAAG,WAAW,CAAA;KAAE,EAAE,CAAA;IACvE,yEAAyE;IACzE,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,eAAO,MAAM,KAAK,eACJ,SAAS,SAAS,EAAE,YACtB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,aAC1C,SAAS,QAAQ,EAAE,UACtB,MAAM,UACP,SAAS,QAAQ,EAAE,KACzB,SA4BF,CAAA;AAED,+GAA+G;AAC/G,eAAO,MAAM,UAAU,eACT,SAAS,SAAS,EAAE,aACrB,SAAS,QAAQ,EAAE,UACvB,SAAS,QAAQ,EAAE,KACzB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAWzB,CAAA"}

package/dist/dev/lint.js

@@ -0,0 +1,257 @@
+import { LINT_RULES } from "../standards/lint.js";
+const SUMMARY_LIMIT = 80;
+const EXAMPLES_MIN = 1;
+const EXAMPLES_MAX = 3;
+/** STANDARD's search hierarchy: `search <resource>`, and `search all` for every resource. */
+const SEARCH_ROOT = "search";
+const SEARCH_EVERYTHING = "all";
+const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const walk = (commands) => commands.flatMap((one) => [one, ...walk(one.commands)]);
+const longName = (flags) => flags.split(/[ ,|]+/).find((part) => part.startsWith("--")) ?? flags;
+/** A flag's kind of value: its value name, or `switch`. Two kinds under one name are two meanings. */
+const kindOf = (option) => {
+    if (!option.takesValue)
+        return "switch";
+    return option.flags.match(/[<[]([^>\]]+)[>\]]/)?.[1]?.toLowerCase() ?? "value";
+};
+const summaryOf = (command) => (command.summary ?? command.description.split("\n")[0] ?? "").trim();
+const label = (command) => command.path.join(" ");
+const handwrittenLeaves = (document) => walk(document.commands).filter((command) => command.commands.length === 0 && command.origin === "handwritten");
+/** Splits an example the way a shell would for the quoting examples use: '…', "…" and a backslash. */
+export const exampleWords = (line) => [...line.matchAll(/(?:'[^']*'|"(?:\\.|[^"\\])*"|\\.|[^\s'"\\])+/g)].map(([word]) => word.replace(/'([^']*)'|"((?:\\.|[^"\\])*)"|\\(.)/g, (_, single, double, escaped) => single ?? escaped ?? double.replace(/\\(.)/g, "$1")));
+const BUILT_IN = ["-h", "--help"];
+const optionNames = (option) => option.flags.split(/[ ,|]+/).filter((part) => part.startsWith("-"));
+/** Why an example would not parse against the command it is listed under, or undefined when it would. */
+const faultOf = (example, command, ancestors, document) => {
+    const words = exampleWords(example);
+    if (words[0] !== document.cli)
+        return `does not start with "${document.cli}"`;
+    const known = [document.globalOptions, ...ancestors.map((one) => one.options), command.options].flat();
+    const find = (word) => known.find((option) => optionNames(option).includes(word));
+    const option = (at) => {
+        const word = words[at] ?? "";
+        const [name = word, inline] = word.startsWith("--") ? word.split(/=(.*)/s) : [word];
+        if (BUILT_IN.includes(name))
+            return at + 1;
+        const found = find(name);
+        if (!found)
+            return `${command.path.join(" ")} has no option ${name}`;
+        if (!found.takesValue || inline !== undefined)
+            return at + 1;
+        const optional = /\[[^\]]*\]/.test(found.flags);
+        if (/\.\.\.[>\]]/.test(found.flags)) {
+            let next = at + 1;
+            while (next < words.length && !words[next]?.startsWith("-"))
+                next += 1;
+            return next;
+        }
+        if (optional)
+            return words[at + 1] === undefined || words[at + 1]?.startsWith("-") ? at + 1 : at + 2;
+        return words[at + 1] === undefined ? `${name} needs a value` : at + 2;
+    };
+    let at = 1;
+    let profile = false;
+    while (words[at] !== command.path[0]) {
+        if (at >= words.length)
+            return `does not run ${command.path.join(" ")}`;
+        if (words[at]?.startsWith("-")) {
+            const next = option(at);
+            if (typeof next === "string")
+                return next;
+            at = next;
+        }
+        else if (!profile) {
+            profile = true;
+            at += 1;
+        }
+        else
+            return `does not run ${command.path.join(" ")}`;
+    }
+    for (const segment of command.path) {
+        if (words[at] !== segment)
+            return `does not run ${command.path.join(" ")}`;
+        at += 1;
+    }
+    let positional = 0;
+    let rest = false;
+    while (at < words.length) {
+        const word = words[at] ?? "";
+        if (!rest && word === "--") {
+            rest = true;
+            at += 1;
+        }
+        else if (!rest && word.startsWith("-") && word.length > 1) {
+            const next = option(at);
+            if (typeof next === "string")
+                return next;
+            at = next;
+        }
+        else {
+            positional += 1;
+            at += 1;
+        }
+    }
+    const required = command.arguments.filter((argument) => argument.required).length;
+    const variadic = command.arguments.some((argument) => argument.variadic);
+    if (positional < required)
+        return `${command.path.join(" ")} needs ${required} argument(s); the example gives ${positional}`;
+    if (!variadic && positional > command.arguments.length)
+        return `${command.path.join(" ")} takes ${command.arguments.length} argument(s); the example gives ${positional}`;
+    return undefined;
+};
+const withAncestors = (commands, above = []) => commands.flatMap((one) => [
+    [one, above],
+    ...withAncestors(one.commands, [...above, one]),
+]);
+const CHECKS = {
+    "unknown-verb": (document, vocabulary) => {
+        const allowed = new Set([
+            ...vocabulary.verbs.map((entry) => entry.word),
+            ...vocabulary.views.map((entry) => entry.word),
+        ]);
+        const roots = new Set(vocabulary.roots.map((entry) => entry.word));
+        const searchable = new Set([...vocabulary.nouns.map((entry) => entry.word), SEARCH_EVERYTHING]);
+        const searchLeaf = (command) => command.path.at(-2) === SEARCH_ROOT && searchable.has(command.name);
+        return handwrittenLeaves(document)
+            .filter((command) => !allowed.has(command.name) && !(command.path.length === 1 && roots.has(command.name)))
+            .filter((command) => !searchLeaf(command))
+            .map((command) => ({
+            target: label(command),
+            message: `"${command.name}" is not a verb or view noun in the vocabulary`,
+        }));
+    },
+    "unknown-resource": (document, vocabulary) => {
+        const nouns = new Set(vocabulary.nouns.map((entry) => entry.word));
+        const roots = new Set(vocabulary.roots.map((entry) => entry.word));
+        const verbs = new Set(vocabulary.verbs.map((entry) => entry.word));
+        return walk(document.commands)
+            .filter((command) => command.commands.length > 0 && command.origin === "handwritten")
+            .filter((command) => !nouns.has(command.name) && !roots.has(command.name))
+            .map((command) => ({
+            target: label(command),
+            message: verbs.has(command.name)
+                ? `the group "${command.name}" is named with a verb; a group is a resource`
+                : `"${command.name}" is not a resource in the vocabulary: a plural, a registered singular, or a root word`,
+        }));
+    },
+    "flag-two-meanings": (document, vocabulary) => {
+        const registered = new Map(vocabulary.flags.map((flag) => [flag.name, flag.value?.slice(1, -1).toLowerCase() ?? "switch"]));
+        const uses = new Map();
+        const note = (option, where) => {
+            const name = longName(option.flags);
+            const kinds = uses.get(name) ?? new Map();
+            kinds.set(kindOf(option), [...(kinds.get(kindOf(option)) ?? []), where]);
+            uses.set(name, kinds);
+        };
+        for (const option of document.globalOptions)
+            note(option, "every command");
+        for (const command of walk(document.commands))
+            if (command.origin === "handwritten")
+                for (const option of command.options)
+                    note(option, label(command));
+        const found = [];
+        for (const [name, kinds] of [...uses].sort(([a], [b]) => byText(a, b))) {
+            const expected = registered.get(name);
+            const off = expected === undefined ? [] : [...kinds.keys()].filter((kind) => kind !== expected);
+            if (kinds.size < 2 && off.length === 0)
+                continue;
+            const described = [...kinds]
+                .map(([kind, where]) => `${kind === "switch" ? "a switch" : `<${kind}>`} in ${where.slice(0, 3).join(", ")}`)
+                .join("; ");
+            found.push({
+                target: name,
+                message: expected === undefined
+                    ? `${name} has ${kinds.size} meanings: ${described}`
+                    : `${name} is ${expected === "switch" ? "a switch" : `<${expected}>`} in the vocabulary, but: ${described}`,
+            });
+        }
+        return found;
+    },
+    "missing-command-help": (document) => walk(document.commands)
+        .filter((command) => summaryOf(command) === "")
+        .map((command) => ({ target: label(command), message: "no summary or description" })),
+    "command-help-too-long": (document) => walk(document.commands)
+        .filter((command) => command.origin === "handwritten" && summaryOf(command).length > SUMMARY_LIMIT)
+        .map((command) => ({
+        target: label(command),
+        message: `summary is ${summaryOf(command).length} characters; at most ${SUMMARY_LIMIT}`,
+    })),
+    "command-example-count": (document) => handwrittenLeaves(document)
+        .filter((command) => {
+        const count = command.examples?.length ?? 0;
+        return count < EXAMPLES_MIN || count > EXAMPLES_MAX;
+    })
+        .map((command) => ({
+        target: label(command),
+        message: `${command.examples?.length ?? 0} examples; give ${EXAMPLES_MIN} to ${EXAMPLES_MAX}`,
+    })),
+    "faulty-help-example-parameters": (document) => withAncestors(document.commands)
+        .filter(([command]) => command.commands.length === 0 && command.origin === "handwritten")
+        .flatMap(([command, ancestors]) => (command.examples ?? []).flatMap((example) => {
+        const fault = faultOf(example, command, ancestors, document);
+        return fault === undefined ? [] : [{ target: `${label(command)}: ${example}`, message: fault }];
+    })),
+    "missing-argument-help": (document) => walk(document.commands).flatMap((command) => command.arguments
+        .filter((argument) => argument.description.trim() === "")
+        .map((argument) => ({ target: `${label(command)} <${argument.name}>`, message: "argument not described" }))),
+    "missing-option-help": (document) => [
+        ...document.globalOptions
+            .filter((option) => option.description.trim() === "")
+            .map((option) => ({ target: longName(option.flags), message: "global option not described" })),
+        ...walk(document.commands).flatMap((command) => command.options
+            .filter((option) => option.description.trim() === "")
+            .map((option) => ({ target: `${label(command)} ${longName(option.flags)}`, message: "option not described" }))),
+    ],
+};
+export const lintRuleIds = () => Object.keys(CHECKS);
+/** Every violation, one per rule and target, sorted. Generated commands keep the names of the API they mirror. */
+export const lintCommands = (document, vocabulary, rules = LINT_RULES) => {
+    const seen = new Set();
+    return rules.flatMap((rule) => {
+        const check = CHECKS[rule.id];
+        if (!check)
+            throw new Error(`lint rule "${rule.id}" has no check`);
+        return check(document, vocabulary)
+            .filter(({ target }) => !seen.has(`${rule.id} ${target}`) && seen.add(`${rule.id} ${target}`))
+            .map((found) => ({ rule: rule.id, ...found }))
+            .sort((a, b) => byText(a.target, b.target));
+    });
+};
+export const judge = (violations, baseline, overrides, budget, rules = LINT_RULES) => {
+    const ids = new Set(rules.map((rule) => rule.id));
+    const key = (rule, target) => `${rule} ${target}`;
+    const overridden = new Set(overrides.map((entry) => key(entry.rule, entry.target)));
+    const baselined = new Set(Object.entries(baseline).flatMap(([rule, targets]) => targets.map((t) => key(rule, t))));
+    const found = new Set(violations.map((violation) => key(violation.rule, violation.target)));
+    const open = violations.filter((violation) => !overridden.has(key(violation.rule, violation.target)));
+    const fresh = open.filter((violation) => !baselined.has(key(violation.rule, violation.target)));
+    return {
+        fresh,
+        baselined: open.length - fresh.length,
+        overridden: violations.length - open.length,
+        stale: [
+            ...Object.entries(baseline).flatMap(([rule, targets]) => targets
+                .filter((target) => !found.has(key(rule, target)) || overridden.has(key(rule, target)))
+                .map((target) => ({ rule, target, in: "baseline" }))),
+            ...overrides
+                .filter((entry) => !found.has(key(entry.rule, entry.target)))
+                .map((entry) => ({ rule: entry.rule, target: entry.target, in: "overrides" })),
+        ],
+        unknownRules: [
+            ...new Set([...Object.keys(baseline), ...overrides.map((entry) => entry.rule)].filter((id) => !ids.has(id))),
+        ].sort(),
+        overBudget: overrides.length > budget,
+    };
+};
+/** What `--write-baseline` writes: per rule, the targets no override covers. A rule with none gets no file. */
+export const baselineOf = (violations, overrides, rules = LINT_RULES) => {
+    const overridden = new Set(overrides.map((entry) => `${entry.rule} ${entry.target}`));
+    return Object.fromEntries(rules.map((rule) => [
+        rule.id,
+        violations
+            .filter((violation) => violation.rule === rule.id && !overridden.has(`${violation.rule} ${violation.target}`))
+            .map((violation) => violation.target)
+            .sort(),
+    ]));
+};
+//# sourceMappingURL=lint.js.map