forge-cc 0.1.0

package/dist/state/writer.js

@@ -0,0 +1,222 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { execSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { readRoadmapProgress } from "./reader.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function ensureDir(filePath) {
+    await mkdir(dirname(filePath), { recursive: true });
+}
+function branchSlug(branch) {
+    return branch.replace(/\//g, "-").toLowerCase();
+}
+// ---------------------------------------------------------------------------
+// writeStateFile
+// ---------------------------------------------------------------------------
+export async function writeStateFile(projectDir, info) {
+    const milestoneRows = info.milestoneTable
+        .map((m) => `| ${m.number} | ${m.name} | ${m.status} |`)
+        .join("\n");
+    const nextActions = info.nextActions
+        .map((a, i) => `${i + 1}. ${a}`)
+        .join("\n");
+    const content = `# ${info.project} — Project State
+
+## Current Position
+- **Project:** ${info.project} (build phase)
+- **Milestone:** Milestone ${info.milestone.number} — ${info.milestone.name}
+- **Branch:** ${info.branch}
+- **Active PRD:** \`${info.activePrd}\`
+- **Last Session:** ${info.lastSession}
+
+## Milestone Progress
+| Milestone | Name | Status |
+|-----------|------|--------|
+${milestoneRows}
+
+## Next Actions
+${nextActions}
+`;
+    const filePath = join(projectDir, ".planning", "STATE.md");
+    await ensureDir(filePath);
+    await writeFile(filePath, content, "utf-8");
+}
+// ---------------------------------------------------------------------------
+// updateRoadmapMilestone
+// ---------------------------------------------------------------------------
+export async function updateRoadmapMilestone(projectDir, milestoneNumber, status) {
+    const filePath = join(projectDir, ".planning", "ROADMAP.md");
+    const raw = await readFile(filePath, "utf-8");
+    // Match the specific milestone row and replace its status
+    const pattern = new RegExp(`^(\\|\\s*${milestoneNumber}\\s*\\|\\s*.+?\\s*\\|)\\s*.+?\\s*\\|`, "m");
+    const match = raw.match(pattern);
+    if (!match) {
+        throw new Error(`Milestone ${milestoneNumber} not found in ROADMAP.md table`);
+    }
+    const updated = raw.replace(pattern, `$1 ${status} |`);
+    await writeFile(filePath, updated, "utf-8");
+}
+// ---------------------------------------------------------------------------
+// writeSessionMemory
+// ---------------------------------------------------------------------------
+export async function writeSessionMemory(projectDir, branch, data) {
+    const slug = branchSlug(branch);
+    const filePath = join(projectDir, ".claude", "memory", `session-${slug}.md`);
+    const content = `# Session State
+**Date:** ${data.date}
+**Developer:** ${data.developer}
+**Branch:** ${branch}
+**Working On:** ${data.workingOn}
+**Status:** ${data.status}
+**Next:** ${data.next}
+**Blockers:** ${data.blockers}
+`;
+    await ensureDir(filePath);
+    await writeFile(filePath, content, "utf-8");
+}
+// ---------------------------------------------------------------------------
+// commitMilestoneWork — commits and optionally pushes milestone work
+// ---------------------------------------------------------------------------
+export function commitMilestoneWork(options) {
+    const { projectDir, milestoneNumber, milestoneName, filesToStage, push, branch, } = options;
+    if (filesToStage.length === 0) {
+        throw new Error("filesToStage must contain at least one file — never use git add .");
+    }
+    // Check if git is available
+    try {
+        execSync("git --version", { cwd: projectDir, stdio: "pipe" });
+    }
+    catch {
+        throw new Error("git is not available on this system. Cannot commit milestone work.");
+    }
+    // Check for detached HEAD
+    try {
+        const headRef = execSync("git symbolic-ref HEAD", {
+            cwd: projectDir,
+            encoding: "utf-8",
+            stdio: "pipe",
+        }).trim();
+        if (!headRef) {
+            throw new Error("Detached HEAD detected — cannot commit. Check out a branch first.");
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes("Detached HEAD")) {
+            throw err;
+        }
+        // git symbolic-ref fails on detached HEAD with exit code 128
+        throw new Error("Detached HEAD detected — cannot commit. Check out a branch first.");
+    }
+    // Stage only the specified files, skipping files that don't exist
+    for (const file of filesToStage) {
+        try {
+            execSync(`git add ${JSON.stringify(file)}`, {
+                cwd: projectDir,
+                stdio: "pipe",
+            });
+        }
+        catch {
+            // File may not exist or be outside the repo — skip and continue
+            console.warn(`Warning: Could not stage file "${file}" — skipping.`);
+        }
+    }
+    // Commit with a descriptive message
+    const commitMessage = `feat: ${milestoneName} (Milestone ${milestoneNumber})`;
+    try {
+        execSync(`git commit -m ${JSON.stringify(commitMessage)}`, {
+            cwd: projectDir,
+            stdio: "pipe",
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`git commit failed: ${msg}`);
+    }
+    // Read back the commit SHA
+    const commitSha = execSync("git rev-parse HEAD", {
+        cwd: projectDir,
+        encoding: "utf-8",
+    }).trim();
+    // Optionally push to remote
+    let pushed = false;
+    if (push && branch) {
+        try {
+            execSync(`git push origin ${branch}`, {
+                cwd: projectDir,
+                stdio: "pipe",
+            });
+            pushed = true;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`Warning: git push failed: ${msg}. Commit was created locally.`);
+        }
+    }
+    return { commitSha, pushed };
+}
+// ---------------------------------------------------------------------------
+// isLastMilestone — detects if this is the final pending milestone
+// ---------------------------------------------------------------------------
+export async function isLastMilestone(projectDir, milestoneNumber) {
+    const roadmap = await readRoadmapProgress(projectDir);
+    if (!roadmap || roadmap.milestones.length === 0) {
+        return true; // No roadmap data — treat as last by default
+    }
+    const maxMilestone = Math.max(...roadmap.milestones.map((m) => m.number));
+    // If this IS the highest milestone number, it's the last
+    if (milestoneNumber >= maxMilestone) {
+        return true;
+    }
+    // If all milestones after this one are already complete, this is effectively last
+    const remaining = roadmap.milestones.filter((m) => m.number > milestoneNumber &&
+        !m.status.toLowerCase().startsWith("complete"));
+    return remaining.length === 0;
+}
+// ---------------------------------------------------------------------------
+// updateMilestoneProgress — updates all state docs after milestone completion
+// ---------------------------------------------------------------------------
+export async function updateMilestoneProgress(options) {
+    const { projectDir, project, milestoneNumber, milestoneName, branch, activePrd, developer, nextMilestone, milestoneTable, } = options;
+    const today = new Date().toISOString().slice(0, 10);
+    // 1. Mark this milestone as complete in ROADMAP.md
+    await updateRoadmapMilestone(projectDir, milestoneNumber, `Complete (${today})`);
+    // 2. Build next actions based on whether there's a next milestone
+    const nextActions = nextMilestone
+        ? [
+            `Begin Milestone ${nextMilestone.number} — ${nextMilestone.name}`,
+            "Read PRD for next milestone scope",
+            "Spawn agent team for next milestone",
+        ]
+        : [
+            "All milestones complete — final review and cleanup",
+            "Merge feature branch to main",
+            "Archive planning docs",
+        ];
+    // 3. Update STATE.md with current position
+    const stateTarget = nextMilestone ?? {
+        number: milestoneNumber,
+        name: milestoneName,
+    };
+    await writeStateFile(projectDir, {
+        project,
+        milestone: stateTarget,
+        branch,
+        activePrd,
+        lastSession: today,
+        milestoneTable,
+        nextActions,
+    });
+    // 4. Write session memory for this branch
+    await writeSessionMemory(projectDir, branch, {
+        date: today,
+        developer,
+        workingOn: `Milestone ${milestoneNumber} — ${milestoneName}`,
+        status: "Complete",
+        next: nextMilestone
+            ? `Milestone ${nextMilestone.number} — ${nextMilestone.name}`
+            : "All milestones complete",
+        blockers: "None",
+    });
+}
+//# sourceMappingURL=writer.js.map

package/dist/state/writer.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/** Structured error from a verification gate */
+export interface GateError {
+    file?: string;
+    line?: number;
+    message: string;
+    remediation?: string;
+}
+/** Result from a single verification gate */
+export interface GateResult {
+    gate: string;
+    passed: boolean;
+    errors: GateError[];
+    warnings: string[];
+    duration_ms: number;
+}
+/** Extended result for visual validation with screenshots */
+export interface VisualResult extends GateResult {
+    screenshots: Array<{
+        page: string;
+        path: string;
+    }>;
+    consoleErrors: string[];
+}
+/** Input for the full verification pipeline */
+export interface PipelineInput {
+    projectDir: string;
+    gates?: string[];
+    prdPath?: string;
+    milestoneType?: "ui" | "data" | "mixed";
+    pages?: string[];
+    apiEndpoints?: string[];
+    maxIterations?: number;
+    devServerCommand?: string;
+    devServerPort?: number;
+    baseBranch?: string;
+}
+/** Result from the full verification pipeline */
+export interface PipelineResult {
+    passed: boolean;
+    iteration: number;
+    maxIterations: number;
+    gates: GateResult[];
+    report: string;
+}
+/** Configuration from .forge.json */
+export interface ForgeConfig {
+    gates: string[];
+    maxIterations: number;
+    verifyFreshness: number;
+    devServer?: {
+        command: string;
+        port: number;
+        readyPattern?: string;
+    };
+    prdPath?: string;
+    linearProject?: string;
+}
+/** Verification cache written to .forge/last-verify.json */
+export interface VerifyCache {
+    passed: boolean;
+    timestamp: string;
+    gates: GateResult[];
+    branch: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/browser.d.ts

@@ -0,0 +1,10 @@
+import { type Browser } from "playwright";
+import { type ChildProcess } from "node:child_process";
+export declare function getBrowser(): Promise<Browser>;
+export declare function closeBrowser(): Promise<void>;
+export declare function startDevServer(projectDir: string, command?: string, port?: number): Promise<{
+    port: number;
+    process: ChildProcess;
+}>;
+export declare function stopDevServer(): Promise<void>;
+export declare function waitForServer(port: number, timeoutMs?: number): Promise<boolean>;

package/dist/utils/browser.js

@@ -0,0 +1,89 @@
+import { chromium } from "playwright";
+import { spawn, execSync } from "node:child_process";
+import { setTimeout } from "node:timers/promises";
+let browserInstance = null;
+let devServerProcess = null;
+export async function getBrowser() {
+    if (!browserInstance || !browserInstance.isConnected()) {
+        try {
+            browserInstance = await chromium.launch({ headless: true });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes("Executable doesn't exist") || message.includes("browserType.launch")) {
+                throw new Error(`Playwright browsers are not installed. Run "npx playwright install chromium" to fix this. Original error: ${message}`);
+            }
+            throw err;
+        }
+    }
+    return browserInstance;
+}
+export async function closeBrowser() {
+    if (browserInstance) {
+        await browserInstance.close();
+        browserInstance = null;
+    }
+}
+export async function startDevServer(projectDir, command, port) {
+    const resolvedCommand = command ?? "npm run dev";
+    const resolvedPort = port ?? 3000;
+    // Kill any existing dev server before starting a new one
+    await stopDevServer();
+    devServerProcess = spawn(resolvedCommand, {
+        cwd: projectDir,
+        shell: true,
+        stdio: "pipe",
+    });
+    // Wait for the server to become reachable
+    const ready = await waitForServer(resolvedPort);
+    if (!ready) {
+        await stopDevServer();
+        throw new Error(`Dev server failed to start on port ${resolvedPort} within timeout`);
+    }
+    return { port: resolvedPort, process: devServerProcess };
+}
+export async function stopDevServer() {
+    if (devServerProcess) {
+        const proc = devServerProcess;
+        devServerProcess = null;
+        try {
+            if (process.platform === "win32" && proc.pid) {
+                // On Windows, proc.kill() doesn't kill the child process tree.
+                // Use taskkill with /T (tree) /F (force) to kill the process and its children.
+                try {
+                    execSync(`taskkill /pid ${proc.pid} /T /F`, { stdio: "pipe" });
+                }
+                catch {
+                    // taskkill may fail if the process already exited — fall back to proc.kill()
+                    try {
+                        proc.kill();
+                    }
+                    catch { /* already exited */ }
+                }
+            }
+            else {
+                proc.kill();
+            }
+        }
+        catch {
+            // Process may have already exited — ignore
+        }
+        // Brief wait for cleanup
+        await setTimeout(500);
+    }
+}
+export async function waitForServer(port, timeoutMs) {
+    const deadline = Date.now() + (timeoutMs ?? 30_000);
+    while (Date.now() < deadline) {
+        try {
+            await fetch(`http://localhost:${port}`);
+            return true;
+        }
+        catch {
+            // Server not ready yet — wait and retry
+            await setTimeout(1000);
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=browser.js.map

package/dist/utils/browser.js.map

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

package/hooks/pre-commit-verify.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+// Read hook input from stdin
+let input = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+  input += chunk;
+});
+process.stdin.on("end", () => {
+  try {
+    const hookData = JSON.parse(input);
+    const result = checkPreCommit(hookData);
+    console.log(JSON.stringify(result));
+  } catch {
+    // On any error, allow (don't block the user's work)
+    console.log(JSON.stringify({ decision: "allow" }));
+  }
+});
+
+function checkPreCommit(hookData) {
+  // Only intercept Bash calls with "git commit" in the command
+  if (hookData.tool_name !== "Bash") {
+    return { decision: "allow" };
+  }
+
+  const command = hookData.tool_input?.command ?? "";
+  if (!command.includes("git commit")) {
+    return { decision: "allow" };
+  }
+
+  const projectDir = process.cwd();
+
+  // Check 1: Wrong branch protection
+  try {
+    const branch = execSync("git branch --show-current", {
+      encoding: "utf-8",
+    }).trim();
+    if (branch === "main" || branch === "master") {
+      return {
+        decision: "block",
+        reason: `Forge: Cannot commit directly to ${branch}. Create a feature branch first.`,
+      };
+    }
+  } catch {
+    // Can't determine branch — allow
+  }
+
+  // Check 2: Verify cache exists
+  const cachePath = join(projectDir, ".forge", "last-verify.json");
+  if (!existsSync(cachePath)) {
+    return {
+      decision: "block",
+      reason:
+        "Forge: No verification found. Run `npx forge verify` before committing.",
+    };
+  }
+
+  try {
+    const cache = JSON.parse(readFileSync(cachePath, "utf-8"));
+
+    // Check 3: Did verification pass?
+    if (!cache.passed) {
+      return {
+        decision: "block",
+        reason:
+          "Forge: Last verification FAILED. Fix errors and run `npx forge verify` again.",
+      };
+    }
+
+    // Check 4: Is it fresh? (default 10 minutes = 600000ms)
+    let freshness = 600_000;
+    const configPath = join(projectDir, ".forge.json");
+    if (existsSync(configPath)) {
+      try {
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (config.verifyFreshness) freshness = config.verifyFreshness;
+      } catch {
+        /* use default */
+      }
+    }
+
+    const age = Date.now() - new Date(cache.timestamp).getTime();
+    if (age > freshness) {
+      const ageMin = Math.round(age / 60_000);
+      return {
+        decision: "block",
+        reason: `Forge: Verification is stale (${ageMin}min old). Run \`npx forge verify\` again.`,
+      };
+    }
+
+    return { decision: "allow" };
+  } catch {
+    return {
+      decision: "block",
+      reason:
+        "Forge: Could not read verification cache. Run `npx forge verify`.",
+    };
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "forge-cc",
+  "version": "0.1.0",
+  "description": "Pre-PR verification harness for Claude Code agents — gate runner + CLI + MCP server",
+  "type": "module",
+  "license": "MIT",
+  "author": "Troy Hoffman",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/troyhoffman/forge-cc.git"
+  },
+  "keywords": [
+    "forge",
+    "verification",
+    "claude-code",
+    "mcp",
+    "pre-commit",
+    "lint",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/gates/index.js",
+  "exports": {
+    ".": "./dist/gates/index.js",
+    "./cli": "./dist/cli.js",
+    "./server": "./dist/server.js"
+  },
+  "bin": {
+    "forge": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "hooks/",
+    ".forge.json",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "node dist/cli.js verify",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^13.0.0",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/README.md

@@ -0,0 +1,33 @@
+# forge-cc Skills
+
+Skills are markdown instruction files that Claude Code discovers and executes. When a user types a skill command (e.g., `/forge:triage`), Claude Code reads the corresponding markdown file and follows its instructions using available tools (MCP tools, Bash, file operations, etc.).
+
+Skills are prompts, not code. The LLM interprets the instructions and orchestrates tool calls to execute the workflow.
+
+## Installation
+
+Copy or symlink the skill files into your Claude Code skills directory:
+
+```bash
+# Copy all skills
+cp skills/forge-*.md ~/.claude/skills/
+
+# Or symlink (updates automatically with forge-cc)
+ln -s "$(pwd)/skills/forge-triage.md" ~/.claude/skills/forge-triage.md
+```
+
+Skills are also distributed via `npm install forge-cc` and can be found in `node_modules/forge-cc/skills/`.
+
+## Available Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| Triage | `/forge:triage` | Brain dump to Linear projects. Paste unstructured ideas, get organized projects. |
+| Spec | `/forge:spec` | Interview to PRD. Select a project, answer questions, get milestones + issues. *(coming soon)* |
+| Go | `/forge:go` | Execute milestones. Wave-based agents, self-healing verification, auto mode. *(coming soon)* |
+
+## Prerequisites
+
+- Claude Code with MCP tools enabled
+- Linear MCP tools configured (`mcp__linear__*`) for triage and spec skills
+- `forge-cc` installed in the project for verification gates (used by go skill)