@jevitate/cli 0.1.0 → 0.3.0

package/dist/demo-aspect-cli.js

@@ -0,0 +1,243 @@
+import { existsSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { MissingCredentialError, SecretLeakError } from "@jevitate/ai-core";
+import { UnauthorizedExploreTargetError } from "@jevitate/explore";
+import { formatAnnotationChanges } from "@jevitate/journey";
+import { SiteGateRefusedError } from "@jevitate/runtime";
+import { ok, fail } from "./envelope.js";
+import { intArg, positiveIntArg } from "./cli-args.js";
+import { artifactStamp } from "./mission-journal.js";
+import { logsDirFor } from "./project-dir.js";
+import { withSiteGate } from "./site-gate-cli.js";
+import { buildMissionFixtures, withFixtureFlags } from "./fixture-cli.js";
+import { FixtureSetupError, FixtureSpecError, UnboundSetupRefError } from "./mission-fixtures.js";
+import { withEngine } from "./engine.js";
+import { EXIT_CODES } from "./exit-codes.js";
+import { parseAssertionSpec } from "./explore-api.js";
+import { isEnvironmentError, resolveJourneyEnvironment } from "./environments.js";
+import { loadTargetsFile, TargetConfigError } from "./target-config.js";
+import { UnknownJourneyError, JourneyRequiresAuthError } from "./journey-api.js";
+import { AnnotationDraftNotFoundError, InvalidAnnotationDraftError, StaleAnnotationDraftError } from "./journey-annotate-api.js";
+import { DEMO_DEFAULT_PACE_MS, DEMO_MAX_PACE_MS, DemoArgsError, DemoOutputError } from "./journey-demo-api.js";
+import { DemoAspectArgsError, DemoDraftNotFoundError, DemoExistsError, DemoProductionEnvironmentError, InvalidDemoDraftError, approveDemo, assertDemoEnvironment, demoAspect, demoJourneyId, loadDemoForApproval, } from "./demo-aspect-api.js";
+import { resolveDbPath, resolveJourneysDir, withBrowserLaunchFlags, browserRunFromFlags, withDemoFlags, withEmulationFlags, emulationFromFlags, emitJson, emitUsageLine, environmentSeams, GatewaySelectionError, buildExploreGateways, } from "./cli-shared.js";
+import { clock } from "@jevitate/domain";
+/**
+ * #249 — `jevitate demo "<aspect>" --env <name> --success <spec>`: explore → clean path → Journey →
+ * annotate → a DRAFT narrated demo; `jevitate demo approve <id>`: the one human approval (promotes the
+ * Journey, applies the annotations, renders the final demo). See `demo-aspect-api.ts`.
+ */
+/** A thrown refusal → its envelope (exit 64 for usage/input codes, else 2), or rethrow-worthy null. */
+function refusalOf(err) {
+    if (err instanceof DemoAspectArgsError ||
+        err instanceof DemoProductionEnvironmentError ||
+        err instanceof DemoExistsError ||
+        err instanceof DemoDraftNotFoundError ||
+        err instanceof InvalidDemoDraftError ||
+        err instanceof DemoArgsError ||
+        err instanceof DemoOutputError ||
+        err instanceof SiteGateRefusedError ||
+        err instanceof AnnotationDraftNotFoundError ||
+        err instanceof InvalidAnnotationDraftError ||
+        err instanceof StaleAnnotationDraftError ||
+        err instanceof FixtureSpecError ||
+        err instanceof UnboundSetupRefError ||
+        isEnvironmentError(err)) {
+        return { code: err.code, message: err.message };
+    }
+    if (err instanceof UnknownJourneyError)
+        return { code: "E_UNKNOWN_JOURNEY", message: err.message };
+    if (err instanceof JourneyRequiresAuthError)
+        return { code: "E_JOURNEY_REQUIRES_AUTH", message: err.message };
+    if (err instanceof UnauthorizedExploreTargetError)
+        return { code: "E_UNAUTHORIZED_EXPLORE_TARGET", message: err.message };
+    if (err instanceof TargetConfigError)
+        return { code: "E_TARGET_CONFIG", message: err.message };
+    if (err instanceof SecretLeakError)
+        return { code: "E_DEMO_SECRET", message: err.message };
+    if (err instanceof FixtureSetupError)
+        return { code: "E_DEMO", message: err.message };
+    return null;
+}
+/** The shared replay options from a command's flags (throws a typed refusal on unusable input). */
+function replayOptionsFrom(cmd, deps, o, environment) {
+    const fixtureFlags = {
+        fixtures: o.fixtures,
+        before: o.before ?? environment.hooks?.before,
+        after: o.after ?? environment.hooks?.after,
+        allowShellHooks: o.allowShellHooks,
+        hookTimeoutMs: o.hookTimeoutMs,
+        fixtureIdentity: o.fixtureIdentity,
+    };
+    const storageState = o.storageState ?? environment.storageState;
+    if (storageState !== undefined && !existsSync(storageState))
+        throw new DemoAspectArgsError(`storage state not found: ${storageState}`);
+    let browser;
+    let emulation;
+    try {
+        browser = browserRunFromFlags(cmd.opts(), deps.explore?.env ?? process.env);
+        emulation = emulationFromFlags({ viewport: o.viewport, device: o.device });
+    }
+    catch (err) {
+        throw new DemoAspectArgsError(err instanceof Error ? err.message : String(err));
+    }
+    return {
+        environment,
+        ...(storageState === undefined ? {} : { storageState }),
+        ...(deps.explore?.browserPortFactory === undefined ? {} : { browserPortFactory: deps.explore.browserPortFactory }),
+        ...(browser === undefined ? {} : { browser }),
+        ...(emulation === undefined ? {} : { emulation }),
+        ...(o.pace === undefined ? {} : { paceMs: o.pace }),
+        fixtures: (site) => buildMissionFixtures(fixtureFlags, {
+            allowlist: environment.allowedOrigins,
+            baseUrl: site,
+            ...(storageState === undefined ? {} : { storageState }),
+            ...(environment.fixtures === undefined ? {} : { targetFixtures: environment.fixtures }),
+        }),
+    };
+}
+function withReplayFlags(cmd) {
+    return withDemoFlags(withBrowserLaunchFlags(withEmulationFlags(withFixtureFlags(cmd))))
+        .option("--dir <path>", "journeys directory (default: the repo's .jevitate/journeys; outside a repo ~/.jevitate/journeys)")
+        .option("--storage-state <file>", "Playwright storageState JSON to start authenticated (default: the environment's session in ~/.jevitate/targets.json); must exist")
+        .option("--out <dir>", "write the demo (demo.webm + demo.vtt + guide.md with guide.assets/) into this folder (default: a fresh folder in the logs dir)")
+        .option("--pace <ms>", `how long each step's caption shows before it acts (default ${DEMO_DEFAULT_PACE_MS})`, intArg({ min: 0, max: DEMO_MAX_PACE_MS }))
+        .option("--json", "emit a JSON envelope");
+}
+function outDirFor(flag, id, kind) {
+    if (flag !== undefined)
+        return resolvePath(flag);
+    return join(logsDirFor(), `demo-${id}-${kind}-${artifactStamp(clock.nowIso())}`);
+}
+function stepLines(steps) {
+    return steps
+        .map((s) => `  ${s.number}. ${s.objective ?? s.step}${s.expectedResult === undefined ? "" : `\n     expected: ${s.expectedResult}`}\n`)
+        .join("");
+}
+export function registerDemoCommands(program, deps) {
+    const demo = program
+        .command("demo")
+        .description('demo one aspect of an app from a one-line request: explore → clean path → Journey → annotate → a DRAFT narrated demo; `demo approve <id>` promotes and renders the final one');
+    withReplayFlags(demo.command("create <aspect>", { isDefault: true }))
+        .description('explore a named non-production environment toward <aspect> (checked by --success), minimize the path to its essential steps (verified by replay), ' +
+        "annotate it and render a DRAFT demo (video, .vtt, guide); nothing is promoted until `demo approve <id>` (also: jevitate demo \"<aspect>\")")
+        .option("--env <name>", "the named environment to demo on (.jevitate/environments.json); required, and never one flagged production: true")
+        .option("--success <spec>", "independent success check that proves the aspect was shown, e.g. textIncludes:testId=status|Saved (required)")
+        .option("--persona <name>", "the persona whose session (~/.jevitate/targets.json personas) the demo runs as")
+        .option("--id <id>", "the Journey id (default: demo-<aspect slug>)")
+        .option("--start <path>", "the app path exploration starts from (default /)")
+        .option("--max-actions <n>", "hard cap on explored actions", positiveIntArg)
+        .option("--max-decisions <n>", "hard cap on model decisions", positiveIntArg)
+        .option("--real", "use live Jev + OpenRouter gateways (requires keys)", false)
+        .option("--fake-ai", "use deterministic fake gateways (pipeline smoke only)", false)
+        .action(async function (aspect) {
+        const o = this.opts();
+        const out = program.configureOutput().writeOut;
+        try {
+            if (o.success === undefined)
+                throw new DemoAspectArgsError("--success <spec> is required: the independent check that proves the aspect was shown");
+            let successAssertion;
+            try {
+                successAssertion = parseAssertionSpec(o.success);
+            }
+            catch (err) {
+                throw new DemoAspectArgsError(`--success: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const seams = environmentSeams(deps);
+            const environment = o.env === undefined ? undefined : resolveJourneyEnvironment({ env: o.env, ...(o.persona === undefined ? {} : { persona: o.persona }), ...seams });
+            assertDemoEnvironment(environment); // #249: a named, non-production environment — before anything runs
+            const replay = replayOptionsFrom(this, deps, o, environment);
+            const safety = (seams.targetsFile === undefined ? loadTargetsFile() : loadTargetsFile(seams.targetsFile))[environment.baseUrl]?.safety;
+            const id = o.id ?? demoJourneyId(aspect);
+            const { judge, gen, usage } = await buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false });
+            const bounds = { ...(o.maxActions === undefined ? {} : { maxActions: o.maxActions }), ...(o.maxDecisions === undefined ? {} : { maxDecisions: o.maxDecisions }) };
+            const result = await withSiteGate(resolveDbPath(deps), (siteGate) => demoAspect({
+                ...replay,
+                ...(siteGate === undefined ? {} : { siteGate }),
+                aspect,
+                successAssertion,
+                successSpec: o.success ?? "",
+                journeysDir: resolveJourneysDir(deps, o.dir),
+                id,
+                ...(o.start === undefined ? {} : { start: o.start }),
+                ...(o.persona === undefined ? {} : { persona: o.persona }),
+                judge,
+                gen,
+                ...(Object.keys(bounds).length === 0 ? {} : { bounds }),
+                ...(safety === undefined ? {} : { safety }),
+                outDir: outDirFor(o.out, id, "draft"),
+            }));
+            const data = withEngine({ ...result, usage: usage.snapshot() });
+            // Only a drafted demo did the job; a goal not reached / a path that does not replay is a failed check.
+            process.exitCode = result.outcome === "drafted" ? EXIT_CODES.ok : EXIT_CODES.defects;
+            if (o.json) {
+                emitJson(program, ok(data));
+                return;
+            }
+            if (result.outcome !== "drafted") {
+                program.configureOutput().writeErr?.(`error: demo of "${result.aspect}" on ${result.environment}: ${result.outcome}: ${result.reason ?? "unknown"}\n`);
+                emitUsageLine(program, data);
+                return;
+            }
+            const m = result.minimize;
+            out?.(`DRAFT demo of "${result.aspect}" on ${result.environment} — journey '${result.id}' (not promoted)\n`);
+            if (m !== undefined) {
+                out?.(`clean path: explored ${m.exploredSteps} step(s), kept ${m.keptSteps}${m.dropped.length === 0 ? "" : `; dropped: ${m.dropped.join("; ")}`}` +
+                    `${m.budgetExhausted ? " (replay budget reached: verified, maybe not minimal)" : ""}\n`);
+            }
+            out?.(`steps (with the drafted annotations):\n${stepLines(result.steps ?? [])}`);
+            if (result.annotations !== undefined)
+                out?.(formatAnnotationChanges(result.annotations.proposed));
+            if (result.draft?.video !== undefined)
+                out?.(`DRAFT video: ${result.draft.video}\nDRAFT subtitles: ${result.draft.subtitles ?? ""}\n`);
+            if (result.draft?.guide !== undefined)
+                out?.(`DRAFT guide: ${result.draft.guide}\n`);
+            out?.(`annotations: ${result.annotations?.draftPath ?? ""}\nreview it, then approve (promotes the Journey, renders the final demo): ${result.next ?? ""}\n`);
+            emitUsageLine(program, data);
+        }
+        catch (err) {
+            if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
+                emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
+                return;
+            }
+            const r = refusalOf(err);
+            emitJson(program, r === null ? fail("E_DEMO", String(err instanceof Error ? err.message : err)) : fail(r.code, r.message));
+        }
+    });
+    withReplayFlags(demo.command("approve <id>"))
+        .description("the one human approval of a DRAFT demo: shows the Journey and its annotations, renders the final demo (no DRAFT marks) on the environment it was made on, " +
+        "then applies the annotations and promotes the Journey; a replay that no longer works promotes nothing (exit 1)")
+        .action(async function (id) {
+        const o = this.opts();
+        const out = program.configureOutput().writeOut;
+        try {
+            const journeysDir = resolveJourneysDir(deps, o.dir);
+            const { record } = await loadDemoForApproval(journeysDir, id);
+            const environment = resolveJourneyEnvironment({ env: record.env, ...(record.persona === undefined ? {} : { persona: record.persona }), ...environmentSeams(deps) });
+            assertDemoEnvironment(environment); // re-checked: the environment may have been flagged production since
+            const replay = replayOptionsFrom(this, deps, o, environment);
+            const result = await withSiteGate(resolveDbPath(deps), (siteGate) => approveDemo({ ...replay, ...(siteGate === undefined ? {} : { siteGate }), journeysDir, id, outDir: outDirFor(o.out, id, "final") }));
+            process.exitCode = result.outcome === "approved" ? EXIT_CODES.ok : EXIT_CODES.defects;
+            if (o.json) {
+                emitJson(program, ok(withEngine(result)));
+                return;
+            }
+            out?.(`journey '${id}' — "${record.aspect}" on ${result.environment}:\n${stepLines(result.steps)}`);
+            if (result.outcome !== "approved") {
+                program.configureOutput().writeErr?.(`error: demo '${id}' is stale: ${result.reason ?? "unknown"}\n`);
+                return;
+            }
+            out?.(formatAnnotationChanges(result.changes));
+            out?.(`approved: journey '${id}' promoted\n`);
+            if (result.final?.video !== undefined)
+                out?.(`video: ${result.final.video}\nsubtitles: ${result.final.subtitles ?? ""}\n`);
+            if (result.final?.guide !== undefined)
+                out?.(`guide: ${result.final.guide}\n`);
+        }
+        catch (err) {
+            const r = refusalOf(err);
+            emitJson(program, r === null ? fail("E_DEMO", String(err instanceof Error ? err.message : err)) : fail(r.code, r.message));
+        }
+    });
+}
+//# sourceMappingURL=demo-aspect-cli.js.map

package/dist/demo-aspect-cli.js.map

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

package/dist/demo-capture.d.ts

@@ -0,0 +1,142 @@
+import type { Locator, Page } from "playwright";
+import { REVEALED_SECRET_SELECTORS, REVEALED_SECRET_SHAPES, revealedSecretsIn } from "@jevitate/ai-core";
+import type { TargetDescriptor } from "@jevitate/recording";
+import type { BrowserPort } from "@jevitate/playwright";
+/**
+ * #248 — the ONE place a demo screenshot is taken. The overlay is always hidden (Playwright's
+ * `screenshot({ style })`, applied only for the capture: the page's DOM is never touched), and the
+ * capture is built from LAYERS so later safety passes plug in without touching the callers: pixel
+ * masking of secret fields (#250/#251) is a layer contributing `mask` locators and/or extra `style`.
+ * A layer cannot drop the overlay-hiding style: styles are concatenated, never replaced.
+ *
+ * #250/#251 — the pixel mask ({@link SecretPixelMask}): every registered secret value the page
+ * shows (text nodes, non-password input/textarea/select values, attribute-rendered text such as a
+ * `title`) is painted over by a DISPLAY-ONLY layer — the #245 overlay's technique: a CLOSED shadow
+ * root on a `<jevitate-mask>` host appended to `<html>`, pointer-events none, inert, aria-hidden;
+ * the page's own nodes are never changed. The layer re-measures on every animation frame (before
+ * each paint) and re-scans on every DOM mutation / input, so a video frame never shows a secret the
+ * mask has not caught. Screenshots and videos FAIL CLOSED: a capture whose mask cannot be proven
+ * (every occurrence covered by a painted box, the layer attached, visible and on top) is not written.
+ */
+/** What a layer adds to one capture. */
+export interface CaptureContribution {
+    /** Extra CSS applied only while capturing (appended after the overlay-hiding style). */
+    readonly style?: string;
+    /** Elements painted over in the image (Playwright `mask`). */
+    readonly mask?: readonly Locator[];
+    /** The mask colour (Playwright `maskColor`); the last layer that sets one wins. */
+    readonly maskColor?: string;
+}
+/** Where in the demo a capture is taken. */
+export interface CaptureContext {
+    /** 1-based step number. */
+    readonly step: number;
+}
+/** A capture layer: consulted just before each screenshot. It must not change the page. */
+export interface CaptureLayer {
+    readonly name: string;
+    prepare(page: Page, ctx: CaptureContext): Promise<CaptureContribution | void>;
+    /**
+     * #250: re-checked right AFTER the screenshot; a throw deletes the file just written (fail
+     * closed: the page may have changed between `prepare` and the capture).
+     */
+    confirm?(page: Page, ctx: CaptureContext): Promise<void>;
+}
+/** The screenshot options a set of layers produces (the overlay-hiding style always first). */
+export declare function captureOptions(page: Page, ctx: CaptureContext, layers: readonly CaptureLayer[]): Promise<{
+    style: string;
+    mask: Locator[];
+    maskColor?: string;
+}>;
+/**
+ * Writes one step's PNG at `path`: the viewport (or `clip`, a page-coordinate region — #198's cropped
+ * finding shots), overlay hidden, every layer applied. Throws on failure.
+ */
+export declare function captureStepScreenshot(page: Page, path: string, ctx: CaptureContext, layers?: readonly CaptureLayer[], clip?: {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}): Promise<void>;
+/** The solid colour a secret is painted over with (the usability capture's mask colour, pinned). */
+export declare const PIXEL_MASK_COLOR = "#FF00FF";
+/** The attribute marking the mask layer's host element (never hidden by the capture style). */
+export declare const PIXEL_MASK_ATTR = "data-jevitate-mask-layer";
+/**
+ * #298 — a secret the app REVEALS mid-run (a freshly minted API key, a one-time reveal panel, an
+ * invite or reset link) is not known in advance, so it cannot be registered with `--secret`. The
+ * pixel mask also covers, with no registration:
+ *
+ *  - elements the target marks as secret: these selectors (a target opts in with the
+ *    `data-jevitate-mask` attribute; the rest are common one-time-secret markers);
+ *  - text and field values shaped like a credential ({@link REVEALED_SECRET_SHAPES}).
+ *
+ * A value found either way is LEARNED for the rest of the run: masked wherever it appears later
+ * (another screen, a frame) and redacted from the screenshot index. Learned values live only in
+ * memory (the run's mask), never on disk. Limits (docs/safety.md): a secret with no marker and
+ * no credential shape (a short code, a plain word) is not masked; a password field shows dots.
+ */
+export { REVEALED_SECRET_SELECTORS, REVEALED_SECRET_SHAPES, revealedSecretsIn };
+/** The mask could not be applied or proven: the capture is skipped (fail closed), never written. */
+export declare class MaskUnavailableError extends Error {
+    readonly code: "E_PIXEL_MASK";
+    constructor(message: string);
+}
+/** One proof of the mask at capture time, across every frame of the page. */
+export interface MaskCheck {
+    readonly ok: boolean;
+    /** Visible occurrences of a registered secret (text ranges, fields, attribute-bearing elements). */
+    readonly occurrences: number;
+    /** Of those, how many a painted mask box fully covers. */
+    readonly masked: number;
+    /** Why the proof failed (never contains a secret). */
+    readonly reason?: string;
+    /** The covered occurrences' viewport rects (top frame only) — what a pixel check can sample. */
+    readonly rects: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    }>;
+}
+/**
+ * One run's pixel mask over its registered secrets (raw and URL-encoded forms, as `redactText`).
+ * `install` (per browser context, before its first navigation — every later document and frame gets
+ * it from an init script) keeps a VIDEO masked; `verify`/`layer()` prove it at each capture and
+ * `assertMasked` throws {@link MaskUnavailableError} when it cannot be proven. With no secrets there
+ * is nothing to mask: `verify` is trivially ok and nothing is injected for it.
+ */
+export declare class SecretPixelMask {
+    #private;
+    /**
+     * Always true (#298): even with no registered secret, a secret the app reveals mid-run (a marked
+     * element, a credential-shaped value) is masked, so every capture installs and proves the mask.
+     */
+    readonly active: boolean;
+    constructor(secrets: readonly string[]);
+    /** Installs the live mask in `page`'s context (every future document/frame) and every current frame. Throws when it cannot. */
+    install(page: Page): Promise<void>;
+    /**
+     * The secrets the app revealed during the run (#298), as learned so far — for redacting what the
+     * run writes about its captures (the screenshot index). Never persisted.
+     */
+    revealed(): readonly string[];
+    /** Proves the mask covers every visible secret occurrence in every frame of `page`, now. */
+    verify(page: Page): Promise<MaskCheck>;
+    /** Throws {@link MaskUnavailableError} unless {@link verify} proves the mask. */
+    assertMasked(page: Page): Promise<MaskCheck>;
+    /** The capture layer: proven before the screenshot and again after it (a failure deletes the file). */
+    layer(): CaptureLayer;
+    /** Draws a capture highlight box around `target`'s first match (display-only). True when shown. */
+    highlight(page: Page, target: TargetDescriptor): Promise<boolean>;
+    /** #198: the same display-only highlight box around `locator`'s first match (a control or a quoted text). */
+    highlightLocator(page: Page, locator: Locator): Promise<boolean>;
+    /** Removes the capture highlight (best-effort). */
+    clearHighlight(page: Page): Promise<void>;
+}
+/**
+ * A port whose every session carries the live pixel mask from before its first navigation — so a
+ * `recordVideo` session's every frame is masked. A session whose mask cannot be installed is closed
+ * and the open throws {@link MaskUnavailableError}: nothing is recorded unmasked.
+ */
+export declare function maskingPort(port: BrowserPort, mask: SecretPixelMask): BrowserPort;