@tea-agent/loop-agent 0.44.0-next.10 → 0.44.0-next.12

package/dist/workflows/dag/frontend-repair.js

@@ -1,5 +1,19 @@
 import { z } from "zod";
 import { FRONTEND_NO_VERIFICATION_MARKER_TEXT, } from "./frontend-verification-trace.js";
+import { FRONTEND_TEST_OBSERVATION_FAILURES } from "./frontend-test-execution-evidence.js";
+/**
+ * Substrings that prove a behavior-verification failure came from the
+ * verification configuration rather than the candidate's code. Kept next to the
+ * taxonomy so a new failure code is routed deliberately instead of falling
+ * through to the string-blob heuristics below.
+ */
+const FRONTEND_TEST_VERIFICATION_CONFIG_MARKERS = [
+    FRONTEND_TEST_OBSERVATION_FAILURES.bindingDrift,
+    FRONTEND_TEST_OBSERVATION_FAILURES.reportProtocol,
+    FRONTEND_TEST_OBSERVATION_FAILURES.capabilityGap,
+    "FRONTEND_TEST_OBSERVATION_INVALID",
+    "frontend test execution report unavailable",
+];
 export const frontendRepairFailureClassSchema = z.enum([
     "typecheck",
     "build",
@@ -73,6 +87,16 @@ export function classifyFrontendFailure(input) {
     if (input.failureCategory === "write-guard") {
         return "path";
     }
+    // Verification-config faults must never be mistaken for product defects.
+    // A missing/unreadable report, a stale report, an unsupported runner or a
+    // drifted command binding are all tooling/contract problems: rewriting the
+    // candidate's business code cannot fix them and burns a repair round. These
+    // are detected structurally, before any blob heuristic can see a runner name
+    // (the `unit-test` rule matches the literal word "jest") and misroute the
+    // failure to the implementation owner.
+    if (FRONTEND_TEST_VERIFICATION_CONFIG_MARKERS.some((marker) => `${input.stderr ?? ""}\n${input.stdout ?? ""}`.includes(marker))) {
+        return "contract";
+    }
     if (`${input.stderr ?? ""}\n${input.stdout ?? ""}`.includes(FRONTEND_NO_VERIFICATION_MARKER_TEXT)) {
         // Verification unavailability is a generation-time contract gap: no
         // authorized verification command exists. Bounded repair cannot fix it;

package/dist/workflows/dag/frontend-review-scopes.js

@@ -1,4 +1,5 @@
 import { parseFrontendTestExecutionReport } from "./frontend-test-execution-evidence.js";
+import { isFrontendTestReportScheme } from "./frontend-test-framework-adapters.js";
 import { readFileBoundarySafe } from "../../shared/path-safety.js";
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, realpath, lstat } from "node:fs/promises";
@@ -109,12 +110,16 @@ export async function loadFrontendReviewScopes(runDir, phase, targetBytes, works
         const reportCoverage = new Map();
         const reportedTests = [];
         for (const ref of payload.verificationTrace?.testExecutionEvidence ?? []) {
-            if (!isArtifactReference(ref) || typeof ref.reportPath !== "string" || !/^[a-f0-9]{64}$/.test(ref.reportSha256))
+            if (!isArtifactReference(ref) || typeof ref.reportPath !== "string" || !/^[a-f0-9]{64}$/.test(ref.reportSha256) || !isFrontendTestReportScheme(ref.scheme))
                 throw invalidScope("invalid test execution reference");
             const excerpt = await read(ref.path, ref.sha256);
             const data = JSON.parse(excerpt.text);
             if (data.reportSha256 !== ref.reportSha256)
                 throw invalidScope("test execution report binding mismatch");
+            // The excerpt records the protocol that produced it. A mismatch means the
+            // trace and its report disagree, so refuse rather than guess an adapter.
+            if (data.scheme !== ref.scheme)
+                throw invalidScope("test execution report protocol binding mismatch");
             const coverage = reportCoverage.get(ref.reportPath) ?? { count: 0, total: data.total };
             if (!Number.isInteger(data.total) || data.total < 1 || data.total !== coverage.total || data.offset !== coverage.count || !Array.isArray(data.tests) || !data.tests.length || data.tests.length > 24)
                 throw invalidScope("test report excerpt coverage invalid");
@@ -128,7 +133,10 @@ export async function loadFrontendReviewScopes(runDir, phase, targetBytes, works
                 const cwdPath = await realpath(path.resolve(workspaceRoot, data.cwd));
                 if (cwdPath !== rootPath && !cwdPath.startsWith(rootPath + path.sep))
                     throw invalidScope("test report cwd escaped workspace");
-                const actual = parseFrontendTestExecutionReport(JSON.parse(report.text), cwdPath, rootPath);
+                // Parse with the protocol the runner actually used. Defaulting to
+                // Vitest here failed every Playwright/Jest report at review time even
+                // though execution and trace had accepted it.
+                const actual = parseFrontendTestExecutionReport(JSON.parse(report.text), cwdPath, rootPath, ref.scheme);
                 const expected = actual.slice(data.offset, data.offset + 24).map(test => ({ file: test.file, status: test.status, title: test.title.slice(0, 500), ...(test.title.length > 500 ? { titleTruncated: true } : {}) }));
                 if (data.total !== actual.length || !expected.length || sha256OfCanonicalJson(expected) !== sha256OfCanonicalJson(data.tests))
                     throw invalidScope("test report excerpt differs from actual runner report");

package/dist/workflows/dag/frontend-test-execution-evidence.js

@@ -3,14 +3,32 @@ import { createHash } from "node:crypto";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { readFile, realpath } from "node:fs/promises";
 import { z } from "zod";
+import { FRONTEND_TEST_ADAPTERS, detectUnadaptedRunner, frontendTestReportSchemeSchema, resolveFrontendTestAdapter, resolveRunnerArgv, } from "./frontend-test-framework-adapters.js";
+/** Scheme → adapter lookup, built once from the adapter registry. */
+const FRONTEND_TEST_ADAPTERS_BY_SCHEME = Object.fromEntries(FRONTEND_TEST_ADAPTERS.map((adapter) => [adapter.scheme, adapter]));
+/**
+ * Failure taxonomy for behavior verification. Kept separate from the writer's
+ * `failureCategory` so a broken report protocol never reads as broken product
+ * code and trigger a pointless implementation rewrite.
+ */
+export const FRONTEND_TEST_OBSERVATION_FAILURES = {
+    /** The frozen command drift from what the contract bound. */
+    bindingDrift: "FRONTEND_TEST_BINDING_DRIFT",
+    /** The runner produced no readable report, or the report was stale. */
+    reportProtocol: "FRONTEND_TEST_REPORT_PROTOCOL",
+    /** The runner itself is not adapted (Cypress, `node --test`, …). */
+    capabilityGap: "FRONTEND_TEST_CAPABILITY_GAP",
+};
 export const frontendTestObservationSchema = z.object({
-    scheme: z.literal("vitest-json-v1"),
+    scheme: frontendTestReportSchemeSchema,
     commandId: z.string().optional(),
     status: z.enum(["supported", "deferred", "unsupported"]),
     commandSha256: z.string().regex(/^[a-f0-9]{64}$/),
     cwd: z.string(),
     packageScript: z.object({ file: z.string(), name: z.string(), sha256: z.string().nullable() }).optional(),
     reason: z.string().optional(),
+    /** Set when `status: "unsupported"` because no adapter exists yet. */
+    capabilityGap: z.string().optional(),
 }).strict();
 const hash = (text) => createHash("sha256").update(text).digest("hex");
 const quote = (text) => `'${text.replace(/'/g, `'"'"'`)}'`;
@@ -124,20 +142,68 @@ function literalCommand(command, cwd, depth = 0) {
     }
     return { argv, cwd, append: suffix => command.trimEnd() + suffix };
 }
-function directVitest(argv) {
-    const args = [...argv];
-    if (["npx"].includes(args[0] ?? ""))
-        args.shift();
-    else if (["pnpm", "yarn"].includes(args[0] ?? "") && args[1] === "exec")
-        args.splice(0, 2);
-    return args[0] === "vitest" && args[1] === "run";
-}
 function hasReporter(argv) { return argv.some(arg => /^--(?:reporter|outputFile)(?:[.=]|$)/.test(arg)); }
-/** Shared read-only capability resolver, used at generation, admission and
- * immediately before execution. It never executes or rewrites an npm script. */
+/** Locate the `npm|pnpm|yarn` script invocation in a literal argv. */
+function scriptInvocation(argv) {
+    const manager = argv[0];
+    if (manager !== "npm" && manager !== "pnpm" && manager !== "yarn")
+        return undefined;
+    // `exec`/`dlx`/`create` run a binary rather than a package script, so they
+    // are not script invocations — `yarn exec vitest run` must resolve as a
+    // direct runner command, not as a script literally named "exec".
+    const subcommands = new Set(["exec", "dlx", "create", "init", "add", "install", "why", "config"]);
+    // npm test | npm run <name> | pnpm test | pnpm run <name> | yarn <name>
+    let name;
+    let rest = [];
+    if (argv[1] === "test") {
+        name = "test";
+        rest = argv.slice(2);
+    }
+    else if (argv[1] === "run") {
+        name = argv[2];
+        rest = argv.slice(3);
+    }
+    else if (manager === "yarn" && argv[1] && !argv[1].startsWith("-") && !subcommands.has(argv[1])) {
+        name = argv[1];
+        rest = argv.slice(2);
+    }
+    if (!name || !/^[\w:-]+$/.test(name))
+        return undefined;
+    if (rest.length && rest[0] !== "--")
+        throw Error("package manager script arguments require --");
+    return { name, rest };
+}
+/**
+ * Build the report invocation for an adapter.
+ *
+ * When the adapter names a `reportPathEnv`, the path travels in the environment
+ * and the suffix only selects the reporter — appending the path to the command
+ * would hand it to the runner as a positional argument (Playwright treats a
+ * stray argument as a test-name filter and then finds no tests at all).
+ *
+ * Otherwise the path is joined to the suffix: a suffix ending in `=` (Vitest's
+ * `--outputFile=`) binds it directly, and any other suffix names a flag
+ * (`--outputFile`, `--json`) that takes the path as the next argument.
+ */
+function reportInvocation(adapter, append, suffix, reportPath) {
+    if (adapter.reportPathEnv) {
+        return {
+            command: append(suffix),
+            env: { [adapter.reportPathEnv]: reportPath },
+        };
+    }
+    const joiner = suffix.endsWith("=") ? "" : " ";
+    return { command: append(`${suffix}${joiner}${quote(reportPath)}`) };
+}
+/**
+ * Shared read-only capability resolver, used at generation, admission and
+ * immediately before execution. It never executes or rewrites an npm script.
+ */
 export async function inspectFrontendTestCommand(input) {
     const root = path.resolve(input.workspaceRoot ?? input.cwd);
     let cwd = path.resolve(input.cwd);
+    // `scheme` is unknowable until an adapter resolves; the placeholder is only
+    // ever surfaced on the unsupported path, where no report is produced.
     const base = { scheme: "vitest-json-v1", status: "unsupported", commandSha256: hash(input.command), cwd: path.relative(root, cwd).replace(/\\/g, "/") || "." };
     try {
         const parsed = literalCommand(input.command, cwd);
@@ -154,79 +220,109 @@ export async function inspectFrontendTestCommand(input) {
             throw Error("test cwd resolves outside the workspace");
         if (hasReporter(parsed.argv))
             throw Error("frozen command already owns reporter/outputFile flags");
-        let separator = "";
-        if (!directVitest(parsed.argv)) {
-            const argv = parsed.argv;
-            const name = argv[0] === "npm" ? argv[1] === "test" ? "test" : argv[1] === "run" ? argv[2] : undefined : undefined;
-            if (!name || !/^[\w:-]+$/.test(name))
-                throw Error("no supported test reporter adapter for this command");
-            const rest = argv.slice(argv[1] === "test" ? 2 : 3);
-            if (rest.length && rest[0] !== "--")
-                throw Error("npm script arguments require --");
-            const file = path.relative(root, path.join(cwd, "package.json")).replace(/\\/g, "/");
-            let manifest = {};
-            try {
-                manifest = JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    throw Error("package.json is unreadable or invalid");
-            }
-            const script = manifest?.scripts?.[name];
-            base.packageScript = { file, name, sha256: typeof script === "string" ? hash(JSON.stringify({ script, pre: manifest.scripts?.[`pre${name}`] ?? null, post: manifest.scripts?.[`post${name}`] ?? null })) : null };
-            if (script === undefined) {
-                const authorized = input.allowedPaths?.some(pattern => pathMatchesPattern(file, pattern)) && !input.forbiddenPaths?.some(pattern => pathMatchesPattern(file, pattern));
-                if (!authorized)
-                    throw Error(`missing npm script ${name}; ${file} is not an authorized delivery`);
-                return { observation: { ...base, status: "deferred", reason: `Awaiting authorized ${file} script ${name} with vitest-json-v1 capability` }, effectiveCwd: cwd };
-            }
-            if (typeof script !== "string")
-                throw Error("npm script must be a string");
-            const scriptWords = words(script);
-            if (scriptWords.some(word => word.operator) || !directVitest(scriptWords.map(w => w.value)) || hasReporter(scriptWords.map(w => w.value)))
-                throw Error("npm script has no supported Vitest JSON reporter capability");
-            separator = rest.length ? "" : " --";
+        const runner = resolveRunnerArgv(parsed.argv);
+        const invocation = scriptInvocation(parsed.argv);
+        if (!invocation) {
+            const adapter = resolveFrontendTestAdapter({ argv: parsed.argv, runner });
+            if (!adapter)
+                throw capabilityGapError(runner);
+            const suffix = adapter.reportSuffix({ argv: parsed.argv, runner });
+            if (suffix === undefined)
+                throw Error(`${adapter.runner} project configuration owns report output; declare an explicit regression command instead of overriding it`);
+            return { observation: { ...base, scheme: adapter.scheme, status: "supported" }, effectiveCwd: cwd,
+                withReporter: reportPath => reportInvocation(adapter, inner => parsed.append(` ${inner}`), suffix, reportPath) };
+        }
+        const file = path.relative(root, path.join(cwd, "package.json")).replace(/\\/g, "/");
+        let manifest = {};
+        try {
+            manifest = JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
         }
-        return { observation: { ...base, status: "supported" }, effectiveCwd: cwd,
-            withReporter: reportPath => parsed.append(`${separator} --reporter=json --outputFile=${quote(reportPath)}`) };
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw Error("package.json is unreadable or invalid");
+        }
+        const script = manifest?.scripts?.[invocation.name];
+        base.packageScript = { file, name: invocation.name, sha256: typeof script === "string" ? hash(JSON.stringify({ script, pre: manifest.scripts?.[`pre${invocation.name}`] ?? null, post: manifest.scripts?.[`post${invocation.name}`] ?? null })) : null };
+        if (script === undefined) {
+            const authorized = input.allowedPaths?.some(pattern => pathMatchesPattern(file, pattern)) && !input.forbiddenPaths?.some(pattern => pathMatchesPattern(file, pattern));
+            if (!authorized)
+                throw Error(`missing npm script ${invocation.name}; ${file} is not an authorized delivery`);
+            return { observation: { ...base, status: "deferred", reason: `Awaiting authorized ${file} script ${invocation.name} with a supported test report capability` }, effectiveCwd: cwd };
+        }
+        if (typeof script !== "string")
+            throw Error("npm script must be a string");
+        const scriptWords = words(script);
+        if (scriptWords.some(word => word.operator))
+            throw Error("npm script must be a single literal command");
+        const scriptArgv = scriptWords.map(w => w.value);
+        if (hasReporter(scriptArgv))
+            throw Error("npm script already owns reporter/outputFile flags");
+        const scriptRunner = resolveRunnerArgv(scriptArgv);
+        const adapter = resolveFrontendTestAdapter({ argv: parsed.argv, runner: scriptRunner, scriptName: invocation.name, scriptArgv });
+        if (!adapter)
+            throw capabilityGapError(scriptRunner);
+        const suffix = adapter.reportSuffix({ argv: scriptArgv, runner: scriptRunner });
+        if (suffix === undefined)
+            throw Error(`${adapter.runner} project configuration owns report output; declare an explicit regression command instead of overriding it`);
+        // `npm test -- --json` forwards the flags to the script; a bare script
+        // uses the same `--` separator so npm never eats the report flags.
+        // Space-prefixed because `append` concatenates onto the trimmed
+        // command; a bare script needs `--` so npm forwards the report flags.
+        const separator = invocation.rest.length ? "" : " -- ";
+        return { observation: { ...base, scheme: adapter.scheme, status: "supported" }, effectiveCwd: cwd,
+            withReporter: reportPath => reportInvocation(adapter, inner => parsed.append(invocation.rest.length ? ` ${inner}` : `${separator}${inner}`), suffix, reportPath) };
     }
     catch (error) {
-        return { observation: { ...base, status: "unsupported", reason: error instanceof Error ? error.message : String(error) }, effectiveCwd: cwd };
+        const gap = error.capabilityGap;
+        return { observation: { ...base, status: "unsupported", reason: error instanceof Error ? error.message : String(error), ...(gap ? { capabilityGap: gap } : {}) }, effectiveCwd: cwd };
     }
 }
+/**
+ * An unadapted runner is a capability gap in this tool, not a user mistake: the
+ * message must never suggest switching frameworks.
+ */
+function capabilityGapError(runner) {
+    const known = detectUnadaptedRunner(runner);
+    const binary = known ?? (runner[0] ?? "unknown");
+    const error = new Error(`${FRONTEND_TEST_OBSERVATION_FAILURES.capabilityGap}: no test report adapter for ${binary}; ` +
+        `frontend behavior verification currently adapts vitest, jest and playwright test, ` +
+        `so this command cannot produce execution evidence`);
+    error.capabilityGap = binary;
+    return error;
+}
 export function compareFrontendTestObservation(frozen, observed, phase, writeSet = []) {
     if (frozen.status === "unsupported")
         return frozen.reason ?? "unsupported test observation scheme";
     if (observed.status === "unsupported")
         return observed.reason ?? "unsupported test observation scheme";
-    if (frozen.scheme !== observed.scheme || frozen.commandSha256 !== observed.commandSha256 || frozen.cwd !== observed.cwd || frozen.packageScript?.file !== observed.packageScript?.file || frozen.packageScript?.name !== observed.packageScript?.name)
-        return "frozen test command/cwd/script binding changed";
+    // A `deferred` observation has no resolved adapter, so its `scheme` is the
+    // placeholder rather than a binding. Comparing it would reject every new
+    // Jest/Playwright project the moment the writer adds the very script the
+    // contract asked for. The scheme only becomes a binding once the frozen
+    // observation is `supported`; script identity is still checked below.
+    const schemeBound = frozen.status !== "deferred";
+    if ((schemeBound && frozen.scheme !== observed.scheme) || frozen.commandSha256 !== observed.commandSha256 || frozen.cwd !== observed.cwd || frozen.packageScript?.file !== observed.packageScript?.file || frozen.packageScript?.name !== observed.packageScript?.name)
+        return `${FRONTEND_TEST_OBSERVATION_FAILURES.bindingDrift}: frozen test command/cwd/script binding changed`;
     if (frozen.status === "supported" && (observed.status !== "supported" || frozen.packageScript?.sha256 !== observed.packageScript?.sha256))
-        return "frozen npm test script changed";
+        return `${FRONTEND_TEST_OBSERVATION_FAILURES.bindingDrift}: frozen npm test script changed`;
     if (frozen.status === "deferred" && phase === "admission" && (!frozen.packageScript || !writeSet.includes(frozen.packageScript.file)))
         return "future test script is outside the admitted concrete writeSet";
     if (phase === "execution" && observed.status !== "supported")
         return "future test reporter capability is still unavailable";
     return undefined;
 }
-/** Observe supported frozen Vitest commands without changing their selection. */
+/** Observe supported frozen commands without changing their selection. */
 export async function withFrontendTestReporter(input) {
-    return (await inspectFrontendTestCommand(input)).withReporter?.(input.reportPath);
+    return (await inspectFrontendTestCommand(input)).withReporter?.(input.reportPath)?.command;
 }
-const resultSchema = z.object({
-    testResults: z.array(z.object({
-        name: z.string().min(1),
-        assertionResults: z.array(z.object({
-            title: z.string(), fullName: z.string().optional(),
-            ancestorTitles: z.array(z.string()).optional(), status: z.string(),
-        })),
-    })),
-});
-/** Resolve runner paths against its cwd, then use the contract workspace coordinates. */
-export function parseFrontendTestExecutionReport(raw, cwd, workspaceRoot = cwd) {
-    return resultSchema.parse(raw).testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
-        file: path.relative(workspaceRoot, path.resolve(cwd, suite.name)).replace(/\\/g, "/"),
-        title: test.fullName ?? [...(test.ancestorTitles ?? []), test.title].join(" "),
-        status: test.status,
-    })));
+/**
+ * Parse a runner report into uniform execution records using the adapter for
+ * `scheme`. A malformed report throws; callers classify that as a report
+ * protocol failure, never as a product defect.
+ */
+export function parseFrontendTestExecutionReport(raw, cwd, workspaceRoot = cwd, scheme = "vitest-json-v1") {
+    const adapter = FRONTEND_TEST_ADAPTERS_BY_SCHEME[scheme];
+    if (!adapter)
+        throw Error(`no test report adapter for scheme ${scheme}`);
+    return adapter.parse(raw, cwd, workspaceRoot);
 }