@opengsd/gsd-pi 1.5.0 → 1.6.0

package/src/resources/extensions/gsd/auto-worktree-milestone-shelter.ts

@@ -0,0 +1,159 @@
+// gsd-pi — Milestone directory shelter for auto-worktree merge closeout.
+//
+// Owns the #2505 queued-milestone directory protection step that runs before
+// merge stash handling. This keeps queued CONTEXT files out of the stash and
+// restores them after merge closeout without hiding restore failures.
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+
+import {
+  canonicalPhaseDirName,
+  gsdRoot,
+  milestonesDir,
+  resolveMilestonePath,
+} from "./paths.js";
+import { logError, logWarning } from "./workflow-logger.js";
+
+export interface MilestoneDirectoryShelter {
+  restore(): void;
+}
+
+/**
+ * Optional override for the shelter restore copy step (milestone merge #2505).
+ * Production leaves this null so restore uses the real cpSync; tests inject a
+ * throwing function to deterministically exercise the best-effort failure path
+ * and the shelter-retention guarantee.
+ * @internal
+ */
+let restoreEntryFn: ((src: string, dest: string) => void) | null = null;
+
+/** @internal */
+export function _setRestoreEntryFnForTests(
+  fn: ((src: string, dest: string) => void) | null,
+): () => void {
+  restoreEntryFn = fn;
+  return () => { restoreEntryFn = null; };
+}
+
+export function createMilestoneDirectoryShelter(
+  originalBasePath: string,
+  milestoneId: string,
+  milestoneTitle: string | undefined,
+): MilestoneDirectoryShelter {
+  const planningDir = milestonesDir(originalBasePath);
+  const shelterDir = join(gsdRoot(originalBasePath), ".milestone-shelter");
+  const shelteredDirs: string[] = [];
+  const mergeDirNames = milestoneDirectoryNames(originalBasePath, milestoneId, milestoneTitle);
+  let restored = false;
+
+  try {
+    if (existsSync(planningDir)) {
+      const entries = readdirSync(planningDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (mergeDirNames.has(entry.name)) continue;
+        shelterMilestoneDirectory(planningDir, shelterDir, entry.name, shelteredDirs);
+      }
+    }
+  } catch (err) {
+    // Non-fatal — proceed with merge; untracked files may block it.
+    logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return {
+    restore(): void {
+      if (restored) return;
+      restored = true;
+      restoreShelteredDirectories(planningDir, shelterDir, shelteredDirs);
+    },
+  };
+}
+
+function milestoneDirectoryNames(
+  originalBasePath: string,
+  milestoneId: string,
+  milestoneTitle: string | undefined,
+): Set<string> {
+  const mergeDirNames = new Set<string>([milestoneId]);
+  const resolvedMergeDir = resolveMilestonePath(originalBasePath, milestoneId);
+  if (resolvedMergeDir) {
+    mergeDirNames.add(basename(resolvedMergeDir));
+  } else {
+    mergeDirNames.add(canonicalPhaseDirName(milestoneId, milestoneTitle));
+  }
+  return mergeDirNames;
+}
+
+function shelterMilestoneDirectory(
+  planningDir: string,
+  shelterDir: string,
+  dirName: string,
+  shelteredDirs: string[],
+): void {
+  const srcDir = join(planningDir, dirName);
+  const dstDir = join(shelterDir, dirName);
+  try {
+    mkdirSync(shelterDir, { recursive: true });
+    cpSync(srcDir, dstDir, { recursive: true, force: true });
+    rmSync(srcDir, { recursive: true, force: true });
+    shelteredDirs.push(dirName);
+  } catch (err) {
+    // Non-fatal — if shelter fails, the merge may still succeed.
+    logWarning("worktree", `milestone shelter failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function restoreShelteredDirectories(
+  planningDir: string,
+  shelterDir: string,
+  shelteredDirs: string[],
+): void {
+  if (shelteredDirs.length === 0) return;
+
+  let restoreFailed = false;
+  for (const dirName of shelteredDirs) {
+    const src = join(shelterDir, dirName);
+    if (!existsSync(src)) {
+      logWarning(
+        "worktree",
+        `shelter source missing for ${dirName}; skipping restore (shelter already cleaned or entry never staged)`,
+      );
+      continue;
+    }
+    try {
+      mkdirSync(planningDir, { recursive: true });
+      const dest = join(planningDir, dirName);
+      if (restoreEntryFn) {
+        restoreEntryFn(src, dest);
+      } else {
+        cpSync(src, dest, { recursive: true, force: true });
+      }
+    } catch (err) {
+      restoreFailed = true;
+      logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Preserve the shelter if any per-entry restore failed — it is the only
+  // surviving copy of the queued milestone dirs (sources were deleted during
+  // shelter). Deleting it here would permanently lose those files (#2505).
+  if (restoreFailed) {
+    logWarning("worktree", `shelter retained at ${shelterDir} — manual recovery required for unrestored entries`);
+    return;
+  }
+
+  if (existsSync(shelterDir)) {
+    try {
+      rmSync(shelterDir, { recursive: true, force: true });
+    } catch (err) {
+      logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}

package/src/resources/extensions/gsd/auto-worktree-path-resolution.ts

@@ -0,0 +1,6 @@
+// gsd-pi — Auto-worktree path resolution seam.
+//
+// Keeps callers that only resolve existing auto-worktree paths on the focused
+// entry/path module instead of the legacy auto-worktree compatibility barrel.
+
+export { getAutoWorktreePath } from "./auto-worktree-entry.js";

package/src/resources/extensions/gsd/auto-worktree-path-utils.ts

@@ -0,0 +1,10 @@
+// gsd-pi — Narrow auto-worktree path utility seam.
+//
+// Keeps path comparison, pathspec, and expected-warning callers off the legacy
+// auto-worktree compatibility barrel while extraction continues.
+
+export {
+  _gitPathspecForWorktreePath,
+  _isExpectedWorktreeUnlinkError,
+  _isSamePath,
+} from "./auto-worktree-cleanup.js";

package/src/resources/extensions/gsd/auto-worktree-resource-version.ts

@@ -0,0 +1,44 @@
+// gsd-pi — Auto-worktree resource version module.
+//
+// Owns managed-resource freshness checks for long-running auto sessions.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { gsdHome } from "./gsd-home.js";
+import { logWarning } from "./workflow-logger.js";
+
+/**
+ * Read the resource version (semver) from the managed-resources manifest.
+ * Uses gsdVersion instead of syncedAt so that launching a second session
+ * doesn't falsely trigger staleness (#804).
+ */
+export function readResourceVersion(): string | null {
+  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
+  const manifestPath = join(agentDir, "managed-resources.json");
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    return typeof manifest?.gsdVersion === "string"
+      ? manifest.gsdVersion
+      : null;
+  } catch (e) {
+    logWarning("worktree", `readResourceVersion failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * Check if managed resources have been updated since session start.
+ * Returns a warning message if stale, null otherwise.
+ */
+export function checkResourcesStale(
+  versionOnStart: string | null,
+): string | null {
+  if (versionOnStart === null) return null;
+  const current = readResourceVersion();
+  if (current === null) return null;
+  if (current !== versionOnStart) {
+    return "GSD resources were updated since this session started. Restart gsd to load the new code.";
+  }
+  return null;
+}

package/src/resources/extensions/gsd/auto-worktree-runtime-cleanup.ts

@@ -0,0 +1,119 @@
+// gsd-pi — Auto-worktree runtime cleanup module.
+//
+// Owns stale worktree cwd escape and runtime unit cleanup during auto startup.
+
+import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { gsdHome } from "./gsd-home.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
+import {
+  normalizeWorktreePathForCompare,
+  projectRootFromWorktreePath,
+} from "./worktree-root.js";
+import { logWarning } from "./workflow-logger.js";
+
+const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
+  "workflow-preferences-WORKFLOW-PREFS.json",
+  "discuss-project-PROJECT.json",
+  "discuss-requirements-REQUIREMENTS.json",
+  "research-decision-RESEARCH-DECISION.json",
+  "research-project-RESEARCH-PROJECT.json",
+]);
+
+/**
+ * Detect and escape a stale worktree cwd (#608).
+ *
+ * After milestone completion + merge, the worktree directory is removed but
+ * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
+ * When a new session starts, `process.cwd()` is passed as `base` to startAuto
+ * and all subsequent writes land in the wrong directory. This function detects
+ * that scenario and chdir back to the project root.
+ *
+ * Returns the corrected base path.
+ */
+export function escapeStaleWorktree(base: string): string {
+  const projectRoot = projectRootFromWorktreePath(base);
+  if (projectRoot === null) return base;
+
+  // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
+  // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
+  // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
+  // resolved through the symlink. Returning ~ would be catastrophic (#1676).
+  const candidateGsd = normalizeWorktreePathForCompare(join(projectRoot, ".gsd"));
+  const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
+  if (candidateGsd === gsdHomeNorm || candidateGsd.startsWith(gsdHomeNorm + "/")) {
+    // Don't chdir to home — return base unchanged.
+    // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
+    // and will be called by the caller (startAuto → projectRoot()).
+    return base;
+  }
+
+  try {
+    process.chdir(projectRoot);
+  } catch (e) {
+    // If chdir fails, return the original — caller will handle errors downstream
+    logWarning("worktree", `escapeStaleWorktree chdir failed: ${(e as Error).message}`);
+    return base;
+  }
+  return projectRoot;
+}
+
+/**
+ * Clean stale runtime unit files for completed milestones.
+ *
+ * After restart, stale runtime/units/*.json from prior milestones can
+ * cause deriveState to resume the wrong milestone (#887). Removes files
+ * for milestones that have a SUMMARY (fully complete).
+ */
+export function cleanStaleRuntimeUnits(
+  gsdRootPath: string,
+  hasMilestoneSummary: (mid: string) => boolean,
+): number {
+  const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
+  if (!existsSync(runtimeUnitsDir)) return 0;
+
+  let cleaned = 0;
+  try {
+    for (const file of readdirSync(runtimeUnitsDir)) {
+      if (!file.endsWith(".json")) continue;
+      if (shouldRemoveRuntimeUnit(file, hasMilestoneSummary)) {
+        cleaned += unlinkRuntimeUnit(runtimeUnitsDir, file);
+      }
+    }
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `stale runtime unit cleanup failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return cleaned;
+}
+
+function shouldRemoveRuntimeUnit(
+  file: string,
+  hasMilestoneSummary: (mid: string) => boolean,
+): boolean {
+  if (LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES.has(file)) return true;
+
+  const staleDiscussMatch = file.match(/^discuss-milestone-(.+)\.json$/);
+  if (staleDiscussMatch && !MILESTONE_ID_RE.test(staleDiscussMatch[1])) {
+    return true;
+  }
+
+  const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
+  return Boolean(midMatch && hasMilestoneSummary(midMatch[1]));
+}
+
+function unlinkRuntimeUnit(runtimeUnitsDir: string, file: string): number {
+  try {
+    unlinkSync(join(runtimeUnitsDir, file));
+    return 1;
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return 0;
+  }
+}

package/src/resources/extensions/gsd/auto-worktree-session-registry.ts

@@ -0,0 +1,71 @@
+// gsd-pi — Auto-worktree active session registry.
+//
+// Owns the process-local active workspace state used by auto-worktree create,
+// enter, teardown, and merge paths. Keeping this state behind a focused module
+// gives registry tests the same interface production uses instead of reaching
+// through the legacy auto-worktree compatibility barrel.
+
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import {
+  isGsdWorktreePath,
+  normalizeWorktreePathForCompare,
+  resolveWorktreeProjectRoot,
+} from "./worktree-root.js";
+import { detectWorktreeName } from "./worktree.js";
+import type { GsdWorkspace } from "./workspace.js";
+
+/** Active workspace registry — replaces the legacy `originalBase` singleton. */
+let activeWorkspace: GsdWorkspace | null = null;
+
+export function setActiveWorkspace(ws: GsdWorkspace | null): void {
+  activeWorkspace = ws;
+}
+
+export function getActiveWorkspace(): GsdWorkspace | null {
+  return activeWorkspace;
+}
+
+/**
+ * Get the original project root stored when entering an auto-worktree.
+ * Returns null if not currently in an auto-worktree.
+ */
+export function getAutoWorktreeOriginalBase(): string | null {
+  return getActiveWorkspace()?.projectRoot ?? null;
+}
+
+/**
+ * Test-only — resets the module-level `activeWorkspace` registry between
+ * runs. Production code never clears the registry directly; tests call this
+ * in `beforeEach`/`afterEach` to isolate registry-mutating cases.
+ */
+export function _resetAutoWorktreeOriginalBaseForTests(): void {
+  setActiveWorkspace(null);
+}
+
+export function getActiveAutoWorktreeContext(): {
+  originalBase: string;
+  worktreeName: string;
+  branch: string;
+} | null {
+  const ws = getActiveWorkspace();
+  if (!ws) return null;
+  const originalBase = ws.projectRoot;
+  const cwd = process.cwd();
+  if (!isGsdWorktreePath(cwd)) return null;
+  const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+  if (
+    normalizeWorktreePathForCompare(cwdProjectRoot) !==
+    normalizeWorktreePathForCompare(originalBase)
+  ) {
+    return null;
+  }
+  const worktreeName = detectWorktreeName(cwd);
+  if (!worktreeName) return null;
+  const branch = nativeGetCurrentBranch(cwd);
+  if (!branch.startsWith("milestone/")) return null;
+  return {
+    originalBase,
+    worktreeName,
+    branch,
+  };
+}