ai-hist 0.18.0 → 0.18.1

package/dist/cli.d.ts

@@ -1,3 +1,129 @@
 #!/usr/bin/env node
+import type { Writable } from 'node:stream';
+type Parsed = {
+    positional: string[];
+    flags: Map<string, Array<string | true>>;
+};
+/**
+ * Where a run's output goes.
+ *
+ * The bin writes to the real streams; a host that mounts this CLI (see
+ * `relay-cli.ts`) supplies its own sink. Nothing below `runCli` touches
+ * `process.stdout`/`process.stderr` directly, so the same dispatch serves both.
+ */
+export interface CliIo {
+    stdout(chunk: string): void;
+    stderr(chunk: string): void;
+}
+export declare const BOOLEAN_FLAGS: Set<string>;
+export declare const VALUE_FLAGS: Set<string>;
+export declare function humanLine(value: unknown): string;
+export declare function output(io: CliIo, value: unknown, json: boolean): void;
+/** One positional argument, as the mounted help renders it. */
+export interface CommandArgSpec {
+    name: string;
+    description: string;
+    required: boolean;
+    variadic?: boolean;
+}
+export interface CommandSpec {
+    /** Name used in flag- and argument-rejection messages. */
+    name: string;
+    /**
+     * One line for the mounted help.
+     *
+     * A host renders its own help from this table rather than forwarding
+     * `--help`, so an empty description is a user-visible hole, not an internal
+     * detail.
+     */
+    description: string;
+    /**
+     * Path under the mounted group, or `null` for a command the group does not
+     * expose. `['sessions', 'list']` here is `ai-hist sessions list`, reached as
+     * `agent-relay sessions list`.
+     */
+    surface: readonly string[] | null;
+    /** Extra spellings the mounted group accepts for `surface`. */
+    surfaceAliases?: readonly string[];
+    /**
+     * The positionals named for help. `positionals` below stays the authority on
+     * how many are accepted; the drift test asserts the two agree.
+     */
+    args?: readonly CommandArgSpec[];
+    allowed: readonly string[];
+    /** Positional arguments after the command words: [minimum, maximum]. */
+    positionals: readonly [number, number | null];
+    /** Named in the usage error when fewer than the minimum are given. */
+    requires?: string;
+    /** Answers from the local database, so it takes the shared first-use bootstrap. */
+    readsLocalStore?: boolean;
+    /** Addresses a session by identity; --local/--remote/--all are meaningless. */
+    rejectsScope?: boolean;
+    /** Remaining command-line checks, run before any store work. */
+    validate?: (args: Parsed) => void;
+    /**
+     * Reads `RunCliOptions.signal`, so the bin claims the process's signals for
+     * it. Left off, the bin leaves `SIGINT`/`SIGTERM` at their default: a
+     * listener suppresses Node's own termination, so claiming them for a command
+     * that never looks at the signal swallows the user's first Ctrl-C.
+     */
+    cancellable?: true;
+}
+/**
+ * Every option a command may list in `allowed`, spelled the way help shows it.
+ *
+ * This is the only place a flag's user-facing text lives. The drift test
+ * asserts it covers exactly the flags the command table allows, and that each
+ * one's arity matches `BOOLEAN_FLAGS`/`VALUE_FLAGS` — so a flag that `parse`
+ * cannot accept can never reach the mounted help.
+ */
+export declare const FLAG_SPECS: Record<string, {
+    flags: string;
+    description: string;
+}>;
+/** Options the host owns, so they never reach a mounted command's help. */
+export declare const HOST_OWNED_FLAGS: Set<string>;
+export declare const COMMANDS: Map<string, CommandSpec>;
+/**
+ * Whether this command line routes to a command that reads the cancellation
+ * signal.
+ *
+ * The bin asks before installing a `SIGINT`/`SIGTERM` handler. A listener
+ * replaces Node's default termination, so a handler on an invocation that
+ * never reads the signal swallows the first shutdown request: the user presses
+ * Ctrl-C, nothing happens, and they press it again. Resolved from the same
+ * `COMMANDS` table `dispatch` resolves against, so the two cannot disagree
+ * about which commands those are.
+ */
+export declare function usesCancellation(argv: readonly string[]): boolean;
+/** Knobs the bin owns and a mounted host does not. */
+export interface RunCliOptions {
+    /**
+     * Cancels a long-running `delivery drain`/`delivery run`.
+     *
+     * The signal handlers that produce it belong to whoever owns the process:
+     * the bin installs them, a host passes its own, and `dispatch` installs none.
+     */
+    signal?: AbortSignal;
+    /** Check npm for a newer release on `--version`. The bin only. */
+    updateNotice?: boolean;
+    /** Colourize `sessions list --pretty`. Defaults to stdout being a TTY. */
+    color?: boolean;
+    /**
+     * Where `export` writes when no `--out` is given.
+     *
+     * NDJSON export is unbounded, so it needs a real stream with backpressure
+     * rather than the unbuffered `io.stdout` callback.
+     */
+    stdoutStream?: Writable;
+}
+/**
+ * Run one `ai-hist` command line and resolve to its exit code.
+ *
+ * Never calls `process.exit`, never writes to `process.stdout`/`process.stderr`
+ * and never installs a signal handler: the caller owns all three. `argv` is the
+ * arguments after the program name.
+ */
+export declare function runCli(argv: readonly string[], io: CliIo, options?: RunCliOptions): Promise<number>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAY5C,KAAK,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAA;CAAE,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAoBD,eAAO,MAAM,aAAa,aAA8J,CAAC;AACzL,eAAO,MAAM,WAAW,aAMtB,CAAC;AA2KH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOhD;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAgBrE;AAkUD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,wEAAwE;IACxE,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAWD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CA+B7E,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,aAAkC,CAAC;AAKhE,eAAO,MAAM,QAAQ,0BAmGnB,CAAC;AAcH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAajE;AAkPD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa7G"}