@jevitate/cli 0.7.0 → 0.9.0

package/dist/jev-advisor.js

@@ -0,0 +1,172 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { contentHash } from "@jevitate/domain";
+import { JevJudgmentGateway, JevProviderError, MissingCredentialError, RetryingJudgmentPort, UsageTracker, envCredentialStore, jevProviderOverride, realJevClientCall, resolveJevRoute, } from "@jevitate/ai-core";
+import { GatewaySelectionError, keyPreflightOpts } from "./cli-shared.js";
+import { loadLocalCredentials } from "./credentials-file.js";
+import { preflightRunKeys } from "./run-key-preflight.js";
+import { resolveUsagePricing } from "./usage-config.js";
+/**
+ * #434/#435 — the advisory Jev layer of the review sheets and the pre-approval pipeline: one
+ * `JudgmentPort` (the existing judgment gateway, TypeSafe or OpenRouter key, #429) behind a cache
+ * keyed by the content hash of what is asked, plus the usage of every call actually made.
+ *
+ * Model use follows the CLI's `--real` convention: the layer runs only on a command given `--real`
+ * (review sheets, approvals, `catalog analyze`; MCP `real: true`). Unlike a run, a missing judgment
+ * key is not a refusal here — the deterministic layer stands on its own, so the sheet says
+ * "skipped: no judgment key". Without `--real` it says "skipped: pass --real".
+ *
+ * The cache (`<project>/.jevitate/cache/jev/<sha256>.json`, gitignored) holds ANSWERS only — a kind,
+ * a value, a probability — keyed by `sha256(state + questions)`. The state is built from catalog
+ * text (job stories, persona descriptions, a Journey's review-sheet lines, which never carry a
+ * secret value), and it is never written: nothing secret is cached. A re-review of unchanged
+ * content asks nothing new. An unreadable entry is a miss (it is re-asked and rewritten).
+ */
+/** Bumped when the questions' meaning changes in a way their text does not show. */
+export const JEV_CACHE_VERSION = 1;
+/** Why the Jev layer did not run. */
+export const JEV_SKIPPED_PASS_REAL = "pass --real to ask Jev (needs a judgment key)";
+export const JEV_SKIPPED_NO_KEY = "no judgment key — set TYPESAFE_API_KEY or OPENROUTER_API_KEY (jevitate ai setup)";
+function validAnswer(q, a) {
+    if (a === null || typeof a !== "object")
+        return false;
+    const o = a;
+    if (o.kind !== q.kind)
+        return false;
+    if (q.kind === "choice")
+        return typeof o.value === "string" && q.options.includes(o.value) && typeof o.confidence === "number" && Number.isFinite(o.confidence);
+    if (q.kind === "noul")
+        return typeof o.value === "boolean" && typeof o.probability === "number" && Number.isFinite(o.probability);
+    return typeof o.value === "number" && Number.isFinite(o.value);
+}
+function validAnswers(questions, answers) {
+    if (answers === null || typeof answers !== "object")
+        return false;
+    const rec = answers;
+    return Object.entries(questions).every(([name, q]) => validAnswer(q, rec[name]));
+}
+/** #434/#435: the judgment port behind a memory + on-disk answer cache, counting what it asks. */
+export class CachedJevAdvisor {
+    judge;
+    cacheDir;
+    usage;
+    #memory = new Map();
+    #asked = 0;
+    #cached = 0;
+    constructor(judge, 
+    /** The answer cache directory; null: memory only (outside a project). */
+    cacheDir, usage) {
+        this.judge = judge;
+        this.cacheDir = cacheDir;
+        this.usage = usage;
+    }
+    async ask(state, questions) {
+        const key = contentHash({ v: JEV_CACHE_VERSION, state, questions });
+        const hit = this.#memory.get(key) ?? (await this.#read(key, questions));
+        if (hit !== undefined) {
+            this.#memory.set(key, hit);
+            this.#cached += Object.keys(questions).length;
+            return { answers: hit, cached: true };
+        }
+        this.#asked += Object.keys(questions).length;
+        const answers = await this.judge.systemOne({ state, questions });
+        if (!validAnswers(questions, answers))
+            throw new Error("the judgment answers do not match the questions asked");
+        this.#memory.set(key, answers);
+        await this.#write(key, answers);
+        return { answers, cached: false };
+    }
+    layer() {
+        const usage = this.usage.snapshot();
+        const { priceSource, missing, ...counts } = usage;
+        return {
+            status: "ran",
+            asked: this.#asked,
+            cached: this.#cached,
+            ...(usage.judgments + usage.generations === 0
+                ? {}
+                : { usage: { ...counts, ...(priceSource === undefined ? {} : { priceSource: [...priceSource] }), ...(missing === undefined ? {} : { missing: [...missing] }) } }),
+        };
+    }
+    async #read(key, questions) {
+        if (this.cacheDir === null)
+            return undefined;
+        let raw;
+        try {
+            raw = await readFile(join(this.cacheDir, `${key}.json`), "utf8");
+        }
+        catch (err) {
+            if (typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT")
+                return undefined;
+            throw err;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined; // a torn entry is a miss: re-asked and rewritten
+        }
+        const answers = parsed?.version === JEV_CACHE_VERSION ? parsed.answers : undefined;
+        return validAnswers(questions, answers) ? answers : undefined;
+    }
+    async #write(key, answers) {
+        if (this.cacheDir === null)
+            return;
+        await mkdir(this.cacheDir, { recursive: true, mode: 0o700 });
+        const file = join(this.cacheDir, `${key}.json`);
+        const tmp = `${file}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify({ version: JEV_CACHE_VERSION, answers })}\n`, { mode: 0o600 });
+        await rename(tmp, file);
+    }
+}
+/** The answer cache directory of a project data dir (`<.jevitate>/cache/jev`), or null outside a project. */
+export function jevCacheDir(catalogDir) {
+    return catalogDir === null ? null : join(catalogDir, "cache", "jev");
+}
+/** The Jev layer's report when it did not run. */
+export function skippedLayer(reason) {
+    return { status: "skipped", reason, asked: 0, cached: 0 };
+}
+export function jevLayerOf(setup) {
+    if (setup === undefined)
+        return skippedLayer(JEV_SKIPPED_PASS_REAL);
+    return "advisor" in setup ? setup.advisor.layer() : skippedLayer(setup.skipped);
+}
+/**
+ * #434/#435: the Jev layer of one command. Without `--real`: skipped ("pass --real"). With it: an
+ * injected judge (tests) wins; else the live judgment gateway on the resolved Jev route
+ * (`--jev-provider`, else TypeSafe then OpenRouter) after the startup key check — or, when no
+ * judgment key is configured, skipped ("no judgment key"): the deterministic layer still runs.
+ * An unknown `--jev-provider` is refused (`GatewaySelectionError`), never ignored.
+ */
+export async function buildJevSetup(deps, opts) {
+    if (opts.real !== true)
+        return { skipped: JEV_SKIPPED_PASS_REAL };
+    const env = deps.explore?.env ?? process.env;
+    const usage = deps.explore?.usage ?? new UsageTracker(resolveUsagePricing(env));
+    if (deps.explore?.judge !== undefined)
+        return { advisor: new CachedJevAdvisor(deps.explore.judge, opts.cacheDir, usage) };
+    let provider;
+    try {
+        provider = jevProviderOverride(env, opts.jevProvider);
+    }
+    catch (err) {
+        if (err instanceof JevProviderError)
+            throw new GatewaySelectionError(err.message);
+        throw err;
+    }
+    const store = envCredentialStore(env, deps.explore?.localConfig ?? loadLocalCredentials());
+    try {
+        resolveJevRoute(store, provider);
+    }
+    catch (err) {
+        if (err instanceof MissingCredentialError)
+            return { skipped: JEV_SKIPPED_NO_KEY };
+        throw err;
+    }
+    await preflightRunKeys(["judgment"], store, { ...keyPreflightOpts(deps), ...(provider === undefined ? {} : { jevProvider: provider }) });
+    const judge = new RetryingJudgmentPort(new JevJudgmentGateway(store, await realJevClientCall(undefined, usage), provider));
+    return { advisor: new CachedJevAdvisor(judge, opts.cacheDir, usage) };
+}
+//# sourceMappingURL=jev-advisor.js.map

package/dist/jev-advisor.js.map

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

package/dist/journey-api.d.ts

@@ -1,4 +1,6 @@
-import { type Journey, type JourneyLintFinding } from "@jevitate/journey";
+import { type Journey, type JourneyLintFinding, type ApprovalProvenance } from "@jevitate/journey";
+import { type ApprovalConfirm } from "./approval-provenance.js";
+import type { JevSetup } from "./jev-advisor.js";
 import { type RunPolicy } from "@jevitate/domain";
 import { type BrowserPort, type BrowserSession, type EmulationSpec } from "@jevitate/playwright";
 import { type BrowserRunOptions } from "./browser-run-options.js";
@@ -6,7 +8,8 @@ import { RecordingInterpreter, type StepObserver } from "@jevitate/interpreter";
 import { type BlockedWrite, type ReplayDeltaSummary } from "@jevitate/explore";
 import { SecretPixelMask } from "./demo-capture.js";
 import { type ScreenshotsResult, type ScreenshotsSpec } from "./run-screenshots.js";
-import { type JourneyRunResult, type SelfHealer, type SiteGateDeps } from "@jevitate/runtime";
+import { type ProposedRevisionDraft, type ChangeScope, type JourneyRunResult, type SelfHealer, type SiteGateDeps } from "@jevitate/runtime";
+import { type JourneyResultProposal } from "./journey-result-record.js";
 import { type FixtureRecord, type MissionFixtures } from "./mission-fixtures.js";
 import { type ResolvedJourneyEnvironment } from "./environments.js";
 import { type OutcomeCheckFailure } from "./journey-network-checks.js";
@@ -28,6 +31,14 @@ export declare class JourneyRequiresAuthError extends Error {
  * #401: the Journey's assertions cannot prove its outcome (the `lintJourney` errors). `promote`
  * refuses unless the reviewer accepts it with a non-empty `--accept-weak <reason>`.
  */
+/** #432: `journey promote --reviewed-hash`: the Journey changed after the reviewer's sheet was produced. */
+export declare class StaleReviewError extends Error {
+    readonly code = "E_JOURNEY_REVIEW_STALE";
+}
+/** #453: a bad combination of proposal flags (`--proposal` with `--reject-proposal`; a rejection with no reason). Exit 64. */
+export declare class JourneyProposalArgsError extends Error {
+    readonly code = "E_JOURNEY_PROPOSAL_ARGS";
+}
 export declare class WeakJourneyError extends Error {
     readonly findings: readonly JourneyLintFinding[];
     constructor(message: string, findings?: readonly JourneyLintFinding[]);
@@ -56,6 +67,14 @@ export interface RunJourneyProgrammaticallyOptions {
      * this port (enforced by `JourneyRunner`'s write floor).
      */
     selfHealer?: SelfHealer;
+    /**
+     * #453: the change context a `hybrid`/`full` self-heal is explained by (`readJourneyChangeScope`).
+     * With it the runner gets the risky-control classification (`journeyStepRisk`) and a per-step write
+     * blocker, so a guarded click/fill may be retargeted. Absent: every break is unexplained (never healed).
+     */
+    heal?: {
+        readonly scope: ChangeScope;
+    };
     /**
      * Mission fixtures (#140/#144), built for the journey's own site once it is known: set up before
      * the browser opens (a failure throws `FixtureSetupError` — the journey never runs on unknown
@@ -153,6 +172,14 @@ export interface MutationReplayFields {
     /** The writes aborted in `blockWritesAtStep`'s window. */
     blockedWrites?: BlockedWrite[];
 }
+/** #453: what a self-heal run adds to its result — the proposal it wrote and the persisted result file. */
+export interface HealRunFields {
+    proposal?: JourneyResultProposal & {
+        reviewCommand: string;
+        acceptCommand: string;
+    };
+    resultPath?: string;
+}
 /**
  * #246: a secret parameter's value (declared `secret: true`, or a credential-like name) never comes
  * back in a run's output — the interpreter's vars start as the params, so the value is masked there.
@@ -184,10 +211,48 @@ export declare function lintJourneyById(dir: string, id: string, opts?: {
  * #401: lints first — a Journey whose assertions cannot prove its outcome is refused
  * (`WeakJourneyError`) unless the reviewer accepts it with a non-empty `--accept-weak <reason>`,
  * which is recorded on the Journey (`metadata.acceptedWeak`). Warnings never block.
+ *
+ * #432: records the approval (`metadata.approval`: the review hash, when, the waiver) and keeps a
+ * snapshot of the approved Journey (`.approved/<id>.json`). Given `reviewedHash` (what the reviewer's
+ * sheet showed), a Journey that changed since is refused (`StaleReviewError`) before anything else.
+ *
+ * #433: then the catalog gate (`journeyCatalogGate`): a Journey linking a job/persona that is not
+ * approved is refused (`UnvettedLinksError`) unless `acceptUnvetted` (recorded in
+ * `approval.waivers`), and the shared pre-approval findings are acknowledged (`acceptFindings`,
+ * recorded in `approval.acceptedFindings`) — the same pipeline `persona|job approve` and
+ * `demo approve` use. `catalogDir` (default: the project's `.jevitate/`) holds personas/jobs.
  */
-export declare function promoteJourney(dir: string, id: string, opts?: {
+export interface PromoteJourneyOptions {
     acceptWeak?: string;
-}): Promise<Journey>;
+    reviewedHash?: string;
+    acceptUnvetted?: string;
+    acceptFindings?: string;
+    /** The catalog's directory; undefined: the project's `.jevitate/` (none outside a project). */
+    catalogDir?: string | null;
+    /** Which approval path asks (`demo approve` promotes through here too). */
+    action?: "journey promote" | "demo approve";
+    /** #434/#435: the advisory Jev layer of the pre-approval readiness and analysis (`--real`), or why it is skipped. */
+    jev?: JevSetup;
+    /**
+     * #437: confirms the approval (after every gate, before anything is written) and returns its
+     * provenance — the CLI's `makeApprovalConfirm` (a typed confirmation on a TTY, the escape hatch,
+     * or the MCP channel). Omitted: recorded as `non-interactive` (`programmaticProvenance`).
+     */
+    confirm?: ApprovalConfirm;
+    /**
+     * #453: accept this pending self-heal proposal (its id) instead of promoting the stored Journey as
+     * is. The proposal is re-checked (stale / proof untouched), goes through every gate as the
+     * Journey it would make, is confirmed with the proposal shown, and `reviewedHash` is compared with
+     * ITS `proposedHash`. Only this writes the stored Journey.
+     */
+    proposal?: string;
+    /** #453: reject this pending proposal (its id) — needs `reason`; the stored Journey is untouched. */
+    rejectProposal?: string;
+    reason?: string;
+    /** #453: how the rejection was made (`rejectionProvenance`); omitted: the programmatic one. */
+    rejectProvenance?: ApprovalProvenance;
+}
+export declare function promoteJourney(dir: string, id: string, opts?: PromoteJourneyOptions): Promise<Journey>;
 /**
  * The one programmatic surface for "run this published Journey by id" —
  * used by BOTH the CLI `journey run` action and external callers. Builds
@@ -201,6 +266,12 @@ export declare function runJourneyProgrammatically(opts: RunJourneyProgrammatica
     fixtures?: FixtureRecord;
     videoPaths?: string[];
     actionDeltas?: ReplayDeltaSummary;
-} & Partial<ScreenshotsResult> & MutationReplayFields>;
+} & Partial<ScreenshotsResult> & MutationReplayFields & HealRunFields>;
+/**
+ * The revision a run on an environment proposed, onto the STORED Journey: each changed step's
+ * `before` is the stored step, its `after` the retarget — a navigate URL on the environment's base
+ * URL moved back onto the recorded site. Without an environment the draft is the stored Journey's.
+ */
+export declare function draftOnStored(stored: Journey, draft: ProposedRevisionDraft, env: ResolvedJourneyEnvironment | undefined): ProposedRevisionDraft;
 /** `err` with every secret (and its URL-encoded forms) masked in its message and stack — same object, same class. */
 export declare function redactErrorSecrets(err: unknown, secrets: readonly string[]): unknown;