@jevitate/cli 0.1.0 → 0.2.0

package/dist/demo-capture.js

@@ -0,0 +1,438 @@
+import { randomBytes } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { secretForms } from "@jevitate/ai-core";
+import { DEMO_OVERLAY_HIDE_STYLE } from "@jevitate/explore";
+import { descriptorToLocator } from "@jevitate/recorder";
+/** The screenshot options a set of layers produces (the overlay-hiding style always first). */
+export async function captureOptions(page, ctx, layers) {
+    const styles = [DEMO_OVERLAY_HIDE_STYLE];
+    const mask = [];
+    let maskColor;
+    for (const layer of layers) {
+        const c = await layer.prepare(page, ctx);
+        if (c === undefined)
+            continue;
+        if (c.style !== undefined && c.style !== "")
+            styles.push(c.style);
+        if (c.mask !== undefined)
+            mask.push(...c.mask);
+        if (c.maskColor !== undefined)
+            maskColor = c.maskColor;
+    }
+    return { style: styles.join("\n"), mask, ...(maskColor === undefined ? {} : { maskColor }) };
+}
+/** Writes one step's PNG at `path`: the viewport, overlay hidden, every layer applied. Throws on failure. */
+export async function captureStepScreenshot(page, path, ctx, layers = []) {
+    const { style, mask, maskColor } = await captureOptions(page, ctx, layers);
+    await page.screenshot({
+        path,
+        type: "png",
+        animations: "disabled",
+        style,
+        ...(mask.length === 0 ? {} : { mask }),
+        ...(maskColor === undefined ? {} : { maskColor }),
+    });
+    try {
+        for (const layer of layers)
+            await layer.confirm?.(page, ctx);
+    }
+    catch (err) {
+        await rm(path, { force: true });
+        throw err;
+    }
+}
+// ── #250/#251: the pixel mask ────────────────────────────────────────────────────────────────────
+/** The solid colour a secret is painted over with (the usability capture's mask colour, pinned). */
+export const PIXEL_MASK_COLOR = "#FF00FF";
+/** The attribute marking the mask layer's host element (never hidden by the capture style). */
+export const PIXEL_MASK_ATTR = "data-jevitate-mask-layer";
+/** The mask could not be applied or proven: the capture is skipped (fail closed), never written. */
+export class MaskUnavailableError extends Error {
+    code = "E_PIXEL_MASK";
+    constructor(message) {
+        super(message);
+        this.name = "MaskUnavailableError";
+    }
+}
+/**
+ * BROWSER CODE (a string: evaluated as-is, never transpiled). `__CFG__` is replaced by the JSON
+ * config `{ name, secrets, fill, attr }`. Idempotent per document; installs `window[name]`
+ * (non-enumerable, non-writable, non-configurable — a random name per run, so a page cannot
+ * pre-empt or fake it). Secret values live only inside this closure.
+ */
+const MASK_RUNTIME = String.raw `((cfg) => {
+  if (window[cfg.name]) return true;
+  const SECRETS = cfg.secrets.filter((s) => typeof s === "string" && s.trim().length > 0);
+  const SKIP = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "TITLE", "META", "LINK"]);
+  const PAD = 2;
+  const CSS = ":host{all:initial}*{pointer-events:none !important;box-sizing:border-box}[hidden]{display:none !important}" +
+    ".m{position:fixed;background:" + cfg.fill + ";border-radius:2px}" +
+    ".h{position:fixed;border:3px solid #f59e0b;border-radius:6px;box-shadow:0 0 0 4px rgba(245,158,11,.35)}";
+  let host = null;
+  let layer = null;
+  let hiBox = null;
+  let dirty = true;
+  let targets = [];
+  const boxes = [];
+  let drawn = [];
+  let highlightEl = null;
+  let lastError = "";
+  const holds = (s) => typeof s === "string" && s.length > 0 && SECRETS.some((x) => s.includes(x));
+  const ensureHost = () => {
+    const root = document.documentElement;
+    if (!root) return false;
+    if (host === null) {
+      host = document.createElement("jevitate-mask");
+      host.setAttribute(cfg.attr, "");
+      host.setAttribute("aria-hidden", "true");
+      host.setAttribute("inert", "");
+      const st = { display: "block", visibility: "visible", opacity: "1", position: "fixed", top: "0", left: "0",
+        width: "0", height: "0", overflow: "visible", "pointer-events": "none", "z-index": "2147483647",
+        transform: "none", filter: "none", "clip-path": "none", margin: "0", padding: "0", border: "0" };
+      for (const k of Object.keys(st)) host.style.setProperty(k, st[k], "important");
+      const shadow = host.attachShadow({ mode: "closed" });
+      try {
+        const sheet = new CSSStyleSheet();
+        sheet.replaceSync(CSS);
+        shadow.adoptedStyleSheets = [sheet];
+      } catch (e) {
+        const s = document.createElement("style");
+        s.textContent = CSS;
+        shadow.appendChild(s);
+      }
+      layer = document.createElement("div");
+      hiBox = document.createElement("div");
+      hiBox.className = "h";
+      hiBox.hidden = true;
+      shadow.append(layer, hiBox);
+    }
+    // The last child of <html>: painted after (above) every same-z-index page layer.
+    if (host.parentNode !== root || root.lastElementChild !== host) root.appendChild(host);
+    return true;
+  };
+  const collect = () => {
+    const out = [];
+    if (SECRETS.length === 0) return out;
+    const roots = [document];
+    const perSecretRanges = new Map();
+    for (let i = 0; i < roots.length; i++) {
+      const w = document.createTreeWalker(roots[i], NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+      for (let n = w.nextNode(); n !== null; n = w.nextNode()) {
+        if (n.nodeType === 3) {
+          const p = n.parentElement;
+          if (p !== null && SKIP.has(p.tagName)) continue;
+          const v = n.nodeValue;
+          if (!v) continue;
+          for (const s of SECRETS) {
+            let at = v.indexOf(s);
+            while (at >= 0) {
+              out.push({ kind: "range", node: n, start: at, end: at + s.length });
+              perSecretRanges.set(s, (perSecretRanges.get(s) || 0) + 1);
+              at = v.indexOf(s, at + s.length);
+            }
+          }
+          continue;
+        }
+        const el = n;
+        if (el === host) continue;
+        if (el.shadowRoot) roots.push(el.shadowRoot);
+        if (SKIP.has(el.tagName)) continue;
+        let hit = false;
+        const tag = el.tagName;
+        if (tag === "INPUT" || tag === "TEXTAREA") {
+          const type = (el.getAttribute("type") || "").toLowerCase();
+          if (!(tag === "INPUT" && type === "password") && holds(el.value)) hit = true;
+        } else if (tag === "SELECT") {
+          const t = Array.from(el.selectedOptions || []).map((o) => o.text).join(" ");
+          if (holds(t) || holds(el.value)) hit = true;
+        }
+        if (!hit) for (const a of Array.from(el.attributes)) if (holds(a.value)) { hit = true; break; }
+        if (hit) out.push({ kind: "el", el });
+      }
+    }
+    // A secret split across text nodes (e.g. "sec<b>ret</b>"): mask the deepest element holding it whole.
+    const body = document.body;
+    if (body) {
+      const text = body.textContent || "";
+      for (const s of SECRETS) {
+        let total = 0;
+        for (let at = text.indexOf(s); at >= 0; at = text.indexOf(s, at + s.length)) total++;
+        if (total <= (perSecretRanges.get(s) || 0)) continue;
+        const walk = (el) => {
+          let child = false;
+          for (const c of Array.from(el.children)) {
+            if (SKIP.has(c.tagName)) continue;
+            if ((c.textContent || "").includes(s)) { child = true; walk(c); }
+          }
+          if (!child && !out.some((t) => t.kind === "range" && el.contains(t.node))) out.push({ kind: "el", el });
+        };
+        walk(body);
+      }
+    }
+    return out;
+  };
+  const rectsOf = (t) => {
+    if (t.kind === "range") {
+      if (!t.node.isConnected) return null;
+      const r = document.createRange();
+      try { r.setStart(t.node, t.start); r.setEnd(t.node, t.end); } catch (e) { return null; }
+      return Array.from(r.getClientRects());
+    }
+    if (!t.el.isConnected) return null;
+    return [t.el.getBoundingClientRect()];
+  };
+  const fieldText = (el) => el.tagName === "SELECT" ? Array.from(el.selectedOptions || []).map((o) => o.text).join(" ") + " " + el.value : el.value;
+  const inputsChanged = () => {
+    if (SECRETS.length === 0) return false;
+    const flagged = new Set(targets.filter((t) => t.kind === "el").map((t) => t.el));
+    for (const el of Array.from(document.querySelectorAll("input, textarea, select"))) {
+      if (el.tagName === "INPUT" && (el.getAttribute("type") || "").toLowerCase() === "password") continue;
+      if (holds(fieldText(el)) && !flagged.has(el)) return true;
+    }
+    return false;
+  };
+  const place = (d, r, pad) => {
+    d.style.left = (r.left - pad) + "px";
+    d.style.top = (r.top - pad) + "px";
+    d.style.width = (r.width + 2 * pad) + "px";
+    d.style.height = (r.height + 2 * pad) + "px";
+  };
+  const update = () => {
+    if (!ensureHost()) return;
+    if (dirty || inputsChanged()) { targets = collect(); dirty = false; }
+    const rects = [];
+    for (const t of targets) {
+      const rs = rectsOf(t);
+      if (rs === null) { dirty = true; continue; }
+      for (const r of rs) if (r.width > 0 || r.height > 0) rects.push(r);
+    }
+    while (boxes.length < rects.length) {
+      const d = document.createElement("div");
+      d.className = "m";
+      layer.appendChild(d);
+      boxes.push(d);
+    }
+    for (let i = 0; i < boxes.length; i++) {
+      const d = boxes[i];
+      if (i < rects.length) { place(d, rects[i], PAD); d.hidden = false; } else d.hidden = true;
+    }
+    drawn = rects;
+    if (highlightEl !== null && highlightEl.isConnected) {
+      place(hiBox, highlightEl.getBoundingClientRect(), 5);
+      hiBox.hidden = false;
+    } else hiBox.hidden = true;
+  };
+  const tick = () => {
+    try { update(); lastError = ""; } catch (e) { lastError = String((e && e.message) || e).slice(0, 200); }
+    requestAnimationFrame(tick);
+  };
+  const mo = new MutationObserver((records) => {
+    for (const r of records) {
+      if (r.type === "attributes" && (r.attributeName === "style" || r.attributeName === "class")) continue;
+      if (r.type === "childList" && r.target === document.documentElement &&
+        Array.from(r.addedNodes).concat(Array.from(r.removedNodes)).every((x) => x === host)) continue;
+      dirty = true;
+      return;
+    }
+  });
+  mo.observe(document, { subtree: true, childList: true, characterData: true, attributes: true });
+  const mark = () => { dirty = true; };
+  window.addEventListener("input", mark, true);
+  window.addEventListener("change", mark, true);
+  const covers = (b, r) => b.left <= r.left + 0.5 && b.top <= r.top + 0.5 && b.right >= r.right - 0.5 && b.bottom >= r.bottom - 0.5;
+  const api = {
+    verify() {
+      dirty = true;
+      try { update(); } catch (e) {
+        return { ok: false, occurrences: 0, masked: 0, reason: "the mask update failed: " + String((e && e.message) || e).slice(0, 200), rects: [] };
+      }
+      const problems = [];
+      if (SECRETS.length > 0) {
+        if (host === null || !host.isConnected) problems.push("the mask layer is not attached");
+        else {
+          const cs = getComputedStyle(host);
+          if (cs.display === "none" || cs.visibility !== "visible" || Number(cs.opacity) < 1) problems.push("the mask layer is hidden");
+          if (document.documentElement.lastElementChild !== host) problems.push("the mask layer is not the last layer");
+        }
+      }
+      if (drawn.length > 0 && document.querySelector(":modal, :popover-open, :fullscreen") !== null) {
+        problems.push("a top-layer element (modal dialog, popover or fullscreen) could paint over the mask");
+      }
+      let masked = 0;
+      const live = boxes.filter((d) => !d.hidden).map((d) => d.getBoundingClientRect());
+      for (const r of drawn) if (live.some((b) => covers(b, r))) masked++;
+      if (masked < drawn.length) problems.push((drawn.length - masked) + " occurrence(s) not covered by a mask box");
+      if (lastError !== "") problems.push("the mask loop failed: " + lastError);
+      const out = { ok: problems.length === 0, occurrences: drawn.length, masked, rects: drawn.map((r) => ({ x: r.left, y: r.top, width: r.width, height: r.height })) };
+      if (problems.length > 0) out.reason = problems.join("; ");
+      return out;
+    },
+    highlight(el) { highlightEl = el || null; try { update(); } catch (e) { /* presentation only */ } return highlightEl !== null; },
+    clearHighlight() { highlightEl = null; try { update(); } catch (e) { /* presentation only */ } return true; },
+  };
+  Object.defineProperty(window, cfg.name, { value: Object.freeze(api), enumerable: false, configurable: false, writable: false });
+  requestAnimationFrame(tick);
+  return true;
+})(__CFG__)`;
+/** Bound on one mask round-trip (ms). */
+const MASK_CALL_MS = 5_000;
+async function within(p, what) {
+    let timer;
+    try {
+        return await Promise.race([
+            p,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new MaskUnavailableError(`${what} timed out after ${MASK_CALL_MS}ms`)), MASK_CALL_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function errText(e) {
+    return (e instanceof Error ? e.message : String(e)).split("\n")[0] ?? "unknown error";
+}
+/**
+ * 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 class SecretPixelMask {
+    #source;
+    #name;
+    #contexts = new WeakSet();
+    /** True when there is at least one secret to mask. */
+    active;
+    constructor(secrets) {
+        const forms = [...new Set(secrets.filter((s) => typeof s === "string" && s.trim() !== "").flatMap((s) => [...secretForms(s)]))];
+        this.active = forms.length > 0;
+        this.#name = `__jevitateMask_${randomBytes(8).toString("hex")}`;
+        // JSON inside a JS expression (valid JS since ES2019); `<` escaped so no value can close a script context.
+        const cfg = JSON.stringify({ name: this.#name, secrets: forms, fill: PIXEL_MASK_COLOR, attr: PIXEL_MASK_ATTR })
+            .replace(/</g, "\\u003c");
+        this.#source = MASK_RUNTIME.replace("__CFG__", () => cfg);
+    }
+    /** Installs the live mask in `page`'s context (every future document/frame) and every current frame. Throws when it cannot. */
+    async install(page) {
+        const ctx = page.context();
+        if (!this.#contexts.has(ctx)) {
+            try {
+                await within(ctx.addInitScript({ content: this.#source }), "installing the pixel mask");
+            }
+            catch (e) {
+                throw new MaskUnavailableError(`could not install the pixel mask: ${errText(e)}`);
+            }
+            this.#contexts.add(ctx);
+        }
+        for (const p of ctx.pages())
+            for (const f of p.frames())
+                await this.#inject(f);
+    }
+    async #inject(frame) {
+        if (frame.isDetached())
+            return;
+        try {
+            await within(frame.evaluate(this.#source), "injecting the pixel mask");
+        }
+        catch (e) {
+            if (frame.isDetached())
+                return;
+            throw new MaskUnavailableError(`could not apply the pixel mask to a frame: ${errText(e)}`);
+        }
+    }
+    /** Proves the mask covers every visible secret occurrence in every frame of `page`, now. */
+    async verify(page) {
+        if (!this.active)
+            return { ok: true, occurrences: 0, masked: 0, rects: [] };
+        let occurrences = 0;
+        let masked = 0;
+        let rects = [];
+        const reasons = [];
+        for (const frame of page.frames()) {
+            if (frame.isDetached())
+                continue;
+            try {
+                await this.#inject(frame);
+                const r = await within(frame.evaluate((name) => window[name]?.verify() ?? null, this.#name), "verifying the pixel mask");
+                if (r === null) {
+                    reasons.push("the mask is not installed in a frame");
+                    continue;
+                }
+                occurrences += r.occurrences;
+                masked += r.masked;
+                if (frame === page.mainFrame())
+                    rects = r.rects;
+                if (!r.ok)
+                    reasons.push(r.reason ?? "the mask could not be proven");
+            }
+            catch (e) {
+                if (frame.isDetached())
+                    continue;
+                reasons.push(errText(e));
+            }
+        }
+        return { ok: reasons.length === 0, occurrences, masked, rects, ...(reasons.length === 0 ? {} : { reason: reasons.join("; ") }) };
+    }
+    /** Throws {@link MaskUnavailableError} unless {@link verify} proves the mask. */
+    async assertMasked(page) {
+        const r = await this.verify(page);
+        if (!r.ok)
+            throw new MaskUnavailableError(`secret masking could not be proven: ${r.reason ?? "unknown"}`);
+        return r;
+    }
+    /** The capture layer: proven before the screenshot and again after it (a failure deletes the file). */
+    layer() {
+        return {
+            name: "secret-pixel-mask",
+            prepare: async (page) => {
+                await this.assertMasked(page);
+            },
+            confirm: async (page) => {
+                await this.assertMasked(page);
+            },
+        };
+    }
+    /** Draws a capture highlight box around `target`'s first match (display-only). True when shown. */
+    async highlight(page, target) {
+        try {
+            await this.#inject(page.mainFrame());
+            return await within(descriptorToLocator(page, target)
+                .first()
+                .evaluate((el, name) => window[name]?.highlight(el) === true, this.#name, { timeout: 2_000 }), "highlighting the failing element");
+        }
+        catch {
+            return false; // a highlight is presentation only
+        }
+    }
+    /** Removes the capture highlight (best-effort). */
+    async clearHighlight(page) {
+        await within(page.evaluate((name) => window[name]?.clearHighlight(), this.#name), "clearing the highlight").catch(() => undefined);
+    }
+}
+/**
+ * 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 function maskingPort(port, mask) {
+    if (!mask.active)
+        return port;
+    return {
+        open: async (o) => {
+            const session = await port.open(o);
+            try {
+                await mask.install(session.page);
+            }
+            catch (e) {
+                await session.close().catch(() => undefined);
+                throw e;
+            }
+            return session;
+        },
+    };
+}
+//# sourceMappingURL=demo-capture.js.map

package/dist/demo-capture.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build identity for every mission result, issue draft, and `--version` (issue #83): "It's hard
+ * to attribute results to a build" — the dev workflow (`npm link` to a live working tree) means
+ * `jevitate --version`'s package.json number alone doesn't change between rebuilds, so two
+ * results from different builds in the same dogfooding session were indistinguishable.
+ *
+ * `commit`/`builtAt` come from ONE of two places, and both fall back to `"unknown"` — never a
+ * fabricated value:
+ *
+ *  - the esbuild bundle (`pnpm --filter @jevitate/cli run bundle`, what npm actually publishes)
+ *    folds them in as literals via an esbuild `define` (`build.mjs`), computed there from
+ *    `git rev-parse` at bundle time;
+ *  - the plain `tsc --build` dist (what a dev `npm link` install runs — no bundler
+ *    substitution ever touches it) reads the SAME git-rev-parse-or-"unknown" computation from a
+ *    small generated module written just before `tsc --build` runs
+ *    (`scripts/generate-build-info.mjs`, hooked into the package's "build" script).
+ *
+ * Both compute identically; only the injection mechanism differs by build path, so this module
+ * simply prefers whichever one actually ran.
+ */
+export interface EngineInfo {
+    readonly version: string;
+    readonly commit: string;
+    readonly builtAt: string;
+}
+/** This build's identity: the published version plus which commit/build produced it. */
+export declare function currentEngineInfo(): EngineInfo;
+/**
+ * Stamps a CLI result with the build that produced it (#112) — every envelope a command emits
+ * (`journey run`, `load run`, `source run`, `verify-fix`, `regression capture`, `ux`) carries the
+ * same `engine` the explore results do, so evidence from any surface can be tied to a build.
+ */
+export declare function withEngine<T extends object>(result: T, engine?: EngineInfo): T & {
+    engine: EngineInfo;
+};

package/dist/engine.js

@@ -0,0 +1,25 @@
+import { GENERATED_BUILT_AT, GENERATED_COMMIT } from "./build-info.generated.js";
+import { readCliVersion } from "./version.js";
+function bundledCommit() {
+    return typeof __JEVITATE_BUILD_COMMIT__ !== "undefined" ? __JEVITATE_BUILD_COMMIT__ : undefined;
+}
+function bundledBuiltAt() {
+    return typeof __JEVITATE_BUILT_AT__ !== "undefined" ? __JEVITATE_BUILT_AT__ : undefined;
+}
+/** This build's identity: the published version plus which commit/build produced it. */
+export function currentEngineInfo() {
+    return {
+        version: readCliVersion(),
+        commit: bundledCommit() ?? GENERATED_COMMIT,
+        builtAt: bundledBuiltAt() ?? GENERATED_BUILT_AT,
+    };
+}
+/**
+ * Stamps a CLI result with the build that produced it (#112) — every envelope a command emits
+ * (`journey run`, `load run`, `source run`, `verify-fix`, `regression capture`, `ux`) carries the
+ * same `engine` the explore results do, so evidence from any surface can be tied to a build.
+ */
+export function withEngine(result, engine = currentEngineInfo()) {
+    return { ...result, engine };
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAkC9C,SAAS,aAAa;IACpB,OAAO,OAAO,yBAAyB,KAAK,WAAW,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,SAAS,CAAC;AAClG,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,OAAO,qBAAqB,KAAK,WAAW,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1F,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,OAAO,EAAE,cAAc,EAAE;QACzB,MAAM,EAAE,aAAa,EAAE,IAAI,gBAAgB;QAC3C,OAAO,EAAE,cAAc,EAAE,IAAI,kBAAkB;KAChD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAmB,MAAS,EAAE,SAAqB,iBAAiB,EAAE;IAC9F,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC"}