@jevitate/cli 0.12.0 → 0.14.0

package/dist/ux-usability/result.js.map

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

package/dist/ux-usability/setup.d.ts

@@ -0,0 +1,76 @@
+import { type SecretCommandRunner, type TranscriptEntry } from "@jevitate/explore";
+import { type ScreenRef, type UxEvidence, type UxFinding } from "@jevitate/ux";
+import { MissionJournal } from "../mission-journal.js";
+import { Http5xxOracle } from "@jevitate/explore";
+import { UsabilityCapture } from "../usability-capture.js";
+import type { RunUsabilityMissionOptions } from "../ux-usability.js";
+/** Usability reads only a spec's `budget` (#150) — never its `invariants`/`capture` (#86/#147, not supported here). */
+export declare class UsabilityInvariantsUnsupportedError extends Error {
+    readonly code: "E_USABILITY_INVARIANTS";
+    constructor();
+}
+/**
+ * Phase 1 — set-up: every bad-input refusal BEFORE a browser opens, the run's artifact paths, the
+ * armed launch (kill switch, host sampler, browser), the capture/journal/server-log listener chain
+ * and the once-only session close. Returns the run's shared state, mutated in place by later phases.
+ */
+export declare function setUpUsabilityMission(opts: RunUsabilityMissionOptions): Promise<{
+    opts: RunUsabilityMissionOptions;
+    origin: string;
+    minConfidence: number;
+    quality: import("@jevitate/ux").QualityPolicy;
+    maxFindingsPerRoute: number;
+    fixture: string | undefined;
+    product: import("../ux-product.js").LoadedProductFacts;
+    runCapture: import("../run-screenshots.js").RunCapture;
+    portFactory: () => import("@jevitate/playwright").BrowserPort;
+    port: import("@jevitate/playwright").BrowserPort;
+    collected: UxEvidence[];
+    history: ScreenRef[];
+    overflowFindings: UxFinding[];
+    seenOverflow: Set<string>;
+    extract: (session: {
+        page: {
+            evaluate: (fn: () => string) => Promise<string>;
+        };
+    }) => Promise<string>;
+    outDir: string;
+    stamp: string;
+    reportPath: string;
+    journal: MissionJournal;
+    screenshotDir: string;
+    videoDir: string | undefined;
+    launch: {
+        storageState?: string | undefined;
+        viewport?: import("@jevitate/playwright").ViewportSize;
+        device?: string;
+        geolocation?: import("@jevitate/playwright").GeolocationSpec;
+        baseUrl: string;
+        blockOffAllowlistNavigation?: boolean | undefined;
+        allowedOrigins: string[];
+        executablePath?: string;
+        channel?: string;
+        args?: readonly string[];
+        slowMo?: number;
+        extensions?: readonly import("@jevitate/playwright").UnpackedExtension[];
+        resources?: import("@jevitate/playwright").ResourceLimits;
+        recordVideo?: {
+            dir: string;
+        } | undefined;
+        headless: boolean;
+    };
+    secrets: string[];
+    runUsage: import("@jevitate/ai-core").UsageLedger | undefined;
+    disarmKillSwitch: () => void;
+    health: import("@jevitate/explore").HostHealthSampler;
+    session: import("@jevitate/playwright").BrowserSession;
+    snapshotter: import("../storage-state-snapshot.js").StorageStateSnapshotter;
+    uxSecretCommand: SecretCommandRunner | undefined;
+    http5xx: Http5xxOracle;
+    capture: UsabilityCapture;
+    journalListener: (entry: TranscriptEntry, all: readonly TranscriptEntry[]) => void;
+    serverLog: import("../log-correlation.js").ServerLogRuntime | undefined;
+    closeSession: () => Promise<void>;
+}>;
+/** The run's shared state: set up once, handed to every later phase (the same objects, never copies). */
+export type UsabilitySetup = Awaited<ReturnType<typeof setUpUsabilityMission>>;

package/dist/ux-usability/setup.js

@@ -0,0 +1,204 @@
+// ux-usability/setup.ts — phase 1 of `runUsabilityMission` (#500): input refusals, launch, listener chain.
+import { resolveProjectMissionFixture } from "../journey-api.js";
+import { logsDirFor } from "../project-dir.js";
+import { join, resolve as resolvePath } from "node:path";
+import { PlaywrightBrowserPort } from "@jevitate/playwright";
+import { closeOnce, runVideoDir, sessionLaunchOptions } from "../browser-run-options.js";
+import { runCaptureFor } from "../run-screenshots.js";
+import { assertAuthorizedExploreTarget, secretFieldSecrets } from "@jevitate/explore";
+import { resolveMinConfidence, resolveMaxFindingsPerRoute, resolveQualityPolicy } from "@jevitate/ux";
+import { loadProductFacts } from "../ux-product.js";
+import { loadUxMaxFindingsPerPage, loadUxMinConfidence, loadUxMinConfidenceByAppClass, loadUxShow } from "../ux-config.js";
+import { clock } from "@jevitate/domain";
+import { MissionJournal, artifactStamp, closeQuietly } from "../mission-journal.js";
+import { launchArmed } from "../launch-armed.js";
+import { Http5xxOracle } from "@jevitate/explore";
+import { openServerLogRuntime } from "../log-correlation.js";
+import { serverLogRuntimeOptions } from "../explore-shared.js";
+import { assertSaveStorageStateOutsideProject, currentUrlSafe, persistStorageState } from "../explore-api.js";
+import { transcriptPathFor } from "../transcript-file.js";
+import { UsabilityCapture } from "../usability-capture.js";
+/** Usability reads only a spec's `budget` (#150) — never its `invariants`/`capture` (#86/#147, not supported here). */
+export class UsabilityInvariantsUnsupportedError extends Error {
+    code = "E_USABILITY_INVARIANTS";
+    constructor() {
+        super("usability does not check app-declared invariants or captures — only a `budget` is read; " +
+            "give a spec with an empty invariants array (and no capture) to use --invariants with usability");
+        this.name = "UsabilityInvariantsUnsupportedError";
+    }
+}
+/**
+ * Phase 1 — set-up: every bad-input refusal BEFORE a browser opens, the run's artifact paths, the
+ * armed launch (kill switch, host sampler, browser), the capture/journal/server-log listener chain
+ * and the once-only session close. Returns the run's shared state, mutated in place by later phases.
+ */
+export async function setUpUsabilityMission(opts) {
+    const origin = assertAuthorizedExploreTarget(opts.url, opts.allowlist);
+    assertSaveStorageStateOutsideProject(opts.saveStorageState);
+    // #150 — usability reads only a spec's `budget`: it does not check invariants or captures (#86/
+    // #147) today. Refused BEFORE a browser opens, same as every other bad-input refusal here.
+    if (opts.invariants !== undefined && (opts.invariants.invariants.length > 0 || opts.invariants.capture !== undefined)) {
+        throw new UsabilityInvariantsUnsupportedError();
+    }
+    // Validate the cutoff before a browser opens — a bad value fails fast, never mid-run.
+    const minConfidence = resolveMinConfidence(opts.minConfidence, opts.env ?? process.env, loadUxMinConfidence(opts.configPath), loadUxMinConfidenceByAppClass(opts.configPath, opts.appContext.appClass));
+    const quality = resolveQualityPolicy(opts.show, opts.env ?? process.env, loadUxShow(opts.configPath), opts.appContext.appClass);
+    const maxFindingsPerRoute = resolveMaxFindingsPerRoute(opts.maxFindingsPerRoute, opts.env ?? process.env, loadUxMaxFindingsPerPage(opts.configPath));
+    const fixture = opts.fixture === undefined ? undefined : await resolveProjectMissionFixture(opts.fixture);
+    // #198: the product facts are validated before a browser opens (a bad file is a usage error).
+    const product = await loadProductFacts(opts.product);
+    // #250/#251: a recorded or screenshotted run's sessions carry the live pixel mask from their first
+    // paint; `--screenshots` captures after each step (the Recording path names their folder).
+    const runCapture = runCaptureFor({
+        recordsVideo: opts.browser?.recordVideo !== undefined,
+        screenshots: opts.screenshots,
+        secrets: [...(opts.secrets ?? []), ...secretFieldSecrets(opts.secretFields)],
+        artifactPath: () => journal.recordingPath,
+        title: `usability: ${opts.job}`,
+    });
+    const portFactory = runCapture.wrap(opts.browserPortFactory ?? (() => new PlaywrightBrowserPort()));
+    const port = portFactory();
+    const collected = [];
+    const history = [];
+    // #149: one signal finding per distinct fingerprint (route + element) — a wide table seen across
+    // many observed screens is still ONE finding, never a finding per occurrence.
+    const overflowFindings = [];
+    const seenOverflow = new Set();
+    const extract = opts.extractText ??
+        (async (s) => s.page.evaluate(() => (typeof document !== "undefined" && document.body ? document.body.innerText : "")));
+    const outDir = opts.outDir ?? logsDirFor();
+    const iso = (opts.nowIso ?? (() => clock.nowIso()))();
+    const stamp = artifactStamp(iso);
+    const reportPath = join(outDir, `usability-${stamp}.json`);
+    // #98 — the same artifact shape as goal/adversarial missions, next to the report: the decision
+    // transcript (each step's redacted typed value and screenshot), the Recording and the per-step
+    // screenshots. Crash-safe: the transcript and partial Recording are flushed after every step.
+    const journal = new MissionJournal(join(outDir, `usability-${stamp}.recording.json`), transcriptPathFor(reportPath));
+    const screenshotDir = join(outDir, `usability-${stamp}.screens`);
+    // #245: shown/recorded like every other strategy's session (videos in `usability-<stamp>.videos/`).
+    const videoDir = runVideoDir(opts.browser, reportPath);
+    const launch = {
+        ...sessionLaunchOptions(opts.browser, videoDir),
+        allowedOrigins: [...opts.allowlist],
+        ...(opts.blockOffAllowlistNavigation === true ? { blockOffAllowlistNavigation: true } : {}),
+        baseUrl: origin,
+        ...opts.emulation,
+        ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
+    };
+    // A bound secret (or TOTP seed) is a run secret too: masked on screen, redacted everywhere.
+    const secrets = [...(opts.secrets ?? []), ...secretFieldSecrets(opts.secretFields)];
+    // #163: this run's own share of a (possibly shared) tracker: its usage and sidecar.
+    const runUsage = opts.usage?.scope();
+    // The screenshot capture needs the open page; until then a killed run has taken none.
+    let armedCapture;
+    // Crash-safe on SIGTERM/SIGINT too (#94): a partial `inconclusive` result is written from
+    // whatever the journal has already flushed, and the process exits with the conventional code.
+    // #120: the transcript lives next to the REPORT (`usability-<stamp>.transcript.json`), not the
+    // Recording — so the killed run's result names the real file, and reports the live step list,
+    // the tokens spent so far and the screens already observed.
+    // #226: the kill switch is armed BEFORE the host sampler and the browser launch (see launch-armed.ts).
+    const { disarmKillSwitch, health, session, snapshotter } = await launchArmed({
+        hostHealth: opts.hostHealth,
+        saveStorageState: opts.saveStorageState !== undefined,
+        open: () => port.open(launch),
+        mission: (hooks) => ({
+            // #220: the killed run's partial result carries the unified schema's common fields too.
+            strategy: "usability",
+            target: { seedUrl: opts.url, allowlist: [...opts.allowlist], ...(opts.storageState !== undefined ? { storageStatePath: resolvePath(opts.storageState) } : {}) },
+            recordingPath: journal.recordingPath,
+            hostHealth: hooks.hostHealth,
+            ...(videoDir === undefined ? {} : { videoDir }),
+            transcriptPath: journal.transcriptPath,
+            transcript: () => journal.transcript,
+            ...(runUsage === undefined ? {} : { usage: runUsage }),
+            partialReport: () => ({ screensObserved: collected.length, screenshotDir, screenshots: armedCapture === undefined ? [] : armedCapture.screenshots() }),
+            ...(opts.saveStorageState === undefined ? {} : { storageState: { path: opts.saveStorageState, snapshot: hooks.snapshot } }),
+        }),
+    });
+    // #324: the engine runs a cmd: binding's command at type time. A value read mid-run joins this
+    // run's secrets at once (screenshots' scan, result, evidence, report) and — #360 — the run's pixel
+    // mask, before the value is typed. (It was once handed to UsabilityCapture, which has no such
+    // option, so a usability run could not type a cmd: field at all.)
+    const uxSecretCommand = opts.secretCommand === undefined
+        ? undefined
+        : async (command) => {
+            const out = await opts.secretCommand(command);
+            const value = out.trim();
+            if (value !== "" && !secrets.includes(value))
+                secrets.push(value);
+            if (value !== "")
+                await runCapture.mask.addSecret(value);
+            return out;
+        };
+    // #208: the shared HTTP 5xx hard signal, listening from before the first navigation.
+    const http5xx = new Http5xxOracle(session.page, { allowlist: opts.allowlist });
+    const capture = new UsabilityCapture({
+        page: session.page,
+        screenshotDir,
+        secrets,
+        ...(opts.secretFields === undefined ? {} : { secretFields: opts.secretFields }),
+    });
+    armedCapture = capture;
+    // The usability capture (screenshots) and the journal (crash-safe flush) are the EXISTING listener
+    // chain; a server-log runtime (#142) is inserted in FRONT of it (never replacing it) so every step
+    // still gets its screenshot/flush exactly as before, whether or not --log-source was given. #159:
+    // every settled step also refreshes the in-memory storageState snapshot (a cheap no-op when
+    // `--save-storage-state` was not given).
+    const journalListener = (entry, all) => {
+        runCapture.noteEntry(session.page, entry);
+        health.noteStep(entry);
+        http5xx.noteStep(entry);
+        capture.noteEntry(entry, all);
+        journal.onTranscriptEntry(entry, capture.withScreenshots(all));
+        snapshotter.noteSettledStep(currentUrlSafe(session));
+    };
+    const serverLog = openServerLogRuntime({
+        ...serverLogRuntimeOptions(opts.serverLog),
+        secrets,
+        onTranscriptEntry: journalListener,
+    });
+    // #204: every request's correlation ids, from before the first navigation.
+    serverLog?.observe(session.page);
+    // #159/#245: persisted and closed once — early (before the result is written) when recording video.
+    const closeSession = closeOnce(async () => {
+        await persistStorageState(session, opts.saveStorageState, snapshotter);
+        await closeQuietly(session);
+    });
+    return {
+        opts,
+        origin,
+        minConfidence,
+        quality,
+        maxFindingsPerRoute,
+        fixture,
+        product,
+        runCapture,
+        portFactory,
+        port,
+        collected,
+        history,
+        overflowFindings,
+        seenOverflow,
+        extract,
+        outDir,
+        stamp,
+        reportPath,
+        journal,
+        screenshotDir,
+        videoDir,
+        launch,
+        secrets,
+        runUsage,
+        disarmKillSwitch,
+        health,
+        session,
+        snapshotter,
+        uxSecretCommand,
+        http5xx,
+        capture,
+        journalListener,
+        serverLog,
+        closeSession,
+    };
+}
+//# sourceMappingURL=setup.js.map

package/dist/ux-usability/setup.js.map

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

package/dist/ux-usability/teardown.d.ts

@@ -0,0 +1,3 @@
+import type { UsabilitySetup } from "./setup.js";
+/** Phase 7 — teardown, on every exit path (the orchestrator's `finally`): listeners, kill switch, host sampler, log sources, session. */
+export declare function tearDownUsabilityMission(ctx: UsabilitySetup): Promise<void>;

package/dist/ux-usability/teardown.js

@@ -0,0 +1,13 @@
+/** Phase 7 — teardown, on every exit path (the orchestrator's `finally`): listeners, kill switch, host sampler, log sources, session. */
+export async function tearDownUsabilityMission(ctx) {
+    const { capture, disarmKillSwitch, health, serverLog, closeSession } = ctx;
+    capture.detach();
+    disarmKillSwitch();
+    health.stop();
+    // Safety net: if the mission threw before `serverLog.finish()` ran, close sources immediately
+    // (no drain wait) rather than leaving them open until process exit.
+    await serverLog?.abort();
+    // #159: reaches this even when the mission above threw — the context is still open here.
+    await closeSession();
+}
+//# sourceMappingURL=teardown.js.map

package/dist/ux-usability/teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.js","sourceRoot":"","sources":["../../src/ux-usability/teardown.ts"],"names":[],"mappings":"AAGA,yIAAyI;AACzI,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,GAAmB;IAChE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,GAAG,CAAC;IAC3E,OAAO,CAAC,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,CAAC;IACnB,MAAM,CAAC,IAAI,EAAE,CAAC;IACd,8FAA8F;IAC9F,oEAAoE;IACpE,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC;IACzB,yFAAyF;IACzF,MAAM,YAAY,EAAE,CAAC;AACvB,CAAC"}

package/dist/ux-usability.d.ts

@@ -1,21 +1,23 @@
 import type { JudgmentPort, GenerationPort, UsageTracker, UsageCounts } from "@jevitate/ai-core";
-import { type BrowserPort, type EmulationSpec } from "@jevitate/playwright";
-import { type BrowserRunOptions } from "./browser-run-options.js";
-import { type ScreenshotsSpec } from "./run-screenshots.js";
+import type { BrowserPort, EmulationSpec } from "@jevitate/playwright";
+import type { BrowserRunOptions } from "./browser-run-options.js";
+import type { ScreenshotsSpec } from "./run-screenshots.js";
 import type { InvariantSpec } from "@jevitate/recording";
-import { type SuccessCheck, type SuccessCheckResult, type SuccessWhen, type Bounds, type TimingSummary, type RunAnswer, type RunOutcome, type SecretField, type SecretCommandRunner, type HangFinding, type SideEffect, type SafetyOverride, type BudgetTrajectory, type CrashReport } from "@jevitate/explore";
-import { type AppContext, type SignalOptions, type UxReport } from "@jevitate/ux";
-import { type ConversationOptions } from "./conversation-options.js";
-import { type GoalOutcome, type MissionFailure, type MissionOutcome } from "@jevitate/domain";
+import type { SuccessCheck, SuccessCheckResult, SuccessWhen, Bounds, TimingSummary, RunAnswer, RunOutcome, SecretField, SecretCommandRunner, HangFinding, SideEffect, SafetyOverride, BudgetTrajectory, CrashReport } from "@jevitate/explore";
+import type { AppContext, SignalOptions, UxReport } from "@jevitate/ux";
+import type { ConversationOptions } from "./conversation-options.js";
+import type { GoalOutcome, MissionFailure, MissionOutcome } from "@jevitate/domain";
 import { MISSION_RESULT_SCHEMA_VERSION, type AdvisoryServerLogDefect } from "./result-schema.js";
-import { type JourneyPrefix } from "./journey-prefix.js";
+import type { JourneyPrefix } from "./journey-prefix.js";
 import type { JourneyBranchPoint } from "@jevitate/journey";
-import { type ActionDeltaStats, type HostHealthSampler, type Http5xxDefect, type RunDepth } from "@jevitate/explore";
+import type { ActionDeltaStats, HostHealthSampler, Http5xxDefect, RunDepth } from "@jevitate/explore";
 import type { DefectOutcome, EnvironmentDegraded, HostHealthSummary } from "@jevitate/domain";
-import { type EngineInfo } from "./engine.js";
-import { type ServerLogsSummary } from "./log-correlation.js";
-import { type MissionTarget, type ServerLogOptions } from "./explore-api.js";
+import type { EngineInfo } from "./engine.js";
+import type { ServerLogsSummary } from "./log-correlation.js";
+import type { MissionTarget, ServerLogOptions } from "./explore-api.js";
 import type { TargetConfig } from "./target-config.js";
+import { UsabilityInvariantsUnsupportedError } from "./ux-usability/setup.js";
+export { UsabilityInvariantsUnsupportedError };
 export interface RunUsabilityMissionOptions {
     /** Test seam (#203): the run's host-health sampler (a deterministic fake host). Default: this host's. */
     readonly hostHealth?: HostHealthSampler;
@@ -156,11 +158,12 @@ export interface RunUsabilityMissionOptions {
      * result (`actionDeltas`), told to the model and used by the no-progress check. Off: no capture.
      */
     readonly actionDeltas?: boolean;
-}
-/** Usability reads only a spec's `budget` (#150) — never its `invariants`/`capture` (#86/#147, not supported here). */
-export declare class UsabilityInvariantsUnsupportedError extends Error {
-    readonly code: "E_USABILITY_INVARIANTS";
-    constructor();
+    /**
+     * #521 `--block-off-allowlist-navigation` (opt-in, off by default): arm the navigation guard on this
+     * run's mission session (and its fresh/hang-replay sessions) — an off-allowlist page navigation is
+     * stopped in place and the mission treats it as a departure. Never on login, Journey or demo sessions.
+     */
+    readonly blockOffAllowlistNavigation?: boolean;
 }
 export interface RunUsabilityMissionResult {
     /** The host's health over the run (#203): peaks, the slowest render, starved steps. */