dorfl 0.10.0 → 0.10.1

package/src/gc.ts

@@ -1,4 +1,4 @@
-import {existsSync, readdirSync, statSync} from 'node:fs';
+import {existsSync, lstatSync, readdirSync, rmSync, statSync} from 'node:fs';
 import {join} from 'node:path';
 import {git, run} from './git.js';
 import {
@@ -261,11 +261,29 @@ export interface GcOptions {
 	env?: NodeJS.ProcessEnv;
 }
 
+/**
+ * An ORPHAN `<workspacesDir>/work/*` entry `gc` swept: a path git never
+ * registered as a worktree and that carries NO job record — a dangling symlink,
+ * or a bare directory left by a run that crashed BEFORE `git worktree add`
+ * registered it (an early `spawn git ENOENT`). It holds no durable work, so it is
+ * always safe to remove; sweeping it self-heals a half-set-up claim instead of
+ * leaving it to wedge the next `worktree add` ("already exists") until a human
+ * `rm`s it. Reported SEPARATELY from reaped jobs (it was never a real job).
+ */
+export interface SweptOrphan {
+	/** Absolute path to the orphan entry that was removed. */
+	dir: string;
+	/** Whether the orphan was a dangling symlink or an un-registered directory. */
+	kind: 'dangling-symlink' | 'orphan-dir';
+}
+
 export interface GcResult {
 	/** The worktrees reaped this sweep (provably safe, or forced). */
 	reaped: ReapedJob[];
 	/** The worktrees retained, each with a clear reason. */
 	retained: RetainedJob[];
+	/** Record-less orphan `work/*` entries swept (dangling symlinks / orphan dirs). */
+	sweptOrphans: SweptOrphan[];
 }
 
 /**
@@ -284,6 +302,11 @@ export function gc(options: GcOptions): GcResult {
 	const reaped: ReapedJob[] = [];
 	const retained: RetainedJob[] = [];
 
+	// First, self-heal any record-less ORPHAN `work/*` entry (a dangling symlink
+	// or a dir git never registered) so a half-set-up claim does not linger unseen
+	// by the job loop below and wedge the next `worktree add`.
+	const sweptOrphans = sweepOrphans(options.workspacesDir, note);
+
 	for (const job of discoverJobs(options.workspacesDir)) {
 		const mirrorPath = resolveMirrorPath(options.workspacesDir, job);
 		const result = reapJob({
@@ -310,7 +333,77 @@ export function gc(options: GcOptions): GcResult {
 		note(`Retained ${job.slug}: ${reasonText}.`);
 	}
 
-	return {reaped, retained};
+	return {reaped, retained, sweptOrphans};
+}
+
+/**
+ * Sweep record-less ORPHAN entries under `<workspacesDir>/work/*`: a DANGLING
+ * SYMLINK (its target gone) or a directory with NO job record at either the
+ * sibling or legacy in-tree location. These are the residue of a run that
+ * crashed BETWEEN creating the `work/<id>` path and registering it as a git
+ * worktree (or writing its record) — e.g. an early `spawn git ENOENT`. They hold
+ * no durable work, are invisible to {@link discoverJobs} (which requires a
+ * record), and block the next same-id `worktree add`. Removing them is a bounded
+ * `rmSync` of ONE path each (never a registered worktree — those carry a record
+ * and go through the reap predicate). Best-effort per entry.
+ */
+function sweepOrphans(
+	workspacesDir: string,
+	note: (message: string) => void,
+): SweptOrphan[] {
+	const workDir = join(workspacesDir, 'work');
+	if (!existsSync(workDir)) {
+		return [];
+	}
+	const swept: SweptOrphan[] = [];
+	for (const entry of readdirSync(workDir)) {
+		if (entry.endsWith('.json')) {
+			continue; // a sibling record file, not a work-id entry
+		}
+		const dir = join(workDir, entry);
+		let link;
+		try {
+			link = lstatSync(dir);
+		} catch {
+			continue; // vanished under us
+		}
+		const isSymlink = link.isSymbolicLink();
+		const targetExists = existsSync(dir); // follows the link; false ⇒ dangling
+		const hasRecord =
+			existsSync(jobRecordPath(dir)) ||
+			(targetExists && existsSync(join(dir, JOB_RECORD_FILENAME)));
+		// Orphan iff: a dangling symlink (target gone), OR a record-less entry that
+		// is not a live directory git could own (a stray symlink-to-elsewhere, or a
+		// dir with no record). A record-bearing entry is a real job → leave it to the
+		// reap predicate above.
+		const danglingSymlink = isSymlink && !targetExists;
+		if (hasRecord) {
+			continue;
+		}
+		if (!danglingSymlink) {
+			// A record-less real directory: only sweep it if git does not track it as a
+			// worktree here. `discoverJobs` already skips it (no record), and a
+			// registered worktree always has our record, so a record-less dir is an
+			// orphan. But be conservative: skip a NON-symlink dir that is not empty of
+			// a `.git` pointer only when it looks like a crashed pre-register dir.
+			if (isSymlink && targetExists) {
+				// symlink to a live path but no record → still an orphan link
+			} else if (!link.isDirectory()) {
+				continue; // not a dir, not a dangling link — leave alone
+			} else if (existsSync(join(dir, '.git'))) {
+				continue; // has a git pointer but no record: leave for a human (rare)
+			}
+		}
+		try {
+			rmSync(dir, {recursive: true, force: true});
+			const kind = danglingSymlink ? 'dangling-symlink' : 'orphan-dir';
+			swept.push({dir, kind});
+			note(`Swept orphan work entry ${entry} (${kind}).`);
+		} catch {
+			// best-effort: a permission error surfaces on the next add attempt
+		}
+	}
+	return swept;
 }
 
 /**

package/src/git.ts

@@ -1,6 +1,6 @@
 import {spawnSync, spawn} from 'node:child_process';
-import {mkdirSync} from 'node:fs';
-import {dirname} from 'node:path';
+import {existsSync, mkdirSync, statSync} from 'node:fs';
+import {delimiter, dirname, isAbsolute, join} from 'node:path';
 
 /** Result of running a git (or any) command. */
 export interface RunResult {
@@ -9,6 +9,176 @@ export interface RunResult {
 	stderr: string;
 }
 
+/**
+ * The standard system dirs core tools (`git`, `ssh`, `sh`) live in. Some callers
+ * launch `dorfl` with a CURATED `PATH` (a version-manager / MCP-agent env that
+ * lists only `~/.volta/bin`, `~/.cargo/bin`, `~/.local/bin`, …) that OMITS these.
+ * `dorfl` spawns bare `git` (and git in turn may shell out to `ssh`/`sh` for
+ * hooks and remote transport), so a `PATH` missing `/usr/bin` produces an opaque
+ * mid-run `spawn git ENOENT`. We UNION these onto whatever `PATH` we are given so
+ * core tools resolve even under a curated caller `PATH`, without discarding the
+ * caller's own entries (a project-pinned `git` earlier on `PATH` still wins).
+ */
+const SYSTEM_PATH_DIRS = [
+	'/usr/local/bin',
+	'/usr/bin',
+	'/bin',
+	'/usr/sbin',
+	'/sbin',
+];
+
+/**
+ * `PATH` with {@link SYSTEM_PATH_DIRS} APPENDED (caller entries kept FIRST, so a
+ * pinned tool earlier on `PATH` still wins; missing system dirs are added, not
+ * substituted). Deduplicated, preserving first-seen order.
+ */
+function pathWithSystemDirs(path: string | undefined): string {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const dir of [
+		...(path ? path.split(delimiter) : []),
+		...SYSTEM_PATH_DIRS,
+	]) {
+		if (dir !== '' && !seen.has(dir)) {
+			seen.add(dir);
+			out.push(dir);
+		}
+	}
+	return out.join(delimiter);
+}
+
+/**
+ * Return `env` with `PATH` hardened via {@link pathWithSystemDirs}, so the
+ * spawned tool (and any tool IT shells out to) can find core system binaries
+ * even when the caller's `PATH` omitted `/usr/bin`. Returns a COPY — never
+ * mutates the caller's env object. `PATH` is looked up case-insensitively so a
+ * Windows `Path`/`PATH` split is not silently missed.
+ */
+function envWithSystemPath(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const key =
+		Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH';
+	return {...env, [key]: pathWithSystemDirs(env[key])};
+}
+
+/**
+ * Per-effective-PATH cache of the resolved absolute `git` path. Keyed by the
+ * effective PATH (+ any `DORFL_GIT`/`GIT` override) so a DIFFERENT env — e.g. a
+ * test's PATH-prepended `git` shim, or a project that pins its own git — is
+ * resolved AGAINST ITS OWN PATH, never masked by a stale global memo. Bounded in
+ * practice (the process uses a handful of distinct envs) and reset in tests.
+ */
+const gitBinaryCache = new Map<string, string>();
+
+/** Clear the {@link resolveGitBinary} cache (tests only). */
+export function resetResolvedGitBinaryForTest(): void {
+	gitBinaryCache.clear();
+}
+
+/**
+ * Resolve the `git` executable to an ABSOLUTE path for a given `env`, robustly —
+ * so a caller `PATH` that omits `/usr/bin` cannot produce a mid-run `spawn git
+ * ENOENT`, WITHOUT masking a git the caller deliberately put earlier on `PATH`
+ * (a project pin, or a test shim). Order:
+ *
+ *   1. an explicit `DORFL_GIT` / `GIT` env override (an absolute path to a git
+ *      binary), for full operator control;
+ *   2. a probe of the env's OWN `PATH` FIRST (so a shim / pinned git earlier on
+ *      `PATH` wins), then the standard system dirs APPENDED — so `/usr/bin/git`
+ *      is still found when the caller dropped `/usr/bin`, but never AHEAD of the
+ *      caller's own entries.
+ *
+ * Falls back to the bare name `'git'` when nothing resolves (git genuinely
+ * absent) so the spawn still runs and produces the diagnostic path. Cached PER
+ * effective PATH so distinct envs resolve independently.
+ */
+export function resolveGitBinary(env: NodeJS.ProcessEnv = process.env): string {
+	const pathValue = pathWithSystemDirs(env.PATH);
+	const cacheKey = `${env.DORFL_GIT ?? ''}\u0000${env.GIT ?? ''}\u0000${pathValue}`;
+	const cached = gitBinaryCache.get(cacheKey);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const resolved = resolveGitBinaryUncached(env, pathValue);
+	gitBinaryCache.set(cacheKey, resolved);
+	return resolved;
+}
+
+function resolveGitBinaryUncached(
+	env: NodeJS.ProcessEnv,
+	pathValue: string,
+): string {
+	for (const override of [env.DORFL_GIT, env.GIT]) {
+		if (override && isAbsolute(override) && isExecutableFile(override)) {
+			return override;
+		}
+	}
+	const exe = process.platform === 'win32' ? 'git.exe' : 'git';
+	for (const dir of pathValue.split(delimiter)) {
+		const candidate = join(dir, exe);
+		if (isExecutableFile(candidate)) {
+			return candidate;
+		}
+	}
+	return 'git'; // unresolved — let the spawn surface the ENOENT diagnostic
+}
+
+/** True iff `path` is a regular file (a symlink target is followed by statSync). */
+function isExecutableFile(path: string): boolean {
+	try {
+		return existsSync(path) && statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Resolve a command + harden its spawn env: bare `'git'` is replaced by the
+ * absolute {@link resolveGitBinary} path, and the spawn env's `PATH` is unioned
+ * with the standard system dirs so git's own child processes (hooks, `ssh`) also
+ * resolve. Any OTHER command is passed through unchanged (only its `PATH` is
+ * hardened). This is the single choke-point both {@link run} and
+ * {@link runAsync} funnel through, so every git spawn in the codebase inherits
+ * the robust resolution for free.
+ */
+function resolveSpawn(
+	command: string,
+	env: NodeJS.ProcessEnv,
+): {command: string; env: NodeJS.ProcessEnv} {
+	const hardenedEnv = envWithSystemPath(env);
+	const resolved = command === 'git' ? resolveGitBinary(hardenedEnv) : command;
+	return {command: resolved, env: hardenedEnv};
+}
+
+/**
+ * Build the spawn-failure message. A plain `spawn git ENOENT` is OPAQUE (it does
+ * not say WHY git was not found); for the `ENOENT` case we surface the effective
+ * `PATH` and point at `DORFL_GIT`, so a curated caller `PATH` that omits the
+ * system dirs is diagnosable at a glance instead of mid-run. Other spawn errors
+ * pass through with the original message.
+ */
+function spawnErrorMessage(
+	command: string,
+	resolved: string,
+	env: NodeJS.ProcessEnv,
+	err: Error & {code?: string},
+): string {
+	if (err.code === 'ENOENT') {
+		const path =
+			env[Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH'] ??
+			'';
+		const hint =
+			command === 'git'
+				? `Is git installed and on PATH? Set DORFL_GIT to an absolute git path, or add its dir to PATH. `
+				: `Is it installed and on PATH? `;
+		return (
+			`failed to spawn '${command}': not found (tried '${resolved}'). ` +
+			hint +
+			`Effective PATH=${path}`
+		);
+	}
+	return `failed to spawn '${command}': ${err.message}`;
+}
+
 /**
  * Run a command synchronously in `cwd`, capturing output. A non-zero exit is NOT
  * thrown here — callers inspect `status` (claim.sh's exit codes are meaningful).
@@ -19,15 +189,16 @@ export function run(
 	cwd: string,
 	options: {input?: string; env?: NodeJS.ProcessEnv} = {},
 ): RunResult {
-	const result = spawnSync(command, args, {
+	const {command: exe, env} = resolveSpawn(command, options.env ?? process.env);
+	const result = spawnSync(exe, args, {
 		cwd,
 		encoding: 'utf8',
 		input: options.input,
-		env: options.env ?? process.env,
+		env,
 		maxBuffer: 64 * 1024 * 1024,
 	});
 	if (result.error) {
-		throw new Error(`failed to spawn '${command}': ${result.error.message}`);
+		throw new Error(spawnErrorMessage(command, exe, env, result.error));
 	}
 	return {
 		status: result.status ?? -1,
@@ -47,10 +218,11 @@ export function runAsync(
 	cwd: string,
 	options: {input?: string; env?: NodeJS.ProcessEnv} = {},
 ): Promise<RunResult> {
+	const {command: exe, env} = resolveSpawn(command, options.env ?? process.env);
 	return new Promise((resolvePromise, reject) => {
-		const child = spawn(command, args, {
+		const child = spawn(exe, args, {
 			cwd,
-			env: options.env ?? process.env,
+			env,
 		});
 		let stdout = '';
 		let stderr = '';
@@ -61,7 +233,7 @@ export function runAsync(
 			stderr += chunk.toString('utf8');
 		});
 		child.on('error', (err) =>
-			reject(new Error(`failed to spawn '${command}': ${err.message}`)),
+			reject(new Error(spawnErrorMessage(command, exe, env, err))),
 		);
 		child.on('close', (code) => {
 			resolvePromise({status: code ?? -1, stdout, stderr});

package/src/workspace.ts

@@ -1,4 +1,10 @@
-import {existsSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {
+	existsSync,
+	lstatSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
 import {basename, dirname, join} from 'node:path';
 import {git} from './git.js';
 import {
@@ -440,21 +446,80 @@ export function updateJobRecord(
 	return next;
 }
 
-/** Remove a stale worktree dir / branch registration before re-creating. */
-function clearStale(
+/**
+ * Clear a stale worktree PATH the contract-safe way, SELF-HEALING a half-set-up
+ * claim. `git worktree remove --force` is the normal path, but it REFUSES with
+ * "is not a working tree" when `dir` is a leftover that git never registered — a
+ * dangling `~/.dorfl/work/<id>` SYMLINK, or a bare directory from a run that
+ * crashed AFTER the path appeared but BEFORE `git worktree add` registered it
+ * (an early `spawn git ENOENT`, exactly the failure this whole change targets).
+ * In that case git's own removal + `worktree prune` both leave the path in place,
+ * so the NEXT `git worktree add <dir>` fails "already exists" and the claim is
+ * wedged until a human `rm`s it by hand.
+ *
+ * So: if after the git removal the path STILL EXISTS and is NOT a live
+ * registered worktree, fall back to a BOUNDED `rmSync` of that one path. This is
+ * ADR §4-safe — we only ever `rm` a path git ITSELF refused to manage and that
+ * carries no registered worktree (no durable work to lose): a broken symlink, or
+ * an orphaned dir git does not know about. A genuinely registered worktree is
+ * removed by git and never reaches the `rmSync`.
+ */
+function forceClearWorktreePath(
 	mirrorPath: string,
 	dir: string,
-	branch: string,
 	env: NodeJS.ProcessEnv | undefined,
 ): void {
-	if (existsSync(dir)) {
-		// Soft-remove: ignore errors (e.g. the dir is not a registered worktree).
+	if (!pathPresent(dir)) {
+		return;
+	}
+	// Soft-remove: ignore errors (e.g. the dir is not a registered worktree).
+	try {
+		git(['worktree', 'remove', '--force', dir], mirrorPath, {env});
+	} catch {
+		// fall through to the prune + orphan-rm below
+	}
+	try {
+		git(['worktree', 'prune'], mirrorPath, {env});
+	} catch {
+		// best-effort
+	}
+	// If the path survived git's removal + prune it is an ORPHAN git will not
+	// manage (a dangling symlink / an un-registered dir). Remove that one path so
+	// the re-create's `worktree add` is not blocked. Never recurse into a
+	// registered worktree (git already handled those).
+	if (pathPresent(dir)) {
 		try {
-			git(['worktree', 'remove', '--force', dir], mirrorPath, {env});
+			rmSync(dir, {recursive: true, force: true});
 		} catch {
-			// fall through to prune below
+			// best-effort: a genuine permission error surfaces on the next add
 		}
 	}
+}
+
+/**
+ * True iff `dir` EXISTS as a path entry — including a DANGLING symlink (whose
+ * target is gone). `existsSync` follows symlinks so it returns `false` for a
+ * broken one, which would let an orphaned `~/.dorfl/work/<id>` symlink slip past
+ * the cleanup; `lstatSync` inspects the LINK itself, so a dangling symlink is
+ * still seen (and removed).
+ */
+function pathPresent(dir: string): boolean {
+	try {
+		lstatSync(dir);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Remove a stale worktree dir / branch registration before re-creating. */
+function clearStale(
+	mirrorPath: string,
+	dir: string,
+	branch: string,
+	env: NodeJS.ProcessEnv | undefined,
+): void {
+	forceClearWorktreePath(mirrorPath, dir, env);
 	pruneAndDropBranch(mirrorPath, branch, env);
 }
 
@@ -469,18 +534,7 @@ function clearStaleWorktreeOnly(
 	dir: string,
 	env: NodeJS.ProcessEnv | undefined,
 ): void {
-	if (existsSync(dir)) {
-		try {
-			git(['worktree', 'remove', '--force', dir], mirrorPath, {env});
-		} catch {
-			// fall through to prune below
-		}
-	}
-	try {
-		git(['worktree', 'prune'], mirrorPath, {env});
-	} catch {
-		// best-effort
-	}
+	forceClearWorktreePath(mirrorPath, dir, env);
 }
 
 /** Prune dangling worktree registrations + delete the work branch if present. */