@tea-agent/loop-agent 0.26.0 → 0.26.2

package/dist/task/source-prepare/prepare.js

@@ -0,0 +1,506 @@
+import { randomUUID } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { ContractMutationError, applyTaskContract, logicalRevisionForState, observeTaskContractState, projectConstraintsMarkdown, projectRequirementMarkdown, sha256OfCanonicalJson, validateDraftForTask, } from "../contract/index.js";
+import { getTaskContractPaths } from "../contract/paths.js";
+import { loadTaskConfig } from "../runtime.js";
+import { buildPrepareDraft } from "./build-draft.js";
+import { hasBlockingGaps, hasBlockingRisks, isFreshLegacyUnversioned, listPrepareGaps, } from "./completeness.js";
+import { extractRequirementFactsFromMarkdown, fillMissingRequirementFacts, mergeRequirementFacts, } from "./parse-intent.js";
+import { draftReferencesFromManifest, validateImportedPrdReferences, } from "./reference-integrity.js";
+import { readSourceManifest } from "../source-references.js";
+import { PREPARE_MAX_FILE_BYTES } from "./types.js";
+async function fileNonEmpty(filePath) {
+    try {
+        const stats = await lstat(filePath);
+        return stats.isFile() && stats.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadExistingTaskConfig(repoRoot, taskId) {
+    try {
+        return await loadTaskConfig(repoRoot, taskId);
+    }
+    catch {
+        return null;
+    }
+}
+function mutationOutcome(code) {
+    switch (code) {
+        case "REVISION_CONFLICT":
+        case "OBSERVED_HASH_CONFLICT":
+        case "REQUEST_ID_REUSE_CONFLICT":
+        case "LEASE_HELD":
+            return "conflict";
+        case "NOT_FOUND":
+            return "not-found";
+        case "TRANSACTION_INCOMPLETE":
+        case "OPERATION_NEEDS_RECONCILE":
+            return "needs-reconcile";
+        case "EXTERNALLY_MODIFIED":
+        case "NOT_MANAGED":
+        case "BINDING_DRIFT":
+            return "blocked";
+        case "INVALID_INPUT":
+        case "PATH_OUTSIDE_REPO":
+        case "UNSUPPORTED_SCHEMA_VERSION":
+            return "invalid";
+        default:
+            return "rejected";
+    }
+}
+function buildNextSteps(input) {
+    const next = [];
+    if (!input.hasImportedPrd) {
+        next.push(`loop-agent import-prd ${input.taskId} --file <prd.md> --role requirement`);
+    }
+    if (input.gaps.some((g) => g.code === "EMPTY_ALLOWED_PATHS")) {
+        next.push("补 --allowed-path <glob>");
+    }
+    if (input.gaps.some((g) => g.code === "EMPTY_ACCEPTANCE")) {
+        next.push("补 --ac <id:text> 或完善 PRD 验收标准章节");
+    }
+    if (input.mode === "dry-run" && input.ok) {
+        next.push(`loop-agent task source prepare ${input.taskId} --use-imported-prd ... --apply --json`);
+    }
+    if (input.ok && input.mode === "apply") {
+        next.push(`loop-agent task contract show ${input.taskId} --json`);
+        next.push(`loop-agent dag run-task ${input.taskId} --profile auto --strict-models`);
+        next.push("审查 DAG writeSet 后再 run-dag");
+    }
+    if (input.gaps.some((g) => g.code === "DIRTY_SOURCE")) {
+        next.push("loop-agent task contract show|diff|adopt|recover");
+        next.push("或显式 --force-overwrite-source 后重跑 prepare");
+    }
+    if (input.gaps.some((g) => g.code === "TRANSACTION_INCOMPLETE")) {
+        next.push(`loop-agent task contract recover --task ${input.taskId}`);
+    }
+    return next;
+}
+function emptyObservedHashPlaceholder() {
+    return "0".repeat(64);
+}
+/**
+ * Core prepare orchestration: facts → thin Draft → gates → optional apply.
+ * No LLM. Production md writes only via applyTaskContract projection.
+ */
+export async function prepareTaskSource(input) {
+    const { repoRoot, taskId } = input;
+    const contractPaths = getTaskContractPaths(repoRoot, taskId);
+    const state = await observeTaskContractState(repoRoot, taskId);
+    if (state.observationErrors.some((e) => e.code === "NOT_FOUND")) {
+        return {
+            ok: false,
+            outcome: "not-found",
+            mode: input.mode,
+            taskId,
+            gaps: [
+                {
+                    code: "TASK_NOT_FOUND",
+                    level: "blocking",
+                    message: `task not found: ${taskId}`,
+                },
+            ],
+            risks: [],
+            next: [`loop-agent new-task ${taskId} "<title>"`],
+            error: {
+                code: "NOT_FOUND",
+                message: `task not found: ${taskId}`,
+            },
+        };
+    }
+    const existingTaskConfig = await loadExistingTaskConfig(repoRoot, taskId);
+    const sourceFilesPresent = {
+        requirement: await fileNonEmpty(contractPaths.requirementPath),
+        constraints: await fileNonEmpty(contractPaths.constraintsPath),
+    };
+    // Contract may record referenceManifestSha256 while observe only reports
+    // EXTERNALLY_MODIFIED after the manifest file disappears (hash already drifts).
+    // That is a non-fresh observation condition force must not bypass.
+    if (state.ref?.sourceHashes.referenceManifestSha256) {
+        const manifest = await readSourceManifest(contractPaths.sourceDir);
+        if (!manifest) {
+            state.observationErrors = [
+                ...state.observationErrors,
+                {
+                    code: "MANIFEST_MISSING",
+                    path: contractPaths.sourceManifestPath,
+                    message: "contract records referenceManifestSha256 but source-manifest.json is missing",
+                },
+            ];
+        }
+    }
+    let baseDraft;
+    let facts;
+    let sourceIntegrity = null;
+    let hasImportedPrd = false;
+    let references;
+    if (input.intent.kind === "draft") {
+        baseDraft = input.intent.draft;
+        if (baseDraft.taskId !== taskId) {
+            return {
+                ok: false,
+                outcome: "invalid",
+                mode: input.mode,
+                taskId,
+                gaps: [
+                    {
+                        code: "DRAFT_TASK_ID_MISMATCH",
+                        level: "blocking",
+                        message: `draft.taskId "${baseDraft.taskId}" does not match ${taskId}`,
+                    },
+                ],
+                risks: [],
+                next: [],
+                error: {
+                    code: "INVALID_INPUT",
+                    message: `draft.taskId "${baseDraft.taskId}" does not match ${taskId}`,
+                },
+            };
+        }
+        // Still verify any references in draft against manifest when present.
+        if (baseDraft.references?.length) {
+            sourceIntegrity = await validateImportedPrdReferences({
+                repoRoot,
+                taskId,
+                requireParseableRequirement: false,
+            });
+            hasImportedPrd = sourceIntegrity.documents.length > 0;
+            const allowedRefs = new Set(sourceIntegrity.documents.map((document) => document.materializedPath));
+            for (const ref of baseDraft.references) {
+                const normalizedRef = ref.ref.replace(/\\/g, "/");
+                if (!allowedRefs.has(normalizedRef)) {
+                    sourceIntegrity.issues.push({
+                        code: "REFERENCE_NOT_IN_MANIFEST",
+                        level: "blocking",
+                        message: `draft reference not found in source-manifest: ${ref.ref}`,
+                        path: ref.ref,
+                    });
+                    sourceIntegrity.ok = false;
+                }
+            }
+        }
+    }
+    else {
+        const importedFactParts = [];
+        let supplementalFacts;
+        if (input.intent.useImportedPrd) {
+            sourceIntegrity = await validateImportedPrdReferences({
+                repoRoot,
+                taskId,
+                requireParseableRequirement: false,
+            });
+            hasImportedPrd = true;
+            if (sourceIntegrity.ok) {
+                references = draftReferencesFromManifest(sourceIntegrity.documents);
+                let acStart = 1;
+                for (const doc of sourceIntegrity.parseableDocuments) {
+                    if (!doc.content)
+                        continue;
+                    const extracted = extractRequirementFactsFromMarkdown(doc.content, {
+                        sourceLabel: doc.materializedPath,
+                        acCounterStart: acStart,
+                    });
+                    acStart += extracted.acceptanceCriteria.filter((ac) => /^AC-\d+$/i.test(ac.id)).length;
+                    // Better: count all auto ids; keep simple sequential across docs.
+                    const maxAuto = extracted.acceptanceCriteria.reduce((max, ac) => {
+                        const m = /^AC-(\d+)$/i.exec(ac.id);
+                        if (!m)
+                            return max;
+                        return Math.max(max, Number(m[1]));
+                    }, acStart - 1);
+                    acStart = maxAuto + 1;
+                    importedFactParts.push(extracted);
+                }
+            }
+        }
+        if (input.intent.text) {
+            if (Buffer.byteLength(input.intent.text, "utf-8") > PREPARE_MAX_FILE_BYTES) {
+                return {
+                    ok: false,
+                    outcome: "invalid",
+                    mode: input.mode,
+                    taskId,
+                    gaps: [
+                        {
+                            code: "INPUT_TOO_LARGE",
+                            level: "blocking",
+                            message: `text input exceeds ${PREPARE_MAX_FILE_BYTES} bytes`,
+                        },
+                    ],
+                    risks: [],
+                    next: [],
+                    error: {
+                        code: "INPUT_TOO_LARGE",
+                        message: `text input exceeds ${PREPARE_MAX_FILE_BYTES} bytes`,
+                    },
+                };
+            }
+            supplementalFacts = extractRequirementFactsFromMarkdown(input.intent.text, {
+                sourceLabel: input.intent.textLabel ?? "supplemental-text",
+            });
+        }
+        const importedFacts = importedFactParts.length > 0
+            ? mergeRequirementFacts(importedFactParts)
+            : undefined;
+        const mergedSupplemental = supplementalFacts
+            ? mergeRequirementFacts([supplementalFacts])
+            : undefined;
+        if (importedFacts && mergedSupplemental) {
+            facts = fillMissingRequirementFacts(importedFacts, mergedSupplemental);
+        }
+        else {
+            facts = importedFacts ?? mergedSupplemental;
+        }
+    }
+    const built = buildPrepareDraft({
+        taskId,
+        existingTaskConfig,
+        baseDraft,
+        facts,
+        flags: input.flags,
+        references,
+    });
+    const { gaps, risks } = listPrepareGaps({
+        draft: built.draft,
+        state,
+        sourceIntegrity,
+        pathAssessment: built.pathAssessment,
+        hasImportedPrd,
+        acceptanceConflicts: built.acceptanceConflicts,
+        sourceFilesPresent,
+        forceOverwriteSource: input.forceOverwriteSource,
+    });
+    // If --use-imported-prd and no parseable requirement and no AC from flags/text → blocking
+    if (input.intent.kind === "facts" &&
+        input.intent.useImportedPrd &&
+        sourceIntegrity &&
+        !sourceIntegrity.parseableDocuments.some((d) => d.role === "requirement") &&
+        built.draft.requirement.acceptanceCriteria.length === 0 &&
+        !input.flags.acceptanceCriteria?.length &&
+        !input.intent.text) {
+        gaps.push({
+            code: "NO_PARSEABLE_REQUIREMENT",
+            level: "blocking",
+            message: "no parseable requirement document and no --ac / supplemental text; import a requirement-role PRD or pass flags",
+        });
+    }
+    const validation = await validateDraftForTask({
+        repoRoot,
+        taskId,
+        draft: built.draft,
+    });
+    if (!validation.ok) {
+        for (const message of validation.errors) {
+            gaps.push({
+                code: "DRAFT_VALIDATION",
+                level: "blocking",
+                message,
+            });
+        }
+    }
+    const requirementPreview = projectRequirementMarkdown(built.draft);
+    const constraintsPreview = projectConstraintsMarkdown(built.draft);
+    const projected = {
+        requirementPath: "source/需求.md",
+        constraintsPath: "source/执行约束.md",
+        requirementPreview,
+        constraintsPreview,
+    };
+    const blocking = hasBlockingGaps(gaps) ||
+        hasBlockingRisks(risks) ||
+        !validation.ok;
+    const warnings = gaps
+        .filter((g) => g.level === "warning")
+        .map((g) => ({ code: g.code, message: g.message }));
+    const next = buildNextSteps({
+        taskId,
+        hasImportedPrd,
+        mode: input.mode,
+        ok: !blocking,
+        gaps,
+    });
+    if (input.mode !== "apply") {
+        return {
+            ok: !blocking,
+            outcome: blocking ? "invalid" : "succeeded",
+            mode: "dry-run",
+            taskId,
+            taskKind: built.draft.taskKind,
+            title: built.draft.title,
+            draft: built.draft,
+            gaps,
+            risks,
+            projected,
+            next,
+            contractStatus: state.effectiveStatus,
+            warnings,
+            ...(blocking
+                ? {
+                    error: {
+                        code: "INVALID_INPUT",
+                        message: "task source draft has blocking gaps",
+                        details: {
+                            gaps: gaps
+                                .filter((g) => g.level === "blocking")
+                                .map((g) => g.code),
+                        },
+                    },
+                }
+                : {}),
+        };
+    }
+    // apply path — prioritize state-machine outcomes over generic invalid gates
+    if (state.effectiveStatus === "transaction-incomplete" ||
+        gaps.some((g) => g.code === "TRANSACTION_INCOMPLETE")) {
+        return {
+            ok: false,
+            outcome: "needs-reconcile",
+            mode: "apply",
+            taskId,
+            taskKind: built.draft.taskKind,
+            title: built.draft.title,
+            draft: built.draft,
+            gaps,
+            risks,
+            projected,
+            next: [`loop-agent task contract recover --task ${taskId}`],
+            contractStatus: state.effectiveStatus,
+            warnings,
+            error: {
+                code: "TRANSACTION_INCOMPLETE",
+                message: "unfinished transaction; run task contract recover first",
+            },
+        };
+    }
+    if (blocking) {
+        const blockingCodes = gaps
+            .filter((g) => g.level === "blocking")
+            .map((g) => g.code);
+        const outcome = blockingCodes.includes("DIRTY_SOURCE")
+            ? "blocked"
+            : "invalid";
+        return {
+            ok: false,
+            outcome,
+            mode: "apply",
+            taskId,
+            taskKind: built.draft.taskKind,
+            title: built.draft.title,
+            draft: built.draft,
+            gaps,
+            risks,
+            projected,
+            next,
+            contractStatus: state.effectiveStatus,
+            warnings,
+            error: {
+                code: outcome === "blocked" ? "DIRTY_SOURCE" : "INVALID_INPUT",
+                message: "task source draft has blocking gaps",
+                details: {
+                    gaps: blockingCodes,
+                },
+            },
+        };
+    }
+    const expectedRevision = logicalRevisionForState(state);
+    const expectedObservedHash = state.observedCanonicalHash ??
+        (expectedRevision === 0 ? emptyObservedHashPlaceholder() : null);
+    if (!expectedObservedHash) {
+        return {
+            ok: false,
+            outcome: "conflict",
+            mode: "apply",
+            taskId,
+            draft: built.draft,
+            gaps,
+            risks,
+            projected,
+            next: [`loop-agent task contract doctor --task ${taskId}`],
+            error: {
+                code: "OBSERVED_HASH_CONFLICT",
+                message: "unable to determine expectedObservedHash",
+            },
+        };
+    }
+    // Dirty without force already blocked above. Fresh legacy is allowed.
+    void isFreshLegacyUnversioned;
+    const requestId = input.requestId?.trim() || `prepare-${taskId}-${randomUUID()}`;
+    const requestPayloadSha256 = sha256OfCanonicalJson(built.draft);
+    try {
+        const applyResult = await applyTaskContract({
+            repoRoot,
+            taskId,
+            draft: built.draft,
+            expectedRevision,
+            expectedObservedHash,
+            requestId,
+            requestPayloadSha256,
+            payloadSha256Trusted: true,
+        });
+        return {
+            ok: true,
+            outcome: "succeeded",
+            mode: "apply",
+            taskId,
+            taskKind: built.draft.taskKind,
+            title: built.draft.title,
+            draft: built.draft,
+            gaps,
+            risks,
+            projected,
+            apply: applyResult,
+            next: buildNextSteps({
+                taskId,
+                hasImportedPrd,
+                mode: "apply",
+                ok: true,
+                gaps,
+            }),
+            contractStatus: "managed",
+            warnings,
+        };
+    }
+    catch (error) {
+        if (error instanceof ContractMutationError) {
+            const outcome = mutationOutcome(error.code);
+            return {
+                ok: false,
+                outcome,
+                mode: "apply",
+                taskId,
+                taskKind: built.draft.taskKind,
+                title: built.draft.title,
+                draft: built.draft,
+                gaps,
+                risks,
+                projected,
+                next: [
+                    `loop-agent task contract show ${taskId} --json`,
+                    `loop-agent task contract doctor --task ${taskId}`,
+                ],
+                error: {
+                    code: error.code,
+                    message: error.message,
+                    details: error.details,
+                },
+            };
+        }
+        return {
+            ok: false,
+            outcome: "rejected",
+            mode: "apply",
+            taskId,
+            draft: built.draft,
+            gaps,
+            risks,
+            projected,
+            next: [],
+            error: {
+                code: "INTERNAL_ERROR",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}