@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0

package/dist/workflows/dag/backend-test-execution-contract.js

@@ -0,0 +1,353 @@
+import { createHash } from "node:crypto";
+import { accessSync, constants, existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+import { ENV_VAR_NAME_PATTERN } from "./types.js";
+export const BACKEND_TEST_EXECUTION_SCHEMA_ID = "backend-test-execution-v1";
+export const BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT = "testcase";
+const SECRET_KEY = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential|authorization)/i;
+const SECRET_VALUE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|ghp|github_pat|xox[baprs]|AKIA)[-_A-Za-z0-9]{12,}\b)/;
+const envNameSchema = z
+    .string()
+    .regex(ENV_VAR_NAME_PATTERN, "env name must match ^[A-Z_][A-Z0-9_]*$");
+const relativePosixPathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    try {
+        normalizeRelativePosixPath(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "path must be repo-relative posix without .. or absolute form" });
+const fixtureSchema = z
+    .object({
+    name: z.string().min(1),
+    sourcePath: relativePosixPathSchema,
+    kind: z.string().min(1),
+})
+    .strict();
+const readinessSchema = z
+    .object({
+    path: relativePosixPathSchema,
+    description: z.string().min(1),
+})
+    .strict();
+const dataIsolationSchema = z
+    .object({
+    mode: z.string().min(1),
+    evidence: z.string().min(1).optional(),
+})
+    .strict();
+const managedCommandSchema = z
+    .object({
+    start: z.string().min(1).optional(),
+    stop: z.string().min(1).optional(),
+    sourceRef: z.string().min(1).optional(),
+})
+    .strict();
+const runnerSchema = z
+    .object({
+    commandParts: z.array(z.string().min(1)).optional(),
+    frozenCommandHints: z.array(z.string().min(1)).optional(),
+})
+    .strict()
+    .refine((value) => (value.commandParts?.length ?? 0) > 0 ||
+    (value.frozenCommandHints?.length ?? 0) > 0, { message: "runner requires commandParts and/or frozenCommandHints" });
+const evidenceGapSchema = z
+    .object({
+    description: z.string().min(1),
+    sourceRef: z.string().min(1).optional(),
+})
+    .strict();
+export const backendTestExecutionContractSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    framework: z.literal("pytest"),
+    runner: runnerSchema,
+    testRoot: relativePosixPathSchema,
+    workingDirectory: relativePosixPathSchema.default("."),
+    report: z
+        .object({
+        format: z.literal("junit"),
+        relativeHint: z.string().min(1),
+    })
+        .strict(),
+    targetMode: z.enum([
+        "in-process",
+        "external-running-service",
+        "managed-command",
+    ]),
+    baseUrlEnvName: envNameSchema.optional(),
+    readiness: z.array(readinessSchema).default([]),
+    existingFixtures: z.array(fixtureSchema).default([]),
+    authenticationMode: z.string().min(1),
+    requiredEnvNames: z.array(envNameSchema).default([]),
+    dataIsolation: dataIsolationSchema,
+    managedCommand: managedCommandSchema.optional(),
+    evidenceGaps: z.array(evidenceGapSchema).default([]),
+    evidenceRefs: z.array(z.string().min(1)).default([]),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.targetMode === "external-running-service" &&
+        !value.baseUrlEnvName) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "baseUrlEnvName is required when targetMode is external-running-service",
+            path: ["baseUrlEnvName"],
+        });
+    }
+    if (value.targetMode === "managed-command") {
+        if (!value.managedCommand) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "managedCommand is required when targetMode is managed-command",
+                path: ["managedCommand"],
+            });
+        }
+        else if (!value.managedCommand.sourceRef?.trim()) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "managed-command requires managedCommand.sourceRef evidence from task source; do not default-enable managed mode",
+                path: ["managedCommand", "sourceRef"],
+            });
+        }
+    }
+    if (value.baseUrlEnvName &&
+        !value.requiredEnvNames.includes(value.baseUrlEnvName)) {
+        // soft consistency: not a hard fail — preflight will still require env presence
+    }
+});
+export function normalizeRelativePosixPath(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error("path must be non-empty");
+    if (path.posix.isAbsolute(trimmed) || path.win32.isAbsolute(trimmed)) {
+        throw new Error("absolute paths are forbidden");
+    }
+    if (trimmed.includes("\\")) {
+        throw new Error("path must use posix separators");
+    }
+    const segments = trimmed.split("/").filter((part, index, arr) => {
+        if (part === "" && index > 0 && index < arr.length - 1)
+            return false;
+        return true;
+    });
+    const normalizedSegments = [];
+    for (const segment of segments) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            throw new Error("path traversal is forbidden");
+        normalizedSegments.push(segment);
+    }
+    if (normalizedSegments.length === 0)
+        return ".";
+    return normalizedSegments.join("/");
+}
+export function secretIssues(value, at = "$", issues = []) {
+    if (typeof value === "string" && SECRET_VALUE.test(value)) {
+        issues.push(`${at}: secret-like value is forbidden`);
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => secretIssues(item, `${at}[${index}]`, issues));
+    }
+    else if (value && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            if (SECRET_KEY.test(key)) {
+                issues.push(`${at}.${key}: secret-shaped field name is forbidden`);
+            }
+            secretIssues(child, `${at}.${key}`, issues);
+        }
+    }
+    return issues;
+}
+export function extractStrictJsonObject(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        return JSON.parse(trimmed);
+    }
+    const blocks = [...trimmed.matchAll(/```json\s*\n([\s\S]*?)\n```/gi)];
+    if (blocks.length !== 1 || trimmed.replace(blocks[0][0], "").trim()) {
+        throw new Error("execution contract output must be one pure JSON object or one fenced json block with no trailing text");
+    }
+    return JSON.parse(blocks[0][1]);
+}
+function normalizeContractPaths(contract) {
+    const existingFixtures = contract.existingFixtures ?? [];
+    const readiness = contract.readiness ?? [];
+    const requiredEnvNames = contract.requiredEnvNames ?? [];
+    const evidenceGaps = contract.evidenceGaps ?? [];
+    const evidenceRefs = contract.evidenceRefs ?? [];
+    return {
+        ...contract,
+        testRoot: normalizeRelativePosixPath(contract.testRoot),
+        workingDirectory: normalizeRelativePosixPath(contract.workingDirectory ?? "."),
+        existingFixtures: existingFixtures.map((fixture) => ({
+            ...fixture,
+            sourcePath: normalizeRelativePosixPath(fixture.sourcePath),
+        })),
+        readiness: readiness.map((item) => ({
+            ...item,
+            path: normalizeRelativePosixPath(item.path),
+        })),
+        requiredEnvNames,
+        evidenceGaps,
+        evidenceRefs,
+    };
+}
+export function assertBackendTestExecutionPreflight(input) {
+    const errors = [];
+    const contract = normalizeContractPaths(input.contract);
+    if (contract.framework !== "pytest") {
+        errors.push(`unsupported framework: ${String(contract.framework)}`);
+    }
+    const testRoot = contract.testRoot;
+    const workingDirectory = contract.workingDirectory;
+    if (input.expectedTestRoot) {
+        const expected = normalizeRelativePosixPath(input.expectedTestRoot);
+        if (expected !== testRoot) {
+            errors.push(`testRoot mismatch: contract=${testRoot} expectedTestRoot=${expected}`);
+        }
+    }
+    if (!input.skipFilesystemChecks) {
+        const rootAbs = path.resolve(input.cwd, testRoot);
+        const workAbs = path.resolve(input.cwd, workingDirectory);
+        if (!rootAbs.startsWith(path.resolve(input.cwd))) {
+            errors.push(`testRoot escapes working tree: ${testRoot}`);
+        }
+        if (!workAbs.startsWith(path.resolve(input.cwd))) {
+            errors.push(`workingDirectory escapes working tree: ${workingDirectory}`);
+        }
+        if (!existsSync(rootAbs)) {
+            errors.push(`testRoot does not exist: ${testRoot}`);
+        }
+        else {
+            try {
+                accessSync(rootAbs, constants.R_OK);
+            }
+            catch {
+                errors.push(`testRoot is not readable: ${testRoot}`);
+            }
+        }
+    }
+    for (const name of contract.requiredEnvNames) {
+        const value = input.env[name];
+        if (value === undefined || value === "") {
+            errors.push(`required env missing or empty: ${name}`);
+        }
+    }
+    if (contract.targetMode === "external-running-service") {
+        if (!contract.baseUrlEnvName) {
+            errors.push("external-running-service requires baseUrlEnvName before writer/execute");
+        }
+        else {
+            const value = input.env[contract.baseUrlEnvName];
+            if (value === undefined || value === "") {
+                errors.push(`external base URL env missing or empty: ${contract.baseUrlEnvName}`);
+            }
+        }
+    }
+    if (contract.targetMode === "managed-command") {
+        if (!contract.managedCommand?.sourceRef?.trim()) {
+            errors.push("managed-command is fail-closed without managedCommand.sourceRef task-source evidence");
+        }
+    }
+    if ((contract.evidenceGaps?.length ?? 0) > 0) {
+        errors.push(`execution contract has ${contract.evidenceGaps.length} evidenceGaps; fail-closed before writer/execute`);
+    }
+    if (contract.targetMode === "in-process" &&
+        (contract.existingFixtures?.length ?? 0) === 0) {
+        errors.push("in-process targetMode requires at least one existingFixtures entry (or record evidenceGaps)");
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        testRoot,
+        workingDirectory,
+    };
+}
+export async function materializeBackendTestExecutionContract(input) {
+    if (!/^[a-z0-9][a-z0-9._-]*\.json$/.test(input.artifactName) ||
+        !/^[a-z0-9][a-z0-9._-]*$/.test(input.outputDir)) {
+        throw new Error("unsafe structured artifact path");
+    }
+    const nodePath = path.join(input.runDir, `${input.fromNodeId}.json`);
+    const record = JSON.parse(await readFile(nodePath, "utf8"));
+    const raw = record.assistantText?.trim() || record.stdout?.trim() || "";
+    let parsed;
+    try {
+        parsed = extractStrictJsonObject(raw);
+    }
+    catch (error) {
+        throw new Error(`invalid-output: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const secrets = secretIssues(parsed);
+    if (secrets.length) {
+        throw new Error(`invalid-output: ${secrets.join("; ")}`);
+    }
+    const result = backendTestExecutionContractSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`invalid-output: ${result.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    const normalized = normalizeContractPaths(result.data);
+    // Incomplete discovery must not become a green gate that unblocks pytest writers.
+    if ((normalized.evidenceGaps?.length ?? 0) > 0) {
+        throw new Error(`invalid-output: evidenceGaps present (${normalized.evidenceGaps.length}); fail-closed until scout resolves gaps or records an explicit alternate contract`);
+    }
+    if (normalized.targetMode === "in-process" &&
+        (normalized.existingFixtures?.length ?? 0) === 0) {
+        throw new Error("invalid-output: in-process targetMode requires existingFixtures evidence");
+    }
+    const relativePath = path.posix.join(input.outputDir, input.artifactName);
+    const artifactPath = await writeDagRunJsonArtifact(input.runDir, relativePath, normalized);
+    const serialized = `${JSON.stringify(normalized, null, 2)}\n`;
+    return {
+        path: artifactPath,
+        sha256: createHash("sha256").update(serialized).digest("hex"),
+        schemaId: BACKEND_TEST_EXECUTION_SCHEMA_ID,
+    };
+}
+/** Shell-friendly preflight body used by execute-backend-pytest-shell. */
+export function buildBackendTestExecutionPreflightShellSnippet(options) {
+    const contractRelativePath = options?.contractRelativePath ?? "contracts/backend-test-execution.json";
+    const expectedTestRoot = options?.expectedTestRoot ?? BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT;
+    // Keep this deterministic and free of secret values. Node is available in the harness.
+    // Keep node -e and its path argument in ONE shell command (space-separated),
+    // not joined by ";" — otherwise "${CONTRACT}" becomes a separate exec attempt.
+    const nodePreflight = [
+        "node -e ",
+        `'const fs=require("fs");const path=require("path");`,
+        `const contractPath=process.argv[1];`,
+        `const contract=JSON.parse(fs.readFileSync(contractPath,"utf8"));`,
+        `const expected=${JSON.stringify(expectedTestRoot)};`,
+        `const errors=[];`,
+        `if(contract.framework!=="pytest") errors.push("framework must be pytest");`,
+        `const testRoot=String(contract.testRoot||"");`,
+        `if(!testRoot||testRoot.includes("..")||path.isAbsolute(testRoot)) errors.push("unsafe testRoot");`,
+        `if(testRoot.replace(/\\/+$/,"")!==expected.replace(/\\/+$/,"")) errors.push("testRoot mismatch vs frozen command: "+testRoot+" !== "+expected);`,
+        `const rootAbs=path.resolve(process.cwd(),testRoot);`,
+        `if(!fs.existsSync(rootAbs)) errors.push("testRoot does not exist: "+testRoot);`,
+        `if(Array.isArray(contract.evidenceGaps)&&contract.evidenceGaps.length) errors.push("evidenceGaps present: "+contract.evidenceGaps.length);`,
+        `if(contract.targetMode==="in-process"&&!(Array.isArray(contract.existingFixtures)&&contract.existingFixtures.length)) errors.push("in-process requires existingFixtures");`,
+        `for (const name of (contract.requiredEnvNames||[])) { if(!process.env[name]) errors.push("required env missing: "+name); }`,
+        `if(contract.targetMode==="external-running-service"){ const n=contract.baseUrlEnvName; if(!n||!process.env[n]) errors.push("external base URL env missing: "+String(n||"<empty>")); }`,
+        `if(contract.targetMode==="managed-command" && !(contract.managedCommand&&contract.managedCommand.sourceRef)) errors.push("managed-command requires sourceRef evidence");`,
+        `if(errors.length){ console.error(errors.join("; ")); process.exit(2);} `,
+        `console.log("backend-test preflight ok: framework=pytest testRoot="+testRoot+" targetMode="+contract.targetMode);'`,
+        ' "${CONTRACT}"',
+    ].join("");
+    return [
+        'test -n "${HARNESS_DAG_RUN_DIR:-}" || { echo "missing HARNESS_DAG_RUN_DIR for backend pytest preflight" >&2; exit 2; }',
+        `CONTRACT="\${HARNESS_DAG_RUN_DIR}/${contractRelativePath}"`,
+        'test -f "${CONTRACT}" || { echo "missing backend-test execution contract: ${CONTRACT}" >&2; exit 2; }',
+        nodePreflight,
+    ].join("; ");
+}