@jevitate/cli 0.1.0 → 0.3.0

package/dist/resource-preflight.d.ts

@@ -0,0 +1,87 @@
+import { Command } from "commander";
+import { type OrphanCleanup, type ProcessTable, type ResourceGovernor, type ResourceLimits } from "@jevitate/playwright";
+import { type JsonEnvelope } from "./envelope.js";
+/**
+ * #205: the CLI side of resource governance — run once before every browser-driving command (the
+ * action wrapper `withBrowserLaunchFlags` installs) and by `jevitate doctor`.
+ *
+ * Before a browser run starts:
+ *  1. ORPHAN SWEEP (once per process): browsers a killed jevitate left behind — marked with their
+ *     owner, owner gone — are closed, and stale machine slots are cleared. Only jevitate-marked
+ *     processes are ever signalled.
+ *  2. STARVED-HOST REFUSAL: when the host is clearly starved (`throttleDecision` → `starved`: load
+ *     ≥ 4/core, or < 512 MiB available) the run refuses to start with `E_HOST_STARVED` (exit 2: it
+ *     could not do its work) instead of timing out and reporting the app as hung — unless
+ *     `--ignore-host-load`, in which case it runs throttled and its result records that.
+ *
+ * Both are skipped under `JEVITATE_RESOURCE_GOVERNANCE=off`.
+ */
+/** Raw commander values of the governance flags. */
+export interface GovernanceFlags {
+    maxBrowsers?: number;
+    /** MiB. */
+    maxBrowserMemory?: number;
+    ignoreHostLoad?: boolean;
+}
+/** The run's `ResourceLimits` from its flags, or undefined when none was given. */
+export declare function resourceLimitsFromFlags(o: GovernanceFlags): ResourceLimits | undefined;
+export interface PreflightDeps {
+    readonly governor?: ResourceGovernor;
+    /** Restricts what the orphan sweep reads (and so may signal) — tests pass their own processes only. */
+    readonly processTable?: ProcessTable;
+    readonly warn?: (line: string) => void;
+}
+/** Test seam: forget that this process already swept (the sweep runs once per process). */
+export declare function resetPreflightSweep(): void;
+/** The startup sweep: closes orphaned jevitate browsers and clears stale machine slots (once per process). */
+export declare function sweepOnce(deps?: PreflightDeps): Promise<void>;
+/**
+ * The pre-run checks; returns the refusal envelope when the run must not start (`E_HOST_STARVED`),
+ * else null.
+ */
+export declare function resourcePreflight(o: GovernanceFlags, deps?: PreflightDeps): Promise<JsonEnvelope<never> | null>;
+/**
+ * Installs the pre-run checks on a browser-driving command: its action (registered AFTER this, by
+ * the command's own `.action(...)`) runs only when `resourcePreflight` lets it; a refusal is emitted
+ * through the shared refusal path and the action never runs.
+ */
+export declare function withResourcePreflight(cmd: Command, deps?: PreflightDeps): Command;
+export interface DoctorReport {
+    readonly host: string;
+    readonly governance: {
+        readonly enabled: boolean;
+        readonly maxBrowsers: number;
+        readonly memoryCeilingBytes: number | null;
+    };
+    readonly load: {
+        readonly level: string;
+        readonly reasons: readonly string[];
+        readonly loadPerCore: number | null;
+        readonly memAvailableBytes: number | null;
+    };
+    readonly slots: Array<{
+        readonly index: number;
+        readonly pid: number | null;
+        readonly host: string | null;
+        readonly acquiredAt: string | null;
+        readonly stale: string | null;
+    }>;
+    /** Every jevitate-launched browser on this machine; null where the platform has no process reader. */
+    readonly browsers: Array<{
+        readonly pid: number;
+        readonly ownerPid: number;
+        readonly orphan: string | null;
+    }> | null;
+    readonly cleanup?: {
+        readonly orphans: OrphanCleanup["orphans"];
+        readonly staleSlotsCleared: number;
+    };
+}
+/** `jevitate doctor`'s report; with `cleanup`, orphaned browsers are closed and stale slots cleared first. */
+export declare function doctorReport(opts?: {
+    readonly cleanup?: boolean;
+} & PreflightDeps): Promise<DoctorReport>;
+/** The human `jevitate doctor` text. */
+export declare function formatDoctor(r: DoctorReport): string;
+/** Registers `jevitate doctor [--cleanup] [--json]`. */
+export declare function registerDoctorCommand(program: Command, deps?: PreflightDeps): void;

package/dist/resource-preflight.js

@@ -0,0 +1,160 @@
+import { hostname } from "node:os";
+import { cleanupOrphanBrowsers, jevitateBrowsers, sharedResourceGovernor, } from "@jevitate/playwright";
+import { fail, ok } from "./envelope.js";
+import { emitJsonOrRefusal } from "./cli-refusal.js";
+/** The run's `ResourceLimits` from its flags, or undefined when none was given. */
+export function resourceLimitsFromFlags(o) {
+    const limits = {
+        ...(o.maxBrowsers === undefined ? {} : { maxBrowsers: o.maxBrowsers }),
+        ...(o.maxBrowserMemory === undefined ? {} : { memoryCeilingBytes: o.maxBrowserMemory * 1024 ** 2 }),
+    };
+    return Object.keys(limits).length > 0 ? limits : undefined;
+}
+let swept = false;
+/** Test seam: forget that this process already swept (the sweep runs once per process). */
+export function resetPreflightSweep() {
+    swept = false;
+}
+/** The startup sweep: closes orphaned jevitate browsers and clears stale machine slots (once per process). */
+export async function sweepOnce(deps = {}) {
+    if (swept)
+        return;
+    swept = true;
+    const governor = deps.governor ?? sharedResourceGovernor();
+    const warn = deps.warn ?? ((line) => process.stderr.write(line));
+    try {
+        const cleanup = await cleanupOrphanBrowsers({ ...(deps.processTable === undefined ? {} : { table: deps.processTable }) });
+        const closed = cleanup.orphans.filter((o) => o.result === "terminated" || o.result === "killed");
+        if (closed.length > 0)
+            warn(`jevitate: closed ${closed.length} orphaned browser process(es) left by a jevitate that exited: pid ${closed.map((o) => o.pid).join(", ")}\n`);
+        governor.slots.clearStale();
+    }
+    catch (err) {
+        // Housekeeping, not the run's business: reported, and the run goes on.
+        warn(`warning: orphan cleanup skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * The pre-run checks; returns the refusal envelope when the run must not start (`E_HOST_STARVED`),
+ * else null.
+ */
+export async function resourcePreflight(o, deps = {}) {
+    const governor = deps.governor ?? sharedResourceGovernor();
+    if (!governor.config.enabled)
+        return null;
+    await sweepOnce({ ...deps, governor });
+    const decision = await governor.decide();
+    if (decision.level !== "starved" || o.ignoreHostLoad === true)
+        return null;
+    return fail("E_HOST_STARVED", `the host is starved (${decision.reasons.join("; ")}): a browser run now would only time out and read as the app hanging, so it did not start. ` +
+        "Wait for the load to drop (see `jevitate doctor`), or pass --ignore-host-load to run anyway (throttled; the result records it)");
+}
+function rootOf(cmd) {
+    let c = cmd;
+    while (c.parent !== null)
+        c = c.parent;
+    return c;
+}
+/**
+ * Installs the pre-run checks on a browser-driving command: its action (registered AFTER this, by
+ * the command's own `.action(...)`) runs only when `resourcePreflight` lets it; a refusal is emitted
+ * through the shared refusal path and the action never runs.
+ */
+export function withResourcePreflight(cmd, deps = {}) {
+    const register = cmd.action.bind(cmd);
+    cmd.action = (fn) => register(async function (...args) {
+        const refusal = await resourcePreflight(this.opts(), deps);
+        if (refusal !== null) {
+            emitJsonOrRefusal(rootOf(this), refusal);
+            return;
+        }
+        await fn.apply(this, args);
+    });
+    return cmd;
+}
+const slotRow = (s) => ({
+    index: s.index,
+    pid: s.holder?.pid ?? null,
+    host: s.holder?.host ?? null,
+    acquiredAt: s.holder?.acquiredAt ?? null,
+    stale: s.stale,
+});
+/** `jevitate doctor`'s report; with `cleanup`, orphaned browsers are closed and stale slots cleared first. */
+export async function doctorReport(opts = {}) {
+    const governor = opts.governor ?? sharedResourceGovernor();
+    const table = opts.processTable;
+    let cleanup;
+    if (opts.cleanup === true) {
+        const orphans = await cleanupOrphanBrowsers({ ...(table === undefined ? {} : { table }) });
+        const cleared = governor.slots.clearStale();
+        cleanup = { orphans: orphans.orphans, staleSlotsCleared: cleared.length };
+    }
+    const decision = await governor.decide();
+    const browsers = jevitateBrowsers(...(table === undefined ? [] : [table]));
+    return {
+        host: hostname(),
+        governance: { enabled: governor.config.enabled, maxBrowsers: governor.config.maxBrowsers, memoryCeilingBytes: governor.config.memoryCeilingBytes },
+        load: {
+            level: decision.level,
+            reasons: decision.reasons,
+            loadPerCore: decision.sample.loadPerCore ?? null,
+            memAvailableBytes: decision.sample.memAvailableBytes ?? null,
+        },
+        slots: governor.slots.list().map(slotRow),
+        browsers: browsers === undefined ? null : browsers.map((b) => ({ pid: b.pid, ownerPid: b.owner.pid, orphan: b.orphan })),
+        ...(cleanup === undefined ? {} : { cleanup }),
+    };
+}
+const mib = (n) => `${Math.round(n / 1024 ** 2)} MiB`;
+/** The human `jevitate doctor` text. */
+export function formatDoctor(r) {
+    const lines = [];
+    const g = r.governance;
+    lines.push(`resource governance: ${g.enabled ? "on" : "off (JEVITATE_RESOURCE_GOVERNANCE=off)"} · max browsers ${g.maxBrowsers} · memory ceiling ${g.memoryCeilingBytes === null ? "off" : mib(g.memoryCeilingBytes)}`);
+    const load = [
+        r.load.loadPerCore === null ? null : `load ${r.load.loadPerCore.toFixed(2)}/core`,
+        r.load.memAvailableBytes === null ? null : `${mib(r.load.memAvailableBytes)} available`,
+    ].filter((x) => x !== null);
+    lines.push(`host: ${r.load.level}${load.length === 0 ? "" : ` (${load.join(", ")})`}${r.load.reasons.length === 0 ? "" : ` — ${r.load.reasons.join("; ")}`}`);
+    lines.push(`machine browser slots held: ${r.slots.length}`);
+    for (const s of r.slots)
+        lines.push(`  slot ${s.index}: ${s.pid === null ? "unreadable" : `pid ${s.pid} on ${s.host}`}${s.stale === null ? "" : ` — stale: ${s.stale}`}`);
+    if (r.browsers === null)
+        lines.push("jevitate browsers: not listed (no process reader on this platform)");
+    else {
+        const orphans = r.browsers.filter((b) => b.orphan !== null);
+        lines.push(`jevitate browsers: ${r.browsers.length} running, ${orphans.length} orphaned`);
+        for (const b of orphans)
+            lines.push(`  pid ${b.pid}: ${b.orphan}`);
+    }
+    if (r.cleanup !== undefined) {
+        const closed = r.cleanup.orphans.filter((o) => o.result === "terminated" || o.result === "killed").length;
+        lines.push(`cleanup: closed ${closed} orphaned browser(s), cleared ${r.cleanup.staleSlotsCleared} stale slot(s)`);
+    }
+    else if (r.browsers?.some((b) => b.orphan !== null) === true || r.slots.some((s) => s.stale !== null)) {
+        lines.push("next: jevitate doctor --cleanup");
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Registers `jevitate doctor [--cleanup] [--json]`. */
+export function registerDoctorCommand(program, deps = {}) {
+    program
+        .command("doctor")
+        .description("resource governance on this machine (#205): host load, machine-wide browser slots, jevitate browsers and orphans left by a killed run")
+        .option("--cleanup", "close orphaned jevitate browsers (only processes jevitate launched, whose jevitate exited) and clear stale browser slots")
+        .option("--json", "emit a JSON envelope")
+        .action(async function () {
+        const o = this.opts();
+        try {
+            const report = await doctorReport({ ...deps, ...(o.cleanup === true ? { cleanup: true } : {}) });
+            if (o.json === true)
+                emitJsonOrRefusal(program, ok(report));
+            else
+                program.configureOutput().writeOut?.(formatDoctor(report));
+        }
+        catch (err) {
+            emitJsonOrRefusal(program, fail("E_DOCTOR", err instanceof Error ? err.message : String(err)));
+        }
+    });
+}
+//# sourceMappingURL=resource-preflight.js.map

package/dist/resource-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-preflight.js","sourceRoot":"","sources":["../src/resource-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,GAMvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,IAAI,EAAE,EAAE,EAAqB,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA0BrD,mFAAmF;AACnF,MAAM,UAAU,uBAAuB,CAAC,CAAkB;IACxD,MAAM,MAAM,GAAmB;QAC7B,GAAG,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACtE,GAAG,CAAC,CAAC,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,gBAAgB,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;KACpG,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AASD,IAAI,KAAK,GAAG,KAAK,CAAC;AAElB,2FAA2F;AAC3F,MAAM,UAAU,mBAAmB;IACjC,KAAK,GAAG,KAAK,CAAC;AAChB,CAAC;AAED,8GAA8G;AAC9G,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAsB,EAAE;IACtD,IAAI,KAAK;QAAE,OAAO;IAClB,KAAK,GAAG,IAAI,CAAC;IACb,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,sBAAsB,EAAE,CAAC;IAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1H,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;QACjG,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,CAAC,oBAAoB,MAAM,CAAC,MAAM,qEAAqE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3K,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uEAAuE;QACvE,IAAI,CAAC,oCAAoC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjG,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,CAAkB,EAAE,OAAsB,EAAE;IAClF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,sBAAsB,EAAE,CAAC;IAC3D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;IACzC,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,cAAc,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3E,OAAO,IAAI,CACT,gBAAgB,EAChB,wBAAwB,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,6FAA6F;QAC9I,gIAAgI,CACnI,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,GAAY;IAC1B,IAAI,CAAC,GAAG,GAAG,CAAC;IACZ,OAAO,CAAC,CAAC,MAAM,KAAK,IAAI;QAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY,EAAE,OAAsB,EAAE;IAC1E,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,GAAG,CAAC,MAAM,GAAG,CAAC,EAA4C,EAAW,EAAE,CACrE,QAAQ,CAAC,KAAK,WAA0B,GAAG,IAAW;QACpD,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAmB,EAAE,IAAI,CAAC,CAAC;QAC5E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YACzC,OAAO;QACT,CAAC;QACD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IACL,OAAO,GAAG,CAAC;AACb,CAAC;AAqBD,MAAM,OAAO,GAAG,CAAC,CAAY,EAAiC,EAAE,CAAC,CAAC;IAChE,KAAK,EAAE,CAAC,CAAC,KAAK;IACd,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,IAAI;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,IAAI,IAAI;IAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,IAAI,IAAI;IACxC,KAAK,EAAE,CAAC,CAAC,KAAK;CACf,CAAC,CAAC;AAEH,8GAA8G;AAC9G,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAuD,EAAE;IAC1F,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,sBAAsB,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC;IAChC,IAAI,OAAgC,CAAC;IACrC,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAC3F,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QAC5C,OAAO,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3E,OAAO;QACL,IAAI,EAAE,QAAQ,EAAE;QAChB,UAAU,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE;QAClJ,IAAI,EAAE;YACJ,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI;YAChD,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,IAAI,IAAI;SAC7D;QACD,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;QACzC,QAAQ,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACxH,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC;AAEtE,wCAAwC;AACxC,MAAM,UAAU,YAAY,CAAC,CAAe;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;IACvB,KAAK,CAAC,IAAI,CACR,wBAAwB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,wCAAwC,mBAAmB,CAAC,CAAC,WAAW,qBAAqB,CAAC,CAAC,kBAAkB,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,EAAE,CAC5M,CAAC;IACF,MAAM,IAAI,GAAG;QACX,CAAC,CAAC,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;QACjF,CAAC,CAAC,IAAI,CAAC,iBAAiB,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,YAAY;KACxF,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9J,KAAK,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5D,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1K,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;SACrG,CAAC;QACJ,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,QAAQ,CAAC,MAAM,aAAa,OAAO,CAAC,MAAM,WAAW,CAAC,CAAC;QAC1F,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;QAC1G,KAAK,CAAC,IAAI,CAAC,mBAAmB,MAAM,iCAAiC,CAAC,CAAC,OAAO,CAAC,iBAAiB,gBAAgB,CAAC,CAAC;IACpH,CAAC;SAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,EAAE,CAAC;QACxG,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,qBAAqB,CAAC,OAAgB,EAAE,OAAsB,EAAE;IAC9E,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,uIAAuI,CAAC;SACpJ,MAAM,CAAC,WAAW,EAAE,0HAA0H,CAAC;SAC/I,MAAM,CAAC,QAAQ,EAAE,sBAAsB,CAAC;SACxC,MAAM,CAAC,KAAK;QACX,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAyC,CAAC;QAC7D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACjG,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI;gBAAE,iBAAiB,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;;gBACvD,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAClE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACjG,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/result-schema.d.ts

@@ -0,0 +1,22 @@
+import type { ServerLogDefect } from "./log-correlation.js";
+/**
+ * The versioned result schema every explore strategy's result follows (#195 part 5) — defined in
+ * `@jevitate/domain` (zod + TS) and re-exported here as part of the CLI's published surface. See
+ * `mission-result.ts` there for the contract; this module holds the helpers the runners fill the
+ * common fields with, so every strategy fills them the same way.
+ */
+export { MISSION_RESULT_SCHEMA_VERSION, MissionResultSchema, PersistedMissionResultSchema, RESULT_STRATEGIES, RESULT_MISSION_OUTCOMES, ResultDefectSchema, type MissionResult, type MissionResultCore, type PersistedMissionResult, type ResultDefect, type ResultMissionOutcome, type ResultStrategy, } from "@jevitate/domain";
+/** A `server-log` defect a strategy reports but never gates on (usability: every UX finding is advisory). */
+export type AdvisoryServerLogDefect = ServerLogDefect & {
+    readonly advisory: true;
+};
+/**
+ * All of a run's defects in ONE list (#195): the strategy's own (hard-signal / declared-invariant)
+ * defects first, then its `server-log` defects — each fingerprint once. What `defects` holds on every
+ * strategy's result (the 0.2.0 `serverLogDefects` alias of the server-log subset was removed in 0.3.0).
+ */
+export declare function unifiedDefects<D extends {
+    readonly fingerprint: string;
+}>(own: readonly D[] | undefined, serverLog: readonly ServerLogDefect[] | undefined): Array<D | ServerLogDefect>;
+/** A usability run's `server-log` defects, marked advisory: reported in `defects`, never gating its outcome. */
+export declare function advisoryDefects(serverLog: readonly ServerLogDefect[] | undefined): AdvisoryServerLogDefect[];

package/dist/result-schema.js

@@ -0,0 +1,28 @@
+/**
+ * The versioned result schema every explore strategy's result follows (#195 part 5) — defined in
+ * `@jevitate/domain` (zod + TS) and re-exported here as part of the CLI's published surface. See
+ * `mission-result.ts` there for the contract; this module holds the helpers the runners fill the
+ * common fields with, so every strategy fills them the same way.
+ */
+export { MISSION_RESULT_SCHEMA_VERSION, MissionResultSchema, PersistedMissionResultSchema, RESULT_STRATEGIES, RESULT_MISSION_OUTCOMES, ResultDefectSchema, } from "@jevitate/domain";
+/**
+ * All of a run's defects in ONE list (#195): the strategy's own (hard-signal / declared-invariant)
+ * defects first, then its `server-log` defects — each fingerprint once. What `defects` holds on every
+ * strategy's result (the 0.2.0 `serverLogDefects` alias of the server-log subset was removed in 0.3.0).
+ */
+export function unifiedDefects(own, serverLog) {
+    const seen = new Set();
+    const out = [];
+    for (const d of [...(own ?? []), ...(serverLog ?? [])]) {
+        if (seen.has(d.fingerprint))
+            continue;
+        seen.add(d.fingerprint);
+        out.push(d);
+    }
+    return out;
+}
+/** A usability run's `server-log` defects, marked advisory: reported in `defects`, never gating its outcome. */
+export function advisoryDefects(serverLog) {
+    return unifiedDefects([], serverLog).map((d) => ({ ...d, advisory: true }));
+}
+//# sourceMappingURL=result-schema.js.map

package/dist/result-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-schema.js","sourceRoot":"","sources":["../src/result-schema.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,OAAO,EACL,6BAA6B,EAC7B,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GAOnB,MAAM,kBAAkB,CAAC;AAK1B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,GAA6B,EAC7B,SAAiD;IAEjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAA+B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACvD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,eAAe,CAAC,SAAiD;IAC/E,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC"}

package/dist/run-index.d.ts

@@ -0,0 +1,29 @@
+import { type LayoutDeps } from "./project-dir.js";
+/**
+ * #213: which runs belong to THIS project — so a bare `jevitate report`/`diff` reads the current
+ * project's runs, never every app's `~/.jevitate/logs` (a fresh project merged 167 unrelated runs),
+ * and still finds the runs written to an `--out` dir.
+ *
+ * Mechanism: every persisted result is recorded, best-effort, as one line
+ * `{"project": <key>, "path": <absolute result path>}` in the per-user index `~/.jevitate/run-index.jsonl`
+ * (machine-local, like the logs themselves; never in a repo). The project key is the directory that
+ * holds the project's `.jevitate/`, else the git root of the working directory, else the working
+ * directory itself. A bare report reads: the project's own `.jevitate/logs` (only this project writes
+ * there) plus every indexed result of this project that still exists — wherever it was written.
+ *
+ * `JEVITATE_RUN_INDEX=off` turns recording off (the test suite does, so it never touches the real index).
+ */
+export interface RunIndexDeps extends LayoutDeps {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Test seam: the index file (default `~/.jevitate/run-index.jsonl`). */
+    readonly indexPath?: string;
+}
+export declare function runIndexPath(deps?: RunIndexDeps): string;
+/** The current project's key: the dir holding its `.jevitate/`, else the git root, else the cwd. */
+export declare function projectKey(deps?: LayoutDeps): string;
+/** Records one persisted result for the current project. Never throws: an index is a convenience. */
+export declare function recordRun(resultPath: string, deps?: RunIndexDeps): void;
+/** Every indexed result of the current project that still exists, oldest first, each once. */
+export declare function indexedRunsFor(deps?: RunIndexDeps): string[];
+/** The current project's own dated logs dirs (`<repo>/.jevitate/logs/<date>`) — none outside a project. */
+export declare function projectLogDirs(deps?: LayoutDeps): string[];

package/dist/run-index.js

@@ -0,0 +1,70 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { findGitRoot, findProjectDir, homeDataRoot } from "./project-dir.js";
+export function runIndexPath(deps = {}) {
+    return deps.indexPath ?? join(homeDataRoot(deps), "run-index.jsonl");
+}
+/** The current project's key: the dir holding its `.jevitate/`, else the git root, else the cwd. */
+export function projectKey(deps = {}) {
+    const project = findProjectDir(deps);
+    if (project !== null)
+        return dirname(project);
+    const cwd = resolve((deps.cwd ?? (() => process.cwd()))());
+    return findGitRoot(cwd) ?? cwd;
+}
+/** Records one persisted result for the current project. Never throws: an index is a convenience. */
+export function recordRun(resultPath, deps = {}) {
+    if ((deps.env ?? process.env)["JEVITATE_RUN_INDEX"] === "off")
+        return;
+    try {
+        const path = runIndexPath(deps);
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify({ project: projectKey(deps), path: resolve(resultPath) })}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // best-effort: a run's result is never replaced by an index failure
+    }
+}
+/** Every indexed result of the current project that still exists, oldest first, each once. */
+export function indexedRunsFor(deps = {}) {
+    const path = runIndexPath(deps);
+    if (!existsSync(path))
+        return [];
+    const key = projectKey(deps);
+    const out = new Set();
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e.project === key && typeof e.path === "string" && existsSync(e.path))
+                out.add(e.path);
+        }
+        catch {
+            continue; // a torn line names nothing
+        }
+    }
+    return [...out];
+}
+/** The current project's own dated logs dirs (`<repo>/.jevitate/logs/<date>`) — none outside a project. */
+export function projectLogDirs(deps = {}) {
+    const project = findProjectDir(deps);
+    if (project === null)
+        return [];
+    const root = join(project, "logs");
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d))
+        .sort()
+        .reverse()
+        .map((d) => join(root, d));
+}
+//# sourceMappingURL=run-index.js.map

package/dist/run-index.js.map

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

package/dist/run-key-preflight.d.ts

@@ -0,0 +1,42 @@
+import { MissingCredentialError, type CredentialKey, type CredentialStore, type Feature, type VerifyFetch } from "@jevitate/ai-core";
+/**
+ * #291 (runs): a run that needs live AI keys (`explore --real`, `check`, `journey run/annotate/demo
+ * --real`, `demo`, `ux`, …) verifies them ONCE at startup with the same live, non-billable auth call
+ * `ai status` / `ai setup` use, and fails fast with a typed setup refusal (`E_AI_SETUP_REQUIRED`,
+ * exit 64) when a provider rejects a key — instead of spending the run and ending `inconclusive`
+ * with "model decision unavailable".
+ *
+ *  - Cheap: one GET per key, cached per process (by key name + a hash of the value — the value itself
+ *    is never kept here) — a multi-run, a retry or a self-heal re-build never re-checks it.
+ *  - Only an `invalid` verdict (401/403) refuses. An `unreachable` provider (offline, 429, 5xx) does
+ *    not block: the run's own calls retry and fail typed, as before; that verdict is not cached.
+ *  - `JEVITATE_NO_KEY_VERIFY=1` skips the check (offline CI). `--fake-ai` and injected gateways never
+ *    reach this code (no network).
+ *  - Names, providers and statuses only: no message here carries a key value.
+ */
+/** The env opt-out (offline CI): `1` / `true` / `yes` skips the startup key check. */
+export declare const NO_KEY_VERIFY_ENV = "JEVITATE_NO_KEY_VERIFY";
+/** A key the provider rejected — a `MissingCredentialError`, so every run surface refuses it as `E_AI_SETUP_REQUIRED`. */
+export declare class InvalidCredentialError extends MissingCredentialError {
+    readonly invalid: Array<{
+        readonly key: CredentialKey;
+        readonly httpStatus: number;
+        readonly looksLike: CredentialKey | null;
+    }>;
+    constructor(feature: Feature, invalid: Array<{
+        readonly key: CredentialKey;
+        readonly httpStatus: number;
+        readonly looksLike: CredentialKey | null;
+    }>);
+}
+/** Test seam: forget the per-process verdicts. */
+export declare function resetKeyPreflightCache(): void;
+export declare function keyPreflightDisabled(env: Record<string, string | undefined>): boolean;
+/**
+ * Verifies every key `features` need (present keys only: a missing one was already refused by
+ * `requireKeys`). Throws `InvalidCredentialError` for the first feature with a rejected key.
+ */
+export declare function preflightRunKeys(features: readonly Feature[], store: CredentialStore, opts: {
+    readonly env: Record<string, string | undefined>;
+    readonly fetchFn: VerifyFetch;
+}): Promise<void>;

package/dist/run-key-preflight.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { FEATURE_KEYS, KEY_PROVIDERS, KEY_VERIFY_URLS, MissingCredentialError, looksLikeOtherKey, verifyKey, } from "@jevitate/ai-core";
+/**
+ * #291 (runs): a run that needs live AI keys (`explore --real`, `check`, `journey run/annotate/demo
+ * --real`, `demo`, `ux`, …) verifies them ONCE at startup with the same live, non-billable auth call
+ * `ai status` / `ai setup` use, and fails fast with a typed setup refusal (`E_AI_SETUP_REQUIRED`,
+ * exit 64) when a provider rejects a key — instead of spending the run and ending `inconclusive`
+ * with "model decision unavailable".
+ *
+ *  - Cheap: one GET per key, cached per process (by key name + a hash of the value — the value itself
+ *    is never kept here) — a multi-run, a retry or a self-heal re-build never re-checks it.
+ *  - Only an `invalid` verdict (401/403) refuses. An `unreachable` provider (offline, 429, 5xx) does
+ *    not block: the run's own calls retry and fail typed, as before; that verdict is not cached.
+ *  - `JEVITATE_NO_KEY_VERIFY=1` skips the check (offline CI). `--fake-ai` and injected gateways never
+ *    reach this code (no network).
+ *  - Names, providers and statuses only: no message here carries a key value.
+ */
+/** The env opt-out (offline CI): `1` / `true` / `yes` skips the startup key check. */
+export const NO_KEY_VERIFY_ENV = "JEVITATE_NO_KEY_VERIFY";
+/** A key the provider rejected — a `MissingCredentialError`, so every run surface refuses it as `E_AI_SETUP_REQUIRED`. */
+export class InvalidCredentialError extends MissingCredentialError {
+    invalid;
+    constructor(feature, invalid) {
+        super(feature, invalid.map((i) => i.key));
+        this.invalid = invalid;
+        this.name = "InvalidCredentialError";
+        const what = invalid
+            .map((i) => `${i.key} (${KEY_PROVIDERS[i.key]}) was rejected by the provider (HTTP ${i.httpStatus})${i.looksLike === null ? "" : ` — it looks like ${/^[aeiou]/i.test(KEY_PROVIDERS[i.looksLike]) ? "an" : "a"} ${KEY_PROVIDERS[i.looksLike]} key (${i.looksLike})`}`)
+            .join("; ");
+        this.message =
+            `feature '${feature}': ${what} — replace it: \`jevitate ai setup ${feature} --replace\` ` +
+                `(or set ${NO_KEY_VERIFY_ENV}=1 to skip this startup check offline)`;
+    }
+}
+const cache = new Map();
+function cacheKey(key, value) {
+    return `${key}:${createHash("sha256").update(value).digest("hex")}`;
+}
+/** Test seam: forget the per-process verdicts. */
+export function resetKeyPreflightCache() {
+    cache.clear();
+}
+export function keyPreflightDisabled(env) {
+    return /^(?:1|true|yes)$/i.test((env[NO_KEY_VERIFY_ENV] ?? "").trim());
+}
+async function verdictFor(key, value, fetchFn) {
+    const id = cacheKey(key, value);
+    const hit = cache.get(id);
+    if (hit !== undefined)
+        return hit;
+    const pending = verifyKey(key, value, fetchFn);
+    cache.set(id, pending);
+    const verdict = await pending;
+    // An unreachable provider proves nothing: a later build may check again.
+    if (verdict.status === "unreachable")
+        cache.delete(id);
+    return verdict;
+}
+/**
+ * Verifies every key `features` need (present keys only: a missing one was already refused by
+ * `requireKeys`). Throws `InvalidCredentialError` for the first feature with a rejected key.
+ */
+export async function preflightRunKeys(features, store, opts) {
+    if (keyPreflightDisabled(opts.env))
+        return;
+    for (const feature of features) {
+        const invalid = [];
+        for (const key of FEATURE_KEYS[feature]) {
+            if (KEY_VERIFY_URLS[key] === undefined)
+                continue;
+            const value = store.read(key);
+            if (value === undefined || value.trim() === "")
+                continue;
+            const verdict = await verdictFor(key, value.trim(), opts.fetchFn);
+            if (verdict.status === "invalid")
+                invalid.push({ key, httpStatus: verdict.httpStatus, looksLike: looksLikeOtherKey(key, value.trim()) });
+        }
+        if (invalid.length > 0)
+            throw new InvalidCredentialError(feature, invalid);
+    }
+}
+//# sourceMappingURL=run-key-preflight.js.map

package/dist/run-key-preflight.js.map

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