@jevitate/cli 0.1.0 → 0.3.0

package/dist/cli-reference.js

@@ -0,0 +1,81 @@
+import { walk } from "./cli-surface.js";
+/** Escapes a value for a markdown table cell. */
+function cell(text) {
+    return text.replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ").trim();
+}
+function code(text) {
+    return `\`${text.replace(/`/g, "'")}\``;
+}
+function anchor(path) {
+    return path.replace(/[^a-z0-9]+/gi, "-").toLowerCase().replace(/^-|-$/g, "");
+}
+function defaultCell(json) {
+    if (json === "null")
+        return "";
+    try {
+        const v = JSON.parse(json);
+        return code(typeof v === "string" ? v : JSON.stringify(v));
+    }
+    catch {
+        return code(json);
+    }
+}
+function usageLine(s, hasChildren) {
+    const args = s.arguments.map((a) => {
+        const n = a.variadic ? `${a.name}...` : a.name;
+        return a.required ? `<${n}>` : `[${n}]`;
+    });
+    const parts = [`jevitate ${s.path}`, ...(s.options.length > 0 ? ["[options]"] : []), ...(hasChildren ? ["[command]"] : []), ...args];
+    return parts.join(" ");
+}
+function renderArguments(args) {
+    if (args.length === 0)
+        return [];
+    const out = ["**Arguments**", "", "| Argument | Description | Required | Default | Choices |", "| --- | --- | --- | --- | --- |"];
+    for (const a of args) {
+        out.push(`| ${code(a.variadic ? `${a.name}...` : a.name)} | ${cell(a.description)} | ${a.required ? "yes" : "no"} | ${defaultCell(a.defaultValue)} | ${a.choices ? a.choices.map(code).join(", ") : ""} |`);
+    }
+    return [...out, ""];
+}
+function renderOptions(opts) {
+    if (opts.length === 0)
+        return [];
+    const out = ["**Options**", "", "| Flags | Description | Default | Choices | Required | Env |", "| --- | --- | --- | --- | --- | --- |"];
+    for (const o of opts) {
+        out.push(`| ${code(o.flags)} | ${cell(o.description)} | ${defaultCell(o.defaultValue)} | ${o.choices ? o.choices.map(code).join(", ") : ""} | ${o.mandatory ? "yes" : ""} | ${o.envVar ? code(o.envVar) : ""} |`);
+    }
+    return [...out, ""];
+}
+/** Renders the full CLI reference markdown from a live commander tree. Deterministic: no versions, dates or absolute paths. */
+export function renderCliReference(program) {
+    const surfaces = walk(program, "");
+    const root = surfaces[0];
+    const commands = surfaces.slice(1);
+    const hasChildren = (path) => commands.some((c) => c.path.startsWith(`${path} `));
+    const top = commands.filter((c) => !c.path.includes(" "));
+    const lines = [
+        "# CLI reference",
+        "",
+        "> Generated from the CLI — do not edit by hand; run `pnpm docs:cli`.",
+        "",
+        root.description,
+        "",
+        ...renderOptions(root.options),
+        "## Commands",
+        "",
+        ...top.map((c) => `- [${code(c.path)}](#${anchor(c.path)}): ${c.description.split("\n")[0]}`),
+        "",
+    ];
+    for (const c of commands) {
+        const depth = Math.min(c.path.split(" ").length + 1, 6);
+        lines.push(`${"#".repeat(depth)} ${c.path}`, "");
+        lines.push("```", usageLine(c, hasChildren(c.path)), "```", "");
+        if (c.description !== "")
+            lines.push(c.description, "");
+        if (c.aliases.length > 0)
+            lines.push(`Aliases: ${c.aliases.map(code).join(", ")}`, "");
+        lines.push(...renderArguments(c.arguments), ...renderOptions(c.options));
+    }
+    return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+}
+//# sourceMappingURL=cli-reference.js.map

package/dist/cli-reference.js.map

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

package/dist/cli-refusal.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from "commander";
+import type { JsonEnvelope } from "./envelope.js";
+/** Records, on every dispatch, the leaf command commander is about to run (a `preAction` hook on the root). */
+export declare function trackActionCommand(program: Command): void;
+/** `ledger add`, `mission target update`, … — the command's path under the root program. */
+export declare function commandPath(cmd: Command): string;
+/**
+ * Prints an envelope a command produced: a success as the envelope line (as it always was); a
+ * refusal as the envelope with `--json`, else `error <CODE>: …` on stderr. Sets `process.exitCode`
+ * (`exitCode` when the caller has a verdict code, else the envelope's class).
+ */
+export declare function emitJsonOrRefusal(program: Command, envelope: JsonEnvelope<unknown>, exitCode?: number): void;

package/dist/cli-refusal.js

@@ -0,0 +1,52 @@
+import { emitEnvelope } from "./cli-output.js";
+import { exitCodeForEnvelope } from "./exit-codes.js";
+/**
+ * THE refusal path for every command (#218). A command that refuses (`fail(code, message)`) prints
+ * the `{v, ok:false, error}` envelope on stdout only when it was asked for JSON (`--json`); without
+ * it, one human `error <CODE>: <message>` line (+ a `--help` hint for a usage error) on stderr, and
+ * nothing on stdout. The exit code comes from exit-codes.ts either way (64 usage · 2 otherwise).
+ *
+ * The emitters that print envelopes (`emitJson` in program.ts, report/invariants/ai commands) all
+ * route here, so which command is running — and whether IT was given `--json` — is looked up from
+ * the command commander dispatched to (recorded by `trackActionCommand`), not threaded by hand.
+ * A successful envelope is printed exactly as before: this module changes refusals only.
+ */
+const actionCommands = new WeakMap();
+/** Records, on every dispatch, the leaf command commander is about to run (a `preAction` hook on the root). */
+export function trackActionCommand(program) {
+    program.hook("preAction", (root, action) => {
+        actionCommands.set(root, action);
+    });
+}
+/** `ledger add`, `mission target update`, … — the command's path under the root program. */
+export function commandPath(cmd) {
+    const names = [];
+    for (let c = cmd; c !== null && c.parent !== null; c = c.parent)
+        names.unshift(c.name());
+    return names.join(" ");
+}
+/** Whether the running command asked for the JSON envelope. A command without a `--json` flag never did. */
+function wantsJson(program) {
+    const action = actionCommands.get(program);
+    if (action === undefined)
+        return { json: true }; // not dispatched through the program (a direct call): unchanged
+    const hasJsonFlag = action.options.some((o) => o.long === "--json");
+    return { json: hasJsonFlag && action.opts().json === true, command: commandPath(action) };
+}
+/**
+ * Prints an envelope a command produced: a success as the envelope line (as it always was); a
+ * refusal as the envelope with `--json`, else `error <CODE>: …` on stderr. Sets `process.exitCode`
+ * (`exitCode` when the caller has a verdict code, else the envelope's class).
+ */
+export function emitJsonOrRefusal(program, envelope, exitCode) {
+    if (!envelope.ok) {
+        const { json, command } = wantsJson(program);
+        if (!json) {
+            emitEnvelope(program, envelope, { json: false, ...(command === undefined ? {} : { command }), ...(exitCode === undefined ? {} : { exitCode }) });
+            return;
+        }
+    }
+    program.configureOutput().writeOut?.(`${JSON.stringify(envelope)}\n`);
+    process.exitCode = exitCode ?? exitCodeForEnvelope(envelope);
+}
+//# sourceMappingURL=cli-refusal.js.map

package/dist/cli-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-refusal.js","sourceRoot":"","sources":["../src/cli-refusal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;GAUG;AAEH,MAAM,cAAc,GAAG,IAAI,OAAO,EAAoB,CAAC;AAEvD,+GAA+G;AAC/G,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QACzC,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAmB,GAAG,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM;QAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzG,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,4GAA4G;AAC5G,SAAS,SAAS,CAAC,OAAgB;IACjC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,gEAAgE;IACjH,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACpE,OAAO,EAAE,IAAI,EAAE,WAAW,IAAI,MAAM,CAAC,IAAI,EAAsB,CAAC,IAAI,KAAK,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;AAChH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,QAA+B,EAAE,QAAiB;IACpG,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;YACjJ,OAAO;QACT,CAAC;IACH,CAAC;IACD,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACtE,OAAO,CAAC,QAAQ,GAAG,QAAQ,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAC/D,CAAC"}

package/dist/cli-shared.d.ts

@@ -0,0 +1,340 @@
+import { Command } from "commander";
+import type { ProfileManager } from "@jevitate/daemon";
+import { type PlannedStep } from "@jevitate/domain";
+import { SqliteSitePolicyRepository } from "@jevitate/storage-sqlite";
+import { UsageTracker, type JudgmentPort, type GenerationPort, type CatalogModel, type ModelConstraints, type UsageSink } from "@jevitate/ai-core";
+import { type UnpackedExtension } from "@jevitate/playwright";
+import { type Actor } from "@jevitate/screenplay";
+import { type JsonEnvelope } from "./envelope.js";
+import { type QueuedMissionExecutor } from "./mission-queue-runner.js";
+import { type StartUiServerDeps, type UiServerHandle } from "./ui-api.js";
+import { type AiCliDeps } from "./ai-cli.js";
+import { type EmitOptions } from "./cli-output.js";
+import { type DetectionDeps } from "./init-skills.js";
+import { type ExploreCliDeps } from "./explore-api.js";
+import { type RecorderLike } from "./record-api.js";
+import { type SourceApiDeps } from "./source-api.js";
+import { type RunResolvedJourney } from "./source-run-api.js";
+import { type GitExec, type GhPort } from "@jevitate/sources";
+import type { BrowserLaunchOptions, BrowserPort, BrowserSession } from "@jevitate/playwright";
+import { type EmulationSpec } from "@jevitate/playwright";
+import { type GovernanceFlags } from "./resource-preflight.js";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+/** Injectable wiring for the `record` command (all optional; real defaults). */
+export interface RecordCliDeps {
+    /** Testing seam — defaults to a real `PlaywrightBrowserPort`. */
+    browserPortFactory?: () => BrowserPort;
+    /** Testing seam — defaults to a real `@jevitate/recorder` `Recorder`. */
+    recorderFactory?: (session: BrowserSession, site: string) => RecorderLike;
+    /** Testing seam — the "user signalled done" wait. Defaults to Enter on stdin. */
+    waitForStop?: () => Promise<void>;
+}
+export interface CliDeps {
+    profiles: ProfileManager;
+    dbPath?: string;
+    /**
+     * Prune `.jevitate/logs` by the retention policy before each command that writes run output (the
+     * real binary sets it; left unset, e.g. in tests, nothing is pruned implicitly). `logsRoot`
+     * overrides where (default: the project's logs, else `~/.jevitate/logs`).
+     */
+    logs?: {
+        readonly autoPrune: boolean;
+        readonly logsRoot?: string;
+        readonly configPath?: string;
+    };
+    journeysDir?: string;
+    /**
+     * Optional, additive (#247): the environments file `--env` reads (default: the repo's
+     * `.jevitate/environments.json`, found from the working directory).
+     */
+    environmentsFile?: string;
+    /** Optional, additive: overrides the mission-targets store directory
+     *  (default: ~/.jevitate/missions/targets). Same dir `queue_exploration`
+     *  resolves promoted targets from. */
+    missionTargetsDir?: string;
+    /** Optional, additive: overrides the inbox store directory (default:
+     *  ~/.jevitate/inbox). Same dir BOTH `jevitate mcp`'s inbox tools AND
+     *  `jevitate ui` resolve against by default — Task 8 threads one resolved
+     *  dir into both so they serve/consume the same store. */
+    inboxDir?: string;
+    /** Optional, additive: `jevitate ui` wiring (see ui-api.ts). Omitted in
+     *  production means the real `startUiServer`, which binds a real loopback
+     *  HTTP port — tests inject a fake so no port is ever bound. */
+    ui?: {
+        startUiServer?: (deps: StartUiServerDeps) => Promise<UiServerHandle>;
+    };
+    /** Optional, additive: `@jevitate/ai-core` wiring (see ai-cli.ts). Omitted in
+     *  production means real env + the deterministic fake generation gateway. */
+    ai?: AiCliDeps;
+    /** Optional, additive: `@jevitate/explore` wiring (see explore-api.ts). */
+    explore?: ExploreCliDeps;
+    /** Optional, additive: `mission run` wiring — tests inject the executor so no browser opens. */
+    missions?: {
+        execute?: QueuedMissionExecutor;
+        /** Optional, additive (#255): the mission queue directory (default ~/.jevitate/missions/queue) — `mission run/queue/result` and `jevitate mcp`. */
+        queueDir?: string;
+    };
+    /** Optional, additive: `jevitate record` wiring (see record-api.ts). */
+    record?: RecordCliDeps;
+    /** Optional, additive: `jevitate init` wiring (see init-skills.ts). Omitted
+     *  in production means the real `existsSync`/`homedir`/`cwd` and the real
+     *  `~/.jevitate/skills-install-state.json` state path.
+     *  `isInteractive` (#230): whether key collection may prompt stdin;
+     *  omitted in production means the real `process.stdin.isTTY` check. */
+    init?: {
+        detection?: DetectionDeps;
+        statePath?: string;
+        isInteractive?: () => boolean;
+    };
+    /**
+     * Optional, additive: distributed-Journey-sources wiring (see source-api.ts).
+     * Every field is injectable so tests never touch the network, the real home
+     * dir, or the real `git`/`gh` binaries. Omitted in production means the real
+     * `~/.jevitate/sources` clone dir, `<cwd>/jevitate.lock`, `~/.jevitate/trust`
+     * stores, and the real `git`/`gh` ports.
+     */
+    sources?: {
+        sourcesDir?: string;
+        lockPath?: string;
+        trustDir?: string;
+        ackDir?: string;
+        git?: GitExec;
+        gh?: GhPort;
+        now?: () => string;
+        /** Identity recorded in a `TrustRecord`/`TouAck`; defaults to the OS user. */
+        approvedBy?: string;
+        /** Optional, additive: `jevitate source run` runner seam (see
+         *  source-run-api.ts). Omitted in production means the real
+         *  Playwright-backed `realResolvedJourneyRunner`; tests inject a fake so no
+         *  browser launches. */
+        runJourney?: RunResolvedJourney;
+    };
+}
+export declare const DEFAULT_DB_PATH: string;
+export declare const DEFAULT_MISSION_TARGETS_DIR: string;
+export declare const DEFAULT_INBOX_DIR: string;
+export declare function resolveDbPath(deps: CliDeps, flag?: string): string;
+/** #247: where `--env` reads environments and per-origin sessions from (test seams; real defaults). */
+export declare function environmentSeams(deps: CliDeps): {
+    environmentsFile?: string;
+    targetsFile?: string;
+};
+/**
+ * Mirrors `resolveDbPath`'s flag > deps > home-dir-default convention: a
+ * per-invocation `--dir` flag wins, then a `CliDeps.journeysDir` wired in by
+ * the host, then `~/.jevitate/journeys`.
+ */
+export declare function resolveJourneysDir(deps: CliDeps, flag?: string): string;
+/** Same flag > home-dir-default convention as `resolveJourneysDir`, for the
+ *  committed-regressions directory `regression capture` writes into. */
+export declare function resolveRegressionsDir(flag?: string): string;
+/** Same flag > deps > home-dir-default convention as `resolveJourneysDir`, for
+ *  the mission-targets store `mission target ...` reads/writes. */
+export declare function resolveMissionTargetsDir(deps: CliDeps, flag?: string): string;
+/** Same flag > deps > home-dir-default convention as `resolveJourneysDir`, for
+ *  the inbox store `jevitate mcp`'s inbox tools AND `jevitate ui` both read
+ *  from — the SAME resolved directory, so the two commands agree on where
+ *  approvals/handbacks/reviews live. */
+export declare function resolveInboxDir(deps: CliDeps, flag?: string): string;
+/**
+ * Assembles the injected `SourceApiDeps` for the distributed-sources commands
+ * from `CliDeps.sources` (test-injected ports) or the real production
+ * defaults: `~/.jevitate/sources` clones, `<cwd>/jevitate.lock`, and the
+ * local, per-user `FsTrustStore`/`FsAckStore` under `~/.jevitate/trust`.
+ * Trust/ack stores are LOCAL by design (§14.1) — never the team-shared lock.
+ */
+export declare function resolveSourceApiDeps(deps: CliDeps): SourceApiDeps;
+/** The identity recorded in a `TrustRecord`/`TouAck` — an injected value, else
+ *  the OS username, else `"local"`. Never a secret/credential. */
+export declare function resolveApprovedBy(deps: CliDeps): string;
+/**
+ * Builds a fresh, real Playwright-backed `Actor` (its own temp profile dir +
+ * browser context, per `journey-api.ts`'s `runJourneyProgrammatically`
+ * pattern) and returns it alongside a `close()` to tear the session down.
+ * `@jevitate/regression`'s `makeActor: () => Promise<Actor>` contract calls
+ * this once per reproduce/minimize attempt — a Playwright session cannot be
+ * reused after a run — so callers must close each one it hands back.
+ */
+export declare function makeRealBrowserActor(site: string, storageState?: string, emulation?: EmulationSpec, browser?: BrowserRunOptions, portFactory?: () => BrowserPort, 
+/** #247: an environment's allowed origins (default: just `site`). */
+allowedOrigins?: readonly string[]): Promise<{
+    actor: Actor;
+    close: () => Promise<void>;
+}>;
+/** Raw commander values of the shared `--browser-*` launch flags (and #205's resource-governance flags). */
+export interface BrowserLaunchFlags extends GovernanceFlags {
+    browserExecutable?: string;
+    browserChannel?: string;
+    browserArg: string[];
+    /** #256: `--extension <dir>` (repeatable), each already read and checked by `extensionArg`. */
+    extension?: readonly UnpackedExtension[];
+}
+/**
+ * #256: the `--extension <dir>` argParser — reads and checks the unpacked extension NOW (a directory
+ * with a valid manifest.json), so a bad directory is a usage error (exit 64) on every command before
+ * anything runs. The same directory twice is kept once; two directories with one id are refused.
+ */
+export declare function extensionArg(value: string, prev: readonly UnpackedExtension[] | undefined): UnpackedExtension[];
+/**
+ * Adds the shared Chromium launch flags to a browser-driving command. They map
+ * 1:1 onto `@jevitate/playwright`'s `BrowserLaunchOptions`; `--browser-arg`
+ * EXTENDS the Linux defaults (`--no-sandbox`, `--disable-dev-shm-usage`).
+ */
+export declare function withBrowserLaunchFlags(cmd: Command): Command;
+/** The `BrowserLaunchOptions` for the parsed flags, or `undefined` when none were given. */
+export declare function browserLaunchFromFlags(o: BrowserLaunchFlags): BrowserLaunchOptions | undefined;
+/** Raw commander values of the demo-mode flags (#245). `overlay` is `--no-overlay`'s attribute. */
+export interface DemoFlags {
+    headed?: boolean;
+    slowMo?: number;
+    recordVideo?: boolean | string;
+    overlay?: boolean;
+}
+/** Which demo-mode flags a command takes: every one shows (`--headed`/`--slow-mo`); some record and overlay. */
+export interface DemoFlagSet {
+    /** `--record-video [dir]` — the command lists the videos in its result. */
+    readonly recordVideo?: boolean;
+    /** `--no-overlay` — the command runs an explore mission (the overlay lives in `@jevitate/explore`). */
+    readonly overlay?: boolean;
+}
+/**
+ * Adds the demo-mode flags (#245) to a browser-driving command. Headless stays the default; these
+ * are all opt-in and resolved by `browserRunFromFlags` (which also reads `JEVITATE_HEADED`).
+ */
+export declare function withDemoFlags(cmd: Command, set?: DemoFlagSet): Command;
+/** Raw commander value of `--screenshots [mode|dir]` (#251). */
+export interface ScreenshotsFlags {
+    screenshots?: boolean | string;
+}
+/**
+ * #251: `--screenshots [mode|dir]` — masked screenshots of the run (one per distinct screen, or
+ * `steps`: one per step) plus an `index.md` contact sheet; parsed by `parseScreenshotsArg`.
+ */
+export declare function withScreenshotsFlag(cmd: Command): Command;
+/**
+ * The runner's `browser` option for the parsed `--browser-*` and demo flags, or `undefined` when none
+ * were given. `--headed` (or `JEVITATE_HEADED=1`) without a display throws `HeadedWithoutDisplayError`
+ * HERE — before any browser launches — which every command reports as its usage error (exit 64).
+ */
+export declare function browserRunFromFlags(o: BrowserLaunchFlags & DemoFlags, env?: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform): BrowserRunOptions | undefined;
+/** `{ browser }` for the parsed `--browser-*` flags, or `{}` when none were given — spread into a runner's options. */
+export declare function browserOption(o: BrowserLaunchFlags): {
+    browser?: BrowserLaunchOptions;
+};
+/** Raw commander values of the shared `--viewport`/`--device` emulation flags (#149). */
+export interface EmulationFlags {
+    viewport?: string;
+    device?: string;
+}
+/**
+ * Adds the shared `--viewport <W>x<H>` / `--device "<name>"` flags (#149) to a browser-driving
+ * command — mutually exclusive, on `explore`, `journey run`, `load run`, `source run`, `verify-fix`
+ * and `regression capture`/`run`. Absent both: Playwright's default (desktop) viewport, documented
+ * in each command's `--help`.
+ */
+export declare function withEmulationFlags(cmd: Command): Command;
+/**
+ * The `EmulationSpec` for the parsed flags, or `undefined` when neither was given (Playwright's own
+ * default viewport applies). Refused HERE, before any browser opens, when both are given —
+ * `resolveEmulation` (an unknown `--device`, or both together) is also re-checked wherever the spec
+ * is finally used, so every call path fails closed the same way.
+ */
+export declare function emulationFromFlags(o: EmulationFlags): EmulationSpec | undefined;
+/**
+ * Parses repeated `--param key=value` flags into a `Record<string,string>`.
+ * `previous` starts as the option's default (`{}`) and this is called once
+ * per occurrence, commander's standard "collect" pattern.
+ */
+export declare function collectParam(value: string, previous: Record<string, string>): Record<string, string>;
+export declare function makeClock(): {
+    nowIso: () => string;
+    monotonicMs: () => number;
+};
+export declare function withSitePolicyRepository<T>(dbPath: string, fn: (repository: SqliteSitePolicyRepository) => Promise<T>): Promise<T>;
+export declare function isPlannedStep(value: unknown): value is PlannedStep;
+export declare function parsePlannedScript(raw: string): PlannedStep[];
+/**
+ * Writes a JSON envelope using the program's CURRENTLY-CONFIGURED output
+ * writer (read at call time via `configureOutput()`), so tests that call
+ * `program.configureOutput({ writeOut })` after `buildProgram()` still see
+ * output routed to their writer. Also sets `process.exitCode` (0 for `ok`; for
+ * `fail`, the error's class from exit-codes.ts — 64 usage, else 2) instead of
+ * hard-exiting, so `exitOverride()` in tests works.
+ */
+export declare function emitJson(program: Command, envelope: JsonEnvelope<unknown>): void;
+/**
+ * #210: the envelope with `--json`, else a human summary (a refusal: `error <CODE>: …` on stderr);
+ * the cost line on stderr either way. Exit code: the verdict's, else the envelope's class (exit-codes.ts).
+ */
+export declare function emitCommandResult<T>(program: Command, envelope: JsonEnvelope<T>, opts: EmitOptions<T>): void;
+/**
+ * #221: a user-supplied name that becomes a path (a profile name, a regression id) must be one safe
+ * segment (`assertSafeName`, @jevitate/domain). Refuses it (E_INVALID_NAME, exit 64) and returns true.
+ */
+export declare function refuseUnsafeName(program: Command, name: string, what: string): boolean;
+/** A non-`--json` result: printed as bare JSON on stdout, with the cost summary line on stderr. */
+export declare function writeRawResult(program: Command, result: unknown): void;
+/** A non-`--json` result (#227): the human summary a `cli-output.ts` formatter renders, with the cost summary line on stderr. */
+export declare function writeHumanResult(program: Command, result: unknown, human: (data: unknown) => string): void;
+/**
+ * The human cost summary (#163) — on STDERR, so stdout stays exactly the JSON a caller parses:
+ * `usage: cost $0.0312 (jev $0.0203 + generation $0.0109) · 398 judgments, …`, flagged
+ * `(partial: …)` when some call could not be priced. Nothing when the result carries no usage.
+ */
+export declare function emitUsageLine(program: Command, data: unknown): void;
+/**
+ * `explore --help` trailer documenting every `outcome`/`stop`/`missionOutcome` value and its
+ * exit code (issue #83 item 2) — mirrors the README "Mission outcomes and exit codes" /
+ * "Every outcome, stop and missionOutcome value" sections, derived from the same sources:
+ * `MISSION_EXIT_CODES` (@jevitate/domain) and `goalExitCode`/`missionExitCode` (./mission-exit.ts).
+ */
+/** `--stall-timeout <seconds>` (#114) → milliseconds; `undefined` when omitted, `null` when not a positive number. */
+export declare function stallTimeoutMs(raw: string | number | undefined): number | undefined | null;
+/** #230: the only `--strategy` values `explore` accepts; anything else is refused, never silently run as goal. */
+export declare const EXPLORE_STRATEGIES: readonly ["goal", "coverage", "exploratory", "adversarial", "usability"];
+export declare const EXPLORE_OUTCOME_HELP = "\nOutcomes, stop reasons and exit codes:\n  Every result carries a canonical missionOutcome (and exitCode), whatever the strategy:\n    clean 0 \u00B7 defects-found 1 \u00B7 inconclusive 2 \u00B7 crashed 2 \u00B7 hang 3 \u00B7 intermittent 4\n  --strategy goal also carries its own ending as \"goalOutcome\" (= its \"outcome\"), folded onto missionOutcome:\n    succeeded \u2192 clean 0 \u00B7 failed / exhausted / blocked \u2192 defects-found 1\n    (defects-found, inconclusive, crashed, hang, intermittent are themselves)\n  --strategy goal's \"stop\" (why the loop itself stopped; not separately exit-coded):\n    done | blocked | exhausted | no-progress | hang | inconclusive | crashed | budget\n    (a \"done\" code rejected ends stop done, goalOutcome failed \u2014 never blocked)\n  --strategy adversarial's \"stop\" (why the hunt ended; its \"outcome\" is the canonical one above):\n    step-budget | action-budget | time-budget | strategies-exhausted | not-rendered\n    | scope-unreachable | targets-refused | target-unresponsive | identity-changed | stalled | hang\n    | crashed\n    (identity-changed: an action switched the signed-in identity and the original one could not be\n    restored \u2014 inconclusive; every switch is listed in \"identityChanges\")\n  --strategy coverage/exploratory's own \"outcome\" (folds into missionOutcome above):\n    exhausted | insufficient-coverage | cap | scope-unreachable | stalled | crashed | hang\n  A run that proved nothing is inconclusive with failure.kind insufficient-coverage (the same word as\n  the frontier outcome), and failure.message says how to reach clean.\n  A starved host (#203): every result carries \"hostHealth\" (peak load/core, min free memory, peak\n  event-loop lag, slowest render). A hang, click timeout or no-progress met while the host was\n  starved is listed in \"environmentDegraded\" (advisory, never a finding); a run most of whose steps\n  ran starved is inconclusive (failure.kind degraded-environment), never clean.\n  --feature's own \"outcome\" (folds into missionOutcome above):\n    exhausted | insufficient-coverage | cap | path-cap | scope-unreachable | stalled | crashed | hang\n  Argument/input errors (E_EXPLORE_ARGS, E_EXPLORE_ASSERTION, \u2026) exit 64, never 1.\n  Without --json: a human summary (verdict, defects by fingerprint, result file, next step);\n  with --json: the {v, ok, data} envelope.\n  Every command's exit codes: docs/outcomes.md \"Exit codes\".\n";
+/** Distinct from MissingCredentialError: "no --real/--fake-ai selected" vs "keys missing." */
+export declare class GatewaySelectionError extends Error {
+}
+export declare const DEFAULT_EXPLORE_CATALOG: CatalogModel[];
+export declare const DEFAULT_EXPLORE_CONSTRAINTS: ModelConstraints;
+/**
+ * Selects the exploration gateways. Injected gateways (tests) win; otherwise
+ * `--real` builds the live Jev + OpenRouter adapters behind a fail-closed
+ * credential preflight, and `--fake-ai` uses deterministic fakes (a pipeline
+ * smoke — the fake judge always proposes `done`, so it will not drive to a
+ * goal). No selection is a fail-closed refusal, never a silent fake.
+ */
+export declare function buildExploreGateways(deps: CliDeps, opts: {
+    real: boolean;
+    fakeAi: boolean;
+}): Promise<{
+    judge: JudgmentPort;
+    gen: GenerationPort;
+    usage: UsageTracker;
+}>;
+/**
+ * #246: the generation gateway ALONE (`journey annotate` drafts text and asks no judgment
+ * question, so it needs no Jev key). Same selection rules as `buildExploreGateways`: injected (tests)
+ * wins, `--real` is fail-closed on the OpenRouter key, `--fake-ai` is the deterministic fake, the two
+ * are exclusive, and no selection is a refusal — never a silent fake.
+ */
+export declare function buildGenerationGateway(deps: CliDeps, opts: {
+    real: boolean;
+    fakeAi: boolean;
+}): Promise<{
+    gen: GenerationPort;
+    usage: UsageTracker;
+}>;
+/**
+ * A judge that always proposes `done` — used only by `--fake-ai` (smoke). It is TOTAL and
+ * deterministic: it answers EVERY question it is asked, whatever the mission or rubric names it
+ * (#213) — a choice offering `done` picks `done` (so the goal/coverage loop stops at once, and
+ * will not drive to a goal); a choice that does NOT offer `done` (e.g. the UX quality grader's
+ * label set, `grade::0`) deterministically picks its first listed option instead of throwing; a
+ * noul answers "no"; a score answers 0. It never throws on a question SHAPE it does not
+ * specifically know about — only on a malformed one (a choice with no options at all), which is a
+ * bug upstream, not an unknown question. `usage` (#100) is optional: when supplied, every call
+ * reports 1 judgment at 0 tokens.
+ */
+export declare function fakeDoneJudge(usage?: UsageSink): JudgmentPort;