@samaksh/git-worker 0.0.0-stage → 0.2.0

package/dist/services/workspace/manager.js

@@ -0,0 +1,301 @@
+import { ok, err } from "../../core/types.js";
+import { workspaceError, gitError } from "../../core/errors.js";
+import { existsSync, readFileSync, unlinkSync } from "fs";
+import { mkdir, writeFile, rm, open } from "fs/promises";
+import { join, resolve, normalize } from "path";
+import { simpleGit, CheckRepoActions } from "simple-git";
+import { homedir } from "os";
+import { createHash } from "crypto";
+const GIT_WORKER_VERSION = "0.2.0";
+const LOCK_FILE = ".git-worker-lock";
+/**
+ * Extract a human-readable repository name from a remote URL or file path.
+ * e.g. "https://github.com/org/repo.git" -> "repo"
+ * e.g. "git@github.com:org/repo.git" -> "repo"
+ * e.g. "/path/to/my-repo" -> "my-repo"
+ */
+export function extractRepoName(urlOrPath, fallbackId) {
+    if (!urlOrPath)
+        return fallbackId || "unnamed-repo";
+    const clean = urlOrPath.trim().replace(/\/+$/, "").replace(/\.git$/i, "");
+    const lastSlash = Math.max(clean.lastIndexOf("/"), clean.lastIndexOf(":"), clean.lastIndexOf("\\"));
+    if (lastSlash >= 0 && lastSlash < clean.length - 1) {
+        return clean.slice(lastSlash + 1);
+    }
+    return clean || fallbackId || "unnamed-repo";
+}
+export function getWorkspaceRoot(config) {
+    // Use config.workspace.root if it looks absolute or explicitly specified
+    const root = config?.workspace?.root;
+    if (root && (root.startsWith("/") || root.startsWith("~"))) {
+        return root.replace(/^~/, homedir());
+    }
+    // Store directly in ~/.git-worker in user's home directory
+    return join(homedir(), ".git-worker");
+}
+function projectIdFromRemote(remoteUrl) {
+    return createHash("sha256").update(remoteUrl).digest("hex").slice(0, 16);
+}
+/**
+ * Verify that the given path is inside our workspace and the marker file is valid.
+ * This is the ownership guard that must run before any destructive ops.
+ */
+export function verifyOwnership(project) {
+    if (!existsSync(project.markerPath)) {
+        return err(workspaceError(`Ownership marker not found at '${project.markerPath}'. Refusing destructive operation.`));
+    }
+    try {
+        const raw = readFileSync(project.markerPath, "utf-8");
+        const marker = JSON.parse(raw);
+        if (marker.id !== project.id) {
+            return err(workspaceError(`Marker ID mismatch: expected '${project.id}', found '${marker.id}'. Refusing destructive operation.`));
+        }
+        // Path escape check: managed repo must be inside the project dir
+        const projectDir = join(project.managedRepoPath, "..");
+        const normalizedRepo = normalize(resolve(project.managedRepoPath));
+        const normalizedProject = normalize(resolve(projectDir));
+        if (!normalizedRepo.startsWith(normalizedProject)) {
+            return err(workspaceError(`Managed repo path '${normalizedRepo}' escapes project directory '${normalizedProject}'.`));
+        }
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(workspaceError(`Failed to read ownership marker: ${e.message}`));
+    }
+}
+export async function checkLocalRepo(dirPath, preferredRemote = "origin") {
+    try {
+        const resolved = resolve(dirPath);
+        const git = simpleGit(resolved);
+        let isRepo = await git.checkIsRepo().catch(() => false);
+        if (!isRepo) {
+            isRepo = await git.checkIsRepo(CheckRepoActions.BARE).catch(() => false);
+        }
+        if (!isRepo) {
+            return { isRepo: false };
+        }
+        try {
+            const remotes = await git.getRemotes(true);
+            const target = remotes.find((r) => r.name === preferredRemote) || remotes[0];
+            if (target?.refs?.fetch) {
+                return { isRepo: true, remoteUrl: target.refs.fetch, remoteName: target.name };
+            }
+        }
+        catch {
+            // no remotes
+        }
+        return { isRepo: true };
+    }
+    catch {
+        return { isRepo: false };
+    }
+}
+export async function resolveProject(sourceRepoPath, remote, config) {
+    try {
+        // Check if this looks like a remote URL (http/git/ssh)
+        const isRemoteUrl = sourceRepoPath.startsWith("http://") ||
+            sourceRepoPath.startsWith("https://") ||
+            sourceRepoPath.startsWith("git@") ||
+            sourceRepoPath.startsWith("ssh://") ||
+            sourceRepoPath.startsWith("git://");
+        const sourceLocation = isRemoteUrl ? sourceRepoPath : resolve(sourceRepoPath);
+        let remoteUrl;
+        if (isRemoteUrl) {
+            // Treat the supplied path directly as the remote URL
+            remoteUrl = sourceRepoPath;
+        }
+        else {
+            // It's a local path — verify it's a git repo and discover its remote
+            const git = simpleGit(sourceLocation);
+            let isRepo = await git.checkIsRepo().catch(() => false);
+            if (!isRepo) {
+                isRepo = await git.checkIsRepo(CheckRepoActions.BARE).catch(() => false);
+            }
+            if (!isRepo) {
+                return err(gitError(`'${sourceLocation}' is not a git repository`));
+            }
+            const targetRemoteName = remote || config.git.remote;
+            try {
+                const remotes = await git.getRemotes(true);
+                const targetRemote = remotes.find((r) => r.name === targetRemoteName) || remotes[0];
+                if (targetRemote?.refs?.fetch) {
+                    remoteUrl = targetRemote.refs.fetch;
+                }
+            }
+            catch {
+                // ignore
+            }
+            // If bare repo with no remotes: use its own path as the remote URL
+            if (!remoteUrl) {
+                const isBare = await git.checkIsRepo(CheckRepoActions.BARE).catch(() => false);
+                if (isBare) {
+                    remoteUrl = sourceLocation;
+                }
+            }
+        }
+        if (!remoteUrl && config.safety.rejectNoRemote) {
+            return err(workspaceError(`No remote found in '${sourceLocation}'. ` +
+                `Git Worker requires a remote to create a safe managed checkout. ` +
+                `Disable reject-no-remote in config to allow local-only repos (not recommended).`));
+        }
+        const id = projectIdFromRemote(remoteUrl || sourceLocation);
+        const root = getWorkspaceRoot(config);
+        const projectDir = join(root, "projects", id);
+        const managedRepoPath = join(projectDir, "repo");
+        const stagingDir = join(projectDir, "staging");
+        const stateDir = join(projectDir, "state");
+        const reportsDir = join(projectDir, "reports");
+        const markerPath = join(projectDir, ".git-worker-marker");
+        await mkdir(projectDir, { recursive: true });
+        await mkdir(managedRepoPath, { recursive: true });
+        await mkdir(stagingDir, { recursive: true });
+        await mkdir(stateDir, { recursive: true });
+        await mkdir(reportsDir, { recursive: true });
+        const markerData = {
+            id,
+            name: extractRepoName(remoteUrl || sourceLocation, id),
+            sourceRepoPath: sourceLocation,
+            remoteUrl: remoteUrl || "",
+            createdAt: new Date().toISOString(),
+            gitWorkerVersion: GIT_WORKER_VERSION,
+        };
+        await writeFile(markerPath, JSON.stringify(markerData, null, 2), "utf-8");
+        // Check if an existing managed clone is already present for this remote URL
+        let isCached = false;
+        if (existsSync(managedRepoPath)) {
+            try {
+                const git = simpleGit(managedRepoPath);
+                const isRepo = await git.checkIsRepo().catch(() => false);
+                if (isRepo) {
+                    const remotes = await git.getRemotes(true);
+                    const origin = remotes.find((r) => r.name === "origin") || remotes[0];
+                    if (origin?.refs?.fetch === remoteUrl) {
+                        isCached = true;
+                    }
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        return ok({
+            id,
+            sourceRepoPath: sourceLocation,
+            remoteUrl,
+            managedRepoPath,
+            stagingDir,
+            stateDir,
+            reportsDir,
+            markerPath,
+            isCached,
+        });
+    }
+    catch (e) {
+        return err(workspaceError(`Failed to resolve project: ${e.message}`, e));
+    }
+}
+export async function ensureManagedClone(project) {
+    try {
+        const git = simpleGit(project.managedRepoPath);
+        const isRepo = await git.checkIsRepo().catch(() => false);
+        if (isRepo) {
+            try {
+                const remotes = await git.getRemotes(true);
+                const origin = remotes.find((r) => r.name === "origin") || remotes[0];
+                if (origin?.refs?.fetch === project.remoteUrl) {
+                    return ok({ isCached: true });
+                }
+            }
+            catch {
+                // remote mismatch, re-clone below
+            }
+            // Remote URL changed — clean and re-clone
+            await rm(project.managedRepoPath, { recursive: true, force: true });
+        }
+        if (!project.remoteUrl) {
+            return err(gitError("Cannot clone: no remote URL available"));
+        }
+        // Clone into 'repo' subdirectory
+        const parentGit = simpleGit(join(project.managedRepoPath, ".."));
+        await parentGit.clone(project.remoteUrl, "repo", ["--no-local"]);
+        return ok({ isCached: false });
+    }
+    catch (e) {
+        return err(gitError(`Failed to clone managed repo: ${e.message}`, e));
+    }
+}
+export function releaseLock(project) {
+    const lockPath = join(project.managedRepoPath, "..", LOCK_FILE);
+    try {
+        if (existsSync(lockPath)) {
+            unlinkSync(lockPath);
+        }
+    }
+    catch {
+        // best effort
+    }
+}
+/**
+ * Acquire a file-based lock on the managed checkout.
+ * Returns a release function to call when done.
+ * Checks for and cleans up stale locks from terminated processes.
+ * Waits up to timeoutMs for the lock to become available.
+ */
+export async function acquireLock(project, timeoutMs) {
+    const lockPath = join(project.managedRepoPath, "..", LOCK_FILE);
+    const deadline = Date.now() + timeoutMs;
+    const pid = process.pid;
+    while (Date.now() < deadline) {
+        // Check if existing lock is stale (process no longer exists)
+        if (existsSync(lockPath)) {
+            try {
+                const raw = readFileSync(lockPath, "utf-8");
+                const data = JSON.parse(raw);
+                if (data.pid && typeof data.pid === "number") {
+                    try {
+                        process.kill(data.pid, 0); // signal 0 tests process existence
+                    }
+                    catch (err) {
+                        if (err.code === "ESRCH") {
+                            // Holding process died — remove stale lock immediately
+                            releaseLock(project);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Malformed lock — clear it
+                releaseLock(project);
+            }
+        }
+        try {
+            // O_EXCL ensures atomic create — fails if file exists
+            const fh = await open(lockPath, "wx");
+            await fh.writeFile(JSON.stringify({ pid, acquiredAt: new Date().toISOString() }));
+            await fh.close();
+            const release = () => {
+                releaseLock(project);
+            };
+            return ok(release);
+        }
+        catch (e) {
+            if (e.code !== "EEXIST") {
+                return err(workspaceError(`Failed to acquire lock: ${e.message}`));
+            }
+            // Lock held by an active process — wait and retry
+            await new Promise((r) => setTimeout(r, 200));
+        }
+    }
+    return err(workspaceError(`Could not acquire workspace lock within ${timeoutMs}ms. ` +
+        `Another git-worker process may be running. Delete '${lockPath}' to force-release.`));
+}
+export function createWorkspaceManager() {
+    return {
+        resolveProject,
+        checkLocalRepo,
+        ensureManagedClone,
+        verifyOwnership,
+        acquireLock,
+        releaseLock,
+    };
+}

package/dist/stages/apply.d.ts

@@ -0,0 +1,3 @@
+import { Stage } from "../core/pipeline.js";
+import { RunContext, AppDeps } from "../core/types.js";
+export declare const applyChangesStage: Stage<RunContext, AppDeps>;

package/dist/stages/apply.js

@@ -0,0 +1,161 @@
+import { ok, err } from "../core/types.js";
+import { workspaceError } from "../core/errors.js";
+import { clack, sectionHeader, statusLine } from "../utils/ui.js";
+import { sha256 } from "../utils/hash.js";
+import chalk from "chalk";
+export const applyChangesStage = async (context, deps) => {
+    if (!context.plans || !context.approvals || !context.project) {
+        return err(workspaceError("Prerequisites missing for apply"));
+    }
+    sectionHeader("Applying Changes");
+    const results = [];
+    const approvedPlans = context.plans.filter((p) => {
+        const approval = context.approvals.find((a) => a.branchName === p.branch.name);
+        return approval?.approved === true;
+    });
+    // Handle unapproved/error plans first
+    for (const plan of context.plans) {
+        const approval = context.approvals.find((a) => a.branchName === plan.branch.name);
+        if (approval?.approved)
+            continue; // Will be handled below
+        if (plan.status === "unchanged") {
+            results.push({ branch: plan.branch, status: "unchanged", reason: "No changes" });
+        }
+        else if (plan.status === "error") {
+            results.push({ branch: plan.branch, status: "failed", reason: plan.reason });
+        }
+        else {
+            results.push({
+                branch: plan.branch,
+                status: approval ? "rejected" : "skipped",
+                reason: approval ? "User rejected" : "Not reviewed",
+            });
+        }
+    }
+    if (approvedPlans.length === 0) {
+        statusLine("info", "No approved changes to apply");
+        return ok({ ...context, results });
+    }
+    for (const plan of approvedPlans) {
+        const s = clack.spinner();
+        s.start(`Applying ${plan.branch.name}…`);
+        try {
+            // Verify ownership before any destructive op
+            const ownerCheck = deps.services.workspace.verifyOwnership(context.project);
+            if (!ownerCheck.ok) {
+                s.stop(chalk.red(`${plan.branch.name} — ownership verification failed`));
+                results.push({ branch: plan.branch, status: "failed", reason: ownerCheck.error.message });
+                continue;
+            }
+            // ── Stale-plan guard ────────────────────────────────────────────
+            // Fetch latest SHA and verify it matches the reviewed plan
+            const currentShaResult = await deps.services.gitOps.getBranchSha(context.project.managedRepoPath, plan.branch.isRemote && plan.branch.remote
+                ? `${plan.branch.remote}/${plan.branch.name}`
+                : plan.branch.name);
+            if (!currentShaResult.ok) {
+                s.stop(chalk.red(`${plan.branch.name} — could not verify branch tip`));
+                results.push({ branch: plan.branch, status: "failed", reason: "Could not verify branch tip" });
+                // Clean up before next branch
+                await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+                await deps.services.gitOps.clean(context.project.managedRepoPath, deps.config.git.cleanMode).catch(() => { });
+                continue;
+            }
+            if (currentShaResult.value !== plan.baseCommitSha) {
+                s.stop(chalk.yellow(`${plan.branch.name} — branch advanced since review (stale plan)`));
+                results.push({
+                    branch: plan.branch,
+                    status: "failed",
+                    reason: `Branch advanced: reviewed at ${plan.baseCommitSha.slice(0, 8)}, now at ${currentShaResult.value.slice(0, 8)}. Re-run to replan.`,
+                });
+                continue;
+            }
+            // ── Clean before checkout ───────────────────────────────────────
+            await deps.services.gitOps.resetHard(context.project.managedRepoPath);
+            await deps.services.gitOps.clean(context.project.managedRepoPath, deps.config.git.cleanMode);
+            // ── Checkout branch ─────────────────────────────────────────────
+            const checkoutResult = await deps.services.gitOps.checkoutBranch(context.project.managedRepoPath, plan.branch.name);
+            if (!checkoutResult.ok) {
+                s.stop(chalk.red(`${plan.branch.name} — checkout failed`));
+                results.push({ branch: plan.branch, status: "failed", reason: checkoutResult.error.message });
+                await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+                await deps.services.gitOps.clean(context.project.managedRepoPath, deps.config.git.cleanMode).catch(() => { });
+                continue;
+            }
+            // ── Clean after checkout ─────────────────────────────────────────
+            await deps.services.gitOps.resetHard(context.project.managedRepoPath);
+            await deps.services.gitOps.clean(context.project.managedRepoPath, deps.config.git.cleanMode);
+            // ── Verify before-content hash ──────────────────────────────────
+            const currentFileResult = await deps.services.git.readFileFromBranch(context.project.managedRepoPath, plan.branch, plan.path);
+            const currentContent = currentFileResult.ok ? currentFileResult.value : "";
+            const currentHash = sha256(currentContent);
+            if (currentHash !== plan.beforeContentHash) {
+                s.stop(chalk.yellow(`${plan.branch.name} — file content changed since review`));
+                results.push({
+                    branch: plan.branch,
+                    status: "failed",
+                    reason: "File content changed since review. Re-run to replan.",
+                });
+                await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+                await deps.services.gitOps.clean(context.project.managedRepoPath, deps.config.git.cleanMode).catch(() => { });
+                continue;
+            }
+            // ── Write and stage ─────────────────────────────────────────────
+            const writeResult = await deps.services.gitOps.writeAndStage(context.project.managedRepoPath, plan.path, plan.afterContent);
+            if (!writeResult.ok) {
+                s.stop(chalk.red(`${plan.branch.name} — write failed`));
+                results.push({ branch: plan.branch, status: "failed", reason: writeResult.error.message });
+                await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+                continue;
+            }
+            // ── Verify only the intended path is staged ─────────────────────
+            const stagedResult = await deps.services.gitOps.getStagedFiles(context.project.managedRepoPath);
+            if (stagedResult.ok) {
+                const staged = stagedResult.value;
+                const unexpected = staged.filter((f) => f !== plan.path);
+                if (unexpected.length > 0) {
+                    s.stop(chalk.red(`${plan.branch.name} — unexpected staged files`));
+                    results.push({
+                        branch: plan.branch,
+                        status: "failed",
+                        reason: `Unexpected staged files: ${unexpected.join(", ")}. Aborting commit for safety.`,
+                    });
+                    await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+                    continue;
+                }
+                if (staged.length === 0) {
+                    // No-op commit — already matches
+                    s.stop(chalk.gray(`${plan.branch.name} — no staged changes (already matches)`));
+                    results.push({ branch: plan.branch, status: "unchanged", reason: "Content identical after write" });
+                    continue;
+                }
+            }
+            // ── Commit ──────────────────────────────────────────────────────
+            const commitMsg = deps.config.git.commitMessage;
+            const commitResult = await deps.services.gitOps.commit(context.project.managedRepoPath, commitMsg);
+            if (!commitResult.ok) {
+                s.stop(chalk.red(`${plan.branch.name} — commit failed`));
+                results.push({ branch: plan.branch, status: "failed", reason: commitResult.error.message });
+                await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+                continue;
+            }
+            s.stop(chalk.green(`${plan.branch.name} — committed ${commitResult.value.slice(0, 8)}`));
+            results.push({
+                branch: plan.branch,
+                status: "committed",
+                commitSha: commitResult.value,
+            });
+        }
+        catch (e) {
+            s.stop(chalk.red(`${plan.branch.name} — unexpected error`));
+            results.push({ branch: plan.branch, status: "failed", reason: e.message });
+            // Clean up managed checkout before next branch
+            await deps.services.gitOps.resetHard(context.project.managedRepoPath).catch(() => { });
+            await deps.services.gitOps.clean(context.project.managedRepoPath, deps.config.git.cleanMode).catch(() => { });
+        }
+    }
+    const committed = results.filter((r) => r.status === "committed").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+    console.log("");
+    statusLine(committed > 0 ? "ok" : "info", `Apply complete — ${committed} committed, ${failed} failed`);
+    return ok({ ...context, results });
+};

package/dist/stages/edit-template.d.ts

@@ -0,0 +1,3 @@
+import { Stage } from "../core/pipeline.js";
+import { RunContext, AppDeps } from "../core/types.js";
+export declare const editTemplateStage: Stage<RunContext, AppDeps>;

package/dist/stages/edit-template.js

@@ -0,0 +1,198 @@
+import { ok, err } from "../core/types.js";
+import { workspaceError, inputCancelledError } from "../core/errors.js";
+import { parseEnvTemplate } from "../services/template/env.js";
+import { extractTemplateVariables } from "../services/template/interpolator.js";
+import { validateTemplateSyntax } from "../services/template/validator.js";
+import { clack, sectionHeader, statusLine } from "../utils/ui.js";
+import { writeFile, readFile, mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import chalk from "chalk";
+const HEADER_SENTINEL = "Git Worker — Template Editor";
+function buildInstructionHeader(targetPath) {
+    const isEnv = targetPath === ".env" || targetPath.startsWith(".env.");
+    const isJson = targetPath.endsWith(".json");
+    // Avoid inserting comments into JSON files
+    if (isJson)
+        return "";
+    if (isEnv) {
+        return [
+            "# ─────────────────────────────────────────────────────────────────",
+            `# ${HEADER_SENTINEL}`,
+            "# Use KEY=value    → static value enforced on every branch",
+            "# Use KEY={KEY}    → dynamic: reads existing value from each branch",
+            "# Lines starting with # are comments and are preserved in the file",
+            "# ─────────────────────────────────────────────────────────────────",
+            "",
+        ].join("\n");
+    }
+    return [
+        "# ─────────────────────────────────────────────────────────────────",
+        `# ${HEADER_SENTINEL}`,
+        "# This template is the declarative SOURCE OF TRUTH for this file.",
+        "# Variables: ${VAR} or ${VAR:-default} are resolved from branch .env",
+        "# Built-ins: ${BRANCH_NAME}, ${BRANCH_SLUG}, ${REPO_NAME}, ${COMMIT_SHA}",
+        "# ─────────────────────────────────────────────────────────────────",
+        "",
+    ].join("\n");
+}
+function stripInstructionHeader(content) {
+    if (!content.includes(HEADER_SENTINEL)) {
+        return content;
+    }
+    const lines = content.split("\n");
+    let headerEnd = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(HEADER_SENTINEL)) {
+            let j = i + 1;
+            while (j < lines.length && (lines[j].startsWith("#") || lines[j].trim() === "")) {
+                j++;
+            }
+            headerEnd = j;
+            break;
+        }
+    }
+    return lines.slice(headerEnd).join("\n");
+}
+export const editTemplateStage = async (context, deps) => {
+    if (!context.template && !context.activeTemplate) {
+        return err(workspaceError("No template loaded"));
+    }
+    const targetPath = context.target?.path ?? ".env";
+    const isEnv = targetPath === ".env" || targetPath.startsWith(".env.");
+    let currentRaw = context.activeTemplate?.raw ?? context.template?.raw ?? "";
+    // In CI mode, validate syntax and proceed without interactive editor
+    if (context.input.ci) {
+        statusLine("info", "CI mode — skipping template editor");
+        const validation = validateTemplateSyntax(targetPath, currentRaw);
+        if (!validation.ok) {
+            clack.log.error(`Template syntax error: ${validation.error.message}`);
+            return validation;
+        }
+        return ok(context);
+    }
+    sectionHeader("Edit Template");
+    const tmpDir = await mkdtemp(join(tmpdir(), "git-worker-"));
+    const templateFileName = targetPath.split("/").pop() ?? "template.env";
+    const templateFile = join(tmpDir, templateFileName);
+    try {
+        while (true) {
+            const header = buildInstructionHeader(targetPath);
+            const content = header ? `${header}${currentRaw}` : currentRaw;
+            await writeFile(templateFile, content, "utf-8");
+            const editorName = context.input.editor || deps.config.editor.name;
+            statusLine("info", `Opening ${targetPath} in ${editorName} — save and close when done`);
+            console.log(chalk.gray(`  File: ${templateFile}`));
+            if (!header) {
+                console.log(chalk.gray(`  Tip: Use \${VAR} or \${VAR:-default} to resolve variables from each branch's .env`));
+            }
+            console.log("");
+            const editResult = await deps.services.editor.openForEdit(templateFile, deps.config);
+            if (!editResult.ok) {
+                clack.log.warn(editResult.error.message);
+                const proceed = await clack.confirm({
+                    message: "Editor not available. Continue with current template?",
+                    initialValue: true,
+                });
+                if (clack.isCancel(proceed) || !proceed) {
+                    return err(inputCancelledError("Template edit cancelled — editor unavailable"));
+                }
+                break;
+            }
+            // Read edited content
+            const edited = await readFile(templateFile, "utf-8");
+            const stripped = stripInstructionHeader(edited).trimEnd() + "\n";
+            // 1. Validate syntax immediately
+            const validation = validateTemplateSyntax(targetPath, stripped);
+            if (!validation.ok) {
+                console.log("");
+                clack.log.error(`Syntax Validation Failed:\n  ${chalk.red(validation.error.message)}`);
+                console.log("");
+                const fixChoice = await clack.select({
+                    message: "How would you like to handle this syntax error?",
+                    options: [
+                        { value: "re-edit", label: "✏️  Re-edit template to fix the error" },
+                        { value: "discard", label: "❌  Discard changes and cancel" },
+                    ],
+                });
+                if (clack.isCancel(fixChoice) || fixChoice === "discard") {
+                    return err(inputCancelledError("Template edit cancelled due to syntax error"));
+                }
+                currentRaw = stripped;
+                continue;
+            }
+            // 2. Syntax is valid!
+            currentRaw = stripped;
+            statusLine("ok", "Template syntax validated successfully");
+            // 3. Post-edit menu
+            const actionChoice = await clack.select({
+                message: "Template ready. What would you like to do next?",
+                options: [
+                    {
+                        value: "proceed",
+                        label: "➜  Proceed to plan changes",
+                        hint: "generate diffs across target branches",
+                    },
+                    {
+                        value: "re-edit",
+                        label: "✏️   Edit template again",
+                        hint: "re-open in editor",
+                    },
+                    {
+                        value: "discard",
+                        label: "❌  Discard changes and cancel",
+                    },
+                ],
+            });
+            if (clack.isCancel(actionChoice) || actionChoice === "discard") {
+                return err(inputCancelledError("Template edit cancelled"));
+            }
+            if (actionChoice === "re-edit") {
+                continue;
+            }
+            break;
+        }
+        // Update context with the validated template
+        if (isEnv) {
+            const parseResult = parseEnvTemplate(currentRaw);
+            if (!parseResult.ok)
+                return parseResult;
+            const activeTemplate = {
+                path: targetPath,
+                engine: "env-reconcile",
+                raw: currentRaw,
+                parsedEnv: parseResult.value,
+            };
+            statusLine("ok", `Template ready — ${parseResult.value.assignments.length} assignment(s)`);
+            return ok({
+                ...context,
+                template: parseResult.value,
+                activeTemplate,
+                templates: [activeTemplate],
+            });
+        }
+        else {
+            const variables = extractTemplateVariables(currentRaw);
+            const activeTemplate = {
+                path: targetPath,
+                engine: "source-of-truth",
+                raw: currentRaw,
+                variables,
+            };
+            statusLine("ok", `Template ready — ${variables.length} variable placeholder(s) detected`);
+            return ok({
+                ...context,
+                template: {
+                    raw: currentRaw,
+                    assignments: [],
+                    placeholders: variables.map((v) => v.name),
+                },
+                activeTemplate,
+                templates: [activeTemplate],
+            });
+        }
+    }
+    finally {
+        await rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+    }
+};

package/dist/stages/eligibility.d.ts

@@ -0,0 +1,3 @@
+import { Stage } from "../core/pipeline.js";
+import { RunContext, AppDeps } from "../core/types.js";
+export declare const checkEligibilityStage: Stage<RunContext, AppDeps>;