@jevitate/cli 0.1.0 → 0.3.0

package/dist/cli-shared.js

@@ -0,0 +1,537 @@
+/**
+ * Helpers shared by the per-command-group CLI modules (`*-cli.ts`) that `program.ts` wires together
+ * (#231): deps and path resolution, JSON/human output, browser/emulation flags, AI gateway selection.
+ */
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve as resolvePath } from "node:path";
+import { userInfo } from "node:os";
+import { InvalidArgumentError } from "commander";
+import { clock } from "@jevitate/domain";
+import { openDatabase, migrateToLatest, SqliteSitePolicyRepository } from "@jevitate/storage-sqlite";
+import { envCredentialStore, requireKeys, FakeGenerationGateway, OpenRouterGenerationGateway, RetryingGenerationPort, RetryingJudgmentPort, JevJudgmentGateway, realJevClientCall, UsageTracker, FAKE_CALL_USAGE, formatUsageLine, usageCountsFrom, } from "@jevitate/ai-core";
+import { loadLocalCredentials } from "./credentials-file.js";
+import { PlaywrightBrowserPort, readUnpackedExtension } from "@jevitate/playwright";
+import { realVerifyFetch } from "./key-report.js";
+import { preflightRunKeys } from "./run-key-preflight.js";
+import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
+import { UnsafeNameError, assertSafeName } from "@jevitate/domain";
+import { fail } from "./envelope.js";
+import { projectDataDir } from "./project-dir.js";
+import { resolveUsagePricing } from "./usage-config.js";
+import { realOpenRouterCall } from "./openrouter-call.js";
+import { emitJsonOrRefusal } from "./cli-refusal.js";
+import { emitEnvelope } from "./cli-output.js";
+import { resolveDataDir } from "./data-dir.js";
+import { FsTrustStore, FsAckStore, DEFAULT_LOCK_PATH } from "@jevitate/sources";
+import { parseViewport, resolveEmulation } from "@jevitate/playwright";
+import { nonNegativeIntArg, positiveIntArg } from "./cli-args.js";
+import { resourceLimitsFromFlags, withResourcePreflight } from "./resource-preflight.js";
+import { HEADED_DEFAULT_SLOW_MO_MS, assertHeadedDisplay, headedFromEnv, sessionLaunchOptions } from "./browser-run-options.js";
+// `~/.jevitate/*` is the product's runtime-data convention (product = Jevitate).
+// See data-dir.ts.
+export const DEFAULT_DB_PATH = resolveDataDir(["db.sqlite"]);
+export const DEFAULT_MISSION_TARGETS_DIR = resolveDataDir(["missions", "targets"]);
+export const DEFAULT_INBOX_DIR = resolveDataDir(["inbox"]);
+export function resolveDbPath(deps, flag) {
+    return flag ?? deps.dbPath ?? DEFAULT_DB_PATH;
+}
+/** #247: where `--env` reads environments and per-origin sessions from (test seams; real defaults). */
+export function environmentSeams(deps) {
+    return {
+        ...(deps.environmentsFile === undefined ? {} : { environmentsFile: deps.environmentsFile }),
+        ...(deps.explore?.targetsConfigPath === undefined ? {} : { targetsFile: deps.explore.targetsConfigPath }),
+    };
+}
+/**
+ * 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 function resolveJourneysDir(deps, flag) {
+    return flag ?? deps.journeysDir ?? projectDataDir(["journeys"]);
+}
+/** Same flag > home-dir-default convention as `resolveJourneysDir`, for the
+ *  committed-regressions directory `regression capture` writes into. */
+export function resolveRegressionsDir(flag) {
+    return flag ?? projectDataDir(["regressions"]);
+}
+/** Same flag > deps > home-dir-default convention as `resolveJourneysDir`, for
+ *  the mission-targets store `mission target ...` reads/writes. */
+export function resolveMissionTargetsDir(deps, flag) {
+    return flag ?? deps.missionTargetsDir ?? DEFAULT_MISSION_TARGETS_DIR;
+}
+/** 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 function resolveInboxDir(deps, flag) {
+    return flag ?? deps.inboxDir ?? DEFAULT_INBOX_DIR;
+}
+/**
+ * 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 function resolveSourceApiDeps(deps) {
+    const s = deps.sources ?? {};
+    return {
+        sourcesDir: s.sourcesDir ?? resolveDataDir(["sources"]),
+        lockPath: s.lockPath ?? DEFAULT_LOCK_PATH(),
+        trust: new FsTrustStore(s.trustDir ?? resolveDataDir(["trust"])),
+        ack: new FsAckStore(s.ackDir ?? resolveDataDir(["trust", "acks"])),
+        git: s.git,
+        now: s.now,
+    };
+}
+/** The identity recorded in a `TrustRecord`/`TouAck` — an injected value, else
+ *  the OS username, else `"local"`. Never a secret/credential. */
+export function resolveApprovedBy(deps) {
+    if (deps.sources?.approvedBy)
+        return deps.sources.approvedBy;
+    try {
+        return userInfo().username || "local";
+    }
+    catch {
+        return "local";
+    }
+}
+/**
+ * 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 async function makeRealBrowserActor(site, storageState, emulation, browser, portFactory = () => new PlaywrightBrowserPort(), 
+/** #247: an environment's allowed origins (default: just `site`). */
+allowedOrigins = [site]) {
+    const port = portFactory();
+    const session = await port.open({
+        ...sessionLaunchOptions(browser),
+        allowedOrigins: [...allowedOrigins],
+        baseUrl: site,
+        ...emulation,
+        ...(storageState !== undefined ? { storageState } : {}),
+    });
+    const actor = CastActor.named("regression-capture").whoCan(new BrowseTheWeb(session, [...allowedOrigins]));
+    return {
+        actor,
+        close: () => session.close(),
+    };
+}
+/**
+ * #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 function extensionArg(value, prev) {
+    const before = prev ?? [];
+    let ext;
+    try {
+        ext = readUnpackedExtension(value);
+    }
+    catch (err) {
+        throw new InvalidArgumentError(err instanceof Error ? err.message : String(err));
+    }
+    const dup = before.find((e) => e.id === ext.id);
+    if (dup === undefined)
+        return [...before, ext];
+    if (dup.dir === ext.dir)
+        return [...before];
+    throw new InvalidArgumentError(`two extension directories have the same extension id ${ext.id}: ${dup.dir} and ${ext.dir}`);
+}
+/**
+ * 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 function withBrowserLaunchFlags(cmd) {
+    // #205: resource governance — the run's limits, and the pre-run checks (orphan sweep, starved-host refusal).
+    return withResourcePreflight(cmd)
+        .option("--max-browsers <n>", "machine-wide cap on jevitate runs with a browser open at once, shared by every jevitate on this machine (default: JEVITATE_MAX_BROWSERS, else cores/4 within 2..6; halved while the host is loaded)", positiveIntArg)
+        .option("--max-browser-memory <MiB>", "memory ceiling of this run's browsers (browser + renderers); over it the run ends inconclusive with failure kind resource-limit (default: JEVITATE_MAX_BROWSER_MEMORY_MB, else 4096 or half the RAM)", positiveIntArg)
+        .option("--ignore-host-load", "start even when the host is starved (load >= 4/core or < 512 MiB free) instead of refusing with E_HOST_STARVED; the run is throttled and its result records it")
+        .option("--browser-executable <path>", "launch this Chromium binary instead of Playwright's pinned one")
+        .option("--browser-channel <name>", "Playwright browser channel to launch, e.g. chrome | msedge")
+        .option("--browser-arg <arg>", "extra Chromium switch (repeatable); extends the Linux defaults --no-sandbox --disable-dev-shm-usage", (v, prev) => [...prev, v], [])
+        .option("--extension <dir>", "load this unpacked browser extension (repeatable; a directory with manifest.json). Its chrome-extension://<id> pages are allowed and navigable, e.g. --url chrome-extension://<id>/sidepanel.html; headless uses Chromium's new headless", extensionArg, []);
+}
+/** The `BrowserLaunchOptions` for the parsed flags, or `undefined` when none were given. */
+export function browserLaunchFromFlags(o) {
+    const launch = {
+        ...(o.browserExecutable !== undefined ? { executablePath: o.browserExecutable } : {}),
+        ...(o.browserChannel !== undefined ? { channel: o.browserChannel } : {}),
+        ...(o.browserArg.length > 0 ? { args: [...o.browserArg] } : {}),
+        ...(o.extension !== undefined && o.extension.length > 0 ? { extensions: [...o.extension] } : {}),
+    };
+    const resources = resourceLimitsFromFlags(o);
+    if (resources !== undefined)
+        launch.resources = resources;
+    return Object.keys(launch).length > 0 ? launch : undefined;
+}
+/**
+ * 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 function withDemoFlags(cmd, set = {}) {
+    cmd
+        .option("--headed", `show the browser window (demo mode); also JEVITATE_HEADED=1. Default: headless. Needs a display${set.recordVideo === true ? " — else use --record-video" : ""}`)
+        .option("--slow-mo <ms>", `slow every browser operation by this many ms (default ${HEADED_DEFAULT_SLOW_MO_MS} with --headed, else 0)`, nonNegativeIntArg);
+    if (set.recordVideo === true) {
+        cmd.option("--record-video [dir]", "record a video of each browser context (works headless too); default: next to the run's result; listed as videoPaths");
+    }
+    if (set.overlay === true)
+        cmd.option("--no-overlay", "with --headed: hide the on-page overlay (step, intent, target highlight, outcome banner)");
+    return cmd;
+}
+/**
+ * #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 function withScreenshotsFlag(cmd) {
+    return cmd.option("--screenshots [mode|dir]", "masked screenshots + index.md: one per distinct screen (default), `steps` one per step; `screens:<dir>`/`steps:<dir>`/`<dir>` set the folder (default: next to the run's result); listed as screenshotPaths");
+}
+/**
+ * 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 function browserRunFromFlags(o, env = process.env, platform = process.platform) {
+    const headed = o.headed === true || headedFromEnv(env);
+    assertHeadedDisplay(headed, env, platform);
+    const run = {
+        ...browserLaunchFromFlags(o),
+        ...(headed ? { headed: true } : {}),
+        ...(o.slowMo === undefined ? {} : { slowMo: o.slowMo }),
+        ...(o.recordVideo === undefined || o.recordVideo === false
+            ? {}
+            : { recordVideo: typeof o.recordVideo === "string" ? { dir: resolvePath(o.recordVideo) } : {} }),
+        ...(o.overlay === false ? { overlay: false } : {}),
+    };
+    return Object.keys(run).length > 0 ? run : undefined;
+}
+/** `{ browser }` for the parsed `--browser-*` flags, or `{}` when none were given — spread into a runner's options. */
+export function browserOption(o) {
+    const launch = browserLaunchFromFlags(o);
+    return launch === undefined ? {} : { browser: launch };
+}
+/**
+ * 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 function withEmulationFlags(cmd) {
+    return cmd
+        .option("--viewport <WxH>", "emulate a viewport of this size, e.g. --viewport 375x812 (mutually exclusive with --device)")
+        .option("--device <name>", 'emulate a Playwright registered device by name, e.g. --device "iPhone 13" (viewport + scale + mobile/touch + UA; mutually exclusive with --viewport)');
+}
+/**
+ * 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 function emulationFromFlags(o) {
+    const spec = {
+        ...(o.viewport !== undefined ? { viewport: parseViewport(o.viewport) } : {}),
+        ...(o.device !== undefined ? { device: o.device } : {}),
+    };
+    if (Object.keys(spec).length === 0)
+        return undefined;
+    resolveEmulation(spec); // throws UnknownDeviceError / ConflictingEmulationError before any browser opens
+    return spec;
+}
+/**
+ * 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 function collectParam(value, previous) {
+    const idx = value.indexOf("=");
+    const key = idx === -1 ? value : value.slice(0, idx);
+    const val = idx === -1 ? "" : value.slice(idx + 1);
+    return { ...previous, [key]: val };
+}
+export function makeClock() {
+    return {
+        nowIso: () => clock.nowIso(),
+        monotonicMs: () => clock.now(),
+    };
+}
+export async function withSitePolicyRepository(dbPath, fn) {
+    await mkdir(dirname(dbPath), { recursive: true });
+    const db = openDatabase(dbPath);
+    try {
+        await migrateToLatest(db);
+        const repository = new SqliteSitePolicyRepository(db, makeClock());
+        return await fn(repository);
+    }
+    finally {
+        await db.destroy();
+    }
+}
+export function isPlannedStep(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (typeof record.label !== "string")
+        return false;
+    switch (record.kind) {
+        case "type":
+            return typeof record.text === "string";
+        case "click":
+        case "navigate":
+            return true;
+        case "read":
+            return typeof record.chars === "number";
+        default:
+            return false;
+    }
+}
+export function parsePlannedScript(raw) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || !parsed.every(isPlannedStep)) {
+        throw new Error("script must be a JSON array of planned steps ({kind, label, ...})");
+    }
+    return parsed;
+}
+/**
+ * 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 function emitJson(program, envelope) {
+    // #218: a refusal without --json is a human `error <CODE>: …` line on stderr (cli-refusal.ts).
+    emitJsonOrRefusal(program, envelope);
+    if (envelope.ok)
+        emitUsageLine(program, envelope.data);
+}
+/**
+ * #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 function emitCommandResult(program, envelope, opts) {
+    emitEnvelope(program, envelope, opts);
+    if (envelope.ok)
+        emitUsageLine(program, envelope.data);
+}
+/**
+ * #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 function refuseUnsafeName(program, name, what) {
+    try {
+        assertSafeName(name, what);
+        return false;
+    }
+    catch (err) {
+        if (!(err instanceof UnsafeNameError))
+            throw err;
+        emitJson(program, fail(err.code, err.message));
+        return true;
+    }
+}
+/** A non-`--json` result: printed as bare JSON on stdout, with the cost summary line on stderr. */
+export function writeRawResult(program, result) {
+    program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
+    emitUsageLine(program, result);
+}
+/** A non-`--json` result (#227): the human summary a `cli-output.ts` formatter renders, with the cost summary line on stderr. */
+export function writeHumanResult(program, result, human) {
+    const text = human(result);
+    if (text !== "")
+        program.configureOutput().writeOut?.(text);
+    emitUsageLine(program, result);
+}
+/**
+ * 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 function emitUsageLine(program, data) {
+    if (data === null || typeof data !== "object")
+        return;
+    const usage = usageCountsFrom(data.usage);
+    if (usage === undefined || usage.judgments + usage.generations === 0)
+        return;
+    program.configureOutput().writeErr?.(`usage: ${formatUsageLine(usage)}\n`);
+}
+/**
+ * `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 function stallTimeoutMs(raw) {
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds > 0 ? Math.round(seconds * 1000) : null;
+}
+/** #230: the only `--strategy` values `explore` accepts; anything else is refused, never silently run as goal. */
+export const EXPLORE_STRATEGIES = ["goal", "coverage", "exploratory", "adversarial", "usability"];
+export const EXPLORE_OUTCOME_HELP = `
+Outcomes, stop reasons and exit codes:
+  Every result carries a canonical missionOutcome (and exitCode), whatever the strategy:
+    clean 0 · defects-found 1 · inconclusive 2 · crashed 2 · hang 3 · intermittent 4
+  --strategy goal also carries its own ending as "goalOutcome" (= its "outcome"), folded onto missionOutcome:
+    succeeded → clean 0 · failed / exhausted / blocked → defects-found 1
+    (defects-found, inconclusive, crashed, hang, intermittent are themselves)
+  --strategy goal's "stop" (why the loop itself stopped; not separately exit-coded):
+    done | blocked | exhausted | no-progress | hang | inconclusive | crashed | budget
+    (a "done" code rejected ends stop done, goalOutcome failed — never blocked)
+  --strategy adversarial's "stop" (why the hunt ended; its "outcome" is the canonical one above):
+    step-budget | action-budget | time-budget | strategies-exhausted | not-rendered
+    | scope-unreachable | targets-refused | target-unresponsive | identity-changed | stalled | hang
+    | crashed
+    (identity-changed: an action switched the signed-in identity and the original one could not be
+    restored — inconclusive; every switch is listed in "identityChanges")
+  --strategy coverage/exploratory's own "outcome" (folds into missionOutcome above):
+    exhausted | insufficient-coverage | cap | scope-unreachable | stalled | crashed | hang
+  A run that proved nothing is inconclusive with failure.kind insufficient-coverage (the same word as
+  the frontier outcome), and failure.message says how to reach clean.
+  A starved host (#203): every result carries "hostHealth" (peak load/core, min free memory, peak
+  event-loop lag, slowest render). A hang, click timeout or no-progress met while the host was
+  starved is listed in "environmentDegraded" (advisory, never a finding); a run most of whose steps
+  ran starved is inconclusive (failure.kind degraded-environment), never clean.
+  --feature's own "outcome" (folds into missionOutcome above):
+    exhausted | insufficient-coverage | cap | path-cap | scope-unreachable | stalled | crashed | hang
+  Argument/input errors (E_EXPLORE_ARGS, E_EXPLORE_ASSERTION, …) exit 64, never 1.
+  Without --json: a human summary (verdict, defects by fingerprint, result file, next step);
+  with --json: the {v, ok, data} envelope.
+  Every command's exit codes: docs/outcomes.md "Exit codes".
+`;
+/** #291: the startup key check's env (opt-out) and verifier (injectable: tests never touch the network). */
+function keyPreflightOpts(deps) {
+    return { env: deps.explore?.env ?? process.env, fetchFn: deps.explore?.verifyFetch ?? deps.ai?.verifyFetch ?? realVerifyFetch };
+}
+/** Distinct from MissingCredentialError: "no --real/--fake-ai selected" vs "keys missing." */
+export class GatewaySelectionError extends Error {
+}
+export const DEFAULT_EXPLORE_CATALOG = [
+    { id: "openai/gpt-4o-mini", promptUsdPer1k: 0.15, completionUsdPer1k: 0.6, regions: [], latencyClass: "fast", capabilities: [] },
+];
+export const DEFAULT_EXPLORE_CONSTRAINTS = { requiredCapabilities: [] };
+/**
+ * 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 async function buildExploreGateways(deps, opts) {
+    // #100: ONE tracker per invocation, handed to whichever gateways are built below — real (counted
+    // at the innermost seam, so a retry counts too) or fake (0 tokens, so a test can assert the shape
+    // without a key). Injected gateways (tests) get an empty tracker: they have no real seam to count.
+    // #136/#163: configured prices (env/config) override the built-in, versioned price tables.
+    // #213: --real and --fake-ai are mutually exclusive — silently preferring one (real used to win)
+    // hides that the caller's own flags contradict each other.
+    if (opts.real && opts.fakeAi) {
+        throw new GatewaySelectionError("--real and --fake-ai are mutually exclusive — pass one, not both");
+    }
+    const usage = deps.explore?.usage ?? new UsageTracker(resolveUsagePricing(deps.explore?.env ?? process.env));
+    if (deps.explore?.judge && deps.explore?.gen) {
+        return { judge: deps.explore.judge, gen: deps.explore.gen, usage };
+    }
+    const store = envCredentialStore(deps.explore?.env ?? process.env, deps.explore?.localConfig ?? loadLocalCredentials());
+    if (opts.real) {
+        requireKeys("generation", store); // fail-closed
+        requireKeys("judgment", store); // fail-closed
+        // #291: a key the provider rejects fails the run at startup (typed setup refusal), once per process.
+        await preflightRunKeys(["generation", "judgment"], store, keyPreflightOpts(deps));
+        const gen = new OpenRouterGenerationGateway({
+            store,
+            catalog: DEFAULT_EXPLORE_CATALOG,
+            constraints: DEFAULT_EXPLORE_CONSTRAINTS,
+            call: await realOpenRouterCall(usage),
+        });
+        const judge = new JevJudgmentGateway(store, await realJevClientCall(undefined, usage));
+        // Transient model/network failures are retried with exponential backoff + jitter (≈16s), then
+        // fail typed; validation/auth errors fail at once (owner ruling 4).
+        return { judge: new RetryingJudgmentPort(judge), gen: new RetryingGenerationPort(gen), usage };
+    }
+    if (opts.fakeAi) {
+        return { judge: fakeDoneJudge(usage), gen: new FakeGenerationGateway(undefined, usage), usage };
+    }
+    throw new GatewaySelectionError("no gateway selected — pass --real for live Jev+OpenRouter (after `jevitate ai setup`), or --fake-ai for a deterministic pipeline smoke");
+}
+/**
+ * #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 async function buildGenerationGateway(deps, opts) {
+    if (opts.real && opts.fakeAi) {
+        throw new GatewaySelectionError("--real and --fake-ai are mutually exclusive — pass one, not both");
+    }
+    const usage = deps.explore?.usage ?? new UsageTracker(resolveUsagePricing(deps.explore?.env ?? process.env));
+    if (deps.explore?.gen)
+        return { gen: deps.explore.gen, usage };
+    if (opts.real) {
+        const store = envCredentialStore(deps.explore?.env ?? process.env, deps.explore?.localConfig ?? loadLocalCredentials());
+        requireKeys("generation", store); // fail-closed
+        await preflightRunKeys(["generation"], store, keyPreflightOpts(deps)); // #291
+        const gen = new OpenRouterGenerationGateway({
+            store,
+            catalog: DEFAULT_EXPLORE_CATALOG,
+            constraints: DEFAULT_EXPLORE_CONSTRAINTS,
+            call: await realOpenRouterCall(usage),
+        });
+        return { gen: new RetryingGenerationPort(gen), usage };
+    }
+    if (opts.fakeAi)
+        return { gen: new FakeGenerationGateway(undefined, usage), usage };
+    throw new GatewaySelectionError("no gateway selected — pass --real for live OpenRouter generation (after `jevitate ai setup generation`), or --fake-ai for a deterministic pipeline smoke");
+}
+/**
+ * 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 function fakeDoneJudge(usage) {
+    return {
+        async systemOne(args) {
+            const out = {};
+            for (const [name, q] of Object.entries(args.questions)) {
+                switch (q.kind) {
+                    case "choice": {
+                        // #213: total over every choice family, not just the goal/coverage loop's `done`.
+                        const value = q.options.includes("done") ? "done" : q.options[0];
+                        if (value === undefined)
+                            throw new Error(`fake judge: question '${name}' offers no options`);
+                        out[name] = { kind: "choice", value, confidence: 1 };
+                        break;
+                    }
+                    case "noul":
+                        out[name] = { kind: "noul", value: false, probability: 0 };
+                        break;
+                    case "score":
+                        out[name] = { kind: "score", value: 0 };
+                        break;
+                    default: {
+                        const exhaustive = q;
+                        throw new Error(`fake judge: unsupported question ${JSON.stringify(exhaustive)}`);
+                    }
+                }
+            }
+            usage?.recordJudgment(FAKE_CALL_USAGE);
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=cli-shared.js.map

package/dist/cli-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-shared.js","sourceRoot":"","sources":["../src/cli-shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAW,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAE1D,OAAO,EAAoB,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACrG,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,GAShB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAA0B,MAAM,sBAAsB,CAAC;AAC5G,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAc,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAqB,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AAGjE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAA6B,MAAM,mBAAmB,CAAC;AAE3G,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAsB,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAwB,MAAM,yBAAyB,CAAC;AAC/G,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,aAAa,EAAE,oBAAoB,EAA0B,MAAM,0BAA0B,CAAC;AAsFvJ,iFAAiF;AACjF,mBAAmB;AACnB,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,2BAA2B,GAAG,cAAc,CAAC,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAE3D,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,IAAa;IACxD,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;AAChD,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,OAAO;QACL,GAAG,CAAC,IAAI,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC3F,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;KAC1G,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa,EAAE,IAAa;IAC7D,OAAO,IAAI,IAAI,IAAI,CAAC,WAAW,IAAI,cAAc,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,OAAO,IAAI,IAAI,cAAc,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,wBAAwB,CAAC,IAAa,EAAE,IAAa;IACnE,OAAO,IAAI,IAAI,IAAI,CAAC,iBAAiB,IAAI,2BAA2B,CAAC;AACvE,CAAC;AAED;;;wCAGwC;AACxC,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,IAAa;IAC1D,OAAO,IAAI,IAAI,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IAC7B,OAAO;QACL,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC;QACvD,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,iBAAiB,EAAE;QAC3C,KAAK,EAAE,IAAI,YAAY,CAAC,CAAC,CAAC,QAAQ,IAAI,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAChE,GAAG,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QAClE,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,GAAG,EAAE,CAAC,CAAC,GAAG;KACX,CAAC;AACJ,CAAC;AAED;kEACkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,IAAI,IAAI,CAAC,OAAO,EAAE,UAAU;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;IAC7D,IAAI,CAAC;QACH,OAAO,QAAQ,EAAE,CAAC,QAAQ,IAAI,OAAO,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAY,EACZ,YAAqB,EACrB,SAAyB,EACzB,OAA2B,EAC3B,cAAiC,GAAG,EAAE,CAAC,IAAI,qBAAqB,EAAE;AAClE,qEAAqE;AACrE,iBAAoC,CAAC,IAAI,CAAC;IAE1C,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC;QAC9B,GAAG,oBAAoB,CAAC,OAAO,CAAC;QAChC,cAAc,EAAE,CAAC,GAAG,cAAc,CAAC;QACnC,OAAO,EAAE,IAAI;QACb,GAAG,SAAS;QACZ,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3G,OAAO;QACL,KAAK;QACL,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;KAC7B,CAAC;AACJ,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,IAA8C;IACxF,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;IAC1B,IAAI,GAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,oBAAoB,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;IAChD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5C,MAAM,IAAI,oBAAoB,CAAC,wDAAwD,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,GAAG,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;AAC9H,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,6GAA6G;IAC7G,OAAO,qBAAqB,CAAC,GAAG,CAAC;SAC9B,MAAM,CAAC,oBAAoB,EAAE,qMAAqM,EAAE,cAAc,CAAC;SACnP,MAAM,CAAC,4BAA4B,EAAE,sMAAsM,EAAE,cAAc,CAAC;SAC5P,MAAM,CAAC,oBAAoB,EAAE,gKAAgK,CAAC;SAC9L,MAAM,CAAC,6BAA6B,EAAE,gEAAgE,CAAC;SACvG,MAAM,CAAC,0BAA0B,EAAE,4DAA4D,CAAC;SAChG,MAAM,CACL,qBAAqB,EACrB,qGAAqG,EACrG,CAAC,CAAC,EAAE,IAAc,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EACnC,EAAc,CACf;SACA,MAAM,CACL,mBAAmB,EACnB,0OAA0O,EAC1O,YAAY,EACZ,EAAyB,CAC1B,CAAC;AACN,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,sBAAsB,CAAC,CAAqB;IAC1D,MAAM,MAAM,GAAyB;QACnC,GAAG,CAAC,CAAC,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,GAAG,CAAC,CAAC,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjG,CAAC;IACF,MAAM,SAAS,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAkBD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,MAAmB,EAAE;IAC/D,GAAG;SACA,MAAM,CAAC,UAAU,EAAE,kGAAkG,GAAG,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;SACpL,MAAM,CAAC,gBAAgB,EAAE,yDAAyD,yBAAyB,yBAAyB,EAAE,iBAAiB,CAAC,CAAC;IAC5J,IAAI,GAAG,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC7B,GAAG,CAAC,MAAM,CAAC,sBAAsB,EAAE,sHAAsH,CAAC,CAAC;IAC7J,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI;QAAE,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,0FAA0F,CAAC,CAAC;IACjJ,OAAO,GAAG,CAAC;AACb,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,GAAG,CAAC,MAAM,CACf,0BAA0B,EAC1B,6MAA6M,CAC9M,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,CAAiC,EACjC,MAAoD,OAAO,CAAC,GAAG,EAC/D,WAA4B,OAAO,CAAC,QAAQ;IAE5C,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IACvD,mBAAmB,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAsB;QAC7B,GAAG,sBAAsB,CAAC,CAAC,CAAC;QAC5B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QACvD,GAAG,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,KAAK;YACxD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAClG,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,aAAa,CAAC,CAAqB;IACjD,MAAM,MAAM,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;IACzC,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACzD,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,GAAG;SACP,MAAM,CAAC,kBAAkB,EAAE,6FAA6F,CAAC;SACzH,MAAM,CACL,iBAAiB,EACjB,sJAAsJ,CACvJ,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAiB;IAClD,MAAM,IAAI,GAAkB;QAC1B,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACrD,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,iFAAiF;IACzG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAAgC;IAC1E,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACnD,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE;QAC5B,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;KAC/B,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAc,EACd,EAA0D;IAE1D,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,eAAe,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,UAAU,GAAG,IAAI,0BAA0B,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QACnE,OAAO,MAAM,EAAE,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACnD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC;QACzC,KAAK,OAAO,CAAC;QACb,KAAK,UAAU;YACb,OAAO,IAAI,CAAC;QACd,KAAK,MAAM;YACT,OAAO,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC;QAC1C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAgB,EAAE,QAA+B;IACxE,+FAA+F;IAC/F,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACrC,IAAI,QAAQ,CAAC,EAAE;QAAE,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAI,OAAgB,EAAE,QAAyB,EAAE,IAAoB;IACpG,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtC,IAAI,QAAQ,CAAC,EAAE;QAAE,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,IAAY,EAAE,IAAY;IAC3E,IAAI,CAAC;QACH,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,eAAe,CAAC;YAAE,MAAM,GAAG,CAAC;QACjD,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,MAAe;IAC9D,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpE,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC;AAED,iIAAiI;AACjI,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,MAAe,EAAE,KAAgC;IAClG,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;IAC5D,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAa;IAC3D,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO;IACtD,MAAM,KAAK,GAAG,eAAe,CAAE,IAA4B,CAAC,KAAK,CAAC,CAAC;IACnE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,WAAW,KAAK,CAAC;QAAE,OAAO;IAC7E,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,UAAU,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,sHAAsH;AACtH,MAAM,UAAU,cAAc,CAAC,GAAgC;IAC7D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrF,CAAC;AAED,kHAAkH;AAClH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,CAAU,CAAC;AAE3G,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BnC,CAAC;AAEF,4GAA4G;AAC5G,SAAS,gBAAgB,CAAC,IAAa;IACrC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,IAAI,IAAI,CAAC,EAAE,EAAE,WAAW,IAAI,eAAe,EAAE,CAAC;AAClI,CAAC;AAED,8FAA8F;AAC9F,MAAM,OAAO,qBAAsB,SAAQ,KAAK;CAAG;AAEnD,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,EAAE,EAAE,EAAE,oBAAoB,EAAE,cAAc,EAAE,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE;CACjI,CAAC;AACF,MAAM,CAAC,MAAM,2BAA2B,GAAqB,EAAE,oBAAoB,EAAE,EAAE,EAAE,CAAC;AAE1F;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAa,EACb,IAAwC;IAExC,iGAAiG;IACjG,kGAAkG;IAClG,mGAAmG;IACnG,2FAA2F;IAC3F,iGAAiG;IACjG,2DAA2D;IAC3D,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,qBAAqB,CAAC,kEAAkE,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,IAAI,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7G,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;IACrE,CAAC;IACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACxH,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,WAAW,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,cAAc;QAChD,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,cAAc;QAC9C,qGAAqG;QACrG,MAAM,gBAAgB,CAAC,CAAC,YAAY,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;QAClF,MAAM,GAAG,GAAG,IAAI,2BAA2B,CAAC;YAC1C,KAAK;YACL,OAAO,EAAE,uBAAuB;YAChC,WAAW,EAAE,2BAA2B;YACxC,IAAI,EAAE,MAAM,kBAAkB,CAAC,KAAK,CAAC;SACtC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,kBAAkB,CAAC,KAAK,EAAE,MAAM,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACvF,8FAA8F;QAC9F,oEAAoE;QACpE,OAAO,EAAE,KAAK,EAAE,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,sBAAsB,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;IACjG,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;IAClG,CAAC;IACD,MAAM,IAAI,qBAAqB,CAC7B,wIAAwI,CACzI,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAa,EACb,IAAwC;IAExC,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,qBAAqB,CAAC,kEAAkE,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,IAAI,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7G,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG;QAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;IAC/D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,IAAI,oBAAoB,EAAE,CAAC,CAAC;QACxH,WAAW,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,cAAc;QAChD,MAAM,gBAAgB,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO;QAC9E,MAAM,GAAG,GAAG,IAAI,2BAA2B,CAAC;YAC1C,KAAK;YACL,OAAO,EAAE,uBAAuB;YAChC,WAAW,EAAE,2BAA2B;YACxC,IAAI,EAAE,MAAM,kBAAkB,CAAC,KAAK,CAAC;SACtC,CAAC,CAAC;QACH,OAAO,EAAE,GAAG,EAAE,IAAI,sBAAsB,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,GAAG,EAAE,IAAI,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;IACpF,MAAM,IAAI,qBAAqB,CAC7B,0JAA0J,CAC3J,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAmE;YACjF,MAAM,GAAG,GAA2B,EAAE,CAAC;YACvC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBACvD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;oBACf,KAAK,QAAQ,CAAC,CAAC,CAAC;wBACd,kFAAkF;wBAClF,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;wBACjE,IAAI,KAAK,KAAK,SAAS;4BAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,qBAAqB,CAAC,CAAC;wBAC7F,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;wBACrD,MAAM;oBACR,CAAC;oBACD,KAAK,MAAM;wBACT,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;wBAC3D,MAAM;oBACR,KAAK,OAAO;wBACV,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;wBACxC,MAAM;oBACR,OAAO,CAAC,CAAC,CAAC;wBACR,MAAM,UAAU,GAAU,CAAC,CAAC;wBAC5B,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;oBACpF,CAAC;gBACH,CAAC;YACH,CAAC;YACD,KAAK,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;YACvC,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli-surface.d.ts

@@ -0,0 +1,33 @@
+import type { Command, Option, Argument } from "commander";
+/** Best-effort placeholder for absolute, environment-dependent paths (home dir, cwd, tmp). */
+export declare function normalizeVolatile(text: string): string;
+export interface OptionSurface {
+    readonly flags: string;
+    readonly description: string;
+    readonly defaultValue: string;
+    readonly choices: readonly string[] | null;
+    readonly required: boolean;
+    readonly mandatory: boolean;
+    readonly negate: boolean;
+    readonly variadic: boolean;
+    readonly envVar: string | null;
+}
+export interface ArgumentSurface {
+    readonly name: string;
+    readonly description: string;
+    readonly required: boolean;
+    readonly variadic: boolean;
+    readonly defaultValue: string;
+    readonly choices: readonly string[] | null;
+}
+export interface CommandSurface {
+    readonly path: string;
+    readonly aliases: readonly string[];
+    readonly description: string;
+    readonly arguments: readonly ArgumentSurface[];
+    readonly options: readonly OptionSurface[];
+}
+export declare function describeOption(o: Option): OptionSurface;
+export declare function describeArgument(a: Argument): ArgumentSurface;
+/** Walks the ENTIRE command tree recursively (subcommands of subcommands included, e.g. `mission target add`). */
+export declare function walk(cmd: Command, path: string): CommandSurface[];

package/dist/cli-surface.js

@@ -0,0 +1,48 @@
+/** Best-effort placeholder for absolute, environment-dependent paths (home dir, cwd, tmp). */
+export function normalizeVolatile(text) {
+    return text
+        .split(process.cwd()).join("<cwd>")
+        .replace(/\/home\/[^/\s"']+/g, "<home>")
+        .replace(/\/root(?=[/\s"'])/g, "<home>");
+}
+export function describeOption(o) {
+    return {
+        flags: o.flags,
+        description: normalizeVolatile(o.description),
+        defaultValue: normalizeVolatile(JSON.stringify(o.defaultValue ?? null)),
+        choices: o.argChoices ?? null,
+        required: o.required,
+        mandatory: o.mandatory,
+        negate: o.negate,
+        variadic: o.variadic,
+        envVar: o.envVar ?? null,
+    };
+}
+export function describeArgument(a) {
+    return {
+        name: a.name(),
+        description: normalizeVolatile(a.description),
+        required: a.required,
+        variadic: a.variadic,
+        defaultValue: normalizeVolatile(JSON.stringify(a.defaultValue ?? null)),
+        choices: a.argChoices ?? null,
+    };
+}
+/** Walks the ENTIRE command tree recursively (subcommands of subcommands included, e.g. `mission target add`). */
+export function walk(cmd, path) {
+    const here = {
+        path,
+        aliases: [...cmd.aliases()].sort(),
+        description: normalizeVolatile(cmd.description()),
+        // Positional arguments: order is semantically meaningful (they're positional), never sorted.
+        arguments: cmd.registeredArguments.map(describeArgument),
+        // Options: sorted so option-registration order (an implementation detail) never causes a diff.
+        options: [...cmd.options].map(describeOption).sort((a, b) => a.flags.localeCompare(b.flags)),
+    };
+    const children = [...cmd.commands]
+        .filter((c) => c.name() !== "help") // Commander's auto-added implicit help subcommand: not user surface.
+        .sort((a, b) => a.name().localeCompare(b.name()))
+        .flatMap((c) => walk(c, path === "" ? c.name() : `${path} ${c.name()}`));
+    return [here, ...children];
+}
+//# sourceMappingURL=cli-surface.js.map