@tea-agent/loop-agent 0.13.0-beta.0 → 0.14.0

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
+const id = z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/);
+const safePath = z
+    .string()
+    .min(1)
+    .refine((value) => !value.startsWith("/") &&
+    !value.includes("\\") &&
+    !value.split("/").includes(".."), "must be a relative POSIX path without traversal");
+const gap = z
+    .object({
+    requirementId: id.optional(),
+    description: z.string().min(1),
+    blocking: z.boolean(),
+})
+    .strict();
+export const frontendImplementationContractSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    sourceBinding: z
+        .object({
+        taskId: z.string().min(1),
+        requirementPath: safePath,
+        requirementSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        referencePaths: z.array(safePath),
+        requirementIds: z.array(id),
+    })
+        .strict(),
+    riskLevel: z.enum(["small", "standard", "high-risk"]),
+    targets: z
+        .object({
+        files: z.array(safePath).min(1),
+        routes: z.array(z.string().startsWith("/")).optional(),
+        publicApiChanges: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
+    requirements: z.array(z
+        .object({
+        id,
+        implementationTargets: z.array(safePath),
+        verificationTargetIds: z.array(z.string().min(1)),
+        evidenceGap: gap.optional(),
+    })
+        .strict()),
+    uiStates: z.array(z
+        .object({
+        name: z.string().min(1),
+        applicable: z.boolean(),
+        expectedBehavior: z.string().min(1).optional(),
+        implementationTargets: z.array(safePath).optional(),
+        verificationTargetIds: z.array(z.string().min(1)).optional(),
+        notApplicableReason: z.string().min(1).optional(),
+    })
+        .strict()),
+    interactions: z.array(z
+        .object({
+        name: z.string().min(1),
+        implementationTargets: z.array(safePath),
+        verificationTargetIds: z.array(z.string().min(1)),
+    })
+        .strict()),
+    mockApi: z
+        .object({
+        strategy: z.enum([
+            "native",
+            "browser-intercept",
+            "request-adapter",
+            "not-needed",
+        ]),
+        productionDefaultOff: z.literal(true),
+        activation: z.string().min(1),
+        endpoints: z.array(z
+            .object({
+            method: z.enum([
+                "GET",
+                "POST",
+                "PUT",
+                "PATCH",
+                "DELETE",
+                "HEAD",
+                "OPTIONS",
+            ]),
+            path: z.string().startsWith("/"),
+            fixture: safePath.optional(),
+            consumer: safePath.optional(),
+        })
+            .strict()),
+    })
+        .strict(),
+    designEvidence: z
+        .object({
+        source: z.string().min(1),
+        paths: z.array(safePath),
+        conflicts: z.array(z.string().min(1)),
+    })
+        .strict(),
+    verificationTargets: z.array(z
+        .object({
+        id: z.string().min(1),
+        type: z.enum(["static", "unit", "component", "integration", "mock"]),
+        commandLabel: z.string().min(1),
+        file: safePath,
+        symbol: z.string().min(1).optional(),
+        requirementIds: z.array(id),
+        uiStates: z.array(z.string().min(1)),
+    })
+        .strict()),
+    evidenceGaps: z.array(gap),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const verificationIds = value.verificationTargets.map((target) => target.id);
+    if (new Set(verificationIds).size !== verificationIds.length)
+        ctx.addIssue({
+            code: "custom",
+            message: "duplicate verification target id",
+            path: ["verificationTargets"],
+        });
+    const known = new Set(value.sourceBinding.requirementIds);
+    for (const requirement of value.requirements) {
+        if (!known.has(requirement.id))
+            ctx.addIssue({
+                code: "custom",
+                message: "unknown requirement id",
+                path: ["requirements"],
+            });
+        if ((!requirement.implementationTargets.length ||
+            !requirement.verificationTargetIds.length) &&
+            !requirement.evidenceGap)
+            ctx.addIssue({
+                code: "custom",
+                message: "requirement needs targets or evidenceGap",
+                path: ["requirements"],
+            });
+        for (const targetId of requirement.verificationTargetIds)
+            if (!verificationIds.includes(targetId))
+                ctx.addIssue({
+                    code: "custom",
+                    message: `unknown verification target ${targetId}`,
+                    path: ["requirements"],
+                });
+    }
+    for (const state of value.uiStates) {
+        if (state.applicable &&
+            (!state.expectedBehavior ||
+                !state.implementationTargets?.length ||
+                !state.verificationTargetIds?.length))
+            ctx.addIssue({
+                code: "custom",
+                message: "applicable UI state requires behavior, implementation, and verification",
+                path: ["uiStates"],
+            });
+        if (!state.applicable && !state.notApplicableReason)
+            ctx.addIssue({
+                code: "custom",
+                message: "non-applicable UI state requires reason",
+                path: ["uiStates"],
+            });
+    }
+});
+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)/;
+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((child, index) => secretIssues(child, `${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 extractFrontendImplementationJson(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)
+        throw new Error("output must contain exactly one fenced json object");
+    return JSON.parse(blocks[0][1]);
+}
+export async function materializeFrontendImplementationContract(input) {
+    if (!input.sourceBinding)
+        throw new Error("frontend implementation contract gate requires DAG sourceBinding");
+    const record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
+    let parsed;
+    try {
+        parsed = extractFrontendImplementationJson(record.assistantText?.trim() || record.stdout?.trim() || "");
+    }
+    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 = frontendImplementationContractSchema.safeParse(parsed);
+    if (!result.success)
+        throw new Error(`invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`);
+    const requirement = input.sourceBinding.sources.find((source) => source.kind === "requirement");
+    const refs = input.sourceBinding.sources
+        .filter((source) => source.kind === "reference")
+        .map((source) => source.path)
+        .sort();
+    const bound = result.data.sourceBinding;
+    if (!requirement ||
+        bound.taskId !== input.sourceBinding.taskId ||
+        bound.requirementPath !== requirement.path ||
+        bound.requirementSha256 !== requirement.sha256 ||
+        JSON.stringify([...bound.referencePaths].sort()) !== JSON.stringify(refs) ||
+        JSON.stringify(bound.requirementIds) !==
+            JSON.stringify(input.sourceBinding.requirementIds))
+        throw new Error("frontend contract source binding does not match DAG source binding");
+    const blockingGaps = [
+        ...result.data.evidenceGaps,
+        ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
+    ].filter((item) => item.blocking);
+    if (blockingGaps.length > 0)
+        throw new Error(`frontend contract has blocking evidence gap: ${blockingGaps
+            .map((item) => item.requirementId ?? item.description)
+            .join(", ")}`);
+    for (const requirementId of bound.requirementIds)
+        if (!result.data.requirements.some((item) => item.id === requirementId) &&
+            !result.data.evidenceGaps.some((item) => item.requirementId === requirementId))
+            throw new Error(`frontend contract does not cover ${requirementId}`);
+    const artifactPath = await writeDagRunJsonArtifact(input.runDir, path.posix.join(input.outputDir, input.artifactName), result.data);
+    return {
+        path: artifactPath,
+        sha256: createHash("sha256")
+            .update(`${JSON.stringify(result.data, null, 2)}\n`)
+            .digest("hex"),
+        schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+    };
+}

package/dist/workflows/dag/frontend-project-capability.js

@@ -0,0 +1,309 @@
+/**
+ * Generation-time frontend project capability discovery (M5/M6).
+ * Strong evidence only: package.json deps, config files, source imports.
+ * Lockfile-only or directory-name-only must NOT activate adapters.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function allDeps(pkg) {
+    return {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+        ...(pkg.peerDependencies ?? {}),
+    };
+}
+function hasDep(deps, name) {
+    return Object.hasOwn(deps, name);
+}
+async function listOpenSpec(repoRoot) {
+    const root = path.join(repoRoot, "openSpec");
+    if (!(await exists(root)))
+        return [];
+    const out = [];
+    async function walk(dir, depth) {
+        if (depth > 4)
+            return;
+        let entries = [];
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const full = path.join(dir, name);
+            try {
+                const info = await stat(full);
+                if (info.isDirectory())
+                    await walk(full, depth + 1);
+                else if (/\.(md|mdx|json)$/i.test(name)) {
+                    out.push(path.relative(repoRoot, full).replace(/\\/g, "/"));
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    await walk(root, 0);
+    return out.slice(0, 40);
+}
+export function buildAdapterGuidance(capability) {
+    const lines = [
+        "## Frontend project capability (generation-time)",
+        `Framework: ${capability.framework}${capability.frameworkVersion ? `@${capability.frameworkVersion}` : ""}`,
+        `Evidence: ${capability.evidencePaths.join(", ") || "(none)"}`,
+        "Rules: openSpec/** and task sources outrank adapter tips; do not invent APIs for unknown versions; lockfile-only is not enough.",
+    ];
+    if (capability.framework === "react") {
+        lines.push("React adapter: prefer function components + hooks; reuse existing Testing Library / Vitest patterns; do not introduce new state libs without authorization.");
+    }
+    else if (capability.framework === "next") {
+        lines.push("Next.js adapter: respect App vs Pages router from evidence; keep server/client boundaries explicit; avoid guessing cache/navigation APIs across major versions.");
+    }
+    else if (capability.framework === "vue") {
+        lines.push("Vue adapter: prefer Composition API if project already uses it; reuse Pinia/Vue Router/Vue Query only when evidenced; Vitest + Vue Test Utils when present.");
+    }
+    else {
+        lines.push("Unknown framework: use generic frontend-implementation skill only; do not assume React/Vue/Next APIs.");
+    }
+    if (capability.a11y.status === "present") {
+        lines.push(`A11y tools present: ${capability.a11y.tools.join(", ")}. Report static/component-level evidence only; Browser a11y remains not-run.`);
+    }
+    else {
+        lines.push("A11y tools: absent/unknown — mark a11y checks unavailable/not-run; do not install tools.");
+    }
+    if (capability.designEvidence.normativePaths.length) {
+        lines.push(`Normative design paths: ${capability.designEvidence.normativePaths.slice(0, 8).join(", ")}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Discover frontend project capability from repo root.
+ * Strong evidence: package.json direct deps + config/bootstrap files.
+ */
+export async function discoverFrontendProjectCapability(repoRoot) {
+    const evidencePaths = [];
+    const reasons = [];
+    const pkgPath = path.join(repoRoot, "package.json");
+    const pkgRaw = await readJson(pkgPath);
+    if (!pkgRaw || typeof pkgRaw !== "object") {
+        const base = {
+            schemaVersion: 1,
+            framework: "unknown",
+            state: [],
+            dataFetching: [],
+            componentLibrary: [],
+            style: [],
+            testRunner: [],
+            mock: [],
+            a11y: { status: "unknown", tools: [], evidencePaths: [] },
+            evidencePaths: [],
+            reasons: ["package.json missing or unreadable"],
+            designEvidence: {
+                normativePaths: [],
+                advisoryPaths: [],
+                conflicts: [],
+            },
+        };
+        return { ...base, adapterGuidance: buildAdapterGuidance(base) };
+    }
+    evidencePaths.push("package.json");
+    const deps = allDeps(pkgRaw);
+    // Lockfile alone does not activate
+    for (const lock of ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"]) {
+        if (await exists(path.join(repoRoot, lock))) {
+            reasons.push(`${lock} present but not used as sole activation evidence`);
+        }
+    }
+    let framework = "unknown";
+    let frameworkVersion;
+    const configHits = [];
+    const nextConfig = ["next.config.js", "next.config.mjs", "next.config.ts"];
+    for (const name of nextConfig) {
+        if (await exists(path.join(repoRoot, name))) {
+            configHits.push(name);
+            evidencePaths.push(name);
+        }
+    }
+    if (hasDep(deps, "next") && configHits.some((c) => c.startsWith("next"))) {
+        framework = "next";
+        frameworkVersion = deps.next?.replace(/^[^\d]*/, "");
+        reasons.push("next dependency + next.config*");
+    }
+    else if (hasDep(deps, "next") && configHits.length === 0) {
+        // dep without config: still weak if only transitive — require direct dep
+        framework = "next";
+        frameworkVersion = deps.next?.replace(/^[^\d]*/, "");
+        reasons.push("next direct dependency (config not found)");
+        evidencePaths.push("package.json#dependencies.next");
+    }
+    if (framework === "unknown") {
+        const vueConfig = ["vite.config.ts", "vite.config.js", "vue.config.js"];
+        let vueCfg = false;
+        for (const name of vueConfig) {
+            if (await exists(path.join(repoRoot, name))) {
+                vueCfg = true;
+                evidencePaths.push(name);
+            }
+        }
+        if (hasDep(deps, "vue") && (vueCfg || hasDep(deps, "nuxt"))) {
+            framework = "vue";
+            frameworkVersion = deps.vue?.replace(/^[^\d]*/, "");
+            reasons.push("vue direct dependency + config/tooling");
+        }
+    }
+    if (framework === "unknown" && hasDep(deps, "react")) {
+        // Need config or jsx tooling — not lockfile-only
+        const reactCfg = (await exists(path.join(repoRoot, "vite.config.ts"))) ||
+            (await exists(path.join(repoRoot, "vite.config.js"))) ||
+            (await exists(path.join(repoRoot, "webpack.config.js"))) ||
+            hasDep(deps, "react-scripts") ||
+            hasDep(deps, "vite");
+        if (reactCfg) {
+            framework = "react";
+            frameworkVersion = deps.react?.replace(/^[^\d]*/, "");
+            reasons.push("react direct dependency + bundler/tooling evidence");
+            evidencePaths.push("package.json#dependencies.react");
+        }
+        else {
+            reasons.push("react listed but no strong config/bundler evidence — framework=unknown");
+        }
+    }
+    const state = [];
+    for (const lib of [
+        "redux",
+        "@reduxjs/toolkit",
+        "zustand",
+        "jotai",
+        "recoil",
+        "pinia",
+        "vuex",
+    ]) {
+        if (hasDep(deps, lib))
+            state.push(lib);
+    }
+    const dataFetching = [];
+    for (const lib of [
+        "@tanstack/react-query",
+        "swr",
+        "axios",
+        "@tanstack/vue-query",
+        "ofetch",
+    ]) {
+        if (hasDep(deps, lib))
+            dataFetching.push(lib);
+    }
+    const componentLibrary = [];
+    for (const lib of [
+        "antd",
+        "@mui/material",
+        "element-plus",
+        "vuetify",
+        "@chakra-ui/react",
+    ]) {
+        if (hasDep(deps, lib))
+            componentLibrary.push(lib);
+    }
+    const style = [];
+    for (const lib of [
+        "tailwindcss",
+        "sass",
+        "less",
+        "styled-components",
+        "@emotion/react",
+    ]) {
+        if (hasDep(deps, lib))
+            style.push(lib);
+    }
+    const testRunner = [];
+    for (const lib of [
+        "vitest",
+        "jest",
+        "@testing-library/react",
+        "@testing-library/vue",
+        "@playwright/test",
+    ]) {
+        if (hasDep(deps, lib))
+            testRunner.push(lib);
+    }
+    const mock = [];
+    for (const lib of ["msw", "nock", "miragejs"]) {
+        if (hasDep(deps, lib))
+            mock.push(lib);
+    }
+    const a11yTools = [];
+    const a11yEvidence = [];
+    for (const lib of [
+        "eslint-plugin-jsx-a11y",
+        "@axe-core/react",
+        "jest-axe",
+        "vitest-axe",
+        "axe-core",
+    ]) {
+        if (hasDep(deps, lib)) {
+            a11yTools.push(lib);
+            a11yEvidence.push(`package.json#${lib}`);
+        }
+    }
+    const a11y = {
+        status: (a11yTools.length > 0 ? "present" : "absent"),
+        tools: a11yTools,
+        evidencePaths: a11yEvidence,
+    };
+    let router;
+    if (hasDep(deps, "react-router-dom") || hasDep(deps, "react-router")) {
+        router = "react-router";
+    }
+    if (framework === "next")
+        router = router ?? "next-router";
+    if (hasDep(deps, "vue-router"))
+        router = "vue-router";
+    const openSpec = await listOpenSpec(repoRoot);
+    const designEvidence = {
+        normativePaths: openSpec,
+        advisoryPaths: [],
+        conflicts: [],
+    };
+    if (openSpec.length)
+        evidencePaths.push(...openSpec.slice(0, 5));
+    const base = {
+        schemaVersion: 1,
+        framework,
+        frameworkVersion,
+        router,
+        state,
+        dataFetching,
+        componentLibrary,
+        style,
+        testRunner,
+        mock,
+        a11y,
+        packageManager: (await exists(path.join(repoRoot, "pnpm-lock.yaml")))
+            ? "pnpm"
+            : (await exists(path.join(repoRoot, "yarn.lock")))
+                ? "yarn"
+                : "npm",
+        evidencePaths: [...new Set(evidencePaths)],
+        reasons,
+        designEvidence,
+    };
+    return { ...base, adapterGuidance: buildAdapterGuidance(base) };
+}