forge-cc 0.1.4 → 0.1.6

package/dist/worktree/manager.js.map

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

package/dist/worktree/parallel.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Parallel Scheduler — Milestone Dependency Analyzer & Execution Planner
+ *
+ * Parses `dependsOn` from PRD milestones, builds a DAG, determines which
+ * milestones can run simultaneously in parallel waves, and provides
+ * functions to query ready milestones given completed set.
+ *
+ * Backward compatible: milestones without `dependsOn` are treated as
+ * having no dependencies (roots).
+ */
+export interface MilestoneDep {
+    number: number;
+    name: string;
+    dependsOn: number[];
+}
+export interface DAGNode {
+    milestone: MilestoneDep;
+    children: number[];
+    parents: number[];
+    depth: number;
+}
+export interface ExecutionWave {
+    waveNumber: number;
+    milestones: number[];
+}
+export interface SchedulerResult {
+    waves: ExecutionWave[];
+    totalMilestones: number;
+    maxParallelism: number;
+    isSequential: boolean;
+}
+/**
+ * Build a directed acyclic graph from milestone dependencies.
+ *
+ * Validates:
+ * - All referenced dependencies exist in the milestone set
+ * - No cycles exist in the dependency graph
+ *
+ * Throws descriptive errors on validation failure.
+ */
+export declare function buildDAG(milestones: MilestoneDep[]): Map<number, DAGNode>;
+/**
+ * Topological sort milestones into parallel execution waves.
+ *
+ * - Wave 1: all milestones with no dependencies (roots)
+ * - Wave 2: milestones whose dependencies are all in Wave 1
+ * - Wave N: milestones whose dependencies are all in waves < N
+ */
+export declare function computeExecutionWaves(dag: Map<number, DAGNode>): SchedulerResult;
+/**
+ * Parse a PRD markdown document to extract milestone definitions and
+ * their `dependsOn` fields.
+ *
+ * Looks for milestone headers like:
+ *   ### Milestone 1: Name Here
+ *   ### Milestone 2 — Name Here
+ *
+ * And within each milestone section, looks for:
+ *   **dependsOn:** 1, 3
+ *   dependsOn: [1, 3]
+ *   **dependsOn:** [1]
+ *
+ * If no `dependsOn` field is found, treats the milestone as having no
+ * dependencies (backward compatible).
+ */
+export declare function parseMilestoneDependencies(prdContent: string): MilestoneDep[];
+/**
+ * Given execution waves and a set of completed milestone numbers,
+ * return which milestones are ready to start.
+ *
+ * A milestone is ready if:
+ * 1. It has not been completed yet
+ * 2. All of its dependencies (from the wave schedule) are in the completed set
+ *
+ * This requires the original DAG to check dependencies, so we accept
+ * the waves plus the DAG.
+ */
+export declare function getReadyMilestones(dag: Map<number, DAGNode>, completed: Set<number>): number[];
+/**
+ * Parse a PRD file and build the full execution schedule.
+ * Combines parseMilestoneDependencies + buildDAG + computeExecutionWaves.
+ *
+ * If the PRD has no `dependsOn` fields, all milestones will be in wave 1
+ * (all roots), which is backward compatible with sequential execution
+ * when the caller processes them in milestone-number order.
+ */
+export declare function buildScheduleFromPRD(prdPath: string): Promise<SchedulerResult>;

package/dist/worktree/parallel.js

@@ -0,0 +1,328 @@
+/**
+ * Parallel Scheduler — Milestone Dependency Analyzer & Execution Planner
+ *
+ * Parses `dependsOn` from PRD milestones, builds a DAG, determines which
+ * milestones can run simultaneously in parallel waves, and provides
+ * functions to query ready milestones given completed set.
+ *
+ * Backward compatible: milestones without `dependsOn` are treated as
+ * having no dependencies (roots).
+ */
+import { readFile } from "node:fs/promises";
+// ---------------------------------------------------------------------------
+// buildDAG
+// ---------------------------------------------------------------------------
+/**
+ * Build a directed acyclic graph from milestone dependencies.
+ *
+ * Validates:
+ * - All referenced dependencies exist in the milestone set
+ * - No cycles exist in the dependency graph
+ *
+ * Throws descriptive errors on validation failure.
+ */
+export function buildDAG(milestones) {
+    const dag = new Map();
+    const milestoneNumbers = new Set(milestones.map((m) => m.number));
+    // Initialize all nodes
+    for (const milestone of milestones) {
+        dag.set(milestone.number, {
+            milestone,
+            children: [],
+            parents: [...milestone.dependsOn],
+            depth: -1, // computed later
+        });
+    }
+    // Validate dependencies exist and build children links
+    for (const milestone of milestones) {
+        for (const dep of milestone.dependsOn) {
+            if (!milestoneNumbers.has(dep)) {
+                throw new Error(`Milestone ${milestone.number} ("${milestone.name}") depends on milestone ${dep}, which does not exist`);
+            }
+            const parentNode = dag.get(dep);
+            parentNode.children.push(milestone.number);
+        }
+    }
+    // Detect cycles using DFS with coloring (white/gray/black)
+    detectCycles(dag);
+    // Compute depths via BFS from roots
+    computeDepths(dag);
+    return dag;
+}
+/**
+ * Detect cycles in the DAG using DFS with three-color marking.
+ * Throws an error with a descriptive message if a cycle is found.
+ */
+function detectCycles(dag) {
+    const WHITE = 0; // unvisited
+    const GRAY = 1; // in current DFS path
+    const BLACK = 2; // fully processed
+    const color = new Map();
+    for (const num of dag.keys()) {
+        color.set(num, WHITE);
+    }
+    const path = [];
+    function dfs(nodeNum) {
+        color.set(nodeNum, GRAY);
+        path.push(nodeNum);
+        const node = dag.get(nodeNum);
+        for (const childNum of node.children) {
+            const childColor = color.get(childNum);
+            if (childColor === GRAY) {
+                // Found a cycle — extract the cycle path for the error message
+                const cycleStart = path.indexOf(childNum);
+                const cyclePath = path.slice(cycleStart);
+                cyclePath.push(childNum); // close the cycle
+                const cycleStr = cyclePath
+                    .map((n) => {
+                    const m = dag.get(n).milestone;
+                    return `M${m.number}("${m.name}")`;
+                })
+                    .join(" -> ");
+                throw new Error(`Dependency cycle detected: ${cycleStr}`);
+            }
+            if (childColor === WHITE) {
+                dfs(childNum);
+            }
+        }
+        color.set(nodeNum, BLACK);
+        path.pop();
+    }
+    for (const num of dag.keys()) {
+        if (color.get(num) === WHITE) {
+            dfs(num);
+        }
+    }
+}
+/**
+ * Compute depth for each node via BFS from roots (nodes with no parents).
+ * Depth = longest path from any root to this node.
+ */
+function computeDepths(dag) {
+    // Find roots (no parents)
+    const roots = [];
+    for (const [num, node] of dag) {
+        if (node.parents.length === 0) {
+            roots.push(num);
+        }
+    }
+    // BFS-like traversal computing max depth
+    // Use Kahn's algorithm approach: process nodes whose all parents are resolved
+    const depth = new Map();
+    const inDegree = new Map();
+    for (const [num, node] of dag) {
+        inDegree.set(num, node.parents.length);
+    }
+    const queue = [];
+    for (const root of roots) {
+        depth.set(root, 0);
+        queue.push(root);
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const currentDepth = depth.get(current);
+        const node = dag.get(current);
+        node.depth = currentDepth;
+        for (const childNum of node.children) {
+            const childDepth = depth.get(childNum);
+            // Set child depth to max of current paths
+            if (childDepth === undefined || currentDepth + 1 > childDepth) {
+                depth.set(childNum, currentDepth + 1);
+            }
+            // Decrement in-degree; enqueue when all parents processed
+            const remaining = inDegree.get(childNum) - 1;
+            inDegree.set(childNum, remaining);
+            if (remaining === 0) {
+                queue.push(childNum);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// computeExecutionWaves
+// ---------------------------------------------------------------------------
+/**
+ * Topological sort milestones into parallel execution waves.
+ *
+ * - Wave 1: all milestones with no dependencies (roots)
+ * - Wave 2: milestones whose dependencies are all in Wave 1
+ * - Wave N: milestones whose dependencies are all in waves < N
+ */
+export function computeExecutionWaves(dag) {
+    if (dag.size === 0) {
+        return {
+            waves: [],
+            totalMilestones: 0,
+            maxParallelism: 0,
+            isSequential: true,
+        };
+    }
+    // Group milestones by depth — depth corresponds to wave number
+    const waveMap = new Map();
+    for (const [num, node] of dag) {
+        const d = node.depth;
+        if (!waveMap.has(d)) {
+            waveMap.set(d, []);
+        }
+        waveMap.get(d).push(num);
+    }
+    // Sort wave keys and build ExecutionWave array
+    const sortedDepths = [...waveMap.keys()].sort((a, b) => a - b);
+    const waves = sortedDepths.map((depth, index) => ({
+        waveNumber: index + 1,
+        milestones: waveMap.get(depth).sort((a, b) => a - b),
+    }));
+    const maxParallelism = Math.max(...waves.map((w) => w.milestones.length));
+    const isSequential = maxParallelism <= 1;
+    return {
+        waves,
+        totalMilestones: dag.size,
+        maxParallelism,
+        isSequential,
+    };
+}
+// ---------------------------------------------------------------------------
+// parseMilestoneDependencies
+// ---------------------------------------------------------------------------
+/**
+ * Parse a PRD markdown document to extract milestone definitions and
+ * their `dependsOn` fields.
+ *
+ * Looks for milestone headers like:
+ *   ### Milestone 1: Name Here
+ *   ### Milestone 2 — Name Here
+ *
+ * And within each milestone section, looks for:
+ *   **dependsOn:** 1, 3
+ *   dependsOn: [1, 3]
+ *   **dependsOn:** [1]
+ *
+ * If no `dependsOn` field is found, treats the milestone as having no
+ * dependencies (backward compatible).
+ */
+export function parseMilestoneDependencies(prdContent) {
+    const milestones = [];
+    // Split PRD into milestone sections
+    // Match headers like: ### Milestone 1: Name or ### Milestone 1 — Name
+    const milestoneHeaderRe = /###\s*Milestone\s+(\d+)\s*[:\—–-]\s*(.+)/g;
+    const headers = [];
+    let headerMatch;
+    while ((headerMatch = milestoneHeaderRe.exec(prdContent)) !== null) {
+        headers.push({
+            number: parseInt(headerMatch[1], 10),
+            name: headerMatch[2].trim(),
+            index: headerMatch.index,
+        });
+    }
+    // Extract section content for each milestone
+    for (let i = 0; i < headers.length; i++) {
+        const header = headers[i];
+        const sectionStart = header.index;
+        const sectionEnd = i + 1 < headers.length ? headers[i + 1].index : prdContent.length;
+        const sectionContent = prdContent.slice(sectionStart, sectionEnd);
+        // Look for dependsOn field in the section
+        const dependsOn = parseDependsOnField(sectionContent);
+        milestones.push({
+            number: header.number,
+            name: header.name,
+            dependsOn,
+        });
+    }
+    return milestones;
+}
+/**
+ * Parse the dependsOn field from a milestone section.
+ * Supports formats:
+ *   **dependsOn:** 1, 3
+ *   dependsOn: [1, 3]
+ *   **dependsOn:** [1]
+ *   **dependsOn:** none
+ *
+ * Returns empty array if not found or explicitly "none".
+ */
+function parseDependsOnField(sectionContent) {
+    // Match patterns like:
+    //   **dependsOn:** 1, 3      (bold markdown: ** before key, :** after)
+    //   dependsOn: [1, 3]        (plain text)
+    //   **dependsOn:** [1]       (bold with brackets)
+    const dependsOnRe = /\*{0,2}dependsOn:\*{0,2}\s*(.+)/i;
+    const match = sectionContent.match(dependsOnRe);
+    if (!match) {
+        return [];
+    }
+    const value = match[1].trim();
+    // Handle "none" or empty
+    if (value.toLowerCase() === "none" ||
+        value === "[]" ||
+        value === "" ||
+        value === "-") {
+        return [];
+    }
+    // Strip brackets if present: [1, 3] -> 1, 3
+    const stripped = value.replace(/^\[/, "").replace(/\].*$/, "");
+    // Parse comma-separated numbers
+    const numbers = [];
+    for (const part of stripped.split(",")) {
+        const trimmed = part.trim();
+        const num = parseInt(trimmed, 10);
+        if (!isNaN(num)) {
+            numbers.push(num);
+        }
+    }
+    return numbers;
+}
+// ---------------------------------------------------------------------------
+// getReadyMilestones
+// ---------------------------------------------------------------------------
+/**
+ * Given execution waves and a set of completed milestone numbers,
+ * return which milestones are ready to start.
+ *
+ * A milestone is ready if:
+ * 1. It has not been completed yet
+ * 2. All of its dependencies (from the wave schedule) are in the completed set
+ *
+ * This requires the original DAG to check dependencies, so we accept
+ * the waves plus the DAG.
+ */
+export function getReadyMilestones(dag, completed) {
+    const ready = [];
+    for (const [num, node] of dag) {
+        // Skip already completed
+        if (completed.has(num)) {
+            continue;
+        }
+        // Check if all parents are completed
+        const allParentsCompleted = node.parents.every((p) => completed.has(p));
+        if (allParentsCompleted) {
+            ready.push(num);
+        }
+    }
+    return ready.sort((a, b) => a - b);
+}
+// ---------------------------------------------------------------------------
+// buildScheduleFromPRD — convenience function
+// ---------------------------------------------------------------------------
+/**
+ * Parse a PRD file and build the full execution schedule.
+ * Combines parseMilestoneDependencies + buildDAG + computeExecutionWaves.
+ *
+ * If the PRD has no `dependsOn` fields, all milestones will be in wave 1
+ * (all roots), which is backward compatible with sequential execution
+ * when the caller processes them in milestone-number order.
+ */
+export async function buildScheduleFromPRD(prdPath) {
+    const prdContent = await readFile(prdPath, "utf-8");
+    const milestones = parseMilestoneDependencies(prdContent);
+    if (milestones.length === 0) {
+        return {
+            waves: [],
+            totalMilestones: 0,
+            maxParallelism: 0,
+            isSequential: true,
+        };
+    }
+    const dag = buildDAG(milestones);
+    return computeExecutionWaves(dag);
+}
+//# sourceMappingURL=parallel.js.map

package/dist/worktree/parallel.js.map

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

package/dist/worktree/session.d.ts

@@ -0,0 +1,64 @@
+import type { UserIdentity } from "./identity.js";
+export interface Session {
+    id: string;
+    user: string;
+    email: string;
+    skill: "go" | "spec";
+    milestone?: string;
+    branch: string;
+    worktreePath: string;
+    startedAt: string;
+    pid: number;
+    status: "active" | "stale" | "completing";
+}
+export interface SessionRegistry {
+    sessions: Session[];
+}
+/**
+ * Get the path to the session registry file.
+ * Located at <repoRoot>/.forge/sessions.json
+ */
+export declare function getRegistryPath(repoRoot: string): string;
+/**
+ * Load the session registry. Returns empty registry if file doesn't exist.
+ */
+export declare function loadRegistry(repoRoot: string): SessionRegistry;
+/**
+ * Save the session registry atomically.
+ */
+export declare function saveRegistry(repoRoot: string, registry: SessionRegistry): void;
+/**
+ * Register a new session. Returns the created session.
+ * Uses file-based locking to prevent lost updates from concurrent writes.
+ */
+export declare function registerSession(repoRoot: string, params: {
+    user: UserIdentity;
+    skill: "go" | "spec";
+    milestone?: string;
+    branch: string;
+    worktreePath: string;
+}): Session;
+/**
+ * Deregister (remove) a session by ID.
+ * Uses file-based locking to prevent lost updates.
+ */
+export declare function deregisterSession(repoRoot: string, sessionId: string): void;
+/**
+ * Update a session's status.
+ * Uses file-based locking to prevent lost updates.
+ */
+export declare function updateSessionStatus(repoRoot: string, sessionId: string, status: Session["status"]): void;
+/**
+ * Find and mark stale sessions.
+ * A session is stale if its PID is no longer running.
+ * Uses file-based locking to prevent lost updates.
+ */
+export declare function detectStaleSessions(repoRoot: string): Session[];
+/**
+ * Get all active sessions.
+ */
+export declare function getActiveSessions(repoRoot: string): Session[];
+/**
+ * Get a session by ID.
+ */
+export declare function getSession(repoRoot: string, sessionId: string): Session | null;