@jevitate/cli 0.5.0 → 0.7.0

package/dist/goal-run-flags.js

@@ -0,0 +1,220 @@
+/**
+ * #369: the goal run's run-shaping flags, shared by `jevitate explore` (goal/usability) and
+ * `jevitate explore-author-journey` (whose discovery and corroborating takes ARE goal runs) — one
+ * definition of each flag (text, parser, default) and one resolver, so the two commands accept and
+ * validate the same setup and an author run can reproduce what a goal run needed.
+ */
+import { Option } from "commander";
+import { parseSecretField, validateDenyPatterns, } from "@jevitate/explore";
+import { intArg, nonNegativeIntArg, positiveIntArg } from "./cli-args.js";
+import { LITERAL_SECRET_WARNING, resolveSecretArgs } from "./secret-args.js";
+import { secretCommandRunner } from "./secret-command.js";
+import { loadTypeFixtures } from "./type-fixture-file.js";
+import { SessionFileInProjectError, assertSessionFileOutsideProject } from "./project-dir.js";
+import { parseScreenshotsArg } from "./run-screenshots.js";
+import { TargetConfigError, loadTargetsFile, resolveTargetConfig } from "./target-config.js";
+import { emulationFromFlags } from "./cli-shared.js";
+const collect = (v, prev) => [...prev, v];
+/** Each shared flag, built fresh per command (commander owns an `Option` once added). */
+export const GOAL_RUN_OPTIONS = {
+    successWhen: () => new Option("--success-when <when>", "when the --success page checks must hold: final (default; on the final page) | held (on the final page, or all together at any settled step — a one-time secret, a toast) | " +
+        "each (each went from not holding to holding at some settled step, in any order — checks on different pages; the run stops once all have). reloadThen is always final"),
+    allowVacuousChecks: () => new Option("--allow-vacuous-checks", "downgrade a vacuous --success check to a warning. By default a check satisfied before the run's first action — a page check that held on the seed page and never changed " +
+        "(an empty result container), a requestMade/responseStatus matched only by a page-load or polling request — FAILS: it cannot verify the goal"),
+    actionDeltas: () => new Option("--action-deltas", "opt-in (#303; every --strategy, not --feature): record what each action changed on the page — an accessibility snapshot before and after, announcements, " +
+        "the action's requests — redacted, with a code verdict per step (no-change | relevant-change | inconclusive) used by the goal loop's no-progress check and a persistence re-check after writes (goal), and as defect evidence (adversarial, coverage); " +
+        "adds `delta` to every transcript step (and Recording step, goal) and `actionDeltas` to the result. Costs about 50-100 ms per action on a small page, 0.3-0.5 s on a large one"),
+    secret: () => new Option("--secret <value|env:VAR>", "REDACTION ONLY: a secret/PII value kept out of every model call and artifact (repeatable); env:VAR reads it from the environment (preferred: a literal is visible in the process list and shell history). It is never typed into a field — to log in, bind it with --secret-field (or start from --storage-state)")
+        .default([])
+        .argParser(collect),
+    secretField: () => new Option("--secret-field <binding>", "goal/usability strategy: '<label|testId|type|id|name>=<value>=env:<VAR>' (repeatable), e.g. 'label=Password=env:APP_PASSWORD'. When the run types into a matching field, code types $VAR itself; the model sees only «secret:VAR» and the Recording {redacted:true}. " +
+        "A value delivered during the run (an emailed code): '<descriptor>=cmd:<command>' runs the command when the field is typed and types its stdout (needs --allow-secret-cmd)")
+        .default([])
+        .argParser(collect),
+    totp: () => new Option("--totp <binding>", "goal/usability strategy: '<descriptor>=env:<VAR>' with $VAR a base32 TOTP seed (repeatable), e.g. 'label=Authentication code=env:APP_TOTP_SEED'. The 6-digit code is computed locally (RFC 6238) when the field is typed; the seed never reaches a model or disk")
+        .default([])
+        .argParser(collect),
+    typeFixture: () => new Option("--type-fixture <binding>", "goal strategy: '<label|testId|type|id|name>=<value>=<file>' (repeatable), e.g. 'label=Paste your text=./fixtures/import.txt'. When the run types into a matching field, code types the file's exact text verbatim (line breaks kept, never paraphrased or capped); the model sees only «fixture:<file name>». Recorded as typed unless it holds a --secret")
+        .default([])
+        .argParser(collect),
+    fixture: () => new Option("--fixture <path>", "local file the upload op attaches to a file input (goal and usability strategies); must exist"),
+    saveStorageState: () => new Option("--save-storage-state <file>", "write the context's storageState (cookies + origin storage) here when the run ends; mode 0600, contents never logged. " +
+        "Useful with a rotating refresh token: --storage-state's file goes stale after one authenticated run refreshes it, " +
+        "so point --save-storage-state at the SAME file (or a new one) to keep it usable for the next run. " +
+        "Written on every exit path -- a crash or a SIGTERM/SIGINT kill included (#159), not only a clean end -- but " +
+        "never over a good file with a session that already looks lost/logged-out; the last known-good state is used " +
+        "instead, or nothing is written if none was ever captured."),
+    replyWaitMs: () => new Option("--reply-wait-ms <ms>", "conversational pages: how long to keep waiting for a reply while the page shows no sign of working on one " +
+        "(goal and usability; default 60000). While a request the message started is in flight, a busy indicator shows, " +
+        "or the reply is still growing, the wait continues up to --reply-ceiling-ms").argParser(positiveIntArg),
+    replyQuietMs: () => new Option("--reply-quiet-ms <ms>", "conversational pages: how long a reply must hold still (no new text, no busy sign) before it is read as complete " +
+        "(goal and usability; default 1000). Raise it for an assistant that answers in several parts (a sentence, then a card a moment later)").argParser(positiveIntArg),
+    replyCeilingMs: () => new Option("--reply-ceiling-ms <ms>", "conversational pages: hard ceiling on the TOTAL wait for one sent message's reply — the send's own wait plus every later 'wait' — " +
+        "however busy the page stays; once spent the run ends naming the missing reply (default 180000; never below --reply-wait-ms) (default 180000; never below --reply-wait-ms)").argParser(positiveIntArg),
+    replyMaxChars: () => new Option("--reply-max-chars <n>", "conversational pages: cap on each generated chat message (goal and usability; default 300)").argParser(intArg({ min: 20, max: 2000 })),
+    jobWaitMs: () => new Option("--job-wait-ms <ms>", "goal and usability: while the page shows an in-progress status (\"Simulating…\", aria-busy, a job \"is running\"), " +
+        "waits keep waiting with backoff — and a model 'blocked' is deferred — up to this budget (default: --reply-ceiling-ms, 180000); " +
+        "it also bounds a busy indicator the app visibly keeps working behind (live progress, a job poll) before it is a hang, " +
+        "and a wait the page documents (\"usually takes a minute\") can raise it").argParser(positiveIntArg),
+    deny: () => new Option("--deny <pattern>", "a control no mission may click (repeatable): an accessible-name regex (/Archive/i or Archive) or a descriptor role=button;name=Archive. " +
+        "Session-ending (Sign out), destructive (Delete, Revoke, Rotate) and paid (Buy, Run simulation, Generate, Send invite) controls are refused by default")
+        .default([])
+        .argParser(collect),
+    paid: () => new Option("--paid <pattern>", "an app control that costs money or credits (repeatable; same syntax as --deny), e.g. /^(Analyze|Draft|Improve)\\b/i: treated like the built-in paid " +
+        "vocabulary — the budget guard sees it, hang replays never repeat it, and a goal that asks for it may still click it")
+        .default([])
+        .argParser(collect),
+    allowDestructive: () => new Option("--allow-destructive", "let missions click session-ending, destructive and paid controls (a --deny pattern still holds). A goal run already may click one its goal asks for"),
+    dialogs: () => new Option("--dialogs <policy>", "native window.confirm/prompt dialogs: dismiss (default) or accept. accept still dismisses one whose message names a session-ending, " +
+        "destructive or paid action the run may not take (without --allow-destructive or a goal asking for it); every dialog is logged"),
+    readRpc: () => new Option("--read-rpc <glob>", "a POST request that only READS (repeatable): an RPC-method glob (Estimate*, pkg.Service/Preview*) or a path glob (/api/search*). " +
+        "gRPC-web/Connect Get*/List*/Search*/Find*/Watch*/Stream*/Count*/Describe*/Read* methods are reads already. Reads are never guarded or reported as duplicate writes")
+        .default([])
+        .argParser(collect),
+    hangReplays: () => new Option("--hang-replays <n>", "fresh-context replays that confirm a hang (default 2; 0 = don't replay, the hang is reported unconfirmed)").argParser(nonNegativeIntArg),
+    settleIgnore: () => new Option("--settle-ignore <pattern>", "a request URL pattern the target marks as background (never pending work; repeatable, * wildcard)")
+        .default([])
+        .argParser(collect),
+    longPollMs: () => new Option("--long-poll-ms <n>", "a request pending this long on an interactive page is a long-poll (default 5000)").argParser(nonNegativeIntArg),
+    apiPrefix: () => new Option("--api-prefix <path>", "a path prefix whose requests are the app's API in the timing summary (repeatable), e.g. /api/")
+        .default([])
+        .argParser(collect),
+    ignoreNoProgress: () => new Option("--ignore-no-progress <pattern>", "a route / action label / busy indicator where ui-no-progress is expected (repeatable, * wildcard)")
+        .default([])
+        .argParser(collect),
+    allowSecretCmd: () => new Option("--allow-secret-cmd", "opt-in: a --secret-field <descriptor>=cmd:<command> may run its command (in a shell, at type time, 60s timeout) and type its output (operator-declared only; refused otherwise)").default(false),
+    secretCmdAttempts: () => new Option("--secret-cmd-attempts <n>", "#359: how many times one cmd: secret field's command may run in this run (default 3); past it, typing that field fails without running the command again (read-the-code commands usually have side effects)").argParser(positiveIntArg),
+};
+/** A goal-run flag the command must refuse (exit 64): `code` + the user-facing message. */
+export class GoalRunFlagError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GoalRunFlagError";
+    }
+}
+/** A refusal keeps its own code when it has a typed one (a session file in the project, a bad targets.json); the rest are E_EXPLORE_ARGS. */
+const asError = (err) => err instanceof GoalRunFlagError
+    ? err
+    : new GoalRunFlagError(err instanceof SessionFileInProjectError || err instanceof TargetConfigError ? err.code : "E_EXPLORE_ARGS", err instanceof Error ? err.message : String(err));
+/** `--dialogs`: a mistyped value never silently means "dismiss" (#334). */
+export function dialogsFromFlags(o) {
+    if (o.dialogs === undefined)
+        return undefined;
+    if (o.dialogs !== "dismiss" && o.dialogs !== "accept") {
+        throw new GoalRunFlagError("E_EXPLORE_ARGS", `--dialogs must be dismiss or accept, got ${JSON.stringify(o.dialogs)}`);
+    }
+    return o.dialogs;
+}
+/** `--success-when`: final | held | each. */
+export function successWhenFromFlags(o) {
+    if (o.successWhen === undefined)
+        return undefined;
+    if (o.successWhen !== "held" && o.successWhen !== "final" && o.successWhen !== "each") {
+        throw new GoalRunFlagError("E_EXPLORE_ARGS", `--success-when must be "final", "held" or "each", got ${JSON.stringify(o.successWhen)}`);
+    }
+    return o.successWhen;
+}
+/** The conversational-page tuning (`--reply-*`, `--job-wait-ms`), validated. */
+export function conversationFromFlags(o) {
+    const conversation = {
+        ...(o.replyWaitMs === undefined ? {} : { replyWaitMs: Number(o.replyWaitMs) }),
+        ...(o.replyQuietMs === undefined ? {} : { replyQuietMs: Number(o.replyQuietMs) }),
+        ...(o.replyCeilingMs === undefined ? {} : { replyCeilingMs: Number(o.replyCeilingMs) }),
+        ...(o.replyMaxChars === undefined ? {} : { replyMaxChars: Number(o.replyMaxChars) }),
+        ...(o.jobWaitMs === undefined ? {} : { jobWaitMs: Number(o.jobWaitMs) }),
+    };
+    if ((conversation.replyWaitMs !== undefined && !(Number.isInteger(conversation.replyWaitMs) && conversation.replyWaitMs > 0)) ||
+        (conversation.replyCeilingMs !== undefined && !(Number.isInteger(conversation.replyCeilingMs) && conversation.replyCeilingMs > 0)) ||
+        (conversation.replyMaxChars !== undefined &&
+            !(Number.isInteger(conversation.replyMaxChars) && conversation.replyMaxChars >= 20 && conversation.replyMaxChars <= 2000))) {
+        throw new GoalRunFlagError("E_EXPLORE_ARGS", "--reply-wait-ms and --reply-ceiling-ms must be positive integers; --reply-max-chars an integer in 20..2000");
+    }
+    if (conversation.jobWaitMs !== undefined && !(Number.isInteger(conversation.jobWaitMs) && conversation.jobWaitMs > 0)) {
+        throw new GoalRunFlagError("E_EXPLORE_ARGS", "--job-wait-ms must be a positive integer");
+    }
+    return conversation;
+}
+/** `--secret-field` / `--totp` bindings, resolved from the environment (#72; `cmd:` needs `--allow-secret-cmd`, #324). */
+export function secretFieldsFromFlags(o, env = process.env) {
+    try {
+        return [
+            ...o.secretField.map((s) => parseSecretField(s, "value", env, { allowCmd: o.allowSecretCmd === true })),
+            ...o.totp.map((s) => parseSecretField(s, "totp", env)),
+        ];
+    }
+    catch (err) {
+        throw asError(err);
+    }
+}
+/** The `targets.json` flag overlay (patterns added, numbers and opt-ins winning). */
+export function targetFlagsFromFlags(o, dialogs) {
+    return {
+        settleIgnore: o.settleIgnore ?? [],
+        ignoreNoProgress: o.ignoreNoProgress ?? [],
+        apiPrefixes: o.apiPrefix ?? [],
+        deny: o.deny ?? [],
+        paid: o.paid ?? [],
+        readRpc: o.readRpc ?? [],
+        ...(o.allowDestructive === true ? { allowDestructive: true } : {}),
+        ...(dialogs === undefined ? {} : { dialogs }),
+        ...(o.allowWrites === true ? { allowWrites: true } : {}),
+        allowWrite: o.allowWrite ?? [],
+        ...(o.hangReplayWrites === true ? { hangReplayWrites: true } : {}),
+        ...(o.longPollMs === undefined ? {} : { longPollMs: Number(o.longPollMs) }),
+    };
+}
+/**
+ * Validates and resolves every shared goal-run flag — before any browser opens — into the goal
+ * run's options. Throws `GoalRunFlagError` (exit 64) on the first unusable one.
+ */
+export function resolveGoalRunFlags(o, url, deps = {}) {
+    const env = deps.env ?? process.env;
+    try {
+        const dialogs = dialogsFromFlags(o);
+        const successWhen = successWhenFromFlags(o);
+        if (o.saveStorageState !== undefined)
+            assertSessionFileOutsideProject(o.saveStorageState, "--save-storage-state");
+        const resolved = resolveSecretArgs(o.secret, env, "--secret");
+        if (resolved.literals > 0)
+            deps.warn?.(LITERAL_SECRET_WARNING);
+        const screenshots = parseScreenshotsArg(o.screenshots);
+        const conversation = conversationFromFlags(o);
+        validateDenyPatterns(o.deny);
+        validateDenyPatterns(o.paid, "--paid");
+        const emulation = emulationFromFlags(o);
+        const secretFields = secretFieldsFromFlags(o, env);
+        const typeFixtures = o.typeFixture.length === 0 ? [] : loadTypeFixtures(o.typeFixture);
+        let target;
+        try {
+            target = resolveTargetConfig(loadTargetsFile(deps.targetsConfigPath), new URL(url).origin, targetFlagsFromFlags(o, dialogs));
+        }
+        catch (err) {
+            // An unparseable URL is refused by the authorized-target guard.
+            if (!(err instanceof TypeError))
+                throw err;
+        }
+        return {
+            ...(successWhen === undefined ? {} : { successWhen }),
+            ...(o.allowVacuousChecks === true ? { allowVacuousChecks: true } : {}),
+            ...(o.actionDeltas === true ? { actionDeltas: true } : {}),
+            ...(resolved.secrets.length === 0 ? {} : { secrets: resolved.secrets }),
+            ...(secretFields.length === 0 ? {} : { secretFields }),
+            ...(secretFields.some((f) => f.kind === "cmd") ? { secretCommand: secretCommandRunner() } : {}),
+            ...(o.secretCmdAttempts === undefined ? {} : { secretCommandAttempts: o.secretCmdAttempts }),
+            ...(typeFixtures.length === 0 ? {} : { typeFixtures }),
+            ...(o.fixture === undefined ? {} : { fixture: o.fixture }),
+            ...(o.saveStorageState === undefined ? {} : { saveStorageState: o.saveStorageState }),
+            ...(screenshots === undefined ? {} : { screenshots }),
+            ...(emulation === undefined ? {} : { emulation }),
+            ...(target === undefined ? {} : { target }),
+            ...(o.hangReplays === undefined ? {} : { hangReplays: o.hangReplays }),
+            ...(Object.keys(conversation).length === 0 ? {} : { conversation }),
+        };
+    }
+    catch (err) {
+        throw asError(err);
+    }
+}
+//# sourceMappingURL=goal-run-flags.js.map

package/dist/goal-run-flags.js.map

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

package/dist/journey-api.d.ts

@@ -1,14 +1,15 @@
-import { type Journey } from "@jevitate/journey";
+import { type Journey, type JourneyLintFinding } from "@jevitate/journey";
 import { type RunPolicy } from "@jevitate/domain";
 import { type BrowserPort, type BrowserSession, type EmulationSpec } from "@jevitate/playwright";
 import { type BrowserRunOptions } from "./browser-run-options.js";
 import { RecordingInterpreter, type StepObserver } from "@jevitate/interpreter";
-import { type ReplayDeltaSummary } from "@jevitate/explore";
+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 FixtureRecord, type MissionFixtures } from "./mission-fixtures.js";
 import { type ResolvedJourneyEnvironment } from "./environments.js";
+import { type OutcomeCheckFailure } from "./journey-network-checks.js";
 /**
  * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
  * can tell "no such journey" apart from "params didn't match the journey's
@@ -23,6 +24,21 @@ export declare class UnknownJourneyError extends Error {
  */
 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>`.
+ */
+export declare class WeakJourneyError extends Error {
+    readonly findings: readonly JourneyLintFinding[];
+    constructor(message: string, findings?: readonly JourneyLintFinding[]);
+}
+/** #401: the assertion-strength lint's verdict for one Journey (`journey lint`). */
+export interface JourneyLintResult {
+    id: string;
+    findings: JourneyLintFinding[];
+    errors: number;
+    warnings: number;
+}
 export interface RunJourneyProgrammaticallyOptions {
     /** Directory a `FsJourneyStore` reads Journey JSON files from. */
     dir: string;
@@ -108,12 +124,55 @@ export interface RunJourneyProgrammaticallyOptions {
      */
     actionDeltas?: boolean;
 }
+/**
+ * #402: how a mutation-proof replay (`journey verify --mutate`) differs from `journey run` — a
+ * separate argument, never a surface option: no other caller passes it.
+ */
+export interface MutationReplayOptions {
+    /**
+     * #402 `journey verify --mutate`: replay a MUTATED copy of the Journey. Applied after params are
+     * validated against the stored Journey (a mutation may stop a step reading a param), and never to
+     * an anchored prefix. Indices must be kept: a mutation changes a step, never removes one.
+     */
+    mutateJourney?: (journey: Journey) => Journey;
+    /** #402: leave this flat step (0-based) out of the replay — `RecordingInterpreter`'s `skipStep`. */
+    skipStep?: (index: number) => boolean;
+    /**
+     * #402: ABORT the write requests (the #110 classifier, first-party only — `ReadOnlyGuard`) that
+     * start while this flat step (0-based) runs, until the network settles after it. Never answered,
+     * never sent; what was blocked comes back as `blockedWrites`.
+     */
+    blockWritesAtStep?: number;
+    /** #402: also return the outcome checks' structured failures (`outcomeFailures`). */
+    structuredFailures?: boolean;
+}
+/** #402: what a mutation-proof replay returns beyond `journey run`'s result. */
+export interface MutationReplayFields {
+    /** The step-request / end-state checks that failed (`structuredFailures`). */
+    outcomeFailures?: OutcomeCheckFailure[];
+    /** The writes aborted in `blockWritesAtStep`'s window. */
+    blockedWrites?: BlockedWrite[];
+}
+/**
+ * #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.
+ */
+export declare function redactSecretParams<T>(result: T, journey: Journey, params: Record<string, string>): T;
+/** Every string in `result` (deeply) with each secret, in each of its URL forms, masked. */
+export declare function redactSecretValues<T>(result: T, secrets: readonly string[]): T;
 /**
  * #293: the params a Journey PREFIX runs with — a `--param` the whole Journey does not take is
  * refused (`ParamValidationError`), one only a later step uses is dropped; the prefix's own required
  * params are then checked by `validateParams` as usual.
  */
 export declare function prefixParams(full: Journey, prefix: Journey, params: Record<string, string>): Record<string, string>;
+/**
+ * #401: the assertion-strength lint (#401) for one Journey by id — an unknown id is refused,
+ * exactly as `journey run`/`promote` refuse one (`UnknownJourneyError`). Pure read; no browser.
+ */
+export declare function lintJourneyById(dir: string, id: string, opts?: {
+    readRequests?: readonly string[];
+}): Promise<JourneyLintResult>;
 /**
  * Promotes a local Journey (#124, mirrors `promoteMissionTarget` in
  * `mission-api.ts`) so it becomes discoverable via `journey find`/MCP
@@ -121,8 +180,14 @@ export declare function prefixParams(full: Journey, prefix: Journey, params: Rec
  * same as `mission target promote`. An unknown id is refused with
  * `UnknownJourneyError` (never silently created). Returns the persisted,
  * now-promoted Journey.
+ *
+ * #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.
  */
-export declare function promoteJourney(dir: string, id: string): Promise<Journey>;
+export declare function promoteJourney(dir: string, id: string, opts?: {
+    acceptWeak?: string;
+}): 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
@@ -132,8 +197,10 @@ export declare function promoteJourney(dir: string, id: string): Promise<Journey
  * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
  * launched, then builds the real Actor + `JourneyRunner` and runs.
  */
-export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions): Promise<JourneyRunResult & {
+export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions, mutation?: MutationReplayOptions): Promise<JourneyRunResult & {
     fixtures?: FixtureRecord;
     videoPaths?: string[];
     actionDeltas?: ReplayDeltaSummary;
-} & Partial<ScreenshotsResult>>;
+} & Partial<ScreenshotsResult> & MutationReplayFields>;
+/** `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;

package/dist/journey-api.js

@@ -1,4 +1,4 @@
-import { FsJourneyStore, JourneyRegistry, ParamValidationError, deriveParamSchema, describeStep, flatJourneySteps, journeyPrefix, secretParamValues, validateParams } from "@jevitate/journey";
+import { FsJourneyStore, JourneyRegistry, ParamValidationError, deriveParamSchema, describeStep, flatJourneySteps, journeyPrefix, lintJourney, secretParamValues, validateParams } from "@jevitate/journey";
 import { redactText } from "@jevitate/ai-core";
 import { safeRunPolicy, clock } from "@jevitate/domain";
 import { join } from "node:path";
@@ -8,7 +8,8 @@ import { artifactStamp } from "./mission-journal.js";
 import { logsDirFor } from "./project-dir.js";
 import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
 import { RecordingInterpreter } from "@jevitate/interpreter";
-import { ReplayDeltas, replayDeltaSummary } from "@jevitate/explore";
+import { ReadOnlyGuard, ReplayDeltas, monitorFor, replayDeltaSummary } from "@jevitate/explore";
+import { writeClassifier } from "@jevitate/recording";
 import { BrowseTheWebToken } from "@jevitate/screenplay";
 import { SecretPixelMask, maskingPort } from "./demo-capture.js";
 import { RunScreenshots, composeObservers, screenshotObserver, screenshotsDirFor } from "./run-screenshots.js";
@@ -16,7 +17,7 @@ import { JourneyRunner } from "@jevitate/runtime";
 import { gateJourney } from "./site-gate-cli.js";
 import { substituteSetupRefs } from "./mission-fixtures.js";
 import { applyJourneyEnvironment } from "./environments.js";
-import { withNetworkChecks } from "./journey-network-checks.js";
+import { JourneyOutcomeChecks } from "./journey-network-checks.js";
 /**
  * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
  * can tell "no such journey" apart from "params didn't match the journey's
@@ -31,12 +32,26 @@ export class UnknownJourneyError extends Error {
  */
 export 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>`.
+ */
+export class WeakJourneyError extends Error {
+    findings;
+    constructor(message, findings = []) {
+        super(message);
+        this.findings = findings;
+    }
+}
 /**
  * #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.
  */
-function redactSecretParams(result, journey, params) {
-    const secrets = secretParamValues(journey, params);
+export function redactSecretParams(result, journey, params) {
+    return redactSecretValues(result, secretParamValues(journey, params));
+}
+/** Every string in `result` (deeply) with each secret, in each of its URL forms, masked. */
+export function redactSecretValues(result, secrets) {
     if (secrets.length === 0)
         return result;
     const scrub = (v) => typeof v === "string"
@@ -61,6 +76,24 @@ export function prefixParams(full, prefix, params) {
     const needed = deriveParamSchema(prefix.recording).required;
     return Object.fromEntries(Object.entries(params).filter(([k]) => needed.includes(k)));
 }
+/**
+ * #401: the assertion-strength lint (#401) for one Journey by id — an unknown id is refused,
+ * exactly as `journey run`/`promote` refuse one (`UnknownJourneyError`). Pure read; no browser.
+ */
+export async function lintJourneyById(dir, id, opts = {}) {
+    const registry = new JourneyRegistry(new FsJourneyStore(dir));
+    const journey = await registry.get(id);
+    if (!journey) {
+        throw new UnknownJourneyError(`unknown journey '${id}'`);
+    }
+    const findings = lintJourney(journey, opts.readRequests === undefined ? {} : { readRequests: opts.readRequests });
+    return {
+        id,
+        findings,
+        errors: findings.filter((f) => f.level === "error").length,
+        warnings: findings.filter((f) => f.level === "warning").length,
+    };
+}
 /**
  * Promotes a local Journey (#124, mirrors `promoteMissionTarget` in
  * `mission-api.ts`) so it becomes discoverable via `journey find`/MCP
@@ -68,14 +101,32 @@ export function prefixParams(full, prefix, params) {
  * same as `mission target promote`. An unknown id is refused with
  * `UnknownJourneyError` (never silently created). Returns the persisted,
  * now-promoted Journey.
+ *
+ * #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.
  */
-export async function promoteJourney(dir, id) {
+export async function promoteJourney(dir, id, opts = {}) {
     const store = new FsJourneyStore(dir);
     const registry = new JourneyRegistry(store);
     const existing = await registry.get(id);
     if (!existing) {
         throw new UnknownJourneyError(`unknown journey '${id}'`);
     }
+    const errors = lintJourney(existing).filter((f) => f.level === "error");
+    const reason = opts.acceptWeak?.trim() ?? "";
+    if (errors.length > 0 && reason === "") {
+        throw new WeakJourneyError([
+            `journey '${id}' has ${errors.length} assertion-strength error(s):`,
+            ...errors.map((f) => f.message),
+            "strengthen the Journey or pass --accept-weak <reason>",
+        ].join("\n"), errors);
+    }
+    if (errors.length > 0) {
+        const acceptedWeak = { reason, rules: [...new Set(errors.map((f) => f.rule))] };
+        await store.put({ ...existing, metadata: { ...existing.metadata, promoted: true, acceptedWeak } });
+        return (await registry.get(id)) ?? { ...existing, metadata: { ...existing.metadata, promoted: true, acceptedWeak } };
+    }
     await registry.promote(id);
     const promoted = await registry.get(id);
     return promoted ?? { ...existing, metadata: { ...existing.metadata, promoted: true } };
@@ -89,7 +140,7 @@ export async function promoteJourney(dir, id) {
  * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
  * launched, then builds the real Actor + `JourneyRunner` and runs.
  */
-export async function runJourneyProgrammatically(opts) {
+export async function runJourneyProgrammatically(opts, mutation = {}) {
     const store = new FsJourneyStore(opts.dir);
     const registry = new JourneyRegistry(store);
     const stored = await registry.get(opts.id);
@@ -113,6 +164,8 @@ export async function runJourneyProgrammatically(opts) {
     // the cost (or risk) of opening a browser.
     const inputParams = journey === full ? opts.params : prefixParams(full, journey, opts.params);
     validateParams(deriveParamSchema(journey.recording), inputParams);
+    // #402: the mutated copy replays (and is judged); the stored Journey still names, redacts and gates.
+    const replayed = mutation.mutateJourney === undefined || journey !== full ? journey : mutation.mutateJourney(journey);
     const policy = opts.policy ?? safeRunPolicy();
     // The site policy (`jevitate site policy set <origin>`): pacing, throttles, budgets, quiet hours —
     // decided before any fixture or browser; a refusal says why and when to retry.
@@ -169,33 +222,91 @@ export async function runJourneyProgrammatically(opts) {
         try {
             const actor = CastActor.named("cli-runner").whoCan(new BrowseTheWeb(session, allowedOrigins), ...gate.abilities);
             const replayDeltas = opts.actionDeltas === true ? new ReplayDeltas({ secrets, recorded: flat.map((f) => f.recorded) }) : undefined;
-            const observer = composeObservers(replayDeltas?.observer(), opts.observer, shots === undefined ? undefined : screenshotObserver(shots, (a) => a.ability(BrowseTheWebToken).session.page, whatOf));
-            const interpreter = opts.interpreter ?? (opts.observer === undefined && shots === undefined && replayDeltas === undefined ? new RecordingInterpreter() : new RecordingInterpreter({ observer }));
+            // #322/#400: a full replay (never an anchored prefix) must also satisfy the Journey's end state
+            // and each step's request expectations.
+            const outcomeChecks = new JourneyOutcomeChecks(session.page, journey === full ? replayed : undefined, { secrets });
+            const blocker = mutation.blockWritesAtStep === undefined ? undefined : await stepWriteBlocker(session.page, mutation.blockWritesAtStep, allowedOrigins);
+            const observer = composeObservers(outcomeChecks.observer(), blocker?.observer, replayDeltas?.observer(), opts.observer, shots === undefined ? undefined : screenshotObserver(shots, (a) => a.ability(BrowseTheWebToken).session.page, whatOf));
+            const skipStep = mutation.skipStep;
+            const interpreter = opts.interpreter ??
+                (opts.observer === undefined && shots === undefined && replayDeltas === undefined && outcomeChecks.observer() === undefined && blocker === undefined && skipStep === undefined
+                    ? new RecordingInterpreter()
+                    : new RecordingInterpreter({ observer, ...(skipStep === undefined ? {} : { skipStep: (i) => skipStep(i) }) }));
             const runner = new JourneyRunner(actor, interpreter, undefined, undefined, opts.selfHealer);
             let result;
             try {
-                // #322: a full replay (never an anchored prefix) must also satisfy the Journey's network checks.
-                const networkChecks = journey === full ? journey.metadata.networkChecks : undefined;
-                result = redactSecretParams(await withNetworkChecks(session.page, networkChecks, () => runner.run({ journey, params, policy })), journey, params);
+                result = redactSecretParams(await outcomeChecks.run(actor, () => runner.run({ journey: replayed, params, policy })), journey, params);
             }
             finally {
                 await gate.done();
+                await blocker?.guard.disarm();
             }
+            const mutationFields = {
+                ...(mutation.structuredFailures === true ? { outcomeFailures: redactSecretParams([...outcomeChecks.lastFailures], journey, params) } : {}),
+                ...(blocker === undefined ? {} : { blockedWrites: blocker.guard.drain() }),
+            };
             const shotFields = shots === undefined ? {} : await shots.finish();
             const deltaFields = replayDeltas === undefined ? {} : { actionDeltas: redactSecretParams(replayDeltaSummary(replayDeltas), journey, params) };
             // #245: the context closed (its video finalized) before the result naming it is returned.
             const videos = await finalizeVideos(videoDir, closeSession);
             if (fx === undefined)
-                return { ...result, ...videos, ...shotFields, ...deltaFields };
+                return { ...result, ...videos, ...shotFields, ...deltaFields, ...mutationFields };
             await fx.restore();
-            return { ...result, ...videos, ...shotFields, ...deltaFields, fixtures: fx.record() };
+            // #399: a fixture output passed in as a secret param (`--param t='${setup.t}'`) is redacted here too.
+            return { ...result, ...videos, ...shotFields, ...deltaFields, ...mutationFields, fixtures: redactSecretParams(fx.record(), journey, params) };
         }
         finally {
             await closeSession();
         }
     }
+    catch (err) {
+        // #399: an error escaping the run (a crash, a closed page) may echo a navigated URL that
+        // carried a secret parameter — its message and stack are redacted, its class kept.
+        throw redactErrorSecrets(err, secretParamValues(journey, { ...inputParams, ...params }));
+    }
     finally {
         await fx?.restore();
     }
 }
+/** How long one blocked step's window stays open for the writes its action triggers (network settle). */
+const BLOCK_WINDOW_SETTLE_MS = 5_000;
+/**
+ * #402 block-write: a `ReadOnlyGuard` armed on the page whose action window is ONLY the given step —
+ * opened as it begins, closed once the network settled after it. Every held write is aborted (a
+ * write navigation too: never answered with a status that could read as a success).
+ */
+async function stepWriteBlocker(page, index, allowedOrigins) {
+    const guard = new ReadOnlyGuard(writeClassifier({}), { allowlist: [...allowedOrigins], navigationWrites: "abort" });
+    await guard.arm(page);
+    const monitor = monitorFor(page);
+    await monitor.instrument();
+    return {
+        guard,
+        observer: {
+            beforeStep: async ({ index: i }) => {
+                if (i === index)
+                    guard.beginAction();
+            },
+            afterStep: async ({ index: i }) => {
+                if (i !== index)
+                    return;
+                try {
+                    await monitor.waitSettled({ ceilingMs: BLOCK_WINDOW_SETTLE_MS });
+                }
+                finally {
+                    guard.settled();
+                }
+            },
+        },
+    };
+}
+/** `err` with every secret (and its URL-encoded forms) masked in its message and stack — same object, same class. */
+export function redactErrorSecrets(err, secrets) {
+    if (!(err instanceof Error) || secrets.length === 0)
+        return err;
+    err.message = redactText(err.message, secrets);
+    if (err.stack !== undefined)
+        err.stack = redactText(err.stack, secrets);
+    return err;
+}
 //# sourceMappingURL=journey-api.js.map