@jevitate/cli 0.1.0 → 0.2.0

package/dist/ledger-api.d.ts

@@ -0,0 +1,106 @@
+import { type RunVerifyFixOptions, type VerifyFixReport } from "./verify-fix-api.js";
+import { type EngineInfo } from "./engine.js";
+/**
+ * The finding ledger (#195 part 6): a built-in store of the repro material `verify-fix` needs,
+ * keyed by fingerprint, so "is it still fixed?" can be asked months later from the fingerprint
+ * alone — after the run's `.jevitate/logs/<date>/` output has been pruned by retention.
+ *
+ * It extends the committed regressions store rather than duplicating it: entries live in
+ * `<regressions>/ledger/<fingerprint>.json` (default `.jevitate/regressions/ledger/`, committed with
+ * the app's code, like `regression capture`'s artifacts). Each entry is a minimal, self-contained
+ * mission result — `{ ledger, result }` — that `runVerifyFix` reads exactly like a `<stem>.result.json`.
+ *
+ * What an entry holds is ALLOW-LISTED, never a copy of the result: the finding itself (with its own
+ * path Recording, when it has one), the run's Recording only when the finding has none, the scope
+ * (`seedUrl` + `allowlist`), the declared-invariant spec and the fixture spec the replay re-checks,
+ * and the write controls the run fired (for hang-replay safety). Never a storage state, a session
+ * PATH, an actor's session, the transcript, page text, screenshots or usage: a replay of an
+ * authenticated target takes `--storage-state` (or the operator's targets.json session) at verify
+ * time. A value the caller names as secret (`--secret`) anywhere in the material refuses the add.
+ */
+export declare const LEDGER_ENTRY_VERSION: 1;
+export declare class LedgerError extends Error {
+    readonly code: "E_LEDGER_INPUT" | "E_LEDGER_NOT_FOUND" | "E_LEDGER_SECRET";
+    constructor(code: LedgerError["code"], message: string);
+}
+export interface LedgerMeta {
+    readonly version: typeof LEDGER_ENTRY_VERSION;
+    readonly fingerprint: string;
+    readonly kind: string;
+    readonly title?: string;
+    /** The tracker ticket the finding was filed as (`--ticket`). */
+    readonly ticket?: string;
+    readonly addedAt: string;
+    /** Where the material came from: the result's file NAME (never a machine-local path), its strategy and build. */
+    readonly source: {
+        readonly result: string;
+        readonly strategy?: string;
+        readonly missionOutcome?: string;
+        readonly engine?: EngineInfo;
+    };
+    /** The build that added it. */
+    readonly addedBy: EngineInfo;
+}
+export interface LedgerEntry {
+    readonly ledger: LedgerMeta;
+    readonly result: Record<string, unknown>;
+}
+/** `<regressions>/ledger` — `.jevitate/regressions/ledger` in a project, else `~/.jevitate/regressions/ledger`. */
+export declare function ledgerDir(regressionsDir?: string): string;
+export interface LedgerAddOptions {
+    readonly resultPath: string;
+    readonly fingerprint: string;
+    readonly ticket?: string;
+    /** `<regressions>` dir (CLI `--dir`); default `.jevitate/regressions`. */
+    readonly regressionsDir?: string;
+    /** Values that must never be stored (CLI `--secret`): an add whose material contains one is refused. */
+    readonly secrets?: readonly string[];
+    /** Test seam. */
+    readonly nowIso?: () => string;
+}
+export interface LedgerAddResult {
+    readonly entryPath: string;
+    readonly fingerprint: string;
+    readonly kind: string;
+    readonly title?: string;
+    readonly ticket?: string;
+    /** True when an entry for this fingerprint already existed (its `addedAt` is kept). */
+    readonly updated: boolean;
+}
+/** `jevitate ledger add <result> <fp>`: stores the redacted repro material `verify-fix` needs. */
+export declare function ledgerAdd(opts: LedgerAddOptions): LedgerAddResult;
+/** Every entry in the ledger, oldest first. */
+export declare function ledgerList(regressionsDir?: string): Array<LedgerMeta & {
+    readonly entryPath: string;
+}>;
+/**
+ * The ledger entry for a fingerprint — its own, or the entry whose finding lists it as `related`
+ * (the same defect seen at another point). What `verify-fix --fingerprint <fp>` replays when no
+ * `--result` is given.
+ */
+export declare function ledgerEntryFor(fingerprint: string, regressionsDir?: string): string;
+/** Which entries to re-check, plus every `verify-fix` option (passed to each replay as `verify-fix` takes it). */
+export interface RunLedgerVerifyOptions extends Omit<RunVerifyFixOptions, "resultPath" | "fingerprint"> {
+    /** Fingerprints to verify; default every entry (narrowed by `ticket`). */
+    readonly fingerprints?: readonly string[];
+    readonly ticket?: string;
+    readonly regressionsDir?: string;
+}
+export interface LedgerVerifyItem {
+    readonly fingerprint: string;
+    readonly ticket?: string;
+    readonly title?: string;
+    readonly verdict: VerifyFixReport["verdict"];
+    readonly exitCode: number;
+    readonly reason?: string;
+    readonly report?: VerifyFixReport;
+}
+export interface LedgerVerifyResult {
+    readonly kind: "ledger-verify";
+    readonly entries: LedgerVerifyItem[];
+    readonly summary: Readonly<Record<VerifyFixReport["verdict"], number>>;
+    /** 0 every entry fixed · 1 any still reproduces · 4 any intermittent · 2 any inconclusive (worst wins, in that order). */
+    readonly exitCode: number;
+}
+/** `jevitate ledger verify`: re-checks every (or the named) ledger entry with `verify-fix`, from the ledger alone. */
+export declare function runLedgerVerify(opts: RunLedgerVerifyOptions): Promise<LedgerVerifyResult>;

package/dist/ledger-api.js

@@ -0,0 +1,237 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { projectDataDir } from "./project-dir.js";
+import { VERIFY_FIX_EXIT_CODES, VerifyFixInputError, findFinding, parsePersistedMission, runVerifyFix, } from "./verify-fix-api.js";
+import { currentEngineInfo } from "./engine.js";
+/**
+ * The finding ledger (#195 part 6): a built-in store of the repro material `verify-fix` needs,
+ * keyed by fingerprint, so "is it still fixed?" can be asked months later from the fingerprint
+ * alone — after the run's `.jevitate/logs/<date>/` output has been pruned by retention.
+ *
+ * It extends the committed regressions store rather than duplicating it: entries live in
+ * `<regressions>/ledger/<fingerprint>.json` (default `.jevitate/regressions/ledger/`, committed with
+ * the app's code, like `regression capture`'s artifacts). Each entry is a minimal, self-contained
+ * mission result — `{ ledger, result }` — that `runVerifyFix` reads exactly like a `<stem>.result.json`.
+ *
+ * What an entry holds is ALLOW-LISTED, never a copy of the result: the finding itself (with its own
+ * path Recording, when it has one), the run's Recording only when the finding has none, the scope
+ * (`seedUrl` + `allowlist`), the declared-invariant spec and the fixture spec the replay re-checks,
+ * and the write controls the run fired (for hang-replay safety). Never a storage state, a session
+ * PATH, an actor's session, the transcript, page text, screenshots or usage: a replay of an
+ * authenticated target takes `--storage-state` (or the operator's targets.json session) at verify
+ * time. A value the caller names as secret (`--secret`) anywhere in the material refuses the add.
+ */
+export const LEDGER_ENTRY_VERSION = 1;
+export class LedgerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LedgerError";
+        this.code = code;
+    }
+}
+/** `<regressions>/ledger` — `.jevitate/regressions/ledger` in a project, else `~/.jevitate/regressions/ledger`. */
+export function ledgerDir(regressionsDir) {
+    return join(regressionsDir ?? projectDataDir(["regressions"]), "ledger");
+}
+const FINGERPRINT = /^[0-9a-f]{16}$/;
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function entryPath(dir, fingerprint) {
+    if (!FINGERPRINT.test(fingerprint))
+        throw new LedgerError("E_LEDGER_INPUT", `not a finding fingerprint: ${JSON.stringify(fingerprint)} (16 hex characters)`);
+    return join(dir, `${fingerprint}.json`);
+}
+/** The raw finding object (as persisted) whose fingerprint or `related` list is `fp`. */
+function rawFinding(result, fp) {
+    for (const list of [result.defects, result.hangs, result.serverLogDefects]) {
+        if (!Array.isArray(list))
+            continue;
+        for (const item of list) {
+            if (!isRecord(item))
+                continue;
+            const related = Array.isArray(item.related) ? item.related : [];
+            if (item.fingerprint === fp || related.includes(fp))
+                return item;
+        }
+    }
+    return undefined;
+}
+/** Refuses repro material that contains any value the caller declared secret. */
+function assertNoSecrets(material, secrets) {
+    const text = JSON.stringify(material);
+    const leaked = secrets.filter((s) => s.length > 0 && text.includes(s));
+    if (leaked.length > 0) {
+        throw new LedgerError("E_LEDGER_SECRET", `the finding's repro material contains ${leaked.length} value(s) passed as --secret — refusing to store it (the ledger is committed with the repo)`);
+    }
+}
+/** `jevitate ledger add <result> <fp>`: stores the redacted repro material `verify-fix` needs. */
+export function ledgerAdd(opts) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(opts.resultPath, "utf8"));
+    }
+    catch (e) {
+        throw new LedgerError("E_LEDGER_INPUT", `cannot read mission result ${opts.resultPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let mission;
+    try {
+        mission = parsePersistedMission(raw);
+    }
+    catch (e) {
+        throw new LedgerError("E_LEDGER_INPUT", `${opts.resultPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const finding = findFinding(mission, opts.fingerprint);
+    const result = isRecord(raw) && isRecord(raw.result) ? raw.result : {};
+    const item = finding === undefined ? undefined : rawFinding(result, finding.fingerprint);
+    if (finding === undefined || item === undefined) {
+        throw new LedgerError("E_LEDGER_INPUT", `no finding with fingerprint ${opts.fingerprint} in ${opts.resultPath}`);
+    }
+    // The replay needs a Recording: the finding's own path, else the run's.
+    const ownRecording = isRecord(item.repro) && item.repro.recording !== undefined;
+    if (!ownRecording && mission.recording === null) {
+        throw new LedgerError("E_LEDGER_INPUT", `finding ${finding.fingerprint} has no Recording to replay — nothing verify-fix could re-check`);
+    }
+    const list = finding.kind === "hang" ? "hangs" : "defects";
+    const persistedFixtures = isRecord(result.fixtures) ? result.fixtures : undefined;
+    const material = {
+        ...(typeof result.schemaVersion === "number" ? { schemaVersion: result.schemaVersion } : {}),
+        ...(typeof result.strategy === "string" ? { strategy: result.strategy } : {}),
+        // The scope only: never a storage-state path or an actor's session (machine-local, and a pointer at credentials).
+        target: { seedUrl: mission.target.seedUrl, allowlist: [...mission.target.allowlist] },
+        recording: ownRecording ? null : mission.recording,
+        defects: list === "defects" ? [item] : [],
+        hangs: list === "hangs" ? [item] : [],
+        ...(finding.kind === "invariant" && mission.invariantSpec !== undefined ? { invariantSpec: mission.invariantSpec } : {}),
+        // The fixture's spec, hook HASHES and non-secret outputs — what a replay restores; hooks are never stored.
+        ...(persistedFixtures === undefined
+            ? {}
+            : {
+                fixtures: {
+                    identity: persistedFixtures.identity,
+                    ...(persistedFixtures.spec === undefined ? {} : { spec: persistedFixtures.spec }),
+                    hooks: isRecord(persistedFixtures.hooks) ? persistedFixtures.hooks : {},
+                    outputs: isRecord(persistedFixtures.outputs) ? persistedFixtures.outputs : {},
+                },
+            }),
+        // Only which controls fired a write (hang-replay safety, #153/#181) — never the requests themselves.
+        sideEffects: (Array.isArray(result.sideEffects) ? result.sideEffects : []).flatMap((e) => isRecord(e) && typeof e.control === "string" ? [{ control: e.control }] : []),
+    };
+    assertNoSecrets(material, opts.secrets ?? []);
+    const dir = ledgerDir(opts.regressionsDir);
+    const path = entryPath(dir, finding.fingerprint);
+    const previous = existsSync(path) ? readEntry(path) : undefined;
+    const ticket = opts.ticket ?? previous?.ledger.ticket;
+    const meta = {
+        version: LEDGER_ENTRY_VERSION,
+        fingerprint: finding.fingerprint,
+        kind: finding.kind,
+        ...(finding.title === undefined ? {} : { title: finding.title }),
+        ...(ticket === undefined ? {} : { ticket }),
+        addedAt: previous?.ledger.addedAt ?? (opts.nowIso ?? (() => new Date().toISOString()))(),
+        source: {
+            result: basename(opts.resultPath),
+            ...(typeof result.strategy === "string" ? { strategy: result.strategy } : {}),
+            ...(isRecord(raw) && typeof raw.missionOutcome === "string" ? { missionOutcome: raw.missionOutcome } : {}),
+            ...(isRecord(result.engine) ? { engine: result.engine } : {}),
+        },
+        addedBy: currentEngineInfo(),
+    };
+    const entry = { ledger: meta, result: material };
+    // The entry must itself be a mission result verify-fix can read (fail closed before writing).
+    const check = findFinding(parsePersistedMission(entry), finding.fingerprint);
+    if (check === undefined)
+        throw new LedgerError("E_LEDGER_INPUT", `finding ${finding.fingerprint} did not survive into its ledger entry`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(entry, null, 2)}\n`, "utf8");
+    return {
+        entryPath: path,
+        fingerprint: finding.fingerprint,
+        kind: finding.kind,
+        ...(finding.title === undefined ? {} : { title: finding.title }),
+        ...(ticket === undefined ? {} : { ticket }),
+        updated: previous !== undefined,
+    };
+}
+function readEntry(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new LedgerError("E_LEDGER_INPUT", `cannot read ledger entry ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isRecord(raw) || !isRecord(raw.ledger) || !isRecord(raw.result) || typeof raw.ledger.fingerprint !== "string") {
+        throw new LedgerError("E_LEDGER_INPUT", `not a ledger entry: ${path}`);
+    }
+    return raw;
+}
+/** Every entry in the ledger, oldest first. */
+export function ledgerList(regressionsDir) {
+    const dir = ledgerDir(regressionsDir);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => FINGERPRINT.test(f.replace(/\.json$/, "")) && f.endsWith(".json"))
+        .map((f) => {
+        const entryPath = join(dir, f);
+        return { ...readEntry(entryPath).ledger, entryPath };
+    })
+        .sort((a, b) => a.addedAt.localeCompare(b.addedAt) || a.fingerprint.localeCompare(b.fingerprint));
+}
+/**
+ * The ledger entry for a fingerprint — its own, or the entry whose finding lists it as `related`
+ * (the same defect seen at another point). What `verify-fix --fingerprint <fp>` replays when no
+ * `--result` is given.
+ */
+export function ledgerEntryFor(fingerprint, regressionsDir) {
+    const dir = ledgerDir(regressionsDir);
+    const own = entryPath(dir, fingerprint);
+    if (existsSync(own))
+        return own;
+    for (const e of ledgerList(regressionsDir)) {
+        if (findFinding(parsePersistedMission(readEntry(e.entryPath)), fingerprint) !== undefined)
+            return e.entryPath;
+    }
+    throw new LedgerError("E_LEDGER_NOT_FOUND", `no ledger entry for fingerprint ${fingerprint} in ${dir} — add one with \`jevitate ledger add <result> ${fingerprint}\`, or pass --result`);
+}
+/** A regression beats a flaky signal beats a check that could not run; only all-`fixed` passes. */
+const VERDICT_SEVERITY = { fixed: 0, inconclusive: 1, intermittent: 2, "still-reproduces": 3 };
+/** `jevitate ledger verify`: re-checks every (or the named) ledger entry with `verify-fix`, from the ledger alone. */
+export async function runLedgerVerify(opts) {
+    const { fingerprints: _fps, ticket: _ticket, regressionsDir: _dir, ...verify } = opts;
+    const all = ledgerList(opts.regressionsDir);
+    const chosen = opts.fingerprints !== undefined && opts.fingerprints.length > 0
+        ? opts.fingerprints.map((fp) => {
+            const entryPath = ledgerEntryFor(fp, opts.regressionsDir);
+            const meta = readEntry(entryPath).ledger;
+            return { ...meta, entryPath, fingerprint: fp };
+        })
+        : all.filter((e) => opts.ticket === undefined || e.ticket === opts.ticket);
+    const entries = [];
+    for (const e of chosen) {
+        const base = { fingerprint: e.fingerprint, ...(e.ticket === undefined ? {} : { ticket: e.ticket }), ...(e.title === undefined ? {} : { title: e.title }) };
+        try {
+            const report = await runVerifyFix({ ...verify, resultPath: e.entryPath, fingerprint: e.fingerprint });
+            entries.push({ ...base, verdict: report.verdict, exitCode: report.exitCode, ...(report.reason === undefined ? {} : { reason: report.reason }), report });
+        }
+        catch (err) {
+            // An entry that cannot be replayed (a missing session, a refused origin) is inconclusive — never fixed.
+            if (!(err instanceof VerifyFixInputError) && !(err instanceof LedgerError))
+                throw err;
+            entries.push({ ...base, verdict: "inconclusive", exitCode: VERIFY_FIX_EXIT_CODES.inconclusive, reason: err.message });
+        }
+    }
+    const summary = { fixed: 0, "still-reproduces": 0, intermittent: 0, inconclusive: 0 };
+    for (const e of entries)
+        summary[e.verdict] += 1;
+    // #227: nothing chosen (an empty ledger, or fingerprints/ticket matching nothing) verified nothing
+    // — `entries.reduce(..., "fixed")`'s empty-array identity would otherwise read as "FIXED: 0
+    // entries" at exit 0, a false pass. Inconclusive (2): the command proved nothing either way.
+    if (entries.length === 0)
+        return { kind: "ledger-verify", entries, summary, exitCode: VERIFY_FIX_EXIT_CODES.inconclusive };
+    const worst = entries.reduce((w, e) => (VERDICT_SEVERITY[e.verdict] > VERDICT_SEVERITY[w] ? e.verdict : w), "fixed");
+    return { kind: "ledger-verify", entries, summary, exitCode: VERIFY_FIX_EXIT_CODES[worst] };
+}
+//# sourceMappingURL=ledger-api.js.map

package/dist/ledger-api.js.map

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

package/dist/ledger-cli.d.ts

@@ -0,0 +1,18 @@
+import type { Command } from "commander";
+import type { BrowserLaunchOptions, BrowserPort } from "@jevitate/playwright";
+/**
+ * `jevitate ledger add|list|verify` (#195 part 6) — registered by `program.ts`, which supplies the
+ * browser wiring. See `ledger-api.ts` for what an entry holds (and never holds).
+ *
+ * Exit codes (exit-codes.ts): `add`/`list` 0 ok · 64 refused input (bad fingerprint, missing entry,
+ * a secret in the material) · 2 an unexpected failure. `verify` 0 every entry fixed · 1 any still
+ * reproduces · 4 any intermittent · 2 any inconclusive · 64 the ledger/arguments were unusable.
+ * Without `--json`, a human summary (#210).
+ */
+export interface LedgerCliDeps {
+    readonly targetsConfigPath?: string;
+    readonly browserPortFactory?: () => BrowserPort;
+    /** Maps the command's browser launch flags to launch options (program.ts's `browserLaunchFromFlags`). */
+    readonly browserLaunch?: (flags: object) => BrowserLaunchOptions | undefined;
+}
+export declare function registerLedgerCommands(program: Command, deps: LedgerCliDeps, withLaunchFlags: (cmd: Command) => Command): void;

package/dist/ledger-cli.js

@@ -0,0 +1,107 @@
+import { UnauthorizedExploreTargetError } from "@jevitate/explore";
+import { ok, fail } from "./envelope.js";
+import { withEngine } from "./engine.js";
+import { LedgerError, ledgerAdd, ledgerList, runLedgerVerify } from "./ledger-api.js";
+import { TargetConfigError, loadTargetsFile } from "./target-config.js";
+import { VerifyFixInputError } from "./verify-fix-api.js";
+import { positiveIntArg } from "./cli-args.js";
+import { emitEnvelope, formatLedgerAddHuman, formatLedgerListHuman, formatLedgerVerifyHuman } from "./cli-output.js";
+function emit(program, envelope, out, exitCode) {
+    emitEnvelope(program, envelope, { ...out, ...(exitCode === undefined ? {} : { exitCode }) });
+}
+/** A refusal's exit code is its class (exit-codes.ts): 64 for unusable input, 2 for an unexpected failure. */
+function refuse(program, err, out) {
+    if (err instanceof LedgerError || err instanceof VerifyFixInputError || err instanceof TargetConfigError) {
+        emit(program, fail(err.code, err.message), out);
+    }
+    else if (err instanceof UnauthorizedExploreTargetError) {
+        emit(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message), out);
+    }
+    else {
+        emit(program, fail("E_LEDGER", err instanceof Error ? err.message : String(err)), out);
+    }
+}
+const collect = (v, prev) => [...prev, v];
+const DIR_HELP = "regressions directory; the ledger is its ledger/ subdirectory (default: the repo's .jevitate/regressions)";
+export function registerLedgerCommands(program, deps, withLaunchFlags) {
+    const ledger = program
+        .command("ledger")
+        .description("keep each finding's repro material by fingerprint, so verify-fix works long after the run's output is gone");
+    ledger
+        .command("add")
+        .description("store a finding's redacted repro material (never a session or storage state) in the committed ledger")
+        .argument("<result>", "the mission's <stem>.result.json that contains the finding")
+        .argument("<fingerprint>", "the defect/hang fingerprint")
+        .option("--ticket <id>", "the tracker ticket the finding was filed as")
+        .option("--dir <path>", DIR_HELP)
+        .option("--secret <value>", "refuse the entry if its material contains this value (repeatable)", collect, [])
+        .option("--json", "emit a JSON envelope (default: a human summary)")
+        .action(function (result, fingerprint) {
+        const o = this.opts();
+        // #230: the follow-up hints carry the same --dir the user passed.
+        const out = { json: o.json === true, command: "ledger add", human: (data) => formatLedgerAddHuman(data, { dir: o.dir }) };
+        try {
+            const added = ledgerAdd({
+                resultPath: result,
+                fingerprint,
+                secrets: o.secret,
+                ...(o.ticket === undefined ? {} : { ticket: o.ticket }),
+                ...(o.dir === undefined ? {} : { regressionsDir: o.dir }),
+            });
+            emit(program, ok(added), out);
+        }
+        catch (err) {
+            refuse(program, err, out);
+        }
+    });
+    ledger
+        .command("list")
+        .description("list the ledger's entries (fingerprint, kind, title, ticket, when added)")
+        .option("--dir <path>", DIR_HELP)
+        .option("--json", "emit a JSON envelope (default: a human summary)")
+        .action(function () {
+        const o = this.opts();
+        // #230: the follow-up hint carries the same --dir the user passed.
+        const out = { json: o.json === true, command: "ledger list", human: (data) => formatLedgerListHuman(data, { dir: o.dir }) };
+        try {
+            emit(program, ok({ entries: ledgerList(o.dir) }), out);
+        }
+        catch (err) {
+            refuse(program, err, out);
+        }
+    });
+    withLaunchFlags(ledger
+        .command("verify")
+        .description("re-check every ledger entry (or the named ones) with verify-fix, from the ledger alone"))
+        .argument("[fingerprints...]", "only these entries (default: every entry)")
+        .option("--ticket <id>", "only the entries filed as this ticket")
+        .option("--dir <path>", DIR_HELP)
+        .option("--storage-state <file>", "the session to replay an authenticated target with (entries never store one)")
+        .option("--replays <n>", "fresh-context replays per entry that confirm a fix (default 3)", positiveIntArg)
+        .option("--allow-log-cmd", "re-checking a server-log entry whose source is cmd:<command> needs this too", false)
+        .option("--json", "emit a JSON envelope (default: a human summary)")
+        .action(async function (fingerprints) {
+        const o = this.opts();
+        // #230: the follow-up hint carries the same --dir the user passed.
+        const out = { json: o.json === true, command: "ledger verify", human: (data) => formatLedgerVerifyHuman(data, { dir: o.dir }) };
+        try {
+            const browser = deps.browserLaunch?.(o);
+            const result = await runLedgerVerify({
+                fingerprints,
+                ...(o.ticket === undefined ? {} : { ticket: o.ticket }),
+                ...(o.dir === undefined ? {} : { regressionsDir: o.dir }),
+                targets: loadTargetsFile(deps.targetsConfigPath),
+                ...(o.storageState === undefined ? {} : { storageState: o.storageState }),
+                ...(o.replays === undefined ? {} : { replays: Number(o.replays) }),
+                ...(o.allowLogCmd === true ? { allowLogCmd: true } : {}),
+                ...(deps.browserPortFactory === undefined ? {} : { browserPortFactory: deps.browserPortFactory }),
+                ...(browser === undefined ? {} : { browser }),
+            });
+            emit(program, ok(withEngine(result)), out, result.exitCode);
+        }
+        catch (err) {
+            refuse(program, err, out);
+        }
+    });
+}
+//# sourceMappingURL=ledger-cli.js.map

package/dist/ledger-cli.js.map

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

package/dist/load-api.d.ts

@@ -1,6 +1,8 @@
+import type { SiteGateDeps } from "@jevitate/runtime";
 import { type RunPolicy } from "@jevitate/domain";
-import { type BrowserPort } from "@jevitate/playwright";
+import { type BrowserLaunchOptions, type BrowserPort, type EmulationSpec } from "@jevitate/playwright";
 import { type CapacityReport } from "@jevitate/load";
+import { type ResolvedJourneyEnvironment } from "./environments.js";
 /** Distinct from `@jevitate/journey`'s ParamValidationError-style "unknown id" cases elsewhere, so CLI callers can branch without string-matching. */
 export declare class UnknownLoadJourneyError extends Error {
 }
@@ -11,12 +13,9 @@ export interface RunJourneyLoadTestOptions {
     concurrency: number;
     iterationsPerActor: number;
     /**
-     * Governs deterministic actor fan-out/scheduling only (see
-     * `@jevitate/load`'s `RunLoadTestConfig.seed` doc comment) — the real
-     * `JourneyRunner` this function drives per pool member has no pacing
-     * hook, so this `seed` does NOT (yet) produce human-speed pacing of the
-     * real run the way `modeledCapacityReport`'s `seed` drives
-     * `simulateTiming()`. Known gap, deferred to a future slice.
+     * Governs deterministic actor fan-out/scheduling, and seeds each actor's human-like pacing when a
+     * site policy declares one (`jevitate site policy set <origin>`): actor N's pacing is reproducible
+     * from `seed` and N.
      */
     seed: number;
     authorizedOrigins: readonly string[];
@@ -29,6 +28,25 @@ export interface RunJourneyLoadTestOptions {
      * to `() => new PlaywrightBrowserPort()`.
      */
     browserPortFactory?: () => BrowserPort;
+    /**
+     * Playwright storageState JSON to seed EVERY pool member's session from (CLI `--storage-state`,
+     * #118) — the deterministic authenticated pre-step a Journey authored behind a login needs.
+     * Contains live session cookies: handed only to the browser, never logged, never returned in
+     * the report.
+     */
+    storageState?: string;
+    /** How Chromium is launched (executable/channel/extra args). Default: pinned Chromium. */
+    browser?: BrowserLaunchOptions;
+    /** Per-mission viewport/device emulation (#149, CLI `--viewport <W>x<H>` / `--device "<name>"`) — applied to EVERY pool member's session. */
+    emulation?: EmulationSpec;
+    /** The site-policy gate (`jevitate site policy set`): only its pacing applies to a load run. */
+    siteGate?: SiteGateDeps;
+    /**
+     * #247 (`--env`/`--base-url`): load-test this environment — the Journey's recorded URLs move onto
+     * its baseUrl (which must still be an `--authorized-origin`); a step on an origin it does not
+     * allow is refused before any browser opens. Absent: the recorded site, as before.
+     */
+    environment?: ResolvedJourneyEnvironment;
 }
 /**
  * The programmatic surface behind `jevitate load run` — resolves a published
@@ -40,9 +58,9 @@ export interface RunJourneyLoadTestOptions {
  *
  * NOTE on "seeded ⇒ reproducible / human-paced" (corrected post-review):
  * `opts.seed` makes the ACTOR POOL's composition reproducible (via
- * `deriveActorSeeds` inside `runLoadTest`) — it does not yet make the real
- * run human-paced, because `JourneyRunner` (constructed below) has no
- * pacing hook to seed. Only the offline `modeledCapacityReport` path is
- * genuinely human-paced today, via `@jevitate/domain`'s `simulateTiming()`.
+ * `deriveActorSeeds` inside `runLoadTest`), and — with a site policy that declares pacing — each
+ * actor's clicks and keystrokes are human-paced, seeded from `seed` and the actor's index. A load
+ * run is the operator's deliberate burst: the policy's throttles, budgets and quiet hours do not
+ * refuse it; only its pacing applies.
  */
 export declare function runJourneyLoadTest(opts: RunJourneyLoadTestOptions): Promise<CapacityReport>;