@jevitate/cli 0.1.0 → 0.2.0

package/dist/explore-shared.js

@@ -0,0 +1,129 @@
+/** Wiring shared by every explore strategy runner (goal, coverage, adversarial, feature): server-log and declared-invariant result fields, storageState persistence, drafts/filing context. */
+import { chmod, writeFile } from "node:fs/promises";
+import { assertSessionFileOutsideProject } from "./project-dir.js";
+import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
+import { currentEnvironment, isLoginLikeUrl, } from "@jevitate/explore";
+import { readCliVersion } from "./version.js";
+export function serverLogResult(runtimeResult) {
+    if (runtimeResult === undefined)
+        return {};
+    return { serverLogs: runtimeResult.summary, ...(runtimeResult.defects.length > 0 ? { serverLogDefects: runtimeResult.defects } : {}) };
+}
+/** The viewport/device emulation actually applied to a session — recorded on the Recording (#149). */
+export function recordingEmulation(resolved) {
+    if (resolved === undefined)
+        return undefined;
+    return {
+        viewport: resolved.viewport,
+        ...(resolved.device === undefined ? {} : { device: resolved.device }),
+        ...(resolved.deviceScaleFactor === undefined ? {} : { deviceScaleFactor: resolved.deviceScaleFactor }),
+        ...(resolved.isMobile === undefined ? {} : { isMobile: resolved.isMobile }),
+        ...(resolved.hasTouch === undefined ? {} : { hasTouch: resolved.hasTouch }),
+    };
+}
+/** Filing is off by default: drafts only, never a tracker call. */
+export const DRAFTS_ONLY = { enabled: false, jevitateRepo: "matt-cochran/jevitate" };
+export const NO_FILER = () => {
+    throw new Error("issue filing is enabled but no filer was configured");
+};
+export function draftContext(origin, journal, secrets, browserVersion, engine) {
+    return {
+        environment: currentEnvironment(origin, {
+            jevitateVersion: readCliVersion(),
+            commit: engine.commit,
+            builtAt: engine.builtAt,
+            ...(browserVersion === undefined ? {} : { browser: browserVersion }),
+        }),
+        recordingPath: journal.recordingPath,
+        transcriptPath: journal.transcriptPath,
+        secrets,
+    };
+}
+/**
+ * Opens a FRESH browser session for replays (hang reproduction): a new context from the same port
+ * and options — same authenticated storageState, never the session the finding was made in.
+ */
+export function freshSessionOpener(portFactory, launch, allowlist) {
+    return async () => {
+        const session = await portFactory().open(launch);
+        const actor = CastActor.named("replay").whoCan(new BrowseTheWeb(session, [...allowlist]));
+        return { page: session.page, actor, close: () => session.close() };
+    };
+}
+/** `session.page.url()`, or `undefined` when reading it throws (a closed/crashed page/context). */
+export function currentUrlSafe(session) {
+    try {
+        return session.page.url();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Writes the browser context's storageState (cookies + origin storage) to `file` when the caller
+ * asked for one (CLI `--save-storage-state`, #82) — so a rotating refresh token stays usable across
+ * runs instead of the `--storage-state` file it started from going stale on first use. Called from
+ * every mission's `finally`, so a thrown error still reaches it (#159) — the context is still open at
+ * that point, whatever failed inside the mission itself. A no-op when `file` is undefined.
+ *
+ * #159 — never persists a lost/logged-out session over a good file: when the CURRENT page looks
+ * login-like (`isLoginLikeUrl`, the #82 signal), a live capture is skipped in favor of `snapshotter`'s
+ * last known-good in-memory snapshot (refreshed after each settled step — see
+ * `storage-state-snapshot.ts` — and itself never updated from a login-like page, so it always holds
+ * the most recent GOOD state). The same fallback covers a live capture that simply fails (a
+ * crashed/closed context after the page url could still be read). If neither a safe live capture nor
+ * a snapshot is available, nothing is written — any existing file at `file` is left untouched. There
+ * is no flag today for an operator to force the write anyway; see `saveStorageState`'s own doc.
+ *
+ * The file holds live session credentials: written with mode 0600 (owner read/write only), and its
+ * contents are never logged either way.
+ */
+/**
+ * #195: refused BEFORE a browser opens — a `saveStorageState` inside a repo's `.jevitate/` (which
+ * never holds sessions or secrets). `persistStorageState` re-checks at the write itself.
+ */
+export function assertSaveStorageStateOutsideProject(file) {
+    if (file !== undefined)
+        assertSessionFileOutsideProject(file, "saveStorageState");
+}
+export async function persistStorageState(session, file, snapshotter) {
+    if (file === undefined)
+        return;
+    // #195: the final chokepoint for every caller — nothing is written inside a repo's .jevitate/;
+    // the refusal is thrown (the run reports it), never swallowed.
+    assertSessionFileOutsideProject(file, "saveStorageState");
+    const url = currentUrlSafe(session);
+    if (url === undefined || !isLoginLikeUrl(url)) {
+        try {
+            await session.saveStorageState(file);
+            await chmod(file, 0o600);
+            return;
+        }
+        catch {
+            // A crashed/closed context, or a mid-write failure — fall back to the last known-good snapshot.
+        }
+    }
+    const fallback = snapshotter?.snapshot();
+    if (fallback === undefined)
+        return;
+    await writeFile(file, fallback, { encoding: "utf8", mode: 0o600 });
+}
+export function browserVersionOf(page) {
+    try {
+        return page.context().browser()?.version();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The declared-invariant fields of a persisted result (#86): the defects (top-level `defects`, where
+ * `verify-fix` looks), the per-invariant report, and the spec itself so a later `verify-fix`
+ * re-checks exactly what the run checked. Nothing at all when the run had no `--invariants`.
+ */
+export function declaredResult(spec, defects, report) {
+    if (spec === undefined)
+        return {};
+    return { defects: [...(defects ?? [])], invariants: [...(report ?? [])], invariantSpec: spec };
+}
+//# sourceMappingURL=explore-shared.js.map

package/dist/explore-shared.js.map

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

package/dist/explore-specs.d.ts

@@ -0,0 +1,53 @@
+/** The compact `--success`/assertion/descriptor spec parsers and the explore allowlist resolution behind the explore CLI flags. */
+import { type Assertion } from "@jevitate/recording";
+import { type SuccessCheck } from "@jevitate/explore";
+/**
+ * Compact assertion spec parser (a recording `Assertion`, checked on a page). Supported forms:
+ *   urlIncludes:<text>
+ *   visible:<descriptor>
+ *   textIncludes:<descriptor>|<text>  — case-insensitive (#113): matches regardless of case, or of a
+ *                                        CSS text-transform (a badge whose DOM text is "Approved" but
+ *                                        renders `uppercase` still matches `|Approved`)
+ *   count:<descriptor>|min=<n>,max=<n>
+ *   valueEquals:<descriptor>|<value>   — a form control's VALUE (input, textarea, select), exactly
+ * and the visual-state kinds (#148), decided by code from fixed page reads:
+ *   style:<descriptor>|<prop><op><value>   — the COMPUTED style of EVERY match (at least one);
+ *                                        <prop> is an allowlisted CSS property, optionally one
+ *                                        channel of it: alpha(background-color)>0, px(outline-width)>=2;
+ *                                        <op> is = != > >= < <= (= compares colors as colors).
+ *                                        `styleMatches:` is an alias.
+ *   inViewport:<descriptor>[|min=<ratio>] — each match's visible fraction (0..1, default 0.5)
+ *   box:<descriptor>|minWidth=<n>,maxWidth=<n>,minHeight=<n>,maxHeight=<n> — each match's size (px)
+ *   overlaps:<descriptor>|<descriptor2> / noOverlap:<descriptor>|<descriptor2> — the first matches' boxes
+ *   attr:<descriptor>|<name>=<value> | attr:<descriptor>|<name> (present) | attr:<descriptor>|!<name> (absent)
+ *   flashed:<descriptor>|class=<cls>|attr=<name>|animation [|withinMs=<n>] — a match GAINED the
+ *                                        class / attribute / an animation after the last user input
+ * where <descriptor> is `k=v` pairs joined by `;` over testId/role/name/label/text/css
+ * (`css=h1`, `label=Display name`, `role=button;name=Save`) — key=value always wins, so a `=` is
+ * never read as CSS or text. With no `=` at all, a descriptor starting with `[`, `#` or `.` is CSS
+ * verbatim (`[data-testid=x]` becomes `testId=x`); any OTHER bare descriptor is read as CSS too, but
+ * only when it is a lowercase-only, syntactically valid CSS selector (#213: `h1`, `main h1`, `body`,
+ * `div.card`, `ul > li` — tag names, combinators, classes, ids, attributes, pseudo-classes; every
+ * character lowercase is what tells a real selector apart from an accessible-name phrase like
+ * `Display name`, which is never guessed at as either CSS or text). Anything that is not a valid
+ * key=value spec and not a lowercase CSS selector is refused with a hint naming the key=value forms
+ * (`css=`, `label=`, `testId=`, `role=`, `text=`) and an example. In `textIncludes` / `valueEquals`
+ * the LAST `|` separates the descriptor from the text.
+ */
+export declare function parseAssertionSpec(spec: string): Assertion;
+/**
+ * The goal mission's `--success` spec parser (repeatable: every check must hold). Besides every
+ * page assertion `parseAssertionSpec` reads:
+ *   reloadThen:<assertion>                     — reload the page, then check (persistence)
+ *   requestMade:<METHOD> <path-glob>           — the run issued this request
+ *   responseStatus:<METHOD> <path-glob>=<2xx|4xx|code> — and it got this status
+ * `<path-glob>` uses the route-glob syntax (`*` within a segment, `**` across segments) against
+ * the request's path; `*` as METHOD matches any method.
+ */
+export declare function parseSuccessSpec(spec: string): SuccessCheck;
+/**
+ * The authorized-origins allowlist for a run: explicit `--allow` origins when
+ * given, otherwise the target URL's own origin (you asked to explore it). An
+ * unparseable URL yields an empty allowlist → the guard fails closed.
+ */
+export declare function resolveExploreAllowlist(url: string, allow: readonly string[]): string[];

package/dist/explore-specs.js

@@ -0,0 +1,333 @@
+/** The compact `--success`/assertion/descriptor spec parsers and the explore allowlist resolution behind the explore CLI flags. */
+import { AssertionSchema, STYLE_CHANNELS, STYLE_PROPERTIES, COMPARE_OPS, } from "@jevitate/recording";
+import { normalizeAllowlist } from "@jevitate/explore";
+/**
+ * Compact assertion spec parser (a recording `Assertion`, checked on a page). Supported forms:
+ *   urlIncludes:<text>
+ *   visible:<descriptor>
+ *   textIncludes:<descriptor>|<text>  — case-insensitive (#113): matches regardless of case, or of a
+ *                                        CSS text-transform (a badge whose DOM text is "Approved" but
+ *                                        renders `uppercase` still matches `|Approved`)
+ *   count:<descriptor>|min=<n>,max=<n>
+ *   valueEquals:<descriptor>|<value>   — a form control's VALUE (input, textarea, select), exactly
+ * and the visual-state kinds (#148), decided by code from fixed page reads:
+ *   style:<descriptor>|<prop><op><value>   — the COMPUTED style of EVERY match (at least one);
+ *                                        <prop> is an allowlisted CSS property, optionally one
+ *                                        channel of it: alpha(background-color)>0, px(outline-width)>=2;
+ *                                        <op> is = != > >= < <= (= compares colors as colors).
+ *                                        `styleMatches:` is an alias.
+ *   inViewport:<descriptor>[|min=<ratio>] — each match's visible fraction (0..1, default 0.5)
+ *   box:<descriptor>|minWidth=<n>,maxWidth=<n>,minHeight=<n>,maxHeight=<n> — each match's size (px)
+ *   overlaps:<descriptor>|<descriptor2> / noOverlap:<descriptor>|<descriptor2> — the first matches' boxes
+ *   attr:<descriptor>|<name>=<value> | attr:<descriptor>|<name> (present) | attr:<descriptor>|!<name> (absent)
+ *   flashed:<descriptor>|class=<cls>|attr=<name>|animation [|withinMs=<n>] — a match GAINED the
+ *                                        class / attribute / an animation after the last user input
+ * where <descriptor> is `k=v` pairs joined by `;` over testId/role/name/label/text/css
+ * (`css=h1`, `label=Display name`, `role=button;name=Save`) — key=value always wins, so a `=` is
+ * never read as CSS or text. With no `=` at all, a descriptor starting with `[`, `#` or `.` is CSS
+ * verbatim (`[data-testid=x]` becomes `testId=x`); any OTHER bare descriptor is read as CSS too, but
+ * only when it is a lowercase-only, syntactically valid CSS selector (#213: `h1`, `main h1`, `body`,
+ * `div.card`, `ul > li` — tag names, combinators, classes, ids, attributes, pseudo-classes; every
+ * character lowercase is what tells a real selector apart from an accessible-name phrase like
+ * `Display name`, which is never guessed at as either CSS or text). Anything that is not a valid
+ * key=value spec and not a lowercase CSS selector is refused with a hint naming the key=value forms
+ * (`css=`, `label=`, `testId=`, `role=`, `text=`) and an example. In `textIncludes` / `valueEquals`
+ * the LAST `|` separates the descriptor from the text.
+ */
+export function parseAssertionSpec(spec) {
+    const ci = spec.indexOf(":");
+    if (ci === -1)
+        throw new Error(`invalid --success spec ${JSON.stringify(spec)}; expected "<kind>:<...>"`);
+    const kind = spec.slice(0, ci);
+    const rest = spec.slice(ci + 1);
+    switch (kind) {
+        case "urlIncludes": {
+            if (rest === "")
+                throw new Error("urlIncludes requires a text (urlIncludes:/path)");
+            return { kind: "urlIncludes", text: rest };
+        }
+        case "visible":
+            return { kind: "visible", target: parseDescriptorSpec(rest) };
+        case "textIncludes": {
+            const bar = rest.lastIndexOf("|");
+            if (bar === -1)
+                throw new Error('textIncludes requires "<descriptor>|<text>"');
+            return { kind: "textIncludes", target: parseDescriptorSpec(rest.slice(0, bar)), text: rest.slice(bar + 1) };
+        }
+        case "valueEquals": {
+            const bar = rest.lastIndexOf("|");
+            if (bar === -1)
+                throw new Error('valueEquals requires "<descriptor>|<value>"');
+            return { kind: "valueEquals", target: parseDescriptorSpec(rest.slice(0, bar)), value: rest.slice(bar + 1) };
+        }
+        case "count": {
+            const bar = rest.indexOf("|");
+            const descPart = bar === -1 ? rest : rest.slice(0, bar);
+            const bounds = bar === -1 ? "" : rest.slice(bar + 1);
+            const target = parseDescriptorSpec(descPart);
+            const out = { kind: "count", target };
+            for (const pair of bounds.split(",")) {
+                const [k, v] = pair.split("=");
+                if (k === "min" && v)
+                    out.min = Number(v);
+                if (k === "max" && v)
+                    out.max = Number(v);
+            }
+            return out;
+        }
+        case "style":
+        case "styleMatches":
+        case "inViewport":
+        case "box":
+        case "overlaps":
+        case "noOverlap":
+        case "attr":
+        case "flashed":
+            return parseVisualSpec(kind, rest);
+        default:
+            throw new Error(`unsupported assertion kind ${JSON.stringify(kind)}`);
+    }
+}
+/** A finite number from a spec, or a precise error. */
+function specNumber(kind, key, v) {
+    const n = v === undefined || v.trim() === "" ? Number.NaN : Number(v);
+    if (!Number.isFinite(n))
+        throw new Error(`${kind}: ${key} must be a number, got ${JSON.stringify(v ?? "")}`);
+    return n;
+}
+/** `<descriptor>|<rest>` split at the FIRST `|`; `rest` required unless `optional`. */
+function splitDescriptor(kind, spec, shape, optional = false) {
+    const bar = spec.indexOf("|");
+    if (bar === -1 && !optional)
+        throw new Error(`${kind} requires "${shape}"`);
+    return [parseDescriptorSpec(bar === -1 ? spec : spec.slice(0, bar)), bar === -1 ? "" : spec.slice(bar + 1)];
+}
+/**
+ * The visual-state assertion specs (#148) — see `parseAssertionSpec`. Validated through the
+ * recording `AssertionSchema` (the allowlisted properties, a closed set of ops/channels), so a typo
+ * fails here, before any browser work.
+ */
+/** `<prop><op><value>` / `<channel>(<prop>)<op><value>` — ops from the shared `COMPARE_OPS` (longest first). */
+const STYLE_CHECK_RE = new RegExp(String.raw `^\s*(?:([a-z]+)\(\s*([a-z-]+)\s*\)|([a-z-]+))\s*(${COMPARE_OPS.join("|")})\s*(.*)$`);
+function parseVisualSpec(kind, rest) {
+    let out;
+    switch (kind) {
+        case "style":
+        case "styleMatches": {
+            // The descriptor ends at the LAST `|` (a style value never contains one).
+            const bar = rest.lastIndexOf("|");
+            if (bar === -1)
+                throw new Error(`${kind} requires "<descriptor>|<prop><op><value>", e.g. ${kind}:[data-heat]|alpha(background-color)>0`);
+            const target = parseDescriptorSpec(rest.slice(0, bar));
+            const m = STYLE_CHECK_RE.exec(rest.slice(bar + 1));
+            if (m === null)
+                throw new Error(`${kind}: expected <prop><op><value> (op = != > >= < <=), got ${JSON.stringify(rest.slice(bar + 1))}`);
+            const channel = m[1];
+            const property = m[2] ?? m[3] ?? "";
+            if (channel !== undefined && !STYLE_CHANNELS.includes(channel)) {
+                throw new Error(`${kind}: unknown channel ${JSON.stringify(channel)} (one of ${STYLE_CHANNELS.join(", ")})`);
+            }
+            if (!STYLE_PROPERTIES.includes(property)) {
+                throw new Error(`${kind}: property ${JSON.stringify(property)} is not allowlisted (one of ${STYLE_PROPERTIES.join(", ")})`);
+            }
+            out = {
+                kind: "style",
+                target,
+                property: property,
+                ...(channel === undefined ? {} : { channel: channel }),
+                op: m[4],
+                value: (m[5] ?? "").trim(),
+            };
+            break;
+        }
+        case "inViewport": {
+            const [target, opts] = splitDescriptor(kind, rest, "<descriptor>[|min=<ratio>]", true);
+            out = { kind: "inViewport", target };
+            for (const pair of opts.split(",").filter((p) => p !== "")) {
+                const [k, v] = pair.split("=");
+                if (k !== "min")
+                    throw new Error(`inViewport: unknown option ${JSON.stringify(k)} (only min=<ratio>)`);
+                out = { ...out, min: specNumber(kind, "min", v) };
+            }
+            break;
+        }
+        case "box": {
+            const [target, opts] = splitDescriptor(kind, rest, "<descriptor>|minWidth=<n>,maxWidth=<n>,minHeight=<n>,maxHeight=<n>");
+            const bounds = {};
+            for (const pair of opts.split(",").filter((p) => p !== "")) {
+                const [k, v] = pair.split("=");
+                if (k !== "minWidth" && k !== "maxWidth" && k !== "minHeight" && k !== "maxHeight") {
+                    throw new Error(`box: unknown bound ${JSON.stringify(k)} (minWidth, maxWidth, minHeight, maxHeight)`);
+                }
+                bounds[k] = specNumber(kind, k, v);
+            }
+            if (Object.keys(bounds).length === 0)
+                throw new Error("box needs at least one bound");
+            out = { kind: "box", target, ...bounds };
+            break;
+        }
+        case "overlaps":
+        case "noOverlap": {
+            const [target, other] = splitDescriptor(kind, rest, "<descriptor>|<descriptor2>");
+            out = { kind: "overlap", target, other: parseDescriptorSpec(other), overlapping: kind === "overlaps" };
+            break;
+        }
+        case "attr": {
+            const [target, spec] = splitDescriptor(kind, rest, "<descriptor>|<name>[=<value>] or <descriptor>|!<name>");
+            if (spec.startsWith("!"))
+                out = { kind: "attr", target, name: spec.slice(1), absent: true };
+            else {
+                const eq = spec.indexOf("=");
+                out = eq === -1 ? { kind: "attr", target, name: spec } : { kind: "attr", target, name: spec.slice(0, eq), value: spec.slice(eq + 1) };
+            }
+            break;
+        }
+        case "flashed": {
+            const [target, opts] = splitDescriptor(kind, rest, "<descriptor>|class=<cls> (or attr=<name>, animation)[|withinMs=<n>]");
+            let f = { kind: "flashed", target };
+            for (const part of opts.split("|").filter((p) => p !== "")) {
+                const eq = part.indexOf("=");
+                const k = eq === -1 ? part : part.slice(0, eq);
+                const v = eq === -1 ? "" : part.slice(eq + 1);
+                if (k === "class")
+                    f = { ...f, className: v };
+                else if (k === "attr")
+                    f = { ...f, attr: v };
+                else if (k === "animation" && eq === -1)
+                    f = { ...f, animation: true };
+                else if (k === "withinMs")
+                    f = { ...f, withinMs: specNumber(kind, "withinMs", v) };
+                else
+                    throw new Error(`flashed: unknown option ${JSON.stringify(part)} (class=<cls>, attr=<name>, animation, withinMs=<n>)`);
+            }
+            out = f;
+            break;
+        }
+        default:
+            throw new Error(`unsupported assertion kind ${JSON.stringify(kind)}`);
+    }
+    const parsed = AssertionSchema.safeParse(out);
+    if (!parsed.success) {
+        throw new Error(`invalid ${kind} spec: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+const HTTP_METHOD = /^(?:[A-Za-z]+|\*)$/;
+/**
+ * `<METHOD> <path-glob>` — the request half of a network check. Two distinct
+ * failure modes get two distinct messages: a missing/malformed method (or no
+ * space at all) doesn't match the shape at all, while a present-but-unrooted
+ * path glob is the far more common mistake (issue #83) and deserves to say
+ * exactly what's wrong instead of re-printing the whole shape as if nothing
+ * was recognized.
+ */
+function parseRequestSpec(kind, text) {
+    const sp = text.indexOf(" ");
+    const method = sp === -1 ? "" : text.slice(0, sp);
+    const pathGlob = sp === -1 ? "" : text.slice(sp + 1).trim();
+    if (!HTTP_METHOD.test(method) || pathGlob.length === 0) {
+        throw new Error(`${kind} requires "<METHOD> <path-glob>", e.g. ${kind}:PUT /api/profile/*`);
+    }
+    if (!pathGlob.startsWith("/")) {
+        throw new Error(`${kind}: path glob must start with "/" (got ${JSON.stringify(pathGlob)})`);
+    }
+    return { method: method.toUpperCase(), pathGlob };
+}
+function parseStatusSpec(text) {
+    if (/^[1-5]xx$/i.test(text))
+        return { class: Number(text[0]) };
+    if (/^[1-5]\d\d$/.test(text))
+        return { code: Number(text) };
+    throw new Error(`responseStatus expects 2xx, 4xx … or a status code, got ${JSON.stringify(text)}`);
+}
+/**
+ * The goal mission's `--success` spec parser (repeatable: every check must hold). Besides every
+ * page assertion `parseAssertionSpec` reads:
+ *   reloadThen:<assertion>                     — reload the page, then check (persistence)
+ *   requestMade:<METHOD> <path-glob>           — the run issued this request
+ *   responseStatus:<METHOD> <path-glob>=<2xx|4xx|code> — and it got this status
+ * `<path-glob>` uses the route-glob syntax (`*` within a segment, `**` across segments) against
+ * the request's path; `*` as METHOD matches any method.
+ */
+export function parseSuccessSpec(spec) {
+    const ci = spec.indexOf(":");
+    const kind = ci === -1 ? spec : spec.slice(0, ci);
+    const rest = ci === -1 ? "" : spec.slice(ci + 1);
+    switch (kind) {
+        case "reloadThen":
+            if (rest.startsWith("reloadThen:"))
+                throw new Error("reloadThen cannot be nested");
+            return { kind: "reloadThen", assertion: parseAssertionSpec(rest) };
+        case "requestMade":
+            return { kind: "requestMade", ...parseRequestSpec(kind, rest) };
+        case "responseStatus": {
+            const eq = rest.lastIndexOf("=");
+            if (eq === -1)
+                throw new Error('responseStatus requires "<METHOD> <path-glob>=<2xx|4xx|code>"');
+            return { kind: "responseStatus", ...parseRequestSpec(kind, rest.slice(0, eq)), status: parseStatusSpec(rest.slice(eq + 1)) };
+        }
+        default:
+            return { kind: "page", assertion: parseAssertionSpec(spec) };
+    }
+}
+function parseDescriptorSpec(s) {
+    const raw = s.trim();
+    if (/^[[#.]/.test(raw)) {
+        // A CSS selector. The common test-id attribute form becomes a test-id descriptor (the most
+        // stable rung); anything else is used as CSS verbatim.
+        const testId = /^\[data-testid=(?:"([^"]*)"|'([^']*)'|([^\]"']*))\]$/.exec(raw);
+        const id = testId === null ? undefined : (testId[1] ?? testId[2] ?? testId[3]);
+        if (id !== undefined && id !== "")
+            return { testId: id };
+        return { css: raw };
+    }
+    const d = {};
+    const keys = ["testId", "role", "name", "label", "text", "css"];
+    for (const pair of s.split(";")) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        const k = pair.slice(0, eq);
+        const v = pair.slice(eq + 1);
+        if (keys.includes(k) && v !== "") {
+            d[k] = v;
+        }
+    }
+    if (d.testId || d.role || d.label || d.text || d.css)
+        return d;
+    // #213: no key=value pair matched — a bare, lowercase, syntactically valid CSS selector (a tag
+    // name or a combination of them) is read as CSS; anything else is refused with a hint, never a
+    // silent guess between CSS and text.
+    if (looksLikeBareCssSelector(raw))
+        return { css: raw };
+    throw new Error(`descriptor spec ${JSON.stringify(s)} has no usable selector — ${DESCRIPTOR_HINT}`);
+}
+/**
+ * The authorized-origins allowlist for a run: explicit `--allow` origins when
+ * given, otherwise the target URL's own origin (you asked to explore it). An
+ * unparseable URL yields an empty allowlist → the guard fails closed.
+ */
+export function resolveExploreAllowlist(url, allow) {
+    if (allow.length > 0)
+        return [...allow];
+    return normalizeAllowlist([url]);
+}
+/**
+ * A conservative CSS-selector grammar check for a BARE (no `=`, no leading `[`/`#`/`.`) `--success`
+ * descriptor (#213). It deliberately does not implement the full CSS grammar — its only job is to
+ * tell a genuine selector (`h1`, `main h1`, `body`, `div.card`, `ul > li`) apart from a plain
+ * accessible-name phrase (`Display name`). HTML tag names, classes, ids and pseudo-classes are
+ * conventionally lowercase; requiring the WHOLE string to be lowercase is the disambiguator — a
+ * descriptor with any uppercase letter is never read as CSS, no matter its shape.
+ */
+const CSS_IDENT = "[a-z][a-z0-9-]*";
+const CSS_ATTR = `\\[${CSS_IDENT}(?:[~^$*|]?=(?:"[^"]*"|'[^']*'|${CSS_IDENT}))?\\]`;
+const CSS_PSEUDO = `::?${CSS_IDENT}(?:\\([^()]*\\))?`;
+const CSS_QUALIFIER = `(?:\\.${CSS_IDENT}|#${CSS_IDENT}|${CSS_ATTR}|${CSS_PSEUDO})`;
+const CSS_COMPOUND = `(?:(?:\\*|${CSS_IDENT})${CSS_QUALIFIER}*|${CSS_QUALIFIER}+)`;
+const BARE_CSS_SELECTOR_RE = new RegExp(`^${CSS_COMPOUND}(?:(?:\\s*[>+~]\\s*|\\s+)${CSS_COMPOUND})*$`);
+function looksLikeBareCssSelector(raw) {
+    return raw !== "" && !/[^\x20-\x7e]/.test(raw) && !/[A-Z]/.test(raw) && BARE_CSS_SELECTOR_RE.test(raw);
+}
+const DESCRIPTOR_HINT = 'use css=<selector>, label=<text>, testId=<id>, role=<role>;name=<name>, or text=<text> (e.g. "css=h1" or "label=Display name")';
+//# sourceMappingURL=explore-specs.js.map

package/dist/explore-specs.js.map

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

package/dist/findings-filing.d.ts

@@ -0,0 +1,64 @@
+import { type FilingConfig, type FilingOutcome, type IssueDraft, type IssueFilerPort } from "@jevitate/domain";
+/**
+ * Where a run's findings go (owner ruling 3). Drafts are ALWAYS written next to the Recording
+ * (`<stem>.issues/<fingerprint>.md`); they are filed only when filing is enabled AND a destination
+ * repo is configured. jevitate stays solution-agnostic: the system-under-test repo is configured
+ * PER TARGET (by origin) in `~/.jevitate/filing.json` or per run with `--issue-repo`, never
+ * hardcoded.
+ *
+ * `~/.jevitate/filing.json`:
+ * ```json
+ * { "enabled": false,
+ *   "jevitateRepo": "matt-cochran/jevitate",
+ *   "targets": { "https://app.example.test": { "repo": "acme/app" } } }
+ * ```
+ */
+export interface FilingFileConfig {
+    readonly enabled?: boolean;
+    readonly jevitateRepo?: string;
+    readonly targets?: Readonly<Record<string, {
+        readonly repo: string;
+    }>>;
+}
+export declare class FilingConfigError extends Error {
+    readonly code: "E_FILING_CONFIG";
+}
+/** `owner/name`, or a config error — a malformed repo is never silently used. */
+export declare function assertRepo(repo: string, where: string): string;
+/** Reads `~/.jevitate/filing.json`; a missing file is "no filing config". Anything malformed fails closed. */
+export declare function loadFilingFileConfig(path?: string): FilingFileConfig;
+export interface FilingFlags {
+    /** `--file-issues`: enable filing for this run. */
+    readonly fileIssues?: boolean;
+    /** `--issue-repo`: the system-under-test repo for this run's target. */
+    readonly issueRepo?: string;
+    /** `--jevitate-repo`: override where engine findings go. */
+    readonly jevitateRepo?: string;
+}
+/** Flags win over the file; the target repo is looked up by the run's origin. */
+export declare function resolveFilingConfig(file: FilingFileConfig, flags: FilingFlags, targetOrigin: string): FilingConfig;
+/** `<dir>/<stem>.json` → `<dir>/<stem>.issues/`. */
+export declare function issuesDirFor(recordingPath: string): string;
+export interface WrittenDraft {
+    readonly fingerprint: string;
+    readonly title: string;
+    readonly attribution: IssueDraft["attribution"];
+    readonly targets: IssueDraft["targets"];
+    /** #250: kept so a draft can be filed later (after its evidence was attached). */
+    readonly labels?: readonly string[];
+    readonly path: string;
+}
+/** Writes each draft as `<fingerprint>.md` (title heading + body) next to the Recording. */
+export declare function writeIssueDrafts(recordingPath: string, drafts: readonly IssueDraft[]): WrittenDraft[];
+export interface FindingsIssues {
+    readonly drafts: WrittenDraft[];
+    readonly filing: Array<{
+        readonly fingerprint: string;
+        readonly outcomes: FilingOutcome[];
+    }>;
+}
+/**
+ * Writes every draft, then files them per the config. The filer is created ONLY when filing is
+ * enabled (so a disabled run never even looks for `gh` or a token).
+ */
+export declare function processIssueDrafts(recordingPath: string, drafts: readonly IssueDraft[], config: FilingConfig, makeFiler: () => IssueFilerPort, nowIso: string): Promise<FindingsIssues>;