@tea-agent/loop-agent 0.38.0 → 0.39.0-next.10

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

@@ -191,6 +191,42 @@ const gap = z
     blocking: z.boolean(),
 })
     .strict();
+/**
+ * Structured component/token selection contract (ADR 0016). Every user-visible
+ * UI purpose the plan touches must be declared here so the prewrite gate can
+ * deterministically cross-check that the selection comes from the frontend
+ * specification (openspec/ai_workspace component + theme specs) instead of
+ * relying on design-review's soft model judgment.
+ *
+ * - `specified`: the frontend spec mandates this component for the purpose →
+ *   `specReference` is required (path/section/line hit).
+ * - `reuse-existing`: reuse an existing repo component/convention not named by
+ *   the spec → `specReference` may be null, rationale explains the basis.
+ * - `new`: neither spec nor existing code fits → `specReference` must be null,
+ *   rationale must declare the deviation (design-review approves it).
+ *
+ * `specReference` is nullable + optional because `stripNullValuesDeep` strips
+ * null object values before validation, so a `new` choice's `specReference:
+ * null` becomes an absent field; the superRefine below treats absent and null
+ * identically.
+ */
+const uiComponentSpecReferenceSchema = z
+    .object({
+    path: safePath,
+    section: z.string(),
+    line: z.number().int().nullable().optional(),
+})
+    .strict();
+const uiComponentChoiceSchema = z
+    .object({
+    purpose: z.string().min(1),
+    component: z.string().min(1),
+    decision: z.enum(["specified", "reuse-existing", "new"]),
+    specReference: uiComponentSpecReferenceSchema.nullable().optional(),
+    rationale: z.string().min(1),
+})
+    .strict();
+const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
 /**
  * Normalize unstable model emissions before the strict schema sees them:
  * recursively drop null values (object entries and array elements). A null for
@@ -316,6 +352,12 @@ export const frontendImplementationContractSchema = z
     })
         .strict()).min(1),
     evidenceGaps: z.array(gap),
+    implementationSteps: z.array(z.string().min(1)).optional(),
+    stylingStrategy: z.string().min(1).optional(),
+    uiComponentChoices: uiComponentChoicesSchema.optional(),
+    dependencyPolicy: z.string().min(1).optional(),
+    residualRisks: z.array(z.string().min(1)).optional(),
+    realIntegrationGap: z.string().min(1).optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -391,6 +433,26 @@ export const frontendImplementationContractSchema = z
                 path: ["uiStates"],
             });
     }
+    for (const [index, choice] of (value.uiComponentChoices ?? []).entries()) {
+        if (choice.decision === "specified") {
+            if (!choice.specReference || !choice.specReference.path) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "specified component choice requires a non-empty specReference.path",
+                    path: ["uiComponentChoices", index, "specReference"],
+                });
+            }
+        }
+        else if (choice.decision === "new") {
+            if (choice.specReference) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "new component choice must not carry a specReference",
+                    path: ["uiComponentChoices", index, "specReference"],
+                });
+            }
+        }
+    }
     if (value.mockApi.strategy !== "not-needed") {
         if (value.mockApi.endpoints.length === 0) {
             ctx.addIssue({
@@ -426,6 +488,44 @@ export const frontendImplementationContractSchema = z
         });
     }
 }));
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Apply an RFC 7386 merge-patch on a target contract without mutating it.
+ * `null` removes the key; plain objects merge recursively when the target value
+ * is also a plain object; arrays and scalars replace the whole value. The
+ * result is re-validated by analyzeFrontendImplementationContract before it is
+ * ever materialized, so a patch that removes a required field still fails
+ * closed at the gate.
+ */
+export function applyFrontendImplementationContractPatch(target, patch) {
+    if (!isPlainObject(patch)) {
+        throw new Error("frontend revision patch must be a JSON object");
+    }
+    const merge = (base, delta) => {
+        if (delta === null)
+            return undefined;
+        if (!isPlainObject(delta))
+            return delta;
+        const result = isPlainObject(base)
+            ? { ...base }
+            : {};
+        for (const [key, value] of Object.entries(delta)) {
+            if (value === null) {
+                delete result[key];
+            }
+            else if (isPlainObject(value) && isPlainObject(result[key])) {
+                result[key] = merge(result[key], value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    };
+    return merge(target, patch);
+}
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -648,6 +748,18 @@ function asStringArray(value) {
         .map((item) => asString(item))
         .filter((item) => item.length > 0);
 }
+/**
+ * Pass structured component choices through the free-form compatibility
+ * branch. The strict-shape branch already spreads unknown fields, so only this
+ * explicit constructor needs to re-emit `uiComponentChoices`; a missing/empty
+ * array normalizes to undefined (absent) so the optional schema field stays
+ * compatible with legacy free-form contracts.
+ */
+function normalizeUiComponentChoices(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    return value;
+}
 function normalizeFrontendRoute(value) {
     const route = asString(value).replaceAll("\\", "/").replace(/^\/+/, "");
     if (!route || route === "." || route.split("/").includes(".."))
@@ -1331,6 +1443,12 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
         },
         verificationTargets,
         evidenceGaps,
+        implementationSteps: asStringArray(record.implementationSteps),
+        stylingStrategy: asString(record.stylingStrategy) || undefined,
+        dependencyPolicy: asString(record.dependencyPolicy) || undefined,
+        residualRisks: asStringArray(record.residualRisks),
+        realIntegrationGap: asString(record.realIntegrationGap) || undefined,
+        uiComponentChoices: normalizeUiComponentChoices(record.uiComponentChoices),
     };
 }
 /**

package/dist/workflows/dag/frontend-plan-render.js

@@ -0,0 +1,90 @@
+/**
+ * Deterministic Markdown renderer for a canonical frontend implementation
+ * contract. The prewrite gate materializes this as `contracts/frontend-plan.md`
+ * next to the contract JSON, so plan prose is never produced by the model — it
+ * is derived from the single machine contract at materialization time.
+ *
+ * The function is pure: the same contract always renders byte-identical
+ * Markdown, and absent optional fields render as placeholders without throwing.
+ */
+function bulletList(items) {
+    if (!items || items.length === 0)
+        return "";
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function requirementsCoverage(contract) {
+    const lines = contract.requirements.map((requirement) => `- ${requirement.id}: ${requirement.expectedOutcome}`);
+    return lines.length > 0 ? lines.join("\n") : "_(no requirements)_";
+}
+function uiStateHandling(contract) {
+    const lines = contract.uiStates.map((state) => {
+        if (state.applicable) {
+            return `- ${state.name}: ${state.expectedBehavior ?? ""}`;
+        }
+        return `- ${state.name}: not applicable — ${state.notApplicableReason ?? ""}`;
+    });
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function interactionNotes(contract) {
+    const lines = contract.interactions.map((interaction) => `- ${interaction.name}: ${interaction.trigger} → ${interaction.expectedBehavior}`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function verificationPlan(contract) {
+    const lines = contract.verificationTargets.map((target) => `- ${target.id}: ${target.commandLabel} (${target.file})`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function componentSelection(contract) {
+    const choices = contract.uiComponentChoices ?? [];
+    if (choices.length === 0)
+        return "_(not specified)_";
+    return choices
+        .map((choice) => {
+        const specReference = choice.specReference;
+        const refText = specReference
+            ? ` ${specReference.path}${specReference.section ? `#${specReference.section}` : ""}${specReference.line != null ? `:${specReference.line}` : ""}`
+            : "";
+        return `- ${choice.purpose} → ${choice.component} (${choice.decision})${refText ? `:${refText}` : ""} — ${choice.rationale}`;
+    })
+        .join("\n");
+}
+export function renderFrontendPlanMarkdown(contract) {
+    return [
+        "# Frontend Implementation Plan",
+        "",
+        "## Requirement Coverage",
+        requirementsCoverage(contract),
+        "",
+        "## Implementation Steps",
+        bulletList(contract.implementationSteps) || "_(not specified)_",
+        "",
+        "## Target Files",
+        bulletList(contract.targets.files) || "_(none)_",
+        "",
+        "## UI State Handling",
+        uiStateHandling(contract),
+        "",
+        "## Styling & Component Strategy",
+        contract.stylingStrategy || "_(not specified)_",
+        "",
+        "## Component Selection (spec conformance)",
+        componentSelection(contract),
+        "",
+        "## Interaction Notes",
+        interactionNotes(contract),
+        "",
+        "## Mock & API Strategy",
+        contract.mockApi.strategy,
+        "",
+        "## Dependency Policy",
+        contract.dependencyPolicy || "_(not specified)_",
+        "",
+        "## Verification Plan",
+        verificationPlan(contract),
+        "",
+        "## Real Integration Gap",
+        contract.realIntegrationGap || "_(not specified)_",
+        "",
+        "## Residual Risks",
+        bulletList(contract.residualRisks) || "_(none)_",
+    ].join("\n") + "\n";
+}