harnery 0.36.0 → 0.37.0

package/dist/lib/browser/qa-run-contracts.js

@@ -0,0 +1,226 @@
+// Contracts for the qa-run matrix runner: one JSON job in, one JSON result
+// out, with the coverage-merge and verdict rules as pure functions.
+//
+// The runner executes a whole page-QA matrix (planner, deterministic gates,
+// interactions, critique, snapshot) in one process so the driving agent stops
+// paying a model turn per browser command. These contracts are frozen first so
+// the orchestrator, its tests, and downstream consumers build against the same
+// shape.
+//
+// Two rules are load-bearing and enforced here, not in prose:
+//   - A job may WIDEN coverage beyond the planner's manifest but can never
+//     narrow it below the manifest (mergeCoverage is a union that keeps
+//     manifest order first).
+//   - A job must not carry credentials. Authentication is referenced through
+//     existing browser profiles and cookie stores; validation refuses
+//     secret-shaped fields before any browser or model work starts.
+//
+// Toolkit tier: this module must not import src/core (layering check).
+export const QA_RUN_JOB_SCHEMA_VERSION = 1;
+export const QA_RUN_RESULT_SCHEMA_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Job validation
+// ---------------------------------------------------------------------------
+/** Field names that indicate an embedded credential. Matched on any object
+ * key anywhere in the job, case-insensitively. */
+const SECRET_KEY_PATTERN = /(password|passwd|secret|token|api[-_]?key|authorization|cookie|credential|bearer)/i;
+/** Value shapes that indicate an embedded credential even under an innocent
+ * key: explicit auth headers and long unbroken high-entropy-looking blobs. */
+const SECRET_VALUE_PATTERNS = [/\bBearer\s+[\w.~+/=-]{16,}/i, /\bBasic\s+[A-Za-z0-9+/=]{16,}/];
+function scanForSecrets(value, path, errors) {
+    if (typeof value === "string") {
+        for (const pattern of SECRET_VALUE_PATTERNS) {
+            if (pattern.test(value)) {
+                errors.push(`${path}: value looks like a credential — reference a browser profile or cookie store instead`);
+                return;
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => {
+            scanForSecrets(item, `${path}[${i}]`, errors);
+        });
+        return;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            if (SECRET_KEY_PATTERN.test(key)) {
+                errors.push(`${path}.${key}: secret-bearing field names are refused — reference a browser profile or cookie store instead`);
+                continue;
+            }
+            scanForSecrets(child, `${path}.${key}`, errors);
+        }
+    }
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+ * Validate an untrusted job document. Structural errors and secret-bearing
+ * fields are all reported at once so a caller can fix the job in one pass.
+ * Validation is deliberately strict: an underspecified job fails here, before
+ * any browser or model process starts.
+ */
+export function validateQaRunJob(value) {
+    const errors = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { ok: false, errors: ["job must be a JSON object"] };
+    }
+    const job = value;
+    if (job.schema_version !== QA_RUN_JOB_SCHEMA_VERSION) {
+        errors.push(`schema_version must be ${QA_RUN_JOB_SCHEMA_VERSION}`);
+    }
+    if (typeof job.target !== "string" || job.target.length === 0) {
+        errors.push("target is required (URL, file path, or route)");
+    }
+    if (job.mode !== "signoff" && job.mode !== "review") {
+        errors.push('mode must be "signoff" or "review"');
+    }
+    const ids = new Set();
+    if (job.contexts !== undefined) {
+        if (!Array.isArray(job.contexts)) {
+            errors.push("contexts must be an array");
+        }
+        else {
+            job.contexts.forEach((ctx, i) => {
+                const c = ctx;
+                if (typeof c?.id !== "string" || c.id.length === 0)
+                    errors.push(`contexts[${i}].id is required`);
+                else if (ids.has(c.id))
+                    errors.push(`contexts[${i}].id duplicates "${c.id}"`);
+                else
+                    ids.add(c.id);
+                if (typeof c?.viewport !== "string" || c.viewport.length === 0) {
+                    errors.push(`contexts[${i}].viewport is required`);
+                }
+                if (c?.theme !== "light" && c?.theme !== "dark") {
+                    errors.push(`contexts[${i}].theme must be "light" or "dark"`);
+                }
+                if (typeof c?.state !== "string" || c.state.length === 0) {
+                    errors.push(`contexts[${i}].state is required ("default" for the plain page)`);
+                }
+                if (c?.args !== undefined && !isStringArray(c.args)) {
+                    errors.push(`contexts[${i}].args must be an argument array (never a shell string)`);
+                }
+            });
+        }
+    }
+    if (job.checks !== undefined) {
+        if (!Array.isArray(job.checks)) {
+            errors.push("checks must be an array");
+        }
+        else {
+            const checkIds = new Set();
+            job.checks.forEach((check, i) => {
+                const c = check;
+                if (typeof c?.id !== "string" || c.id.length === 0)
+                    errors.push(`checks[${i}].id is required`);
+                else if (checkIds.has(c.id))
+                    errors.push(`checks[${i}].id duplicates "${c.id}"`);
+                else
+                    checkIds.add(c.id);
+                if (!isStringArray(c?.args) || c.args.length === 0) {
+                    errors.push(`checks[${i}].args must be a non-empty argument array (never a shell string)`);
+                }
+                if (c?.contexts !== undefined && !isStringArray(c.contexts)) {
+                    errors.push(`checks[${i}].contexts must be an array of context IDs`);
+                }
+            });
+        }
+    }
+    if (job.interaction_states !== undefined) {
+        if (!Array.isArray(job.interaction_states)) {
+            errors.push("interaction_states must be an array");
+        }
+        else {
+            job.interaction_states.forEach((state, i) => {
+                const s = state;
+                if (typeof s?.name !== "string" || s.name.length === 0) {
+                    errors.push(`interaction_states[${i}].name is required`);
+                }
+                if (!isStringArray(s?.setup) || s.setup.length === 0) {
+                    errors.push(`interaction_states[${i}].setup must be a non-empty argument array`);
+                }
+                if (!isStringArray(s?.assertions) || s.assertions.length === 0) {
+                    errors.push(`interaction_states[${i}].assertions must name at least one outcome assertion — a click without a proven outcome is not a gate`);
+                }
+            });
+        }
+    }
+    if (job.policy !== undefined) {
+        const p = job.policy;
+        if (p?.command_concurrency !== undefined) {
+            const n = p.command_concurrency;
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 8) {
+                errors.push("policy.command_concurrency must be an integer between 1 and 8");
+            }
+        }
+        if (p?.command_timeout_ms !== undefined) {
+            const n = p.command_timeout_ms;
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 1000) {
+                errors.push("policy.command_timeout_ms must be an integer ≥ 1000");
+            }
+        }
+    }
+    scanForSecrets(job, "job", errors);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, job: value };
+}
+// ---------------------------------------------------------------------------
+// Coverage merge — widen-only
+// ---------------------------------------------------------------------------
+export function contextIdFor(context) {
+    return `${context.viewport}-${context.theme}-${context.state}`;
+}
+/**
+ * Merge planner-manifest coverage with the job's extra contexts. The manifest
+ * is the floor: its contexts always run, in manifest order, and a job can only
+ * append. The union construction makes narrowing impossible by design; the
+ * returned list is what the runner executes and what the result reports.
+ */
+export function mergeCoverage(manifest, job) {
+    const merged = manifest.contexts.map((context) => ({
+        id: contextIdFor(context),
+        viewport: context.viewport,
+        theme: context.theme,
+        state: context.state,
+    }));
+    const seen = new Set(merged.map((context) => context.id));
+    for (const context of job.contexts ?? []) {
+        const canonical = contextIdFor(context);
+        if (seen.has(canonical) || seen.has(context.id))
+            continue;
+        seen.add(canonical);
+        seen.add(context.id);
+        merged.push(context);
+    }
+    return merged;
+}
+// ---------------------------------------------------------------------------
+// Verdict — fail-closed
+// ---------------------------------------------------------------------------
+/**
+ * Compute the terminal verdict from completed evidence. The rules are the
+ * existing page-QA signoff contract, fail-closed:
+ *   - any blocker → incomplete (a blocker is a fact the run could not
+ *     establish, so a defect cannot be ruled out);
+ *   - any failed or unknown command/critique outcome → failed when the check
+ *     completed and found a defect, incomplete when the outcome is unknown;
+ *   - signoff mode additionally requires the snapshot to have been saved.
+ * `passed` is only reachable when every input proves out.
+ */
+export function computeVerdict(input) {
+    const failed = input.commands.some((command) => command.outcome === "failed") ||
+        input.critique.some((entry) => entry.outcome === "failed");
+    if (failed)
+        return "failed";
+    const unknown = input.commands.some((command) => command.outcome === "unknown") ||
+        input.critique.some((entry) => entry.outcome === "unknown");
+    if (input.blockers.length > 0 || unknown)
+        return "incomplete";
+    if (input.mode === "signoff" && !input.snapshotSaved)
+        return "incomplete";
+    return "passed";
+}

package/dist/lib/browser/qa-run.d.ts

@@ -0,0 +1,51 @@
+import { type QaRunJob, type QaRunResult } from "./qa-run-contracts.js";
+/** Set on critique children unless the job permits metered critique: the
+ * host's critique provider must stay on subscription-backed headless
+ * harnesses and surface exhaustion instead of falling back to a metered API. */
+export declare const QA_RUN_HEADLESS_ONLY_ENV = "HARNERY_CRITIQUE_HEADLESS_ONLY";
+/** Result document written into the run's output directory. */
+export declare const QA_RUN_RESULT_FILENAME = "page-qa-result.json";
+export interface QaRunExecOptions {
+    /** Hard per-command timeout in milliseconds. */
+    timeoutMs: number;
+    /** Complete child environment (already layered by the runner). */
+    env: NodeJS.ProcessEnv;
+}
+export interface QaRunExecResult {
+    /** Process exit code; null when the command never completed normally. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** Spawn failure / timeout / signal description. Presence means the
+     * command's outcome cannot be trusted. */
+    error?: string;
+}
+/** Injectable child-process executor. `argv[0]` is the executable. */
+export type QaRunExec = (argv: string[], options: QaRunExecOptions) => Promise<QaRunExecResult>;
+/** Default executor: execFile with argv arrays only (never a shell string),
+ * closed stdin, bounded output buffers, and the policy timeout. */
+export declare const defaultQaRunExec: QaRunExec;
+export interface QaRunMatrixOptions {
+    /** A validated job (see validateQaRunJob — the runner trusts its shape). */
+    job: QaRunJob;
+    /** Directory for artifacts and the result document. Created if missing. */
+    outDir: string;
+    /** argv prefix that reaches the host CLI's browse command, e.g.
+     * `[process.execPath, cliScript, "browse"]`. */
+    browseArgv: string[];
+    /** Injectable executor (tests). Default: execFile via defaultQaRunExec. */
+    exec?: QaRunExec;
+    /** Extra child-environment overrides layered over process.env. */
+    childEnv?: NodeJS.ProcessEnv;
+    /** Progress callback for human-facing per-stage lines. */
+    onLog?: (message: string) => void;
+}
+/**
+ * Execute the whole QA matrix for one validated job and return the result
+ * (also written to `<outDir>/page-qa-result.json`). Stages: plan →
+ * deterministic gates (bounded pool) → interactions (serial) → critique (one
+ * context at a time; the critique provider owns tile concurrency) → snapshot.
+ * The verdict is computeVerdict over everything recorded — fail-closed.
+ */
+export declare function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunResult>;
+//# sourceMappingURL=qa-run.d.ts.map

package/dist/lib/browser/qa-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qa-run.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-run.ts"],"names":[],"mappings":"AAiBA,OAAO,EAQL,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAE/B;;gFAEgF;AAChF,eAAO,MAAM,wBAAwB,mCAAmC,CAAC;AAEzE,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAiB5D,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf;8CAC0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEhG;mEACmE;AACnE,eAAO,MAAM,gBAAgB,EAAE,SAyC3B,CAAC;AAEL,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,GAAG,EAAE,QAAQ,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf;oDACgD;IAChD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC7B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AA2JD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0enF"}