forge-workflow 0.1.0-beta.4 → 0.1.0-beta.5

package/lib/commands/worktree.js

@@ -3,7 +3,12 @@
 const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { detectDefaultBranch } = require('../beads-sync-scaffold');
+const { detectDefaultBranch } = require('../git-defaults');
+const {
+  resolveRepoRelativePath,
+  assertNoAncestorSymlinkEscape,
+  assertNoSymlinkEscape,
+} = require('../protected-state-surfaces');
 
 /**
  * Forge Worktree Command
@@ -42,12 +47,13 @@ function detectPackageManager(projectRoot, fsApi) {
 /**
  * Check if a git branch already exists.
  * @param {string} branchName - Branch name to check
+ * @param {string} projectRoot - Repo root to run git in
  * @param {Function} runFile - execFileSync function (for DI)
  * @returns {boolean}
  */
-function branchExists(branchName, runFile) {
+function branchExists(branchName, projectRoot, runFile) {
   try {
-    const output = runFile('git', ['branch', '--list', branchName], { stdio: 'pipe' });
+    const output = runFile('git', ['-C', projectRoot, 'branch', '--list', branchName], { stdio: 'pipe' });
     return output.toString().trim().length > 0;
   } catch (_err) { /* intentional: branch doesn't exist */ // NOSONAR S2486
     return false;
@@ -99,35 +105,118 @@ function isLinkPermissionError(error) {
   return ['EPERM', 'EACCES', 'ENOSYS', 'UV_EPERM'].includes(error && error.code);
 }
 
+// Yarn is probe-less here: a Plug'n'Play install produces no node_modules tree to
+// inspect, and `yarn check` was removed in Berry, so there is nothing to verify.
+const PROBE_LESS_MANAGERS = new Set(['yarn']);
+
 /**
- * Run package install in the new worktree if a package manager is detected, and
- * SURFACE failures (spawn error or non-zero exit) instead of swallowing them.
- * @param {string} worktreePath - Absolute path to the new worktree
- * @param {string} projectRoot - Absolute path to the project root
- * @param {Function} spawnFn - spawnSync-compatible function
+ * Direct dependencies the worktree declares. Optional/peer deps are excluded —
+ * they may legitimately be absent. An unreadable package.json yields none, so an
+ * unverifiable worktree is left alone rather than force-reinstalled.
+ * @param {string} worktreePath - Absolute path to the worktree
  * @param {object} fsApi - fs module (for DI)
- * @returns {{ linked: boolean, installed: boolean }}
- * @throws {Error} when the install cannot be spawned or exits non-zero.
+ * @returns {string[]} Declared package names
  */
-function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
-  const pkgManager = detectPackageManager(projectRoot, fsApi);
-  if (!pkgManager) return { linked: false, installed: false };
+function declaredDependencies(worktreePath, fsApi) {
+  try {
+    const pkg = JSON.parse(fsApi.readFileSync(path.join(worktreePath, 'package.json'), 'utf8'));
+    return [...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.devDependencies || {})];
+  } catch (_err) { /* intentional: no readable package.json → nothing to verify */ // NOSONAR S2486
+    return [];
+  }
+}
 
+/**
+ * Verify the install actually landed: every declared direct dependency must be a
+ * real package in the worktree's node_modules.
+ *
+ * The package managers cannot answer this. `bun pm ls`, `bun list`, `bun pm why`
+ * and `bun install --dry-run` all read the LOCKFILE and exit 0 while packages are
+ * physically missing; `pnpm ls --depth=0` does the same; `bun -e require.resolve`
+ * is defeated by Bun's auto-install. Only `npm ls --depth=0` exits non-zero, so a
+ * filesystem check is the one probe that holds for every manager.
+ *
+ * @param {string} worktreePath - Absolute path to the worktree
+ * @param {object} fsApi - fs module (for DI)
+ * @returns {boolean} true when nothing is missing
+ */
+function dependenciesPresent(worktreePath, fsApi) {
+  const deps = declaredDependencies(worktreePath, fsApi);
+  return deps.every((name) => fsApi.existsSync(path.join(worktreePath, 'node_modules', name, 'package.json')));
+}
+
+const STDERR_DETAIL_LIMIT = 400;
+
+/**
+ * The install's captured stderr, trimmed and bounded — stdio 'pipe' otherwise
+ * hides why the install failed.
+ * @param {object} result - spawnSync result
+ * @returns {string} A leading-newline detail block, or '' when there is nothing
+ */
+function stderrDetail(result) {
+  const text = result && result.stderr ? String(result.stderr).trim() : '';
+  if (!text) return '';
+  return `\n${text.length > STDERR_DETAIL_LIMIT ? `${text.slice(0, STDERR_DETAIL_LIMIT)}...` : text}`;
+}
+
+/**
+ * Spawn one install, surfacing spawn errors, kills, and non-zero exits.
+ * @param {string} pkgManager - Detected package manager command
+ * @param {string[]} args - Install args (e.g. ['install'] or ['install', '--force'])
+ * @param {string} worktreePath - cwd for the install
+ * @param {Function} spawnFn - spawnSync-compatible function
+ * @throws {Error} when the install cannot be spawned, is killed, or exits non-zero.
+ */
+function spawnInstall(pkgManager, args, worktreePath, spawnFn) {
   // shell:true on Windows: npm/pnpm/yarn are .cmd shims that cannot be spawned
   // directly (ENOENT / EINVAL). pkgManager comes from lockfile detection (fixed
   // set) and args are hardcoded, so no user input reaches the shell.
-  const result = spawnFn(pkgManager, ['install'], {
+  const result = spawnFn(pkgManager, args, {
     cwd: worktreePath,
     stdio: 'pipe',
     shell: process.platform === 'win32',
   });
+  const label = `${pkgManager} ${args.join(' ')}`;
   if (result && result.error) {
-    throw new Error(`Dependency install failed: could not run '${pkgManager} install' in ${worktreePath}: ${result.error.message}`);
+    throw new Error(`Dependency install failed: could not run '${label}' in ${worktreePath}: ${result.error.message}${stderrDetail(result)}`);
+  }
+  // A killed install (OOM, SIGTERM, CI cancel) reports status null with a signal
+  // set — never a non-zero code — so it must be checked on its own.
+  if (result && result.signal) {
+    throw new Error(`Dependency install failed: '${label}' was killed by ${result.signal} in ${worktreePath}${stderrDetail(result)}`);
   }
   if (result && typeof result.status === 'number' && result.status !== 0) {
-    throw new Error(`Dependency install failed: '${pkgManager} install' exited with code ${result.status} in ${worktreePath}`);
+    throw new Error(`Dependency install failed: '${label}' exited with code ${result.status} in ${worktreePath}${stderrDetail(result)}`);
   }
-  return { linked: false, installed: true };
+}
+
+/**
+ * Run package install in the new worktree if a package manager is detected, then
+ * VERIFY it. A stale shared store makes a plain install report "no changes" while
+ * leaving packages and binaries missing, so the exit code alone is not evidence —
+ * on a failed probe, reinstall once with --force and re-probe.
+ * @param {string} worktreePath - Absolute path to the new worktree
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {Function} spawnFn - spawnSync-compatible function
+ * @param {object} fsApi - fs module (for DI)
+ * @returns {{ linked: boolean, installed: boolean, healed: boolean }}
+ * @throws {Error} when the install fails, or the tree is still broken after --force.
+ */
+function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
+  const pkgManager = detectPackageManager(projectRoot, fsApi);
+  if (!pkgManager) return { linked: false, installed: false, healed: false };
+
+  spawnInstall(pkgManager, ['install'], worktreePath, spawnFn);
+
+  if (PROBE_LESS_MANAGERS.has(pkgManager) || dependenciesPresent(worktreePath, fsApi)) {
+    return { linked: false, installed: true, healed: false };
+  }
+
+  spawnInstall(pkgManager, ['install', '--force'], worktreePath, spawnFn);
+  if (!dependenciesPresent(worktreePath, fsApi)) {
+    throw new Error(`Dependency install could not be verified: packages are still missing in ${worktreePath} after '${pkgManager} install --force'. Run it manually there and inspect the output.`);
+  }
+  return { linked: false, installed: true, healed: true };
 }
 
 /**
@@ -142,7 +231,7 @@ function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
  * @param {Function} deps.spawnFn - spawnSync-compatible function
  * @param {object} deps.fsApi - fs module (for DI)
  * @param {string} deps.platform - process.platform value
- * @returns {{ linked: boolean, installed: boolean }}
+ * @returns {{ linked: boolean, installed: boolean, healed: boolean }}
  * @throws {Error} when linking fails for a non-privilege reason or install fails.
  */
 function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform }) {
@@ -150,14 +239,14 @@ function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform
   const destModules = path.join(worktreePath, 'node_modules');
 
   // Already populated (e.g. git checkout carried it) — nothing to do.
-  if (fsApi.existsSync(destModules)) return { linked: false, installed: false };
+  if (fsApi.existsSync(destModules)) return { linked: false, installed: false, healed: false };
 
   // Fast path: link to the shared install when the main repo has one.
   if (fsApi.existsSync(srcModules)) {
     const linkType = platform === 'win32' ? 'junction' : 'dir';
     try {
       fsApi.symlinkSync(srcModules, destModules, linkType);
-      return { linked: true, installed: false };
+      return { linked: true, installed: false, healed: false };
     } catch (error) {
       // Degrade to a real install only when the link was refused for lack of
       // privilege/support; any other failure is surfaced to the caller.
@@ -168,6 +257,72 @@ function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform
   return runInstall(worktreePath, projectRoot, spawnFn, fsApi);
 }
 
+function readExistingWorktreeLinkage(driver, worktreePath, reuse) {
+  if (!reuse || !driver || typeof driver.getWorktreeLinkage !== 'function') return null;
+  return driver.getWorktreeLinkage({ path: worktreePath }) || null;
+}
+
+function detectLinkageConflict({ projectRoot, existing, issueId, workFolder, reuse }) {
+  if (!reuse || !existing) return null;
+  const existingIssue = existing.issue_id || null;
+  const existingFolder = existing.work_folder || null;
+  const folderChanged = workFolder && existingFolder
+    && path.resolve(projectRoot, workFolder) !== path.resolve(projectRoot, existingFolder);
+  if (!((issueId && existingIssue && issueId !== existingIssue) || folderChanged)) return null;
+  return {
+    issueId: issueId || existingIssue,
+    workFolder: workFolder || existingFolder,
+    reason: 'worktree linkage mismatch; existing issue/work-folder was not changed',
+    conflict: true,
+  };
+}
+
+function isAbsoluteWorkFolder(workFolder) {
+  return path.isAbsolute(workFolder) || path.posix.isAbsolute(workFolder) || path.win32.isAbsolute(workFolder);
+}
+
+function markerPathConflict(reason) {
+  return { conflict: true, reason: `worktree linkage marker path rejected: ${reason}` };
+}
+
+function validateMarkerTarget(projectRoot, workFolder, fsApi) {
+  if (!workFolder) return null;
+  if (isAbsoluteWorkFolder(workFolder)) return markerPathConflict('work-folder must be repo-relative');
+
+  const resolved = resolveRepoRelativePath(projectRoot, workFolder);
+  if (!resolved.insideRoot) return markerPathConflict('work-folder escapes project root');
+  const ancestorEscape = assertNoAncestorSymlinkEscape(resolved.root, resolved.target);
+  if (ancestorEscape) return markerPathConflict(ancestorEscape.reason);
+
+  const statSync = fsApi.statSync || fs.statSync;
+  const folderStat = fsApi.existsSync(resolved.target) ? statSync.call(fsApi, resolved.target) : null;
+  if (folderStat && !folderStat.isDirectory()) return markerPathConflict('work-folder is not a directory');
+  const markerPath = path.join(resolved.target, '.forge-issue');
+  const markerEscape = assertNoSymlinkEscape(resolved.root, markerPath);
+  if (markerEscape) {
+    return markerPathConflict(markerEscape.reason);
+  }
+  return { folderAbs: resolved.target, markerPath, folderExists: Boolean(folderStat) };
+}
+
+function reconcileIssueMarker({ target, linkedIssue, linkedFolder, fsApi }) {
+  if (!target || !linkedIssue || !target.folderExists) return null;
+  let markerIssue = null;
+  try {
+    if (fsApi.existsSync(target.markerPath)) markerIssue = fsApi.readFileSync(target.markerPath, 'utf8').trim() || null;
+  } catch { /* unreadable marker — let the write below repair it */ }
+  if (markerIssue && markerIssue !== linkedIssue) {
+    return {
+      issueId: linkedIssue,
+      workFolder: linkedFolder,
+      reason: 'worktree linkage mismatch; existing issue marker was not changed',
+      conflict: true,
+    };
+  }
+  fsApi.writeFileSync(target.markerPath, `${linkedIssue}\n`, 'utf8');
+  return null;
+}
+
 /**
  * Best-effort: record the issue → worktree → work-folder linkage in the Kernel so
  * `forge worktree list` and orientation READ it instead of guessing the work-folder by
@@ -185,30 +340,44 @@ function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform
  * @param {string|null} params.issueId
  * @param {string|null} params.workFolder - Repo-relative work-folder path.
  * @param {object} params.opts - DI options (may inject `_kernelDriver`, `_exec`, `_fs`).
+ * @param {boolean} [params.reuse] - Validate existing linkage before reconciling.
  * @returns {Promise<{registered: boolean, issueId: string|null, workFolder: string|null, reason?: string}>}
  */
-async function registerWorktreeLinkage({ projectRoot, worktreePath, branch, issueId, workFolder, opts }) {
+async function registerWorktreeLinkage({ projectRoot, worktreePath, branch, issueId, workFolder, opts, reuse = false }) {
   const runFile = opts._exec || execFileSync;
   const fsApi = opts._fs || fs;
   try {
-    // Drop the folder → issue marker first — deterministic even if the DB write fails.
-    if (workFolder && issueId) {
-      const folderAbs = path.resolve(projectRoot, workFolder);
-      fsApi.mkdirSync(folderAbs, { recursive: true });
-      fsApi.writeFileSync(path.join(folderAbs, '.forge-issue'), `${issueId}\n`, 'utf8');
-    }
-
     let driver = opts._kernelDriver;
     if (!driver) {
       // No reachable git repo → no shared Kernel; skip quietly (orientation still works
       // off the folder heuristic). Avoids spawning `git` in a non-repo directory.
-      if (!fsApi.existsSync(path.join(projectRoot, '.git'))) {
-        return { registered: false, issueId: issueId || null, workFolder: workFolder || null, reason: 'no git repository' };
+      if (fsApi.existsSync(path.join(projectRoot, '.git'))) {
+        // Lazy require: keep the worktree command light and avoid paying kernel setup
+        // when linkage is not needed. Migrated deps guarantee the 007 columns exist.
+        const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+        driver = (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
       }
-      // Lazy require: keep the worktree command light and avoid paying kernel setup
-      // when linkage is not needed. Migrated deps guarantee the 007 columns exist.
-      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
-      driver = (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
+    }
+
+    const existing = readExistingWorktreeLinkage(driver, worktreePath, reuse);
+    const linkageConflict = detectLinkageConflict({ projectRoot, existing, issueId, workFolder, reuse });
+    if (linkageConflict) return { registered: false, ...linkageConflict };
+
+    const existingIssue = existing?.issue_id || null;
+    const existingFolder = existing?.work_folder || null;
+    const linkedIssue = issueId || (reuse ? existingIssue : null);
+    const linkedFolder = workFolder || (reuse ? existingFolder : null);
+    const markerTarget = validateMarkerTarget(projectRoot, linkedFolder, fsApi);
+    if (markerTarget?.conflict) {
+      return { registered: false, issueId: linkedIssue || null, workFolder: linkedFolder || null, ...markerTarget };
+    }
+    const markerConflict = reconcileIssueMarker({ target: markerTarget, linkedIssue, linkedFolder, fsApi });
+    if (markerConflict) {
+      return { registered: false, ...markerConflict };
+    }
+
+    if (!driver) {
+      return { registered: false, issueId: linkedIssue || null, workFolder: linkedFolder || null, reason: 'no git repository' };
     }
 
     const { resolveGitCommonDir } = require('../kernel/broker');
@@ -219,13 +388,13 @@ async function registerWorktreeLinkage({ projectRoot, worktreePath, branch, issu
       path: worktreePath,
       branch,
       actor: process.env.FORGE_ACTOR || null,
-      issue_id: issueId || null,
-      work_folder: workFolder || null,
+      issue_id: linkedIssue || null,
+      work_folder: linkedFolder || null,
       registered_at: new Date().toISOString(),
       state: 'active',
     });
 
-    return { registered: true, issueId: issueId || null, workFolder: workFolder || null };
+    return { registered: true, issueId: linkedIssue || null, workFolder: linkedFolder || null };
   } catch (error) {
     // Non-fatal: keep the worktree usable. Only warn when the caller explicitly asked
     // for linkage (--issue/--work-folder); a plain `worktree create` stays quiet.
@@ -331,7 +500,10 @@ async function handleCreate(slug, flags, projectRoot, opts) {
       // A detached worktree reports the literal "HEAD" — don't persist that; keep branchName.
       if (head && head !== 'HEAD') existingBranch = head;
     } catch (_error) { /* not a resolvable worktree HEAD — fall back to branchName */ }
-    const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: existingBranch, issueId, workFolder, opts });
+    const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: existingBranch, issueId, workFolder, opts, reuse: true });
+    if (linkage.conflict) {
+      return { success: false, reused: true, error: linkage.reason, worktreePath, linkage };
+    }
     const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: existingBranch, issueId, opts });
     return {
       success: true,
@@ -350,13 +522,13 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   // the repo's DEFAULT branch — NOT the checkout's current HEAD — so the worktree
   // never silently inherits unrelated WIP commits (B2). An existing branch is
   // checked out as-is (no base applies).
-  const hasBranch = branchExists(branchName, runFile);
+  const hasBranch = branchExists(branchName, projectRoot, runFile);
   let base = null;
   if (hasBranch) {
-    runFile('git', ['worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
+    runFile('git', ['-C', projectRoot, 'worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
   } else {
     base = explicitBase || resolveDefaultBase(projectRoot, runFile);
-    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName, base], { stdio: 'pipe' });
+    runFile('git', ['-C', projectRoot, 'worktree', 'add', worktreePath, '-b', branchName, base], { stdio: 'pipe' });
   }
 
   // Step 3: Populate node_modules (link to the shared install, else install).
@@ -375,11 +547,16 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   }
 
   const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: branchName, issueId, workFolder, opts });
+  if (linkage.conflict) {
+    return { success: false, error: linkage.reason, worktreePath, branch: branchName, linkage };
+  }
   const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: branchName, issueId, opts });
 
   // Report the base so the fork point is never silent. `base` is null when an
   // existing branch was checked out (no fork happened).
   const baseNote = base ? `based on ${base}` : `existing branch ${branchName}`;
+  // Never let a heal be silent — a stale store is worth knowing about.
+  const healNote = deps.healed ? ' Healed dependencies (store was stale): reinstalled with --force.' : '';
   return {
     success: true,
     worktreePath,
@@ -387,9 +564,10 @@ async function handleCreate(slug, flags, projectRoot, opts) {
     base,
     depsLinked: deps.linked,
     depsInstalled: deps.installed,
+    depsHealed: deps.healed,
     linkage,
     backing,
-    output: `Created worktree ${worktreePath} on ${branchName} (${baseNote}).`,
+    output: `Created worktree ${worktreePath} on ${branchName} (${baseNote}).${healNote}`,
   };
 }
 

package/lib/core/runtime-graph.js

@@ -534,7 +534,7 @@ const RESOLVED_RUNTIME_GRAPH = {
       id: 'adapter.issue',
       kind: 'issue',
       label: 'Issue tracking adapter',
-      config: { primary: 'beads', mirrors: ['github'] },
+      config: { primary: 'kernel', mirrors: ['github'] },
     }),
     Adapter({
       id: 'adapter.harness',