@tea-agent/loop-agent 0.8.0 → 0.10.0

package/dist/worker/delivery/git-transaction.js

@@ -0,0 +1,354 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { cp, lstat, mkdir, readFile, readlink, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import path from "node:path";
+import { z } from "zod";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { assertSafeRuntimeId } from "../follow-up/paths.js";
+const execFileAsync = promisify(execFile);
+const checkpointSchema = z.object({
+    taskId: z.string().min(1),
+    workerRunId: z.string().min(1),
+    commit: z.string().regex(/^[a-f0-9]{40}$/),
+    changedFiles: z.array(z.string()),
+    createdAt: z.string().datetime(),
+}).strict();
+const ignoredSensitiveBaselineEntrySchema = z.object({
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+}).strict();
+export const gitTransactionRecordSchema = z.object({
+    schemaVersion: z.literal(1),
+    featureId: z.string().min(1),
+    branch: z.string().min(1),
+    baseBranch: z.string().min(1),
+    baseCommit: z.string().regex(/^[a-f0-9]{40}$/),
+    lastCheckpoint: z.string().regex(/^[a-f0-9]{40}$/),
+    authorizedBy: z.literal("cli --git-mode checkpoint"),
+    startedAt: z.string().datetime(),
+    ignoredBaseline: z.array(ignoredSensitiveBaselineEntrySchema),
+    ignoredSensitiveBaseline: z.array(ignoredSensitiveBaselineEntrySchema),
+    checkpoints: z.array(checkpointSchema),
+}).strict();
+export async function startGitTransaction(input) {
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    assertSafeRuntimeId(input.featureId, "featureId");
+    const gitRoot = await git(repoRoot, ["rev-parse", "--show-toplevel"]);
+    if (await realpath(gitRoot) !== repoRoot)
+        throw new Error(`Git root does not match target repo: ${gitRoot}`);
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]);
+    const baseBranch = await git(repoRoot, ["branch", "--show-current"]);
+    if (!baseBranch)
+        throw new Error("Git checkpoint requires a named current branch");
+    await assertClean(repoRoot);
+    const branch = input.branch ?? `agent/${input.featureId.toLowerCase()}`;
+    assertSafeBranch(branch);
+    const recordPath = transactionRecordPath(repoRoot, input.featureId);
+    const existing = await readOptionalRecord(recordPath);
+    const branchExists = await gitOk(repoRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+    if (branchExists) {
+        if (!existing)
+            throw new Error(`Feature branch already exists without transaction ownership: ${branch}`);
+        if (existing.branch !== branch || existing.featureId !== input.featureId)
+            throw new Error(`Feature branch ownership mismatch: ${branch}`);
+        if (baseBranch === existing.baseBranch && head !== existing.baseCommit)
+            throw new Error(`Feature base branch moved from recorded commit: ${existing.baseCommit}`);
+        if (baseBranch === branch && head !== existing.lastCheckpoint)
+            throw new Error(`Feature branch HEAD does not match recorded checkpoint: ${head}`);
+        if (baseBranch !== existing.baseBranch && baseBranch !== branch)
+            throw new Error(`Current branch is not owned by this Feature transaction: ${baseBranch}`);
+        await git(repoRoot, ["switch", branch]);
+        const branchHead = await git(repoRoot, ["rev-parse", "HEAD"]);
+        if (branchHead !== existing.lastCheckpoint)
+            throw new Error(`Feature branch HEAD does not match recorded checkpoint: ${branchHead}`);
+        return { repoRoot, recordPath, record: existing };
+    }
+    if (existing)
+        throw new Error(`Git transaction record exists but branch is missing: ${branch}`);
+    await git(repoRoot, ["switch", "-c", branch]);
+    const ignoredBaseline = await readIgnoredBaseline(repoRoot);
+    const record = {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        branch,
+        baseBranch,
+        baseCommit: head,
+        lastCheckpoint: head,
+        authorizedBy: "cli --git-mode checkpoint",
+        startedAt: (input.now ?? new Date()).toISOString(),
+        ignoredBaseline,
+        ignoredSensitiveBaseline: ignoredBaseline.filter((entry) => isSensitivePath(entry.path)),
+        checkpoints: [],
+    };
+    try {
+        await writeJsonAtomic(recordPath, record);
+    }
+    catch (error) {
+        await git(repoRoot, ["switch", baseBranch]).catch(() => { });
+        await git(repoRoot, ["branch", "-D", branch]).catch(() => { });
+        throw error;
+    }
+    return { repoRoot, recordPath, record };
+}
+export async function finalizeGitTask(transaction, outcome) {
+    const current = gitTransactionRecordSchema.parse(JSON.parse(await readFile(transaction.recordPath, "utf-8")));
+    if (JSON.stringify(current) !== JSON.stringify(transaction.record))
+        throw new Error("Git transaction record changed outside the finalizer");
+    await assertTransactionPosition(transaction.repoRoot, current);
+    const currentIgnored = await readIgnoredBaseline(transaction.repoRoot);
+    const ignoredBaselineByPath = new Map(current.ignoredBaseline.map((entry) => [entry.path, entry.sha256]));
+    const changedBaselineIgnored = currentIgnored.filter((entry) => ignoredBaselineByPath.has(entry.path) && ignoredBaselineByPath.get(entry.path) !== entry.sha256).map((entry) => entry.path);
+    const missingBaselineIgnored = current.ignoredBaseline.filter((entry) => !currentIgnored.some((candidate) => candidate.path === entry.path)).map((entry) => entry.path);
+    if (changedBaselineIgnored.length > 0 || missingBaselineIgnored.length > 0) {
+        throw new Error(`pre-existing ignored file changed during Git transaction: ${[...changedBaselineIgnored, ...missingBaselineIgnored].join(", ")}`);
+    }
+    const existing = current.checkpoints.find((entry) => entry.workerRunId === outcome.workerRunId);
+    if (outcome.status === "reused" || existing) {
+        if (!existing)
+            throw new Error(`reused Worker run has no recorded checkpoint: ${outcome.workerRunId}`);
+        if (existing.taskId !== outcome.taskSpec.id || current.featureId !== outcome.taskSpec.feature_id)
+            throw new Error(`reused Worker run does not match current TaskSpec: ${outcome.workerRunId}`);
+        if (!await gitOk(transaction.repoRoot, ["cat-file", "-e", `${existing.commit}^{commit}`]))
+            throw new Error(`recorded checkpoint is missing from Git history: ${existing.commit}`);
+        if (!await gitOk(transaction.repoRoot, ["merge-base", "--is-ancestor", existing.commit, current.lastCheckpoint]))
+            throw new Error(`recorded checkpoint is outside the Feature transaction history: ${existing.commit}`);
+        await assertCheckpointMetadata(transaction.repoRoot, existing.commit, outcome.taskSpec, existing.workerRunId);
+        return { status: "reused", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit: existing.commit, changedFiles: existing.changedFiles };
+    }
+    const changes = await readChanges(transaction.repoRoot);
+    const newIgnored = currentIgnored.map((entry) => entry.path).filter((entry) => !ignoredBaselineByPath.has(entry));
+    if (outcome.status === "succeeded") {
+        if (changes.length === 0)
+            throw new Error(`successful task produced no checkpointable changes: ${outcome.taskSpec.id}`);
+        if (newIgnored.length > 0)
+            throw new Error(`task created ignored files outside the Git checkpoint: ${newIgnored.join(", ")}`);
+        auditChangedPaths(changes, outcome.taskSpec);
+        await git(transaction.repoRoot, ["add", "--", ...changes]);
+        const message = commitMessage(outcome.taskSpec, outcome.workerRunId);
+        await git(transaction.repoRoot, ["commit", "-m", message]);
+        const commit = await git(transaction.repoRoot, ["rev-parse", "HEAD"]);
+        const checkpoint = { taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit, changedFiles: changes, createdAt: (outcome.now ?? new Date()).toISOString() };
+        const previousCheckpoint = current.lastCheckpoint;
+        try {
+            await assertTransactionPosition(transaction.repoRoot, { ...current, lastCheckpoint: commit });
+            await assertCheckpointMetadata(transaction.repoRoot, commit, outcome.taskSpec, outcome.workerRunId);
+            const afterCommitIgnored = await readIgnoredBaseline(transaction.repoRoot);
+            assertIgnoredBaselineUnchanged(current.ignoredBaseline, afterCommitIgnored);
+        }
+        catch (error) {
+            const branch = await git(transaction.repoRoot, ["branch", "--show-current"]).catch(() => "");
+            if (branch === current.branch) {
+                await git(transaction.repoRoot, ["reset", "--hard", previousCheckpoint]).catch(() => { });
+                const afterFailureIgnored = await readIgnoredBaseline(transaction.repoRoot).catch(() => []);
+                const baselinePaths = new Set(current.ignoredBaseline.map((entry) => entry.path));
+                for (const entry of afterFailureIgnored)
+                    if (!baselinePaths.has(entry.path))
+                        await rm(path.join(transaction.repoRoot, entry.path), { recursive: true, force: true });
+            }
+            throw error;
+        }
+        current.lastCheckpoint = commit;
+        current.checkpoints.push(checkpoint);
+        try {
+            await writeJsonAtomic(transaction.recordPath, current);
+        }
+        catch (error) {
+            await git(transaction.repoRoot, ["reset", "--hard", previousCheckpoint]).catch(() => { });
+            throw error;
+        }
+        transaction.record = current;
+        await assertClean(transaction.repoRoot);
+        return { status: "checkpointed", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit, changedFiles: changes };
+    }
+    const artifactDir = path.join(path.dirname(transaction.recordPath), "failures", outcome.workerRunId);
+    await captureFailureArtifacts(transaction.repoRoot, artifactDir, changes, newIgnored, outcome);
+    if (outcome.keepFailedDiff) {
+        return { status: "kept-failed-diff", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, artifactDir, changedFiles: changes };
+    }
+    await git(transaction.repoRoot, ["reset", "--hard", current.lastCheckpoint]);
+    await git(transaction.repoRoot, ["clean", "-fd"]);
+    for (const relative of newIgnored)
+        await rm(path.join(transaction.repoRoot, relative), { recursive: true, force: true });
+    await assertClean(transaction.repoRoot);
+    return { status: "restored", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, artifactDir, changedFiles: changes };
+}
+export function transactionRecordPath(repoRoot, featureId) {
+    return path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "git", "transaction.json");
+}
+async function captureFailureArtifacts(repoRoot, artifactDir, changes, ignoredFiles, outcome) {
+    await mkdir(path.join(artifactDir, "untracked"), { recursive: true });
+    const patchText = await gitRaw(repoRoot, ["diff", "--binary", "HEAD"]);
+    await writeFile(path.join(artifactDir, "changes.patch"), patchText, "utf-8");
+    const untracked = (await gitRaw(repoRoot, ["ls-files", "--others", "--exclude-standard"])).split(/\r?\n/).filter(Boolean);
+    for (const relative of untracked) {
+        const source = path.join(repoRoot, relative);
+        const target = path.join(artifactDir, "untracked", relative);
+        if ((await stat(source)).isFile()) {
+            await mkdir(path.dirname(target), { recursive: true });
+            await cp(source, target);
+        }
+    }
+    await writeJsonAtomic(path.join(artifactDir, "failure.json"), {
+        schemaVersion: 1,
+        featureId: outcome.taskSpec.feature_id,
+        taskId: outcome.taskSpec.id,
+        workerRunId: outcome.workerRunId,
+        changedFiles: changes,
+        untrackedFiles: untracked,
+        ignoredFiles,
+        ignoredSensitiveFiles: ignoredFiles.filter(isSensitivePath),
+        writeBoundaryAudit: auditChangedPathsReport([...changes, ...ignoredFiles], outcome.taskSpec),
+        lastCheckpoint: await git(repoRoot, ["rev-parse", "HEAD"]),
+        ...(outcome.runRecordPath ? { runRecordPath: outcome.runRecordPath } : {}),
+        capturedAt: (outcome.now ?? new Date()).toISOString(),
+    });
+}
+function auditChangedPaths(changes, taskSpec) {
+    const audit = auditChangedPathsReport(changes, taskSpec);
+    if (audit.violations.length > 0)
+        throw new Error(audit.violations[0]);
+}
+function auditChangedPathsReport(changes, taskSpec) {
+    const violations = [];
+    for (const changed of changes) {
+        if (/(^|\/)(\.env(?:\.|$)|[^/]*\.(?:pem|key|p12|pfx))$/i.test(changed))
+            violations.push(`changed path may contain sensitive material: ${changed}`);
+        else if (taskSpec.constraints.forbidden_paths.some((glob) => matchesGlob(changed, glob)))
+            violations.push(`changed path is forbidden for ${taskSpec.id}: ${changed}`);
+        else if (!taskSpec.constraints.allowed_paths.some((glob) => matchesGlob(changed, glob)))
+            violations.push(`changed path is outside allowed_paths for ${taskSpec.id}: ${changed}`);
+    }
+    return { ok: violations.length === 0, violations };
+}
+function matchesGlob(filePath, glob) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const normalizedGlob = glob.replace(/\\/g, "/");
+    let pattern = "^";
+    for (let index = 0; index < normalizedGlob.length; index += 1) {
+        const char = normalizedGlob[index];
+        if (char === "*" && normalizedGlob[index + 1] === "*") {
+            pattern += ".*";
+            index += 1;
+            continue;
+        }
+        if (char === "*") {
+            pattern += "[^/]*";
+            continue;
+        }
+        pattern += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`${pattern}$`).test(normalizedPath);
+}
+function commitMessage(taskSpec, workerRunId) {
+    const type = taskSpec.type === "bugfix" || taskSpec.type === "fix-from-failure" ? "fix" : taskSpec.type.startsWith("qa-") ? "test" : "feat";
+    return `${type}(${taskSpec.id.toLowerCase()}): ${taskSpec.title}\n\nFeature: ${taskSpec.feature_id}\nTask: ${taskSpec.id}\nAcceptance: ${taskSpec.acceptance_refs.join(", ")}\nAgent-Run: ${workerRunId}\nWorker-Run: ${workerRunId}`;
+}
+function assertSafeBranch(branch) {
+    if (!/^agent\/[a-z0-9][a-z0-9._-]*$/.test(branch) || branch.includes("..") || branch.endsWith("."))
+        throw new Error(`unsafe Feature branch name: ${branch}`);
+}
+async function assertClean(repoRoot) {
+    const statusText = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (statusText.trim())
+        throw new Error(`Git worktree is not clean:\n${statusText.trim()}`);
+}
+async function assertTransactionPosition(repoRoot, record) {
+    const branch = await git(repoRoot, ["branch", "--show-current"]);
+    if (branch !== record.branch)
+        throw new Error(`current branch is outside the Feature transaction: expected ${record.branch}, got ${branch || "detached HEAD"}`);
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]);
+    if (head !== record.lastCheckpoint)
+        throw new Error(`Feature branch HEAD does not match recorded checkpoint: expected ${record.lastCheckpoint}, got ${head}`);
+}
+async function assertCheckpointMetadata(repoRoot, commit, taskSpec, workerRunId) {
+    const message = await gitRaw(repoRoot, ["show", "-s", "--format=%B", commit]);
+    for (const trailer of [`Feature: ${taskSpec.feature_id}`, `Task: ${taskSpec.id}`, `Acceptance: ${taskSpec.acceptance_refs.join(", ")}`, `Worker-Run: ${workerRunId}`]) {
+        if (!message.split(/\r?\n/).includes(trailer))
+            throw new Error(`recorded checkpoint metadata mismatch: ${trailer}`);
+    }
+}
+function assertIgnoredBaselineUnchanged(baseline, current) {
+    const baselineByPath = new Map(baseline.map((entry) => [entry.path, entry.sha256]));
+    const changed = current.filter((entry) => baselineByPath.has(entry.path) && baselineByPath.get(entry.path) !== entry.sha256).map((entry) => entry.path);
+    const missing = baseline.filter((entry) => !current.some((candidate) => candidate.path === entry.path)).map((entry) => entry.path);
+    const added = current.filter((entry) => !baselineByPath.has(entry.path)).map((entry) => entry.path);
+    if (changed.length > 0 || missing.length > 0 || added.length > 0)
+        throw new Error(`ignored files changed during Git checkpoint: ${[...changed, ...missing, ...added].join(", ")}`);
+}
+async function readChanges(repoRoot) {
+    const raw = await gitRaw(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+    const fields = raw.split("\0");
+    const changes = new Set();
+    for (let index = 0; index < fields.length; index += 1) {
+        const field = fields[index];
+        if (!field)
+            continue;
+        const status = field.slice(0, 2);
+        changes.add(field.slice(3).replace(/\\/g, "/"));
+        if (/[RC]/.test(status)) {
+            const source = fields[index + 1];
+            if (source)
+                changes.add(source.replace(/\\/g, "/"));
+            index += 1;
+        }
+    }
+    return [...changes];
+}
+async function listIgnoredFiles(repoRoot) {
+    const raw = await gitRaw(repoRoot, ["ls-files", "-z", "--others", "--ignored", "--exclude-standard"]);
+    return raw.split("\0").filter((entry) => entry && !entry.startsWith(".harness/")).sort();
+}
+async function readIgnoredBaseline(repoRoot) {
+    const paths = await listIgnoredFiles(repoRoot);
+    return Promise.all(paths.map(async (relative) => {
+        const absolute = path.join(repoRoot, relative);
+        const info = await lstat(absolute);
+        const content = info.isSymbolicLink() ? `symlink:${await readlink(absolute)}` : await readFile(absolute);
+        return { path: relative, sha256: createHash("sha256").update(content).digest("hex") };
+    }));
+}
+function isSensitivePath(relative) {
+    return /(^|\/)(\.env(?:\.|$)|[^/]*\.(?:pem|key|p12|pfx))$/i.test(relative);
+}
+async function readOptionalRecord(filePath) {
+    try {
+        return gitTransactionRecordSchema.parse(JSON.parse(await readFile(filePath, "utf-8")));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+async function writeJsonAtomic(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const temp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+        await rename(temp, filePath);
+    }
+    finally {
+        await unlink(temp).catch(() => { });
+    }
+}
+async function git(repoRoot, args) {
+    const result = await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+    return result.stdout.trim();
+}
+async function gitRaw(repoRoot, args) {
+    const result = await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+    return result.stdout;
+}
+async function gitOk(repoRoot, args) {
+    try {
+        await git(repoRoot, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNotFound(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}