@jevitate/cli 0.1.0 → 0.3.0

package/dist/check-types.d.ts

@@ -0,0 +1,181 @@
+import { type GenerationPort, type JudgmentPort, type UsageAggregate, type UsageTracker } from "@jevitate/ai-core";
+import type { BrowserPort } from "@jevitate/playwright";
+import type { BrowserRunOptions } from "./browser-run-options.js";
+import type { JourneyRunResult } from "@jevitate/runtime";
+import { type ConsolidatedDefect, type DiffEntry, type FindingIdentity, type FindingsDiff } from "@jevitate/findings";
+import { runAdversarialCliMission, runCoverageMission, runExploration, runFeatureCliMission } from "./explore-api.js";
+import { type RunJourneyProgrammaticallyOptions } from "./journey-api.js";
+import { runUsabilityMission } from "./ux-api.js";
+import { runVerifyFix } from "./verify-fix-api.js";
+import { type TargetConfig } from "./target-config.js";
+import { type EngineInfo } from "./engine.js";
+import type { CheckSuite, SuiteBudget } from "./check-suite.js";
+import { type RunSummary } from "./report-api.js";
+/**
+ * `jevitate check --suite <file>` (#137): jevitate as a CI regression gate. Runs every suite item
+ * — promoted Journeys, goals, missions, verify-fix replays — SEQUENTIALLY through the existing
+ * runners, inside one total action / wall-clock / USD budget, then decides pass/fail from the
+ * shared finding identity (`@jevitate/findings`):
+ *
+ *  - HARD findings fail the gate: a Journey assertion failed, an invariant was violated, a goal
+ *    success check failed, a verify-fix still reproduces (or is intermittent), a hard-signal
+ *    defect or a hang. Advisory findings (UX, 4xx-correlated console errors, Jev flags) never do,
+ *    unless the suite sets `gateAdvisory`.
+ *  - With `--baseline`, only findings NOT seen in the baseline gate ("new", including a new flaky
+ *    one); findings already in the baseline are tracked, not gated.
+ *  - Fail closed: an item that could not prove anything (crashed, inconclusive, refused) and any
+ *    budget overrun fail the gate; nothing that did not run is ever reported as passing.
+ *
+ * Everything is validated before the first browser opens (suite, invariant files and their probe
+ * origins, success specs, Journeys and their origins, verify-fix inputs, the model gateway). Every
+ * result is stamped with the engine identity and the caller's `--target-build`.
+ */
+export declare class CheckPreflightError extends Error {
+    readonly code: "E_CHECK_SUITE";
+    constructor(message: string);
+}
+/** The suite needs a model gateway and none was selected (fail closed, before anything runs). */
+export declare class CheckAiSetupError extends Error {
+    readonly code: "E_AI_SETUP_REQUIRED";
+    constructor(message: string);
+}
+export interface CheckGateways {
+    readonly judge: JudgmentPort;
+    readonly gen: GenerationPort;
+    readonly usage: UsageTracker;
+}
+/** The runners (real by default; tests inject fakes). */
+export interface CheckRunners {
+    readonly journey: (o: RunJourneyProgrammaticallyOptions) => Promise<JourneyRunResult>;
+    readonly goal: typeof runExploration;
+    readonly coverage: typeof runCoverageMission;
+    readonly adversarial: typeof runAdversarialCliMission;
+    readonly feature: typeof runFeatureCliMission;
+    readonly usability: typeof runUsabilityMission;
+    readonly verifyFix: typeof runVerifyFix;
+}
+export interface RunCheckOptions {
+    readonly suite: CheckSuite;
+    /** Where results, JUnit, SARIF, the report and the check record go. */
+    readonly outDir: string;
+    /** The caller's target build/commit id, stamped on every result. */
+    readonly targetBuild?: string;
+    /** `--baseline <run|tag|last>`: only findings not in it gate. */
+    readonly baseline?: string;
+    /** Dirs searched for run ids and `last` (default: this check's results dir). */
+    readonly baselineDirs?: readonly string[];
+    readonly baselinesDir?: string;
+    /** `--changed-routes`: only Journeys and goals touching these route globs run. */
+    readonly changedRoutes?: readonly string[];
+    readonly junitPath?: string;
+    readonly sarifPath?: string;
+    readonly jsonPath?: string;
+    /** Default Journeys dir (`~/.jevitate/journeys`) for targets that name none. */
+    readonly journeysDir: string;
+    /** The site-policy database (`jevitate site policy set`): Journey items are paced, throttled and budgeted per origin. */
+    readonly sitePolicyDbPath?: string;
+    /**
+     * Builds the model gateways — called only when an item needs one. Throws when no gateway is
+     * selected (fail closed, before anything runs).
+     */
+    readonly gateways?: () => Promise<CheckGateways>;
+    /** The selected gateway kind: `fake` gateways cost nothing (USD 0), so `maxUsd` is measurable. */
+    readonly aiMode?: "real" | "fake";
+    /** Per-origin settle/hang configuration (`~/.jevitate/targets.json`). */
+    readonly targetsConfig?: Readonly<Record<string, TargetConfig>>;
+    /** #247: the environments file a Journey item's `env` names (default: the repo's `.jevitate/environments.json`). */
+    readonly environmentsFile?: string;
+    /** Where a target's `secretFields` read their values (default `process.env`). */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly browserPortFactory?: () => BrowserPort;
+    readonly browser?: BrowserRunOptions;
+    readonly runners?: Partial<CheckRunners>;
+    /** Clock seams. */
+    readonly now?: () => number;
+    readonly nowIso?: () => string;
+    /** The suite file as the caller named it (SARIF's physical location). Default: its absolute path. */
+    readonly suiteUri?: string;
+}
+export type ItemKind = "journey" | "goal" | "mission" | "verify-fix";
+export interface CheckItemReport {
+    readonly target: string;
+    readonly kind: ItemKind;
+    readonly name: string;
+    readonly strategy?: string;
+    /** `ran`: a result exists; `error`: the item could not prove anything; `skipped`: not affected by `--changed-routes`. */
+    readonly status: "ran" | "error" | "skipped";
+    readonly error?: {
+        readonly type: string;
+        readonly message: string;
+    };
+    readonly resultPath?: string;
+    readonly runId?: string;
+    readonly outcome?: string;
+    /** #217: a goal item's own ending (succeeded/failed/exhausted/blocked/…); `outcome` is its canonical verdict. */
+    readonly goalOutcome?: string;
+    readonly actions: number;
+    readonly durationMs: number;
+    /** JUnit verdict after gating. */
+    readonly verdict: "passed" | "failed" | "error" | "skipped";
+    /** Keys of the gating findings this item's run observed. */
+    readonly gating: readonly string[];
+}
+export interface BudgetReport {
+    readonly limits: SuiteBudget;
+    readonly used: {
+        readonly actions: number;
+        readonly minutes: number;
+        readonly usd?: number;
+    };
+    /** Why the budget was exceeded (fail closed), or absent. */
+    readonly exceeded?: string;
+}
+export interface CheckFinding {
+    readonly key: string;
+    readonly title: string;
+    readonly category: string;
+    readonly severity: string;
+    readonly identity: FindingIdentity;
+    readonly gating: boolean;
+    readonly status?: DiffEntry["status"];
+    readonly modes: ConsolidatedDefect["modes"];
+    readonly reproduce?: string;
+}
+export interface CheckResult {
+    readonly kind: "jevitate-check";
+    readonly suite: string;
+    readonly suitePath: string;
+    readonly verdict: "pass" | "fail";
+    /** 0 pass · 1 a gating finding · 2 no gating finding, but an item errored or the budget was exceeded. */
+    readonly exitCode: 0 | 1 | 2;
+    readonly engine: EngineInfo;
+    readonly targetBuild?: string;
+    readonly startedAt: string;
+    readonly budget: BudgetReport;
+    /**
+     * Model usage summed over every item that ran (#163): calls, tokens, `jevUsd` + `generationUsd` =
+     * `totalUsd`, and `priced` (a `partial` total fails a `maxUsd` budget closed). Absent when no item
+     * needed a model gateway.
+     */
+    readonly usage?: UsageAggregate;
+    readonly items: readonly CheckItemReport[];
+    readonly findings: readonly CheckFinding[];
+    readonly summary: {
+        readonly items: number;
+        readonly passed: number;
+        readonly failed: number;
+        readonly errors: number;
+        readonly skipped: number;
+        readonly gatingFindings: number;
+    };
+    readonly diff?: {
+        readonly baseline: readonly RunSummary[];
+        readonly summary: FindingsDiff["summary"];
+    };
+    /** Every result file this check wrote (what `report`/`diff`/`baseline tag` read back). */
+    readonly results: readonly string[];
+    readonly junitPath: string;
+    readonly sarifPath: string;
+    readonly jsonPath: string;
+    readonly reportPath: string;
+}

package/dist/check-types.js

@@ -0,0 +1,35 @@
+/**
+ * `jevitate check --suite <file>` (#137): jevitate as a CI regression gate. Runs every suite item
+ * — promoted Journeys, goals, missions, verify-fix replays — SEQUENTIALLY through the existing
+ * runners, inside one total action / wall-clock / USD budget, then decides pass/fail from the
+ * shared finding identity (`@jevitate/findings`):
+ *
+ *  - HARD findings fail the gate: a Journey assertion failed, an invariant was violated, a goal
+ *    success check failed, a verify-fix still reproduces (or is intermittent), a hard-signal
+ *    defect or a hang. Advisory findings (UX, 4xx-correlated console errors, Jev flags) never do,
+ *    unless the suite sets `gateAdvisory`.
+ *  - With `--baseline`, only findings NOT seen in the baseline gate ("new", including a new flaky
+ *    one); findings already in the baseline are tracked, not gated.
+ *  - Fail closed: an item that could not prove anything (crashed, inconclusive, refused) and any
+ *    budget overrun fail the gate; nothing that did not run is ever reported as passing.
+ *
+ * Everything is validated before the first browser opens (suite, invariant files and their probe
+ * origins, success specs, Journeys and their origins, verify-fix inputs, the model gateway). Every
+ * result is stamped with the engine identity and the caller's `--target-build`.
+ */
+export class CheckPreflightError extends Error {
+    code = "E_CHECK_SUITE";
+    constructor(message) {
+        super(message);
+        this.name = "CheckPreflightError";
+    }
+}
+/** The suite needs a model gateway and none was selected (fail closed, before anything runs). */
+export class CheckAiSetupError extends Error {
+    code = "E_AI_SETUP_REQUIRED";
+    constructor(message) {
+        super(message);
+        this.name = "CheckAiSetupError";
+    }
+}
+//# sourceMappingURL=check-types.js.map

package/dist/check-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-types.js","sourceRoot":"","sources":["../src/check-types.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,eAAwB,CAAC;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,iGAAiG;AACjG,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,GAAG,qBAA8B,CAAC;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/cli-args.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Numeric option parsers (#218), used as commander `argParser`s so a bad number is refused while
+ * the command line is parsed — a usage error (exit 64, `useUsageExitCode`), before anything runs —
+ * rather than a `NaN` reaching a run and failing it at runtime (exit 2, "proves nothing").
+ *
+ * Every numeric flag of every command takes one of these; `cli-refusal.test.ts` walks the program
+ * and fails when a `<n>`/`<ms>`/`<k>` option has none.
+ */
+export interface IntArgBounds {
+    /** Smallest accepted value (inclusive). */
+    readonly min?: number;
+    /** Largest accepted value (inclusive). */
+    readonly max?: number;
+}
+/** A commander argParser for an integer option within `bounds` (decimal digits only: no `1e3`, `0x10`, `2.5`). */
+export declare function intArg(bounds?: IntArgBounds): (value: string) => number;
+/** `≥ 1`: counts and caps (replays, attempts, takes, actions, concurrency, …). */
+export declare const positiveIntArg: (value: string) => number;
+/** `≥ 0`: durations in ms and counts where 0 means "none" (e.g. `--hang-replays 0`). */
+export declare const nonNegativeIntArg: (value: string) => number;
+/** A commander argParser for a ratio in [0, 1] (e.g. `--min-control-coverage 0.8`). */
+export declare function ratioArg(value: string): number;
+/** A commander argParser for a number > 0, fractions allowed (e.g. `--stall-timeout 1.5` seconds). */
+export declare function positiveNumberArg(value: string): number;
+/** A commander argParser for any finite number (e.g. an RNG `--seed`). */
+export declare function finiteNumberArg(value: string): number;

package/dist/cli-args.js

@@ -0,0 +1,50 @@
+import { InvalidArgumentError } from "commander";
+function describe(bounds) {
+    if (bounds.min !== undefined && bounds.max !== undefined)
+        return `an integer from ${bounds.min} to ${bounds.max}`;
+    if (bounds.min === 0)
+        return "a non-negative integer";
+    if (bounds.min === 1)
+        return "a positive integer";
+    if (bounds.min !== undefined)
+        return `an integer ≥ ${bounds.min}`;
+    if (bounds.max !== undefined)
+        return `an integer ≤ ${bounds.max}`;
+    return "an integer";
+}
+/** A commander argParser for an integer option within `bounds` (decimal digits only: no `1e3`, `0x10`, `2.5`). */
+export function intArg(bounds = {}) {
+    return (value) => {
+        const n = /^-?\d+$/.test(value.trim()) ? Number(value) : Number.NaN;
+        if (!Number.isSafeInteger(n) || (bounds.min !== undefined && n < bounds.min) || (bounds.max !== undefined && n > bounds.max)) {
+            throw new InvalidArgumentError(`must be ${describe(bounds)} (got ${JSON.stringify(value)})`);
+        }
+        return n;
+    };
+}
+/** `≥ 1`: counts and caps (replays, attempts, takes, actions, concurrency, …). */
+export const positiveIntArg = intArg({ min: 1 });
+/** `≥ 0`: durations in ms and counts where 0 means "none" (e.g. `--hang-replays 0`). */
+export const nonNegativeIntArg = intArg({ min: 0 });
+/** A commander argParser for a ratio in [0, 1] (e.g. `--min-control-coverage 0.8`). */
+export function ratioArg(value) {
+    const n = value.trim() === "" ? Number.NaN : Number(value);
+    if (!Number.isFinite(n) || n < 0 || n > 1)
+        throw new InvalidArgumentError(`must be a number from 0 to 1 (got ${JSON.stringify(value)})`);
+    return n;
+}
+/** A commander argParser for a number > 0, fractions allowed (e.g. `--stall-timeout 1.5` seconds). */
+export function positiveNumberArg(value) {
+    const n = value.trim() === "" ? Number.NaN : Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new InvalidArgumentError(`must be a positive number (got ${JSON.stringify(value)})`);
+    return n;
+}
+/** A commander argParser for any finite number (e.g. an RNG `--seed`). */
+export function finiteNumberArg(value) {
+    const n = value.trim() === "" ? Number.NaN : Number(value);
+    if (!Number.isFinite(n))
+        throw new InvalidArgumentError(`must be a finite number (got ${JSON.stringify(value)})`);
+    return n;
+}
+//# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

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

package/dist/cli-output.d.ts

@@ -0,0 +1,106 @@
+import { type KeySourceReport, type KeyVerificationReport } from "./key-report.js";
+import type { Command } from "commander";
+import type { JsonEnvelope } from "./envelope.js";
+/**
+ * Human vs machine output for the CLI (#210). One rule for every command that has both:
+ *
+ *  - `--json`: exactly one line, the `{v, ok, data | error}` envelope, on stdout — the machine
+ *    contract, byte-for-byte what it always was.
+ *  - otherwise: a short human summary on stdout (a success) or an `error <CODE>: <message>` line on
+ *    stderr (a refusal) — never raw JSON.
+ *
+ * The human style follows `jevitate check`'s: an upper-case tag padded to a column, then the detail;
+ * the last lines say where the full result is and what to run next (`next: …`).
+ *
+ * The exit code always comes from exit-codes.ts: the caller's verdict code when it has one,
+ * otherwise the envelope's class (0 ok · 64 usage error · 2 the command failed).
+ */
+export interface EmitOptions<T> {
+    /** `--json` was passed: print the envelope. */
+    readonly json: boolean;
+    /** The verdict's exit code (a mission's `exitCode`, a check's, a verify-fix's); default: the envelope's class. */
+    readonly exitCode?: number;
+    /** The human rendering of a successful envelope's `data`; default: nothing but the exit code. */
+    readonly human?: (data: T) => string;
+    /** The command, named in a usage error's `--help` hint (e.g. `explore`, `ledger add`). */
+    readonly command?: string;
+}
+export declare function emitEnvelope<T>(program: Command, envelope: JsonEnvelope<T>, opts: EmitOptions<T>): void;
+/** `error E_EXPLORE_ARGS: --url is required` (+ a `--help` hint for a usage error). */
+export declare function formatErrorHuman(error: {
+    readonly code: string;
+    readonly message: string;
+}, command?: string): string;
+/**
+ * A mission result (any strategy) as a human summary: the verdict, the defects and hangs by
+ * fingerprint, why a broken run proved nothing, where the result file is, and what to run next.
+ */
+export declare function formatMissionHuman(result: unknown): string;
+/**
+ * `explore --repeat/--persona`'s aggregate (multi-run) result (#226: the #217 contract): the canonical
+ * verdict as the headline (a goal's own ending beside it, never in its place), why it is what it is,
+ * each persona's verdict and each run's with its reason, the persona diff's status differences, the
+ * agreed and flaky findings, and the find-out answer(s).
+ */
+export declare function formatMultiRunHuman(result: unknown): string;
+/**
+ * `verify-fix`: the verdict, why, and what to do about it.
+ * #230: `opts.result` is the `--result` the user passed (not the ledger fallback's own path) — a
+ * re-check hint must carry it too, or (with no ledger entry for this fingerprint at that path) the
+ * follow-up `verify-fix` fails to find the repro material.
+ */
+export declare function formatVerifyFixHuman(report: unknown, opts?: {
+    readonly result?: string;
+}): string;
+/** `ledger list`. #230: `opts.dir` is the `--dir` the user passed — the follow-up hints must carry it too. */
+export declare function formatLedgerListHuman(listed: {
+    readonly entries: readonly object[];
+}, opts?: {
+    readonly dir?: string;
+}): string;
+/**
+ * `ledger add`. #230: `opts.dir` is the `--dir` the user passed. `verify-fix`'s equivalent flag is
+ * named `--regressions-dir` (same directory, a ledger's own `--dir`), so the hint uses that name.
+ */
+export declare function formatLedgerAddHuman(added: object, opts?: {
+    readonly dir?: string;
+}): string;
+/** `ledger verify`. #230: `opts.dir` is the `--dir` the user passed (see `formatLedgerAddHuman`). */
+export declare function formatLedgerVerifyHuman(verified: object, opts?: {
+    readonly dir?: string;
+}): string;
+/**
+ * `init`'s key report: per feature, which keys are configured — never "collected: []", which read
+ * as "keys missing" when every key was already set (#210). Collection either stores every missing
+ * key or fails closed, so after it every required key is configured. Names only, never a value.
+ */
+export declare function formatInitKeysHuman(keys: Readonly<Record<string, {
+    readonly required: readonly string[];
+    readonly collected: readonly string[];
+    readonly missing?: readonly string[];
+    readonly sources?: readonly KeySourceReport[];
+    readonly verification?: readonly KeyVerificationReport[];
+    readonly warnings?: readonly string[];
+}>>): string;
+/**
+ * `regression capture` (#227): a committed regression, or a failure too flaky to commit — never the
+ * raw envelope. #230: `opts.dir` is the `--dir` the user passed — the `regression run` hint must
+ * carry it too, or (a non-default regressions dir, e.g. the README demo's `--dir demo-regressions`)
+ * the follow-up looks in the default dir and refuses E_REGRESSION_NOT_FOUND.
+ */
+export declare function formatRegressionCaptureHuman(result: unknown, opts?: {
+    readonly dir?: string;
+}): string;
+/**
+ * `regression run` (#227): the verdict, why, and what to do about it — matches `verify-fix`'s shape.
+ * #230: `opts.dir` is the `--dir` the user passed — the re-check hints must carry it too.
+ */
+export declare function formatRegressionRunHuman(report: unknown, opts?: {
+    readonly dir?: string;
+}): string;
+/** `baseline tag` (#227). */
+export declare function formatBaselineTagHuman(data: unknown): string;
+/** `baseline list` (#227): every tag, or a next step when there are none yet. */
+export declare function formatBaselineListHuman(data: unknown): string;
+/** `baseline show` (#227). */
+export declare function formatBaselineShowHuman(data: unknown): string;