stitchkit 0.93.0 → 0.94.1

package/dist/tools/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAgHT"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjF,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAgHT"}

package/dist/tools/cli/args-fields.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What each flag of a command should become: the kind of every field its
+ * schema declares, and the coercion from argv's strings to that kind. Every
+ * argv token is a string; the schema says what it should be.
+ */
+import { z } from 'zod';
+export type FieldKind = 'boolean' | 'number' | 'bigint' | 'date' | 'string' | 'enum' | 'array' | 'object' | 'other';
+export interface FieldInfo {
+    kind: FieldKind;
+    /** Element kind for an `array` field — drives per-element coercion. */
+    elementKind?: FieldKind;
+    /** A `number` field that only accepts integers — named in its coercion error. */
+    integer?: boolean;
+}
+/**
+ * Map a merged tool schema to per-field kind info — what each `--flag` should
+ * coerce to. Object members of unions and intersections contribute their
+ * fields too, so a boolean member of a union stays reachable as a bare flag; a
+ * scalar schema yields an empty map and every value is left as a string.
+ */
+export declare function describeSchemaFields(schema: z.ZodType | undefined): Map<string, FieldInfo>;
+/** Strict boolean for a RESERVED option — an unrecognised value is a usage error, never a silent `true`. */
+/** True for a value the reserved-boolean grammar already claims. */
+export declare function isReservedBoolWord(value: string): boolean;
+export declare function parseReservedBool(name: string, value: string): boolean;
+/** Best-effort coercion for a dotted-path leaf, where the schema type is unknown. */
+export declare function looseCoerce(value: string): unknown;
+/** Coerce the collected raw string value(s) for one field to its typed form. */
+export declare function coerceField(info: FieldInfo | undefined, values: string[], label: string): unknown;
+export declare function setNested(target: Record<string, unknown>, path: string[], value: unknown): void;
+//# sourceMappingURL=args-fields.d.ts.map

package/dist/tools/cli/args-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6ED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAKD,4GAA4G;AAC5G,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}

package/dist/tools/cli/args-route.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Whether the token after an option that expects a value is another option
+ * rather than that value: `--name`, `--name=value`, `--` itself, or a
+ * single-letter short form (`-f`, `-f=value`).
+ *
+ * Everything else that merely starts with `-` is the value — a negative
+ * number, a search pattern `-foo`. Rejecting those as "misplaced options" made
+ * ordinary values unpassable except inline, while the mistake it was meant to
+ * catch (`--grep --json`) is still caught: a long option is always an option.
+ */
+export declare function isOptionToken(token: string): boolean;
+/**
+ * Whether a free-standing token is an option rather than a positional: any
+ * long form, or `-` followed by a letter (`-f`, and `-n100`, which is refused
+ * as unknown rather than read as a value nobody meant).
+ *
+ * `-` followed by anything else is positional — a message body `- item`, a
+ * negative number, `-` for stdin — instead of an "Unknown option" the caller
+ * can only escape with `--`.
+ */
+export declare function looksLikeOption(token: string): boolean;
+export declare const VIEW_OPTIONS: Set<string>;
+export declare const RESERVED_CLI_OPTIONS: Set<string>;
+export interface CliLongOptionToken {
+    name: string;
+    value?: string;
+    inline: boolean;
+    globalKind?: 'boolean' | 'value';
+}
+/** One source of truth for long-option token shape and framework-global ownership. */
+export declare function classifyLongOptionToken(token: string): CliLongOptionToken | undefined;
+export interface CliArgvRoute {
+    command?: string;
+    commandArgv: string[];
+    topLevelHelp: boolean;
+    version: boolean;
+    /** `--help <substring>` — narrow the command list instead of printing it whole. */
+    helpFilter?: string;
+    error?: string;
+}
+export declare function routeCliArgv(argv: string[], defaultCommand?: string): CliArgvRoute;
+//# sourceMappingURL=args-route.d.ts.map

package/dist/tools/cli/args-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-route.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-route.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAGD,eAAO,MAAM,YAAY,aAA6D,CAAC;AAEvF,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAcrF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CA6GlF"}

package/dist/tools/cli/args-view.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A requested aggregate view over the result.
+ *
+ * `--by` always names the grouping field, in every form it appears in, so the
+ * grammar has one meaning rather than two: `--top 5 --by status` is the five
+ * largest groups of `status`, exactly as `--count-by status --top 5` is.
+ */
+export type CliResultView = {
+    kind: 'count';
+    field: string;
+    top?: number;
+} | {
+    kind: 'sum';
+    field: string;
+    by?: string;
+    top?: number;
+} | {
+    kind: 'records';
+    sort?: string;
+    ascending?: boolean;
+    top?: number;
+    table?: readonly string[];
+};
+/**
+ * Turn the raw view flags into one view, or refuse the combination.
+ *
+ * Refusing here rather than at emission time is the point: a caller who asked
+ * for two aggregates at once, or for `--by` with nothing to group, gets the
+ * message before the command runs, not a shape they did not ask for after it.
+ */
+export declare function resolveCliView(flags: ReadonlyMap<string, string>, ascending: boolean): CliResultView | undefined;
+//# sourceMappingURL=args-view.d.ts.map

package/dist/tools/cli/args-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-view.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-view.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,OAAO,GACjB,aAAa,GAAG,SAAS,CAmG3B"}

package/dist/tools/cli/args.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Turn a CLI `argv` slice into the flat argument object `executeToolMethod`
+ * parses — the CLI transport's front half, the counterpart of how the HTTP
+ * transport slices a `Request`.
+ *
+ * Two jobs the other transports never face:
+ *  1. **Reserved options.** `--json`, `--wait`, `--output-dir`, … are CLI
+ *     behaviour, not tool arguments — they are stripped before the rest is read
+ *     as tool args.
+ *  2. **String → typed coercion.** Every argv token is a string; the tool's Zod
+ *     schema says what each field should be. We coerce primitives here
+ *     (`--count 5` → `5`, `--flag` → `true`) and leave array / object values as
+ *     strings for `executeToolMethod`'s `coerceJson` pass (the same path the MCP
+ *     transport uses for an LLM's double-serialized JSON).
+ *
+ * The advertised schema is never mutated — coercion operates on the arguments,
+ * so a CLI call validates against the exact same contract schema an HTTP or MCP
+ * call does (ADR 0014 parity).
+ */
+import type { z } from 'zod';
+import { type CliResultView } from './args-view.js';
+/** CLI-behaviour flags, parsed out of argv before the tool arguments. */
+export interface CliRunOptions {
+    /** `--json` — emit compact success/error JSON records for scripts. */
+    json: boolean;
+    /** `--wait` — block-poll an async result to a terminal state. */
+    wait: boolean;
+    /** `--wait-timeout <seconds>` — override the poll timeout. */
+    waitTimeout?: number;
+    /** `--output-dir <dir>` — download result media into this directory. */
+    outputDir?: string;
+    /** `--quiet` — suppress non-essential stderr chatter. */
+    quiet: boolean;
+    /** `--dry-run` — print the resolved call instead of executing it. */
+    dryRun: boolean;
+    /** `--help` / `-h` — print usage for the command. */
+    help: boolean;
+    /** `--count-by` / `--sum` / `--top` / `--table` — aggregate instead of the collection. */
+    view?: CliResultView;
+}
+export interface ParsedCliArgs {
+    /** The flat tool-argument object handed to `executeToolMethod`. */
+    toolArgs: Record<string, unknown>;
+    /** The CLI-behaviour flags. */
+    options: CliRunOptions;
+}
+export declare function parseCliArgs(argv: string[], schema: z.ZodType | undefined, config?: {
+    allowUnknown?: boolean;
+    knownFields?: readonly string[];
+    optionAliases?: ReadonlyMap<string, string>;
+    positionals?: readonly string[];
+}): ParsedCliArgs;
+/** The application's own global options, lifted out of one invocation's argv. */
+export interface CliGlobalOptionsParse {
+    /** argv with the application-global tokens removed, ready for routing. */
+    argv: string[];
+    /** The validated values, as the application's own schema types them. */
+    globals: Record<string, unknown>;
+}
+/**
+ * Lift the APPLICATION's global options out of argv, wherever they stand.
+ *
+ * These are not arguments of any operation: which identity key to use, which
+ * checkout a call speaks for, which profile. They belong to the invocation, so
+ * they may precede the command name as easily as follow it — and a command's
+ * own parser must never see them, or an app-global would read as an unknown
+ * flag on every operation that does not declare it.
+ *
+ * Stripping them BEFORE routing is what keeps this one grammar rather than two:
+ * `routeCliArgv` then sees a command where a command is, `parseCliArgs` sees
+ * only operation arguments, and `passthrough` cannot swallow an app-global into
+ * a freeform bag. The token shape is the same `classifyLongOptionToken` the
+ * framework's own globals use, so `--root /x`, `--root=/x` and a bare boolean
+ * `--verbose` all behave as they do everywhere else.
+ *
+ * `--` ends the sweep: past it every token is a literal value, so a positional
+ * that happens to read as `--root` survives intact.
+ */
+export declare function extractCliGlobalOptions(argv: readonly string[], schema: z.ZodObject | undefined): CliGlobalOptionsParse;
+//# sourceMappingURL=args.d.ts.map

package/dist/tools/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgB7B,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAkRD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAUf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAgDvB"}

package/dist/tools/cli/argument-error.d.ts

@@ -0,0 +1,5 @@
+/** A command line that cannot be read: an unknown option, a missing value, a value of the wrong kind. */
+export declare class CliArgumentError extends Error {
+    name: string;
+}
+//# sourceMappingURL=argument-error.d.ts.map

package/dist/tools/cli/argument-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-error.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/argument-error.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;CACpC"}

package/dist/tools/cli/checkpoint.d.ts

@@ -0,0 +1,24 @@
+/** One recorded line: what it was, and what running it produced. */
+export interface CliCheckpointEntry {
+    digest: string;
+    answer: unknown;
+}
+export interface CliCheckpoint {
+    entries: Record<string, CliCheckpointEntry>;
+    digestOf(line: {
+        command: string;
+        args: Record<string, unknown>;
+    }): string;
+    record(id: string, digest: string, answer: unknown): void;
+}
+/**
+ * Read a checkpoint, or start an empty one.
+ *
+ * A file that cannot be parsed starts an empty checkpoint rather than throwing:
+ * the alternative is a batch that refuses to run because of a corrupted record
+ * of a previous run, which is worse than doing the work again.
+ */
+export declare function readCliCheckpoint(path: string): CliCheckpoint;
+/** Persist the checkpoint atomically. */
+export declare function writeCliCheckpoint(path: string, checkpoint: CliCheckpoint): void;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/tools/cli/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/checkpoint.ts"],"names":[],"mappings":"AAmBA,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM,CAAC;IAC3E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3D;AAYD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAgB7D;AAED,yCAAyC;AACzC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,GAAG,IAAI,CAIhF"}

package/dist/tools/cli/command.d.ts

@@ -0,0 +1,70 @@
+import type { ZodObject, ZodType, z } from 'zod';
+import { type ToolResult } from '../execute-result.js';
+import type { CliRunOptions } from './args.js';
+import type { CliWriters } from './format.js';
+export interface CliCommandContext<TInput extends ZodObject> extends CliWriters {
+    input: z.output<TInput>;
+    options: Readonly<CliRunOptions>;
+    /**
+     * The application's own global options for this invocation, already validated
+     * against `CliConfig.globalOptions`. Empty when the CLI declares none. Typed
+     * loosely because a command is defined independently of the CLI it is mounted
+     * on — read it through the same schema the application declared.
+     */
+    globals: Readonly<Record<string, unknown>>;
+}
+export interface CliCommandDefinitionBase<TInput extends ZodObject> {
+    name: string;
+    description: string;
+    input: TInput;
+}
+export interface CliCommandDefinitionWithOutput<TInput extends ZodObject, TOutput extends ZodType> extends CliCommandDefinitionBase<TInput> {
+    output: TOutput;
+    handler: (context: CliCommandContext<TInput>) => z.output<TOutput> | Promise<z.output<TOutput>>;
+    /** Pure post-validation stdout presentation; returned bytes are written verbatim once. */
+    present?: (context: {
+        result: z.output<TOutput>;
+        options: Readonly<CliRunOptions>;
+    }) => string;
+    /** Process exit code for a successfully validated result. */
+    exitCode?: (result: z.output<TOutput>) => number;
+}
+export interface CliCommandDefinitionWithoutOutput<TInput extends ZodObject> extends CliCommandDefinitionBase<TInput> {
+    output?: never;
+    present?: never;
+    exitCode?: never;
+    handler: (context: CliCommandContext<TInput>) => void | Promise<void>;
+}
+export type CliCommandDefinition = CliCommandDefinitionWithOutput<ZodObject, ZodType> | CliCommandDefinitionWithoutOutput<ZodObject>;
+/** Typed identity helper for one transport-local executable command. */
+export declare function defineCliCommand<TInput extends ZodObject, TOutput extends ZodType>(definition: CliCommandDefinitionWithOutput<TInput, TOutput>): CliCommandDefinitionWithOutput<TInput, TOutput>;
+export declare function defineCliCommand<TInput extends ZodObject>(definition: CliCommandDefinitionWithoutOutput<TInput>): CliCommandDefinitionWithoutOutput<TInput>;
+export interface PreparedCliCommandEmission {
+    result: ToolResult;
+    presentation?: string;
+    successExitCode: number;
+}
+/**
+ * Whether a native command yields a value at all.
+ *
+ * The two halves of `CliCommandDefinition` are not the same kind of thing: one
+ * returns a validated result and lets the frame print it, the other prints
+ * itself and returns nothing. Only the first can be executed somewhere that has
+ * no stdout to print to — an in-process invocation, a stream of JSON lines —
+ * and this is the test that decides it.
+ */
+export declare function cliCommandReturnsResult(definition: CliCommandDefinition): definition is CliCommandDefinitionWithOutput<ZodObject, ZodType>;
+/**
+ * The exit code a successful result earns, or a throw naming the offence.
+ *
+ * Shared, because a command run in process must exit-code identically to the
+ * same command typed at a prompt; two copies of this rule would eventually
+ * disagree and the divergence would show up as a script that branches wrong.
+ */
+export declare function cliCommandSuccessExitCode(definition: CliCommandDefinition, data: unknown): number;
+/** Apply native-only presentation policy after canonical output validation. */
+export declare function prepareCliCommandEmission(definition: CliCommandDefinition, result: ToolResult, options: Readonly<CliRunOptions>): PreparedCliCommandEmission;
+export declare function cliCommandPresentationSchema(definition: CliCommandDefinition): Record<string, unknown>;
+/** Execute a CLI-only definition without inventing a tool operation identity. */
+export declare function executeCliCommand(definition: CliCommandDefinition, rawArgs: Record<string, unknown>, options: CliRunOptions, writers: CliWriters, coerceJson: boolean, globals?: Readonly<Record<string, unknown>>): Promise<ToolResult>;
+//# sourceMappingURL=command.d.ts.map

package/dist/tools/cli/command.d.ts.map

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

package/dist/tools/cli/config.d.ts

@@ -0,0 +1,90 @@
+import type { ZodObject, z } from 'zod';
+import type { ErrorHintFn, ToolCallHooks, ToolLifecycle } from '../execute-hooks.js';
+import type { ExitCodeMap } from './format.js';
+import type { CliInvokerConfig } from './invoke.js';
+import type { CliWaitConfig } from './wait.js';
+export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>, TGlobals extends ZodObject = ZodObject> extends CliInvokerConfig<TAuth, TContext, TGlobals> {
+    /** Program version — printed by `--version`. */
+    version: string;
+    /**
+     * Identity for the single CLI invocation — resolved ONCE at startup (from an
+     * env var / token file), like a stdio MCP server, not per call. A value or a
+     * promise of one.
+     */
+    auth?: TAuth | Promise<TAuth>;
+    /**
+     * Lazily resolve identity only when a managed command/surface actually needs
+     * it. Receives the application's global options, so `--caller <key>` can
+     * select WHICH identity this invocation speaks as.
+     */
+    resolveAuth?: (globals: z.output<TGlobals>) => TAuth | Promise<TAuth>;
+    /**
+     * The application's OWN global options — invocation context that belongs to
+     * no single operation: which identity key, which checkout, which profile.
+     * Declared as a Zod object of optional fields; `createCli` lifts these flags
+     * out of argv wherever they stand (before or after the command name),
+     * validates them against this schema and keeps them out of every operation's
+     * arguments. A name that collides with a framework option or with a field of
+     * any command is a startup error, never silent shadowing.
+     */
+    globalOptions?: TGlobals;
+    /**
+     * Context merged into every handler. Typed against the app's context shape
+     * when the CLI is built via `createToolkit<AppContext>()`.
+     */
+    context?: (auth: Awaited<TAuth> | undefined, globals: z.output<TGlobals>) => TContext;
+    /** Explicit cancellation for this invocation; applications may bind SIGINT to it. */
+    signal?: AbortSignal;
+    /** Tool-call observability hooks — `afterToolCall` fires for every result,
+     *  `onToolError` for the raw value behind a thrown one. */
+    hooks?: ToolCallHooks;
+    /**
+     * Auth / scope gate — pass the same `createAuthHook` result used for the HTTP
+     * server's `beforeHandle` so a CLI command is guarded identically. Without it
+     * a scoped command bypasses the gate.
+     */
+    lifecycle?: ToolLifecycle;
+    /** Coerce JSON-stringified arrays/objects in arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Global error hint appended to every failed command's error. */
+    errorHint?: ErrorHintFn;
+    /** Override exit codes per `ToolResult.code`, merged over the defaults. */
+    exitCodes?: ExitCodeMap;
+    /**
+     * Route a command's unknown `--flags` into a freeform object field, keyed by
+     * command name → field. Lets `generate <model> --prompt … --aspect_ratio 16:9`
+     * fill the model's `parameters` directly, instead of a `--parameters '{json}'`
+     * blob. Values are loosely coerced (`"30"` → `30`, `"true"` → `true`).
+     */
+    passthrough?: Record<string, string>;
+    /** Per-command `--wait` polling behaviour, keyed by command name. */
+    wait?: Record<string, CliWaitConfig>;
+    /** Extract downloadable media URLs from a result for `--output-dir`. */
+    download?: (result: unknown) => Array<{
+        url: string;
+        name: string;
+    }>;
+    /**
+     * Allow `--output-dir` downloads from private / internal / loopback hosts.
+     * Default `false` — the SSRF guard, since the URLs come from handler output.
+     */
+    allowPrivateDownloadHosts?: boolean;
+    /** Max bytes per `--output-dir` download before aborting. Default 100 MB. */
+    maxDownloadBytes?: number;
+    /**
+     * Deadline for producing response headers per `--output-dir` download (DNS,
+     * connects and redirects share it). Default 15 seconds.
+     */
+    downloadTimeoutMs?: number;
+    /** argv to parse — default `process.argv.slice(2)`; injectable for tests. */
+    argv?: string[];
+    /** stdout sink — default `process.stdout`; injectable for tests. */
+    stdout?: (text: string) => void;
+    /** stderr sink — default `process.stderr`; injectable for tests. */
+    stderr?: (text: string) => void;
+    /** Exit hook — default `process.exit`; injectable for tests. */
+    exit?: (code: number) => void;
+    /** Read piped stdin — default reads when not a TTY; injectable for tests. */
+    stdin?: () => Promise<string | null>;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/tools/cli/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,SAAS,CACxB,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,QAAQ,SAAS,SAAS,GAAG,SAAS,CACtC,SAAQ,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACnD,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACtE;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC;IACtF,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;+DAC2D;IAC3D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC"}

package/dist/tools/cli/create-cli.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The CLI transport — the fourth surface a `defineContract` drives, alongside
+ * HTTP, MCP and agent tools. `createCli` turns contract services into a
+ * command-line program: `<app> <command> [positional] [--flags]`, one command
+ * per contract tool exposed on `'CLI'`.
+ *
+ * It is a peer of `mountMcp` / `mountAgent`, not a wrapper around the HTTP
+ * client: a command runs through the very same `executeToolMethod` pipeline —
+ * the same validation, the same `lifecycle.beforeHandle` auth gate, the same
+ * error model — so a CLI call accepts and rejects exactly as the other
+ * transports do (ADR 0014 parity). The CLI-unique parts live around that core:
+ * argv parsing (`cli-args`), stdout/exit formatting (`cli-format`) and `--wait`
+ * polling (`cli-wait`).
+ *
+ * Exposure is opt-in: a method appears as a command only when its contract
+ * `expose` lists `'CLI'` (the default `['MCP','AGENT']` keeps it off the CLI).
+ *
+ * stitchkit ships no binary — `createCli` is the building block. A consuming app
+ * writes the executable (`#!/usr/bin/env node` → `createCli({ … })`) and the
+ * `bin` entry in its own `package.json`.
+ */
+import type { ZodObject } from 'zod';
+import type { CliConfig } from './config.js';
+import { type CliInvocationResult, type CliInvoker, type CliInvokerCommand, type CliInvokerConfig, type CliSurfaceSource, cliInvocationResult, createCliInvoker } from './invoke.js';
+export type { CliConfig, CliInvocationResult, CliInvoker, CliInvokerCommand, CliInvokerConfig, CliSurfaceSource, };
+export { cliInvocationResult, createCliInvoker };
+/**
+ * Build and run one mixed contract/runtime/native CLI surface, then exit.
+ *
+ * The phases run in a fixed order and each ends the invocation when it answers:
+ * startup (`createCliSession`, where configuration faults throw), routing and
+ * `--version`, native commands (before any identity is resolved), then the
+ * managed surface — the top-level listing or one managed command.
+ */
+export declare function createCli<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>, TGlobals extends ZodObject = ZodObject>(config: CliConfig<TAuth, TContext, TGlobals>): Promise<void>;
+//# sourceMappingURL=create-cli.d.ts.map

package/dist/tools/cli/create-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cli.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/create-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAMlB,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,CAAC;AACF,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,QAAQ,SAAS,SAAS,GAAG,SAAS,EACtC,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7D"}

package/dist/tools/cli/download.d.ts

@@ -0,0 +1,8 @@
+/** Default memory cap per downloaded file — overridable via `maxDownloadBytes`. */
+export declare const DEFAULT_DOWNLOAD_MAX_BYTES: number;
+/** Download each extracted URL into `dir`, reporting per-file outcome to stderr. */
+export declare function downloadResults(files: Array<{
+    url: string;
+    name: string;
+}>, dir: string, stderr: (text: string) => void, quiet: boolean, allowPrivate: boolean, maxBytes: number, timeoutMs: number | undefined): Promise<boolean>;
+//# sourceMappingURL=download.d.ts.map

package/dist/tools/cli/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/download.ts"],"names":[],"mappings":"AAIA,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAE5D,oFAAoF;AACpF,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,OAAO,CAAC,CAyBlB"}

package/dist/tools/cli/format.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Render a `ToolResult` for the CLI surface and map it to a process exit code.
+ *
+ * Output is JSON — the CLI's audience is agents (Skills via Bash), scripts and
+ * `| jq`, for which structured JSON is the right shape, not a hand-formatted
+ * table. The default is pretty-printed (indented, the same shape an MCP tool
+ * returns); `--json` switches success and error records to one compact line.
+ *
+ * stdout is reserved for that result; an error goes to stderr as the same
+ * model-facing `{ error, retryable, details, _hint }` object the MCP / agent transports
+ * return (`formatToolError`), so a script can keep `2>/dev/null` clean while
+ * still parsing a success.
+ */
+import type { ErrorHintFn } from '../execute-hooks.js';
+import type { ToolResult } from '../execute-result.js';
+/** Map a `ToolResult.code` to a process exit code. */
+export type ExitCodeMap = Record<string, number>;
+/**
+ * Conventional exit codes — `0` success, distinct non-zero per error class so a
+ * script can branch on `$?`. Merged under any `CliConfig.exitCodes` override.
+ */
+export declare const DEFAULT_EXIT_CODES: ExitCodeMap;
+export interface CliWriters {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export interface EmitOptions {
+    /** Compact single-line success/error JSON; otherwise pretty-printed. */
+    json: boolean;
+    toolName: string;
+    errorHint?: ErrorHintFn;
+    exitCodes?: ExitCodeMap;
+}
+/**
+ * Write a result to the right stream and return the exit code. Success → JSON
+ * on stdout (pretty by default, compact with `--json`), exit `0`. Failure → the
+ * error JSON on stderr, exit per the code map (unknown code → `1`).
+ */
+/**
+ * The exit code a result earns, without writing anything.
+ *
+ * Extracted so a caller that runs an operation in process — a stdin loop, a
+ * resumable batch — gets the SAME code the printed path gives, from the same
+ * table, rather than re-deriving one from the error code and drifting. It was
+ * computed inside `emitResult`, which meant the only way to learn it was to
+ * print.
+ */
+export declare function cliExitCode(result: ToolResult, exitCodes?: ExitCodeMap): number;
+export declare function emitResult(result: ToolResult, writers: CliWriters, opts: EmitOptions): number;
+//# sourceMappingURL=format.d.ts.map

package/dist/tools/cli/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAWhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR"}

package/dist/tools/cli/help.d.ts

@@ -0,0 +1,24 @@
+import { type JsonSchemaField } from '../../json-schema/json-schema.js';
+import type { CliCommandPresentation } from './policy.js';
+/**
+ * Commands matching a substring, by name or by description.
+ *
+ * A discovered surface can be two hundred commands, at which point the full list
+ * stops being an answer: it scrolls past a person and costs an agent the same
+ * context an unfiltered result would. The description is searched too, because
+ * the word someone knows is often in the sentence rather than the name.
+ */
+export declare function filterCommands(commands: Map<string, CliCommandPresentation>, filter: string): Map<string, CliCommandPresentation>;
+export declare function renderTopHelp(input: {
+    name: string;
+    version: string;
+    commands: Map<string, CliCommandPresentation>;
+    defaultCommand?: string;
+    applicationOptions: readonly JsonSchemaField[];
+    /** Why the managed surface is missing from this listing, when it is. */
+    unavailable?: string;
+    /** Narrow the listing; the counted line says what was left out. */
+    filter?: string;
+}): string;
+export declare function renderCommandHelp(name: string, command: string, descriptor: CliCommandPresentation, applicationOptions?: readonly JsonSchemaField[]): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/tools/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA6DvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CAsDR"}

package/dist/tools/cli/installer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generate the one-line installer, from the manifest, on the server.
+ *
+ * A `curl … | sh` runs on a machine where nothing is installed yet — including
+ * `jq`. An installer that fetches the manifest and parses it therefore fails on
+ * exactly the machines it exists for. Generating the script *from* the manifest,
+ * with the URL and the digest already substituted, removes the dependency: the
+ * script downloads one file, checks one digest and renames it into place.
+ */
+import type { CliBuildAsset, CliBuildManifest } from './manifest.js';
+export interface CliInstallerConfig {
+    manifest: CliBuildManifest;
+    /**
+     * The asset this script installs. Omit it to render one script covering every
+     * asset in the manifest, selected by `uname` at run time — otherwise the
+     * dispatch is the one hand-written piece left in the install path, and every
+     * publisher writes the same `uname -s`/`uname -m` mapping from memory.
+     */
+    asset?: CliBuildAsset;
+    /** The name the binary takes on the PATH; defaults to the manifest name. */
+    binaryName?: string;
+    /** Default install directory; overridable by `INSTALL_DIR` at run time. */
+    installDir?: string;
+}
+/**
+ * Render the installer for one asset.
+ *
+ * The three properties that matter, in the script rather than in a comment:
+ * no JSON parsing, the digest is checked against the **decompressed** bytes, and
+ * the final step is a rename — an interrupted download leaves a temporary file,
+ * never a half-written executable on someone's PATH.
+ */
+export declare function renderCliInstaller(config: CliInstallerConfig): string;
+//# sourceMappingURL=installer.d.ts.map

package/dist/tools/cli/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA+ErE"}