pi-thread-engine 0.4.6 → 0.4.9

package/src/core/types.ts

@@ -1,107 +1,107 @@
-/** Thread types from the thread engineering framework */
-export type ThreadType = "base" | "parallel" | "chained" | "fusion" | "meta" | "long" | "zero";
-
-/** Thread lifecycle states */
-export type ThreadState = "pending" | "running" | "paused" | "completed" | "failed" | "killed" | "needs_input";
-
-/** How a thread is executed */
-export type ExecutionBackend = "subagent" | "native";
-
-/** A single unit of work within a thread */
-export interface ThreadTask {
-	usage?: { inputTokens: number; outputTokens: number; cacheRead: number; totalTokens: number; cost: number };
-	id: string;
-	label: string;
-	prompt: string;
-	model?: string;
-	state: ThreadState;
-	startedAt?: number;
-	completedAt?: number;
-	result?: string;
-	error?: string;
-	/** interactive_shell session ID or subagent run ID */
-	sessionId?: string;
-}
-
-/** Thread configuration */
-export interface ThreadConfig {
-	type: ThreadType;
-	tasks: ThreadTask[];
-	/** Execution backend */
-	backend: ExecutionBackend;
-	/** For fusion threads: models to compete */
-	models?: string[];
-	/** For zero threads: verification command */
-	verifyCommand?: string;
-	/** For chained threads: require human checkpoint between phases */
-	checkpoints?: boolean;
-	/** Working directory */
-	cwd?: string;
-	/** Subagent agent name to use (default: "worker") */
-	agent?: string;
-}
-
-/** A thread — the fundamental unit of tracked work */
-export interface Thread {
-	id: string;
-	type: ThreadType;
-	label: string;
-	state: ThreadState;
-	config: ThreadConfig;
-	tasks: ThreadTask[];
-	createdAt: number;
-	startedAt?: number;
-	completedAt?: number;
-	/** Duration in ms */
-	duration?: number;
-}
-
-/** A story — a goal decomposed into thread phases */
-export interface Story {
-	id: string;
-	goal: string;
-	state: "planning" | "executing" | "verifying" | "done" | "failed";
-	phases: StoryPhase[];
-	createdAt: number;
-	completedAt?: number;
-	/** Verification command */
-	verify?: string;
-	/** Files changed */
-	artifacts: string[];
-}
-
-export interface StoryPhase {
-	name: string;
-	threadType: ThreadType;
-	threadId?: string;
-	state: ThreadState;
-	description: string;
-}
-
-/** Short status line for dashboard */
-export interface ThreadSummary {
-	id: string;
-	type: ThreadType;
-	label: string;
-	state: ThreadState;
-	progress: string;
-	elapsed: string;
-	totalTokens: number;
-	totalCost: number;
-	backend: ExecutionBackend;
-}
-
-/** Thread event for state changes */
-export type ThreadEvent =
-	| { type: "thread_created"; thread: Thread }
-	| { type: "thread_started"; thread: Thread }
-	| { type: "task_started"; thread: Thread; task: ThreadTask }
-	| { type: "task_completed"; thread: Thread; task: ThreadTask }
-	| { type: "task_failed"; thread: Thread; task: ThreadTask }
-	| { type: "thread_completed"; thread: Thread }
-	| { type: "thread_failed"; thread: Thread }
-	| { type: "thread_killed"; thread: Thread }
-	| { type: "story_created"; story: Story }
-	| { type: "story_phase_started"; story: Story; phase: StoryPhase }
-	| { type: "story_completed"; story: Story }
-	| { type: "story_failed"; story: Story };
+/** Thread types from the thread engineering framework */
+export type ThreadType = "base" | "parallel" | "chained" | "fusion" | "meta" | "long" | "zero" | "worktree" | "plan" | "scheduled" | "monitor";
+
+/** Thread lifecycle states */
+export type ThreadState = "pending" | "running" | "paused" | "completed" | "failed" | "killed" | "needs_input";
+
+/** How a thread is executed */
+export type ExecutionBackend = "subagent" | "native";
+
+/** A single unit of work within a thread */
+export interface ThreadTask {
+	usage?: { inputTokens: number; outputTokens: number; cacheRead: number; totalTokens: number; cost: number };
+	id: string;
+	label: string;
+	prompt: string;
+	model?: string;
+	state: ThreadState;
+	startedAt?: number;
+	completedAt?: number;
+	result?: string;
+	error?: string;
+	/** interactive_shell session ID or subagent run ID */
+	sessionId?: string;
+}
+
+/** Thread configuration */
+export interface ThreadConfig {
+	type: ThreadType;
+	tasks: ThreadTask[];
+	/** Execution backend */
+	backend: ExecutionBackend;
+	/** For fusion threads: models to compete */
+	models?: string[];
+	/** For zero threads: verification command */
+	verifyCommand?: string;
+	/** For chained threads: require human checkpoint between phases */
+	checkpoints?: boolean;
+	/** Working directory */
+	cwd?: string;
+	/** Subagent agent name to use (default: "worker") */
+	agent?: string;
+}
+
+/** A thread — the fundamental unit of tracked work */
+export interface Thread {
+	id: string;
+	type: ThreadType;
+	label: string;
+	state: ThreadState;
+	config: ThreadConfig;
+	tasks: ThreadTask[];
+	createdAt: number;
+	startedAt?: number;
+	completedAt?: number;
+	/** Duration in ms */
+	duration?: number;
+}
+
+/** A story — a goal decomposed into thread phases */
+export interface Story {
+	id: string;
+	goal: string;
+	state: "planning" | "executing" | "verifying" | "done" | "failed";
+	phases: StoryPhase[];
+	createdAt: number;
+	completedAt?: number;
+	/** Verification command */
+	verify?: string;
+	/** Files changed */
+	artifacts: string[];
+}
+
+export interface StoryPhase {
+	name: string;
+	threadType: ThreadType;
+	threadId?: string;
+	state: ThreadState;
+	description: string;
+}
+
+/** Short status line for dashboard */
+export interface ThreadSummary {
+	id: string;
+	type: ThreadType;
+	label: string;
+	state: ThreadState;
+	progress: string;
+	elapsed: string;
+	totalTokens: number;
+	totalCost: number;
+	backend: ExecutionBackend;
+}
+
+/** Thread event for state changes */
+export type ThreadEvent =
+	| { type: "thread_created"; thread: Thread }
+	| { type: "thread_started"; thread: Thread }
+	| { type: "task_started"; thread: Thread; task: ThreadTask }
+	| { type: "task_completed"; thread: Thread; task: ThreadTask }
+	| { type: "task_failed"; thread: Thread; task: ThreadTask }
+	| { type: "thread_completed"; thread: Thread }
+	| { type: "thread_failed"; thread: Thread }
+	| { type: "thread_killed"; thread: Thread }
+	| { type: "story_created"; story: Story }
+	| { type: "story_phase_started"; story: Story; phase: StoryPhase }
+	| { type: "story_completed"; story: Story }
+	| { type: "story_failed"; story: Story };

package/src/core/worktree.ts

@@ -0,0 +1,309 @@
+/**
+ * Worktree management for pi-thread-engine
+ *
+ * Mirrors Grok CLI's `isolation: "worktree"` pattern.
+ * Each worktree gets its own branch + working directory so parallel
+ * agents never conflict on file edits.
+ *
+ * Worktrees stored under `<repo>/.git/worktrees-pi/` for easy cleanup.
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync, mkdirSync, rmSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve, relative, sep, isAbsolute } from "path";
+
+export interface WorktreeInfo {
+	path: string;
+	branch: string;
+	threadId: string;
+	createdAt: number;
+	ahead: number;
+	behind: number;
+	dirty: boolean;
+}
+
+const WORKTREE_DIR = ".git/worktrees-pi";
+let worktreeRegistry: WorktreeInfo[] = [];
+
+function git(args: string[], cwd: string): string {
+	return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+function shortHash(input: string): string {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return (hash >>> 0).toString(36);
+}
+
+function sanitizeThreadId(threadId: string): string {
+	const safe = threadId.replace(/[^a-zA-Z0-9-]/g, "-").replace(/^-+|-+$/g, "");
+	if (!safe) throw new Error("Invalid threadId");
+	const suffix = shortHash(threadId);
+	return safe.length > 48 ? `${safe.slice(0, 48)}-${suffix}` : `${safe}-${suffix}`;
+}
+
+function isContained(parent: string, child: string): boolean {
+	const rel = relative(resolve(parent), resolve(child));
+	return rel === "" || (!rel.startsWith("..") && !rel.includes(`..${sep}`) && !isAbsolute(rel));
+}
+
+function assertContainedWorktreePath(repoPath: string, wtPath: string): string {
+	const root = resolve(repoPath, WORKTREE_DIR);
+	const resolved = resolve(wtPath);
+	if (!isContained(root, resolved)) throw new Error("Worktree path escapes worktree directory");
+	return resolved;
+}
+
+function validateBranchRef(ref: string, cwd: string, label: string): string {
+	if (!ref || ref.startsWith("-") || ref.includes("\0")) throw new Error(`Invalid ${label}`);
+	try {
+		git(["check-ref-format", "--branch", ref], cwd);
+		return ref;
+	} catch {
+		throw new Error(`Invalid ${label}`);
+	}
+}
+
+function validateStartPoint(ref: string, cwd: string, label: string): string {
+	if (!ref || ref.startsWith("-") || /[\0\r\n]/.test(ref)) throw new Error(`Invalid ${label}`);
+	try {
+		git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], cwd);
+		return ref;
+	} catch {
+		throw new Error(`Invalid ${label}`);
+	}
+}
+
+function loadRegistry(repoPath: string): WorktreeInfo[] {
+	const regPath = join(repoPath, WORKTREE_DIR, "registry.json");
+	if (existsSync(regPath)) {
+		try {
+			return JSON.parse(readFileSync(regPath, "utf8"));
+		} catch { /* corrupt, start fresh */ }
+	}
+	return [];
+}
+
+function saveRegistry(repoPath: string, reg: WorktreeInfo[]) {
+	const regDir = join(repoPath, WORKTREE_DIR);
+	if (!existsSync(regDir)) mkdirSync(regDir, { recursive: true });
+	writeFileSync(join(regDir, "registry.json"), JSON.stringify(reg, null, 2), "utf8");
+}
+
+/** Resolve the git repo root from a path */
+export function findRepoRoot(cwd: string): string | null {
+	try {
+		return git(["rev-parse", "--show-toplevel"], cwd);
+	} catch {
+		return null;
+	}
+}
+
+/** Check if we're in a git repo */
+export function isGitRepo(cwd: string): boolean {
+	return findRepoRoot(cwd) !== null;
+}
+
+/** Generate a unique branch name for a thread */
+export function branchName(threadId: string): string {
+	return `pi-thread/${sanitizeThreadId(threadId)}`;
+}
+
+/** Worktree storage path for a thread */
+export function worktreePath(repoPath: string, threadId: string): string {
+	return assertContainedWorktreePath(repoPath, join(repoPath, WORKTREE_DIR, sanitizeThreadId(threadId)));
+}
+
+/**
+ * Create a worktree for a thread.
+ * Creates a new branch off the current HEAD, checks it out in an isolated dir.
+ */
+export function createWorktree(cwd: string, threadId: string, baseBranch?: string): WorktreeInfo {
+	const repoPath = findRepoRoot(cwd);
+	if (!repoPath) throw new Error("Not in a git repository");
+
+	const branch = validateBranchRef(branchName(threadId), repoPath, "branch ref");
+	const base = validateStartPoint(baseBranch ?? "HEAD", repoPath, "base branch ref");
+	const wtPath = worktreePath(repoPath, threadId);
+
+	// Create the branch if it doesn't exist
+	try {
+		git(["branch", branch, base], repoPath);
+	} catch {
+		// Branch may already exist from a previous run — that's fine
+	}
+
+	// Create worktree
+	git(["worktree", "add", wtPath, branch], repoPath);
+
+	const info: WorktreeInfo = {
+		path: wtPath,
+		branch,
+		threadId,
+		createdAt: Date.now(),
+		ahead: 0,
+		behind: 0,
+		dirty: false,
+	};
+
+	const reg = loadRegistry(repoPath);
+	// Remove any stale entry for this thread
+	const filtered = reg.filter((w) => w.threadId !== threadId);
+	filtered.push(info);
+	saveRegistry(repoPath, filtered);
+	worktreeRegistry = filtered;
+
+	return info;
+}
+
+/**
+ * Remove a worktree and its branch
+ */
+export function removeWorktree(cwd: string, threadId: string): boolean {
+	const repoPath = findRepoRoot(cwd);
+	if (!repoPath) return false;
+
+	const branch = validateBranchRef(branchName(threadId), repoPath, "branch ref");
+	const wtPath = worktreePath(repoPath, threadId);
+
+	let success = true;
+
+	// Remove worktree
+	try {
+		git(["worktree", "remove", wtPath], repoPath);
+	} catch {
+		// Force remove if locked
+		try {
+			git(["worktree", "remove", "--force", wtPath], repoPath);
+		} catch {
+			success = false;
+		}
+	}
+
+	// Delete branch
+	try {
+		git(["branch", "-D", branch], repoPath);
+	} catch {
+		// Branch may not exist
+	}
+
+	// Clean up directory after re-checking containment
+	try {
+		rmSync(assertContainedWorktreePath(repoPath, wtPath), { recursive: true, force: true });
+	} catch { /* best effort */ }
+
+	// Update registry
+	const reg = loadRegistry(repoPath);
+	const filtered = reg.filter((w) => w.threadId !== threadId);
+	saveRegistry(repoPath, filtered);
+	worktreeRegistry = filtered;
+
+	return success;
+}
+
+/**
+ * Get divergence stats for a worktree branch
+ */
+function getDivergence(repoPath: string, branch: string): { ahead: number; behind: number } {
+	try {
+		const ref = validateBranchRef(branch, repoPath, "branch ref");
+		const ahead = parseInt(git(["rev-list", "--count", `HEAD..origin/${ref}`], repoPath) || "0", 10);
+		const behind = parseInt(git(["rev-list", "--count", `origin/${ref}..HEAD`], repoPath) || "0", 10);
+		return { ahead, behind };
+	} catch {
+		return { ahead: 0, behind: 0 };
+	}
+}
+
+/**
+ * Check if a worktree has uncommitted changes
+ */
+function isDirty(path: string): boolean {
+	try {
+		const status = git(["status", "--porcelain"], path);
+		return status.length > 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * List all worktrees with their divergence stats
+ */
+export function listWorktrees(cwd: string): WorktreeInfo[] {
+	const repoPath = findRepoRoot(cwd);
+	if (!repoPath) return [];
+
+	const reg = loadRegistry(repoPath);
+
+	// Refresh stats
+	return reg.map((w) => {
+		const div = getDivergence(repoPath, w.branch);
+		const dirty = existsSync(w.path) ? isDirty(w.path) : false;
+		return { ...w, ...div, dirty };
+	});
+}
+
+/**
+ * Collect worktree results — reads the output file from a finished thread
+ */
+export function collectWorktreeResult(threadId: string, worktree: WorktreeInfo): string | null {
+	const resultFile = join(worktree.path, ".pi-thread-result.json");
+	if (existsSync(resultFile)) {
+		try {
+			return readFileSync(resultFile, "utf8");
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
+
+/**
+ * Clean up ALL worktrees for this repo (emergency / force cleanup)
+ */
+export function cleanupAll(cwd: string): { removed: number; failed: number } {
+	const repoPath = findRepoRoot(cwd);
+	if (!repoPath) return { removed: 0, failed: 0 };
+
+	const reg = loadRegistry(repoPath);
+	let removed = 0;
+	let failed = 0;
+
+	for (const w of reg) {
+		if (removeWorktree(cwd, w.threadId)) removed++;
+		else failed++;
+	}
+
+	saveRegistry(repoPath, []);
+	worktreeRegistry = [];
+
+	return { removed, failed };
+}
+
+/**
+ * Push worktree changes back to the main repo
+ */
+export function pushWorktreeChanges(cwd: string, threadId: string, message?: string): boolean {
+	const repoPath = findRepoRoot(cwd);
+	if (!repoPath) return false;
+
+	const wtPath = worktreePath(repoPath, threadId);
+	if (!existsSync(wtPath)) return false;
+
+	try {
+		// Commit any uncommitted changes
+		const status = git(["status", "--porcelain"], wtPath);
+		if (status) {
+			git(["add", "-A"], wtPath);
+			const defaultMsg = `[pi-threads] ${threadId} worktree changes`;
+			git(["commit", "-m", message ?? defaultMsg], wtPath);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}