taskplane 0.1.14 → 0.1.16

package/extensions/taskplane/workspace.ts

@@ -0,0 +1,382 @@
+/**
+ * Workspace configuration loading and validation.
+ *
+ * Detects workspace mode by checking for `.pi/taskplane-workspace.yaml`.
+ * When the file is absent, the orchestrator runs in repo mode (default).
+ * When the file is present, it must be valid — invalid files are fatal.
+ *
+ * Validation order (deterministic, fail-fast):
+ * 1. File existence check → absent = repo mode (return null)
+ * 2. File read → WORKSPACE_FILE_READ_ERROR
+ * 3. YAML parse → WORKSPACE_FILE_PARSE_ERROR
+ * 4. Top-level schema → WORKSPACE_SCHEMA_INVALID
+ * 5. repos map non-empty → WORKSPACE_MISSING_REPOS
+ * 6. Per-repo validation (sorted key order):
+ *    a. path present → WORKSPACE_REPO_PATH_MISSING
+ *    b. path exists on disk → WORKSPACE_REPO_PATH_NOT_FOUND
+ *    c. path is git repo → WORKSPACE_REPO_NOT_GIT
+ * 7. Duplicate repo paths → WORKSPACE_DUPLICATE_REPO_PATH
+ * 8. routing.tasks_root present → WORKSPACE_MISSING_TASKS_ROOT
+ * 9. routing.tasks_root exists → WORKSPACE_TASKS_ROOT_NOT_FOUND
+ * 10. routing.default_repo present → WORKSPACE_MISSING_DEFAULT_REPO
+ * 11. routing.default_repo valid → WORKSPACE_DEFAULT_REPO_NOT_FOUND
+ *
+ * Path normalization rules:
+ * - Relative paths are resolved against workspaceRoot.
+ * - Existing paths are canonicalized via `fs.realpathSync.native()` to
+ *   expand Windows 8.3 short names and resolve symlinks.
+ * - All paths are forward-slash normalized and lowercased for comparison.
+ * - This matches the precedent in `worktree.ts:normalizePath()`.
+ *
+ * Git repo validation:
+ * - Uses `git rev-parse --git-dir` run inside the repo path.
+ * - The path must be the repo root (not a subdirectory).
+ *   We verify by checking that `git rev-parse --show-toplevel` matches
+ *   the canonicalized path.
+ *
+ * @module orch/workspace
+ */
+import { readFileSync, existsSync, realpathSync } from "fs";
+import { resolve } from "path";
+import { parse as yamlParse } from "yaml";
+
+import { runGit } from "./git.ts";
+import {
+	WorkspaceConfigError,
+	workspaceConfigPath,
+	type WorkspaceConfig,
+	type WorkspaceRepoConfig,
+	type WorkspaceRoutingConfig,
+} from "./types.ts";
+
+
+// ── Path Canonicalization ────────────────────────────────────────────
+
+/**
+ * Canonicalize a filesystem path for comparison and storage.
+ *
+ * Reuses the normalization pattern from `worktree.ts:normalizePath()`:
+ * - `realpathSync.native()` expands Windows 8.3 short names when the path exists.
+ * - Falls back to `resolve()` for non-existent paths.
+ * - Forward-slash normalized and lowercased for platform-safe comparison.
+ *
+ * @param p - Path to canonicalize (absolute or relative)
+ * @param base - Base directory for resolving relative paths
+ * @returns Canonical absolute path (forward-slash, lowercased)
+ */
+export function canonicalizePath(p: string, base: string): string {
+	const resolved = resolve(base, p);
+	let expanded: string;
+	try {
+		expanded = realpathSync.native(resolved);
+	} catch {
+		// Path doesn't exist yet — fall back to resolve()
+		expanded = resolved;
+	}
+	return expanded.replace(/\\/g, "/").toLowerCase();
+}
+
+/**
+ * Canonicalize a path for storage (absolute, native separators, resolved symlinks).
+ * Unlike canonicalizePath(), this preserves original case for display/config output.
+ *
+ * @param p - Path to resolve (absolute or relative)
+ * @param base - Base directory for resolving relative paths
+ * @returns Absolute resolved path (native separators preserved)
+ */
+function resolveAbsolutePath(p: string, base: string): string {
+	const resolved = resolve(base, p);
+	try {
+		return realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+
+// ── Workspace Config Loading ─────────────────────────────────────────
+
+/**
+ * Load and validate workspace configuration from `.pi/taskplane-workspace.yaml`.
+ *
+ * Mode determination rules:
+ * 1. No config file → return null (repo mode, non-fatal, silent).
+ * 2. Config file present + invalid → throw WorkspaceConfigError (fatal).
+ * 3. Config file present + valid → return WorkspaceConfig (workspace mode).
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns WorkspaceConfig if workspace mode, null if repo mode
+ * @throws WorkspaceConfigError when config file is present but invalid
+ */
+export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | null {
+	const configFile = workspaceConfigPath(workspaceRoot);
+
+	// ── 1. File existence check ──────────────────────────────────
+	if (!existsSync(configFile)) {
+		return null;
+	}
+
+	// ── 2. File read ─────────────────────────────────────────────
+	let rawContent: string;
+	try {
+		rawContent = readFileSync(configFile, "utf-8");
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new WorkspaceConfigError(
+			"WORKSPACE_FILE_READ_ERROR",
+			`Cannot read workspace config file: ${msg}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 3. YAML parse ────────────────────────────────────────────
+	let parsed: unknown;
+	try {
+		parsed = yamlParse(rawContent);
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new WorkspaceConfigError(
+			"WORKSPACE_FILE_PARSE_ERROR",
+			`Invalid YAML in workspace config: ${msg}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 4. Top-level schema validation ───────────────────────────
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_SCHEMA_INVALID",
+			"Workspace config must be a YAML mapping (object), not a scalar or sequence.",
+			undefined,
+			configFile,
+		);
+	}
+	const doc = parsed as Record<string, unknown>;
+
+	if (!doc.repos || typeof doc.repos !== "object" || Array.isArray(doc.repos)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_SCHEMA_INVALID",
+			"Workspace config must contain a 'repos' mapping.",
+			undefined,
+			configFile,
+		);
+	}
+	if (!doc.routing || typeof doc.routing !== "object" || Array.isArray(doc.routing)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_SCHEMA_INVALID",
+			"Workspace config must contain a 'routing' mapping.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 5. Repos map non-empty ───────────────────────────────────
+	const rawRepos = doc.repos as Record<string, unknown>;
+	const repoKeys = Object.keys(rawRepos).sort(); // deterministic order
+	if (repoKeys.length === 0) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_MISSING_REPOS",
+			"Workspace config must define at least one repo under 'repos'.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 6. Per-repo validation ───────────────────────────────────
+	const repos = new Map<string, WorkspaceRepoConfig>();
+	const normalizedPaths = new Map<string, string>(); // normalized → repoId (for duplicate detection)
+
+	for (const repoId of repoKeys) {
+		const rawRepo = rawRepos[repoId];
+		if (rawRepo == null || typeof rawRepo !== "object" || Array.isArray(rawRepo)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SCHEMA_INVALID",
+				`Repo '${repoId}' must be a YAML mapping with at least a 'path' field.`,
+				repoId,
+				configFile,
+			);
+		}
+		const repoEntry = rawRepo as Record<string, unknown>;
+
+		// 6a. path present and non-empty
+		const rawPath = repoEntry.path;
+		if (!rawPath || typeof rawPath !== "string" || rawPath.trim() === "") {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_REPO_PATH_MISSING",
+				`Repo '${repoId}' is missing a 'path' field.`,
+				repoId,
+				configFile,
+			);
+		}
+
+		// 6b. path exists on disk
+		const absolutePath = resolveAbsolutePath(rawPath.trim(), workspaceRoot);
+		const normalizedPath = canonicalizePath(rawPath.trim(), workspaceRoot);
+		if (!existsSync(absolutePath)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_REPO_PATH_NOT_FOUND",
+				`Repo '${repoId}' path does not exist: ${absolutePath}`,
+				repoId,
+				absolutePath,
+			);
+		}
+
+		// 6c. path is a git repo root
+		const gitDirCheck = runGit(["rev-parse", "--git-dir"], absolutePath);
+		if (!gitDirCheck.ok) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_REPO_NOT_GIT",
+				`Repo '${repoId}' path is not a git repository: ${absolutePath}`,
+				repoId,
+				absolutePath,
+			);
+		}
+		// Verify we're at the root, not a subdirectory
+		const toplevelCheck = runGit(["rev-parse", "--show-toplevel"], absolutePath);
+		if (toplevelCheck.ok) {
+			const toplevelNormalized = canonicalizePath(toplevelCheck.stdout.trim(), "");
+			if (toplevelNormalized !== normalizedPath) {
+				throw new WorkspaceConfigError(
+					"WORKSPACE_REPO_NOT_GIT",
+					`Repo '${repoId}' path is a subdirectory of a git repo, not the repo root. Expected root: ${toplevelCheck.stdout.trim()}, got: ${absolutePath}`,
+					repoId,
+					absolutePath,
+				);
+			}
+		}
+
+		// 7. Collect for duplicate detection (checked after loop)
+		if (normalizedPaths.has(normalizedPath)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_DUPLICATE_REPO_PATH",
+				`Repos '${normalizedPaths.get(normalizedPath)}' and '${repoId}' share the same path: ${absolutePath}`,
+				repoId,
+				absolutePath,
+			);
+		}
+		normalizedPaths.set(normalizedPath, repoId);
+
+		// Build repo config
+		const defaultBranch = typeof repoEntry.default_branch === "string" && repoEntry.default_branch.trim()
+			? repoEntry.default_branch.trim()
+			: undefined;
+
+		repos.set(repoId, {
+			id: repoId,
+			path: absolutePath,
+			defaultBranch,
+		});
+	}
+
+	// ── 8–11. Routing validation ─────────────────────────────────
+	const rawRouting = doc.routing as Record<string, unknown>;
+
+	// 8. routing.tasks_root present
+	const rawTasksRoot = rawRouting.tasks_root;
+	if (!rawTasksRoot || typeof rawTasksRoot !== "string" || rawTasksRoot.trim() === "") {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_MISSING_TASKS_ROOT",
+			"Workspace config 'routing.tasks_root' is missing or empty.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// 9. routing.tasks_root exists on disk
+	const tasksRootAbsolute = resolveAbsolutePath(rawTasksRoot.trim(), workspaceRoot);
+	if (!existsSync(tasksRootAbsolute)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_TASKS_ROOT_NOT_FOUND",
+			`routing.tasks_root path does not exist: ${tasksRootAbsolute}`,
+			undefined,
+			tasksRootAbsolute,
+		);
+	}
+
+	// 10. routing.default_repo present
+	const rawDefaultRepo = rawRouting.default_repo;
+	if (!rawDefaultRepo || typeof rawDefaultRepo !== "string" || rawDefaultRepo.trim() === "") {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_MISSING_DEFAULT_REPO",
+			"Workspace config 'routing.default_repo' is missing or empty.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// 11. routing.default_repo references a valid repo ID
+	const defaultRepoId = rawDefaultRepo.trim();
+	if (!repos.has(defaultRepoId)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_DEFAULT_REPO_NOT_FOUND",
+			`routing.default_repo '${defaultRepoId}' does not match any repo ID. Available repos: ${Array.from(repos.keys()).join(", ")}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── Build routing config ─────────────────────────────────────
+	const routing: WorkspaceRoutingConfig = {
+		tasksRoot: tasksRootAbsolute,
+		defaultRepo: defaultRepoId,
+	};
+
+	// ── Build and return WorkspaceConfig ─────────────────────────
+	return {
+		mode: "workspace",
+		repos,
+		routing,
+		configPath: configFile,
+	};
+}
+
+
+// ── Execution Context Builder ────────────────────────────────────────
+
+/**
+ * Build an ExecutionContext from the current working directory.
+ *
+ * This is the top-level entry point for Step 2 (wire orchestrator startup).
+ * It loads all configs, detects workspace mode, and returns a unified context.
+ *
+ * @param cwd - Current working directory
+ * @param loadOrchConfig - Orchestrator config loader (for testability)
+ * @param loadTaskConfig - Task runner config loader (for testability)
+ * @returns ExecutionContext ready for orchestrator consumption
+ * @throws WorkspaceConfigError if workspace config is present but invalid
+ */
+export function buildExecutionContext(
+	cwd: string,
+	loadOrchConfig: (root: string) => import("./types.ts").OrchestratorConfig,
+	loadTaskConfig: (root: string) => import("./types.ts").TaskRunnerConfig,
+): import("./types.ts").ExecutionContext {
+	const orchestratorConfig = loadOrchConfig(cwd);
+	const taskRunnerConfig = loadTaskConfig(cwd);
+
+	const workspaceConfig = loadWorkspaceConfig(cwd);
+
+	if (workspaceConfig === null) {
+		// Repo mode: cwd is both workspace root and repo root
+		return {
+			workspaceRoot: cwd,
+			repoRoot: cwd,
+			mode: "repo",
+			workspaceConfig: null,
+			taskRunnerConfig,
+			orchestratorConfig,
+		};
+	}
+
+	// Workspace mode: workspace root is cwd, repo root is the default repo
+	const defaultRepo = workspaceConfig.repos.get(workspaceConfig.routing.defaultRepo)!;
+	return {
+		workspaceRoot: cwd,
+		repoRoot: defaultRepo.path,
+		mode: "workspace",
+		workspaceConfig,
+		taskRunnerConfig,
+		orchestratorConfig,
+	};
+}

package/extensions/taskplane/worktree.ts

@@ -2,7 +2,7 @@
  * Worktree CRUD, bulk ops, branch protection, preflight
  * @module orch/worktree
  */
-import { existsSync, readdirSync, realpathSync } from "fs";
+import { existsSync, readdirSync, realpathSync, rmSync } from "fs";
 import { execSync } from "child_process";
 import { join, basename, resolve } from "path";
 
@@ -1103,8 +1103,9 @@ export function escapeRegex(str: string): string {
  *
  * @param count    - Number of worktrees to create (1-indexed: lane 1..count)
  * @param batchId  - Batch ID timestamp for branch naming
- * @param config   - Orchestrator config (prefix, baseBranch extracted from it)
+ * @param config   - Orchestrator config (prefix extracted from it)
  * @param repoRoot - Absolute path to the main repository root
+ * @param baseBranch - Branch to base worktrees on (captured at batch start)
  * @returns        - CreateLaneWorktreesResult with success flag and details
  */
 export function createLaneWorktrees(
@@ -1112,9 +1113,9 @@ export function createLaneWorktrees(
 	batchId: string,
 	config: OrchestratorConfig,
 	repoRoot: string,
+	baseBranch: string,
 ): CreateLaneWorktreesResult {
 	const prefix = config.orchestrator.worktree_prefix;
-	const baseBranch = config.orchestrator.integration_branch;
 	const created: WorktreeInfo[] = [];
 	const errors: BulkWorktreeError[] = [];
 
@@ -1175,7 +1176,7 @@ export function createLaneWorktrees(
  * Ensure required lane worktrees exist for the current wave.
  *
  * Reuses existing worktrees when present (multi-wave behavior), resetting
- * them to integration HEAD before use, and only creates missing lanes.
+ * them to the base branch HEAD before use, and only creates missing lanes.
  * If creation of a missing lane fails, newly-created lanes in this call are
  * rolled back.
  *
@@ -1187,9 +1188,9 @@ export function ensureLaneWorktrees(
 	batchId: string,
 	config: OrchestratorConfig,
 	repoRoot: string,
+	baseBranch: string,
 ): CreateLaneWorktreesResult {
 	const prefix = config.orchestrator.worktree_prefix;
-	const baseBranch = config.orchestrator.integration_branch;
 
 	const existing = listWorktrees(prefix, repoRoot);
 	const existingByLane = new Map<number, WorktreeInfo>();
@@ -1205,7 +1206,7 @@ export function ensureLaneWorktrees(
 	for (const lane of needed) {
 		const reused = existingByLane.get(lane);
 		if (reused) {
-			// Reused worktrees must be reset to integration branch HEAD before use.
+			// Reused worktrees must be reset to base branch HEAD before use.
 			// This covers normal multi-wave reuse and stale leftovers from prior batches.
 			const resetResult = safeResetWorktree(reused, baseBranch, repoRoot);
 			if (resetResult.success) {
@@ -1594,13 +1595,36 @@ export function safeResetWorktree(
 				};
 			}
 
-			// Remove untracked files
+			// Remove untracked files.
+			// git clean may warn about files it can't delete (e.g., Windows reserved
+			// names like "nul", "con", "aux") but still clean everything else.
+			// We treat this as non-fatal: check porcelain status afterward instead
+			// of failing on the exit code.
 			const cleanResult = runGit(["clean", "-fd"], worktree.path);
 			if (!cleanResult.ok) {
-				return {
-					success: false,
-					error: `git clean -fd failed: ${cleanResult.stderr}`,
-				};
+				execLog("reset", `lane-${worktree.laneNumber}`, "git clean -fd returned non-zero (may be partial)", {
+					stderr: cleanResult.stderr.slice(0, 200),
+				});
+			}
+
+			// Check if the worktree is clean enough to proceed.
+			// If git status --porcelain shows no tracked changes, the reset can work
+			// even if some untracked files couldn't be deleted.
+			const statusCheck = runGit(["status", "--porcelain"], worktree.path);
+			if (statusCheck.ok && statusCheck.stdout.length > 0) {
+				// Still dirty after cleaning — check if only untracked files remain
+				const lines = statusCheck.stdout.split("\n").filter(l => l.trim());
+				const onlyUntracked = lines.every(l => l.startsWith("??"));
+				if (!onlyUntracked) {
+					return {
+						success: false,
+						error: `Worktree still dirty after clean: ${statusCheck.stdout.slice(0, 200)}`,
+					};
+				}
+				// Only untracked files remain (e.g., undeletable "nul") — safe to proceed
+				execLog("reset", `lane-${worktree.laneNumber}`, "untracked files remain after clean (non-blocking)", {
+					files: lines.map(l => l.slice(3)).join(", "),
+				});
 			}
 
 			// Retry reset after cleaning
@@ -1622,3 +1646,81 @@ export function safeResetWorktree(
 	}
 }
 
+
+// ── Force Cleanup ────────────────────────────────────────────────────
+
+/**
+ * Last-resort worktree cleanup: force-remove the directory and prune git state.
+ *
+ * Used when both `safeResetWorktree()` and `removeWorktree()` fail — typically
+ * because undeletable files (e.g., Windows reserved names like "nul", "con")
+ * block `git clean` and `git worktree remove`, leaving git in an inconsistent state.
+ *
+ * Recovery steps:
+ * 1. Force-remove the worktree directory (`rm -rf` equivalent)
+ * 2. Prune stale git worktree references (`git worktree prune`)
+ * 3. Delete the lane branch if it exists (`git branch -D`)
+ *
+ * This allows the next wave to recreate the worktree from scratch.
+ *
+ * @param worktree - WorktreeInfo for the failed worktree
+ * @param repoRoot - Main repository root
+ * @param batchId  - Batch ID for logging context
+ */
+export function forceCleanupWorktree(
+	worktree: WorktreeInfo,
+	repoRoot: string,
+	batchId: string,
+): void {
+	const { path: worktreePath, branch, laneNumber } = worktree;
+
+	// Step 1: Force-remove the directory
+	if (existsSync(worktreePath)) {
+		try {
+			// On Windows, undeletable reserved-name files (nul, con, aux) need
+			// special handling. Try rmSync first, then fall back to OS-specific
+			// removal for stubborn files.
+			rmSync(worktreePath, { recursive: true, force: true });
+			execLog("cleanup", `lane-${laneNumber}`, `force-removed worktree directory`, { path: worktreePath });
+		} catch (rmErr: unknown) {
+			// If Node's rmSync fails (e.g., Windows reserved names), try platform-specific
+			const rmMsg = rmErr instanceof Error ? rmErr.message : String(rmErr);
+			execLog("cleanup", `lane-${laneNumber}`, `rmSync failed, trying OS-level removal`, { error: rmMsg });
+
+			try {
+				if (process.platform === "win32") {
+					// rd /s /q handles Windows reserved names that Node.js cannot delete
+					execSync(`rd /s /q "${worktreePath}"`, { stdio: "pipe", timeout: 30_000 });
+				} else {
+					execSync(`rm -rf "${worktreePath}"`, { stdio: "pipe", timeout: 30_000 });
+				}
+				execLog("cleanup", `lane-${laneNumber}`, `OS-level removal succeeded`, { path: worktreePath });
+			} catch (osErr: unknown) {
+				const osMsg = osErr instanceof Error ? osErr.message : String(osErr);
+				execLog("cleanup", `lane-${laneNumber}`, `OS-level removal also failed — manual cleanup needed`, {
+					path: worktreePath,
+					error: osMsg,
+				});
+			}
+		}
+	}
+
+	// Step 2: Prune stale worktree references
+	runGit(["worktree", "prune"], repoRoot);
+	execLog("cleanup", `lane-${laneNumber}`, `pruned stale worktree references`);
+
+	// Step 3: Delete the lane branch if it still exists
+	const branchCheck = runGit(["rev-parse", "--verify", `refs/heads/${branch}`], repoRoot);
+	if (branchCheck.ok) {
+		const deleteResult = runGit(["branch", "-D", branch], repoRoot);
+		if (deleteResult.ok) {
+			execLog("cleanup", `lane-${laneNumber}`, `deleted stale lane branch`, { branch });
+		} else {
+			execLog("cleanup", `lane-${laneNumber}`, `could not delete lane branch`, {
+				branch,
+				error: deleteResult.stderr,
+			});
+		}
+	}
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",