forge-cc 0.1.0

package/dist/go/finalize.js

@@ -0,0 +1,200 @@
+/**
+ * Final Milestone Detection and PR Creation
+ *
+ * Handles the transition from "last milestone complete" to "PR ready for review".
+ * Uses `gh pr create` to open a pull request with a forge verification report
+ * in the body. Designed to be called by the execution engine after the final
+ * milestone passes verification.
+ */
+import { execSync } from "node:child_process";
+// ---------------------------------------------------------------------------
+// buildPRTitle
+// ---------------------------------------------------------------------------
+/**
+ * Generate a PR title summarizing all completed milestones.
+ *
+ * Examples:
+ * - `feat: my-project — Milestone 1 complete`
+ * - `feat: my-project — Milestones 1-5 complete`
+ */
+export function buildPRTitle(project, milestoneCount) {
+    if (milestoneCount <= 0) {
+        return `feat: ${project} — implementation complete`;
+    }
+    if (milestoneCount === 1) {
+        return `feat: ${project} — Milestone 1 complete`;
+    }
+    return `feat: ${project} — Milestones 1-${milestoneCount} complete`;
+}
+// ---------------------------------------------------------------------------
+// buildVerificationSection
+// ---------------------------------------------------------------------------
+/**
+ * Format a PipelineResult into a PR-ready verification section.
+ *
+ * Includes gate-level pass/fail status with error counts and
+ * duration information. Designed to be embedded in a PR body.
+ */
+export function buildVerificationSection(result) {
+    const lines = [];
+    const status = result.passed ? "PASSED" : "FAILED";
+    lines.push(`**Status:** ${status}`);
+    lines.push(`**Iterations:** ${result.iteration}/${result.maxIterations}`);
+    lines.push("");
+    // Gate results table
+    lines.push("| Gate | Status | Duration | Details |");
+    lines.push("|------|--------|----------|---------|");
+    for (const gate of result.gates) {
+        const statusIcon = gate.passed ? "Pass" : "Fail";
+        const duration = `${(gate.duration_ms / 1000).toFixed(1)}s`;
+        let details = "";
+        if (!gate.passed && gate.errors.length > 0) {
+            details = `${gate.errors.length} error${gate.errors.length === 1 ? "" : "s"}`;
+        }
+        else if (gate.passed && gate.warnings.length > 0) {
+            details = `${gate.warnings.length} warning${gate.warnings.length === 1 ? "" : "s"}`;
+        }
+        else if (gate.passed) {
+            details = "Clean";
+        }
+        lines.push(`| ${gate.gate} | ${statusIcon} | ${duration} | ${details} |`);
+    }
+    lines.push("");
+    // Error details (collapsed for readability)
+    const failedGates = result.gates.filter((g) => !g.passed && g.errors.length > 0);
+    if (failedGates.length > 0) {
+        lines.push("<details>");
+        lines.push("<summary>Error Details</summary>");
+        lines.push("");
+        for (const gate of failedGates) {
+            lines.push(`**${gate.gate}:**`);
+            for (const err of gate.errors) {
+                const loc = err.file
+                    ? `${err.file}${err.line ? `:${err.line}` : ""}`
+                    : "";
+                const prefix = loc ? `\`${loc}\`: ` : "";
+                lines.push(`- ${prefix}${err.message}`);
+            }
+            lines.push("");
+        }
+        lines.push("</details>");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// buildPRBody
+// ---------------------------------------------------------------------------
+/**
+ * Assemble the complete PR body from milestones, verification, and metadata.
+ */
+function buildPRBody(options) {
+    const lines = [];
+    // Summary section — milestone checklist
+    lines.push("## Summary");
+    lines.push("");
+    for (const m of options.milestones) {
+        const checkbox = m.success ? "[x]" : "[ ]";
+        lines.push(`- ${checkbox} M${m.number}: ${m.name}`);
+    }
+    lines.push("");
+    // Verification report section
+    lines.push("## Verification Report");
+    lines.push("");
+    if (options.verificationReport) {
+        lines.push(options.verificationReport);
+    }
+    else {
+        lines.push("_No verification report available._");
+    }
+    lines.push("");
+    // Details section
+    lines.push("## Details");
+    lines.push(`- **Branch:** ${options.branch}`);
+    if (options.commitSha) {
+        lines.push(`- **Commit:** ${options.commitSha.slice(0, 8)}`);
+    }
+    lines.push("");
+    // Footer
+    lines.push("---");
+    lines.push("Generated with [forge-cc](https://github.com/troyhoffman/forge-cc)");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// createPullRequest
+// ---------------------------------------------------------------------------
+/**
+ * Create a GitHub pull request using the `gh` CLI.
+ *
+ * Builds a structured PR body with milestone status, verification report,
+ * and metadata, then calls `gh pr create`. If `gh` is not installed or the
+ * command fails, returns a descriptive error result instead of throwing.
+ */
+export function createPullRequest(options) {
+    const baseBranch = options.baseBranch ?? "main";
+    const body = buildPRBody(options);
+    // Check that gh CLI is available
+    try {
+        execSync("gh --version", { cwd: options.projectDir, stdio: "pipe" });
+    }
+    catch {
+        return {
+            url: "",
+            number: 0,
+            title: options.title,
+            created: false,
+            error: "GitHub CLI (gh) is not installed or not in PATH. " +
+                "Install it from https://cli.github.com/ and run `gh auth login`.",
+        };
+    }
+    // Create the PR
+    try {
+        // Write body to a temp approach using stdin to avoid shell escaping issues
+        const output = execSync(`gh pr create --title ${JSON.stringify(options.title)} --base ${JSON.stringify(baseBranch)} --body ${JSON.stringify(body)}`, {
+            cwd: options.projectDir,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // gh pr create outputs the PR URL on success
+        const url = output.trim();
+        const prNumberMatch = url.match(/\/pull\/(\d+)/);
+        const prNumber = prNumberMatch ? parseInt(prNumberMatch[1], 10) : 0;
+        return {
+            url,
+            number: prNumber,
+            title: options.title,
+            created: true,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Check for common failure modes
+        if (message.includes("already exists")) {
+            return {
+                url: "",
+                number: 0,
+                title: options.title,
+                created: false,
+                error: `A pull request already exists for branch '${options.branch}'. Close or merge the existing PR first.`,
+            };
+        }
+        if (message.includes("not authenticated") ||
+            message.includes("auth login")) {
+            return {
+                url: "",
+                number: 0,
+                title: options.title,
+                created: false,
+                error: "GitHub CLI is not authenticated. Run `gh auth login` to authenticate.",
+            };
+        }
+        return {
+            url: "",
+            number: 0,
+            title: options.title,
+            created: false,
+            error: `Failed to create PR: ${message}`,
+        };
+    }
+}
+//# sourceMappingURL=finalize.js.map

package/dist/go/finalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.js","sourceRoot":"","sources":["../../src/go/finalize.ts"],"names":[],"mappings":"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"}

package/dist/go/linear-sync.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Linear Status Sync for Execution Engine
+ *
+ * Bridges the milestone executor with the Linear project management client.
+ * Manages issue and project state transitions during the go execution flow:
+ *
+ * - Milestone start: issues -> In Progress, project -> In Progress
+ * - Mid-execution: progress comments on milestone issues
+ * - Milestone complete: issues -> In Review (last milestone) or progress comment
+ *
+ * All operations degrade gracefully — the execution engine must never fail
+ * because Linear is unavailable or misconfigured.
+ */
+export interface LinearSyncOptions {
+    projectId: string;
+    milestoneNumber: number;
+    milestoneName: string;
+    apiKey?: string;
+}
+export interface MilestoneStartSync {
+    linearMilestoneId: string | null;
+    issuesUpdated: number;
+    projectUpdated: boolean;
+}
+export interface MilestoneCompleteOptions extends LinearSyncOptions {
+    isLastMilestone: boolean;
+    prUrl?: string;
+}
+export interface MilestoneCompleteSync {
+    issuesUpdated: number;
+    projectUpdated: boolean;
+    finalState: string;
+}
+export interface ProgressCommentOptions {
+    projectId: string;
+    milestoneNumber: number;
+    milestoneName: string;
+    message: string;
+    apiKey?: string;
+}
+/**
+ * Execute a Linear operation safely — catches LinearClientError and logs
+ * a warning instead of crashing. The execution engine should never fail
+ * because Linear is unavailable.
+ *
+ * Returns the function's result on success, or null on failure.
+ */
+export declare function syncLinearSafe<T>(fn: () => Promise<T>): Promise<T | null>;
+/**
+ * Sync Linear state when a milestone starts execution.
+ *
+ * - Finds the Linear milestone by name
+ * - Transitions all milestone issues to "In Progress"
+ * - Transitions the project to "In Progress" (if not already)
+ *
+ * Degrades gracefully if Linear is unavailable or the milestone is not found.
+ */
+export declare function syncMilestoneStart(options: LinearSyncOptions): Promise<MilestoneStartSync>;
+/**
+ * Sync Linear state when a milestone completes.
+ *
+ * - If NOT the last milestone: adds a progress comment to each issue
+ * - If IS the last milestone: transitions all project issues to "In Review",
+ *   transitions the project to "In Review"
+ *
+ * Degrades gracefully if Linear is unavailable.
+ */
+export declare function syncMilestoneComplete(options: MilestoneCompleteOptions): Promise<MilestoneCompleteSync>;
+/**
+ * Add a progress comment to all issues in a milestone.
+ * Used during execution to keep Linear updated with wave progress.
+ *
+ * Degrades gracefully if Linear is unavailable or the milestone is not found.
+ */
+export declare function addMilestoneProgressComment(options: ProgressCommentOptions): Promise<void>;

package/dist/go/linear-sync.js

@@ -0,0 +1,239 @@
+/**
+ * Linear Status Sync for Execution Engine
+ *
+ * Bridges the milestone executor with the Linear project management client.
+ * Manages issue and project state transitions during the go execution flow:
+ *
+ * - Milestone start: issues -> In Progress, project -> In Progress
+ * - Mid-execution: progress comments on milestone issues
+ * - Milestone complete: issues -> In Review (last milestone) or progress comment
+ *
+ * All operations degrade gracefully — the execution engine must never fail
+ * because Linear is unavailable or misconfigured.
+ */
+import { LinearClient, LinearClientError } from "../linear/client.js";
+import { transitionProject } from "../linear/projects.js";
+import { transitionMilestoneIssues } from "../linear/issues.js";
+import { findMilestoneByName } from "../linear/milestones.js";
+// ---------------------------------------------------------------------------
+// Safe Wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Execute a Linear operation safely — catches LinearClientError and logs
+ * a warning instead of crashing. The execution engine should never fail
+ * because Linear is unavailable.
+ *
+ * Returns the function's result on success, or null on failure.
+ */
+export async function syncLinearSafe(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof LinearClientError) {
+            console.warn(`[linear-sync] Linear operation failed: ${error.message}`);
+            return null;
+        }
+        // Re-throw unexpected errors — they indicate bugs, not Linear issues
+        throw error;
+    }
+}
+// ---------------------------------------------------------------------------
+// Client Creation
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to create a LinearClient. Returns null and logs a warning
+ * if no API key is available (graceful degradation).
+ */
+function createClientSafe(apiKey) {
+    try {
+        return new LinearClient(apiKey);
+    }
+    catch (error) {
+        if (error instanceof LinearClientError) {
+            console.warn(`[linear-sync] Linear client unavailable: ${error.message}`);
+            return null;
+        }
+        throw error;
+    }
+}
+// ---------------------------------------------------------------------------
+// Milestone Start
+// ---------------------------------------------------------------------------
+/**
+ * Sync Linear state when a milestone starts execution.
+ *
+ * - Finds the Linear milestone by name
+ * - Transitions all milestone issues to "In Progress"
+ * - Transitions the project to "In Progress" (if not already)
+ *
+ * Degrades gracefully if Linear is unavailable or the milestone is not found.
+ */
+export async function syncMilestoneStart(options) {
+    const noopResult = {
+        linearMilestoneId: null,
+        issuesUpdated: 0,
+        projectUpdated: false,
+    };
+    const client = createClientSafe(options.apiKey);
+    if (!client)
+        return noopResult;
+    const result = await syncLinearSafe(async () => {
+        // Find the milestone in Linear
+        const milestone = await findMilestoneByName(client, options.projectId, options.milestoneName);
+        if (!milestone) {
+            console.warn(`[linear-sync] Milestone "${options.milestoneName}" not found in project ${options.projectId}. Skipping issue transitions.`);
+            // Still try to transition the project
+            let projectUpdated = false;
+            try {
+                await transitionProject(client, options.projectId, "In Progress");
+                projectUpdated = true;
+            }
+            catch {
+                // Project may already be In Progress or beyond — that's fine
+            }
+            return {
+                linearMilestoneId: null,
+                issuesUpdated: 0,
+                projectUpdated,
+            };
+        }
+        // Transition milestone issues to In Progress
+        const { updated } = await transitionMilestoneIssues(client, options.projectId, milestone.id, "In Progress");
+        // Transition project to In Progress
+        let projectUpdated = false;
+        try {
+            await transitionProject(client, options.projectId, "In Progress");
+            projectUpdated = true;
+        }
+        catch {
+            // Project may already be In Progress or beyond — that's fine
+        }
+        return {
+            linearMilestoneId: milestone.id,
+            issuesUpdated: updated,
+            projectUpdated,
+        };
+    });
+    return result ?? noopResult;
+}
+// ---------------------------------------------------------------------------
+// Milestone Complete
+// ---------------------------------------------------------------------------
+/**
+ * Sync Linear state when a milestone completes.
+ *
+ * - If NOT the last milestone: adds a progress comment to each issue
+ * - If IS the last milestone: transitions all project issues to "In Review",
+ *   transitions the project to "In Review"
+ *
+ * Degrades gracefully if Linear is unavailable.
+ */
+export async function syncMilestoneComplete(options) {
+    const noopResult = {
+        issuesUpdated: 0,
+        projectUpdated: false,
+        finalState: "unknown",
+    };
+    const client = createClientSafe(options.apiKey);
+    if (!client)
+        return noopResult;
+    const result = await syncLinearSafe(async () => {
+        if (!options.isLastMilestone) {
+            // Mid-project milestone — add progress comments
+            const milestone = await findMilestoneByName(client, options.projectId, options.milestoneName);
+            if (milestone) {
+                const issues = await client.listIssues({
+                    projectId: options.projectId,
+                    milestoneId: milestone.id,
+                });
+                const commentBody = `Milestone ${options.milestoneNumber} complete. Moving to next milestone.`;
+                for (const issue of issues) {
+                    await client.createComment(issue.id, commentBody);
+                }
+                return {
+                    issuesUpdated: issues.length,
+                    projectUpdated: false,
+                    finalState: "In Progress",
+                };
+            }
+            return {
+                issuesUpdated: 0,
+                projectUpdated: false,
+                finalState: "In Progress",
+            };
+        }
+        // Last milestone — move everything to In Review
+        // Get ALL project issues (not just this milestone's)
+        const allIssues = await client.listIssues({
+            projectId: options.projectId,
+        });
+        let updatedCount = 0;
+        for (const issue of allIssues) {
+            if (issue.state !== "In Review" && issue.state !== "Done") {
+                try {
+                    await client.updateIssue(issue.id, { state: "In Review" });
+                    updatedCount++;
+                }
+                catch {
+                    // Some issues may not support this transition — skip them
+                }
+            }
+        }
+        // Add PR link comment if available
+        if (options.prUrl) {
+            for (const issue of allIssues) {
+                try {
+                    await client.createComment(issue.id, `PR created: ${options.prUrl}`);
+                }
+                catch {
+                    // Comment failures are non-critical
+                }
+            }
+        }
+        // Transition project to In Review
+        let projectUpdated = false;
+        try {
+            await transitionProject(client, options.projectId, "In Review");
+            projectUpdated = true;
+        }
+        catch {
+            // Project may already be In Review or beyond — that's fine
+        }
+        return {
+            issuesUpdated: updatedCount,
+            projectUpdated,
+            finalState: "In Review",
+        };
+    });
+    return result ?? noopResult;
+}
+// ---------------------------------------------------------------------------
+// Progress Comments
+// ---------------------------------------------------------------------------
+/**
+ * Add a progress comment to all issues in a milestone.
+ * Used during execution to keep Linear updated with wave progress.
+ *
+ * Degrades gracefully if Linear is unavailable or the milestone is not found.
+ */
+export async function addMilestoneProgressComment(options) {
+    const client = createClientSafe(options.apiKey);
+    if (!client)
+        return;
+    await syncLinearSafe(async () => {
+        const milestone = await findMilestoneByName(client, options.projectId, options.milestoneName);
+        if (!milestone) {
+            console.warn(`[linear-sync] Milestone "${options.milestoneName}" not found. Skipping progress comment.`);
+            return;
+        }
+        const issues = await client.listIssues({
+            projectId: options.projectId,
+            milestoneId: milestone.id,
+        });
+        for (const issue of issues) {
+            await client.createComment(issue.id, options.message);
+        }
+    });
+}
+//# sourceMappingURL=linear-sync.js.map

package/dist/go/linear-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear-sync.js","sourceRoot":"","sources":["../../src/go/linear-sync.ts"],"names":[],"mappings":"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"}

package/dist/go/verify-loop.d.ts

@@ -0,0 +1,47 @@
+import type { ForgeConfig, GateError, PipelineResult } from "../types.js";
+/** Options for the self-healing verification loop */
+export interface VerifyLoopOptions {
+    projectDir: string;
+    config: ForgeConfig;
+    /** Override config.maxIterations */
+    maxIterations?: number;
+    /** Called after each pipeline run with the iteration number and result */
+    onIteration?: (iteration: number, result: PipelineResult) => void;
+    /**
+     * Called when verification fails, giving the caller a chance to fix errors.
+     * Returns true if a fix was attempted (loop will re-verify).
+     * Returns false or is absent to re-run verification without external fix.
+     */
+    onFixAttempt?: (iteration: number, errors: GateError[]) => Promise<boolean>;
+}
+/** Result from the complete verification loop */
+export interface VerifyLoopResult {
+    passed: boolean;
+    iterations: number;
+    maxIterations: number;
+    /** All pipeline results across every iteration */
+    results: PipelineResult[];
+    /** The last pipeline result */
+    finalResult: PipelineResult;
+    /** Gate names that still fail after all iterations */
+    failedGates: string[];
+    /** Human-readable summary of remaining errors */
+    errorSummary: string;
+}
+/**
+ * Self-healing verification loop.
+ *
+ * Runs the forge verification pipeline, and on failure either invokes the
+ * `onFixAttempt` callback (so the caller can spawn a fix agent) or simply
+ * re-runs verification. Loops until the pipeline passes or max iterations
+ * are exhausted.
+ */
+export declare function runVerifyLoop(options: VerifyLoopOptions): Promise<VerifyLoopResult>;
+/**
+ * Format gate errors into a structured prompt for a fix agent.
+ *
+ * The output is designed to be directly usable in an AI agent prompt:
+ * it includes file paths, line numbers, error messages, and remediation
+ * hints so the agent can locate and fix issues without extra searching.
+ */
+export declare function formatErrorsForAgent(result: PipelineResult): string;