@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -0,0 +1,370 @@
+// gsd-pi — Auto-worktree state sync module.
+//
+// Owns project-root/worktree projection compatibility seams while the project DB
+// remains authoritative for workflow state.
+
+import {
+  cpSync,
+  existsSync,
+  lstatSync as lstatSyncFn,
+  mkdirSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import {
+  _isSamePath as isSamePath,
+  _shouldReconcileWorktreeDb,
+} from "./auto-worktree-cleanup.js";
+import { resolveGsdPathContract } from "./paths.js";
+import type { MilestoneScope } from "./workspace.js";
+import { WorktreeStateProjection } from "./worktree-state-projection.js";
+import { logWarning } from "./workflow-logger.js";
+
+const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
+const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
+
+/**
+ * Root-level .gsd/ projections copied from project root into worktrees for
+ * compatibility. Project root remains the canonical state/projection root.
+ */
+const ROOT_STATE_FILES = [
+  "DECISIONS.md",
+  "REQUIREMENTS.md",
+  "PROJECT.md",
+  "KNOWLEDGE.md",
+  "OVERRIDES.md",
+  "QUEUE.md",
+  "completed-units.json",
+  "metrics.json",
+  "mcp.json",
+  // NOTE: project preferences are intentionally NOT in ROOT_STATE_FILES.
+  // Forward-sync (main → worktree) is handled explicitly in syncGsdStateToWorktree().
+  // Back-sync (worktree → main) must NEVER overwrite the project root's copy
+  // because the project root is authoritative for preferences (#2684).
+] as const;
+
+/**
+ * Path-string entry point to WorktreeStateProjection.projectRootToWorktree.
+ * Production code goes through the Module class; this delegator survives so
+ * the projection-invariant tests (#1886, #2184, #2478, #2821) can exercise
+ * the bodies with raw paths.
+ */
+export function syncProjectRootToWorktree(
+  projectRoot: string,
+  worktreePath_: string,
+  milestoneId: string | null,
+): void {
+  new WorktreeStateProjection().projectRootToWorktreePaths(
+    projectRoot,
+    worktreePath_,
+    milestoneId,
+  );
+}
+
+/**
+ * Path-string entry point to WorktreeStateProjection.projectWorktreeToRoot.
+ * Production code goes through the Module class; this delegator survives so
+ * the projection-invariant tests can exercise the body with raw paths.
+ */
+export function syncStateToProjectRoot(
+  worktreePath_: string,
+  projectRoot: string,
+  milestoneId: string | null,
+): void {
+  new WorktreeStateProjection().projectWorktreeToRootPaths(
+    worktreePath_,
+    projectRoot,
+    milestoneId,
+  );
+}
+
+/**
+ * Scope-typed variant of syncGsdStateToWorktree.
+ *
+ * Takes an explicit (rootScope, worktreeScope) pair. Note: milestoneId is not
+ * used by syncGsdStateToWorktree — this variant only requires workspace
+ * identity. Asserts both scopes belong to the same workspace identity to
+ * prevent silent mismatch bugs.
+ */
+export function syncGsdStateToWorktreeByScope(
+  rootScope: MilestoneScope,
+  worktreeScope: MilestoneScope,
+): { synced: string[] } {
+  if (rootScope.workspace.identityKey !== worktreeScope.workspace.identityKey) {
+    throw new Error(
+      `syncGsdStateToWorktreeByScope: scope identity mismatch — ` +
+        `rootScope.identityKey="${rootScope.workspace.identityKey}" ` +
+        `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}"`,
+    );
+  }
+  const mainBasePath = rootScope.workspace.projectRoot;
+  const worktreePath = worktreeScope.workspace.worktreeRoot
+    ?? worktreeScope.workspace.projectRoot;
+  return syncGsdStateToWorktree(mainBasePath, worktreePath);
+}
+
+/**
+ * Sync .gsd/ state from the main repo into the worktree.
+ *
+ * When .gsd/ is a symlink to the external state directory, both the main
+ * repo and worktree share the same directory — no sync needed.
+ *
+ * When .gsd/ is a real directory (e.g., git-tracked or manage_gitignore:false),
+ * the worktree has its own copy that may be stale. This function copies
+ * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
+ * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
+ *
+ * Only adds missing content — never overwrites existing files in the worktree.
+ * Worktree files are compatibility projections; DB/project root remains
+ * authoritative for runtime state.
+ * @deprecated Use syncGsdStateToWorktreeByScope instead.
+ * TODO(C-future): remove once all callers migrated.
+ */
+export function syncGsdStateToWorktree(
+  mainBasePath: string,
+  worktreePath_: string,
+): { synced: string[] } {
+  const contract = resolveGsdPathContract(worktreePath_, mainBasePath);
+  const mainGsd = contract.projectGsd;
+  const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
+  const synced: string[] = [];
+
+  if (isSamePath(mainGsd, wtGsd)) return { synced };
+  if (!existsSync(mainGsd)) return { synced };
+
+  mkdirSync(wtGsd, { recursive: true });
+  syncRootStateFiles(mainGsd, wtGsd, synced);
+  syncProjectPreferences(mainGsd, wtGsd, synced);
+  syncMilestoneLayouts(mainGsd, wtGsd, synced);
+
+  return { synced };
+}
+
+function syncRootStateFiles(
+  mainGsd: string,
+  wtGsd: string,
+  synced: string[],
+): void {
+  for (const file of ROOT_STATE_FILES) {
+    const src = join(mainGsd, file);
+    const dst = join(wtGsd, file);
+    if (!existsSync(src) || existsSync(dst)) continue;
+
+    try {
+      cpSync(src, dst);
+      synced.push(file);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `file copy failed (${file}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+function syncProjectPreferences(
+  mainGsd: string,
+  wtGsd: string,
+  synced: string[],
+): void {
+  const worktreeHasPreferences = existsSync(join(wtGsd, PROJECT_PREFERENCES_FILE))
+    || existsSync(join(wtGsd, LEGACY_PROJECT_PREFERENCES_FILE));
+  if (worktreeHasPreferences) return;
+
+  for (const file of [PROJECT_PREFERENCES_FILE, LEGACY_PROJECT_PREFERENCES_FILE] as const) {
+    const src = join(mainGsd, file);
+    const dst = join(wtGsd, file);
+    if (!existsSync(src)) continue;
+
+    try {
+      cpSync(src, dst);
+      synced.push(file);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `preferences copy failed (${file}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return;
+  }
+}
+
+function syncMilestoneLayouts(
+  mainGsd: string,
+  wtGsd: string,
+  synced: string[],
+): void {
+  for (const layoutSegment of ["phases", "milestones"] as const) {
+    syncMilestoneLayout(mainGsd, wtGsd, layoutSegment, synced);
+  }
+}
+
+function syncMilestoneLayout(
+  mainGsd: string,
+  wtGsd: string,
+  layoutSegment: "phases" | "milestones",
+  synced: string[],
+): void {
+  const mainMilestonesDir = join(mainGsd, layoutSegment);
+  const wtMilestonesDir = join(wtGsd, layoutSegment);
+  if (!existsSync(mainMilestonesDir)) return;
+
+  try {
+    mkdirSync(wtMilestonesDir, { recursive: true });
+    const mainMilestones = readdirSync(mainMilestonesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+
+    for (const milestoneId of mainMilestones) {
+      syncMilestoneDirectory(
+        mainMilestonesDir,
+        wtMilestonesDir,
+        milestoneId,
+        synced,
+      );
+    }
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+function syncMilestoneDirectory(
+  mainMilestonesDir: string,
+  wtMilestonesDir: string,
+  milestoneId: string,
+  synced: string[],
+): void {
+  const srcDir = join(mainMilestonesDir, milestoneId);
+  const dstDir = join(wtMilestonesDir, milestoneId);
+
+  if (!existsSync(dstDir)) {
+    try {
+      cpSync(srcDir, dstDir, { recursive: true });
+      // Preserve the legacy telemetry string used before this extraction. The
+      // actual layout may be `phases/`; callers only consumed this as a coarse
+      // "milestone projection copied" marker.
+      synced.push(`milestones/${milestoneId}/`);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `milestone copy failed (${milestoneId}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return;
+  }
+
+  try {
+    syncMilestoneTopLevelFiles(srcDir, dstDir, milestoneId, synced);
+    syncSlicesDirectory(srcDir, dstDir, milestoneId, synced);
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+function syncMilestoneTopLevelFiles(
+  srcDir: string,
+  dstDir: string,
+  milestoneId: string,
+  synced: string[],
+): void {
+  const srcFiles = readdirSync(srcDir).filter(
+    (file) => file.endsWith(".md") || file.endsWith(".json"),
+  );
+
+  for (const file of srcFiles) {
+    const srcFile = join(srcDir, file);
+    const dstFile = join(dstDir, file);
+    if (existsSync(dstFile)) continue;
+
+    try {
+      const srcStat = lstatSyncFn(srcFile);
+      if (!srcStat.isFile()) continue;
+
+      cpSync(srcFile, dstFile);
+      synced.push(`milestones/${milestoneId}/${file}`);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `milestone file copy failed (${milestoneId}/${file}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+function syncSlicesDirectory(
+  srcDir: string,
+  dstDir: string,
+  milestoneId: string,
+  synced: string[],
+): void {
+  const srcSlicesDir = join(srcDir, "slices");
+  const dstSlicesDir = join(dstDir, "slices");
+  if (!existsSync(srcSlicesDir)) return;
+
+  if (!existsSync(dstSlicesDir)) {
+    try {
+      cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+      synced.push(`milestones/${milestoneId}/slices/`);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `slices copy failed (${milestoneId}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return;
+  }
+
+  const srcSlices = readdirSync(srcSlicesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  for (const sliceId of srcSlices) {
+    const srcSlice = join(srcSlicesDir, sliceId);
+    const dstSlice = join(dstSlicesDir, sliceId);
+    if (existsSync(dstSlice)) continue;
+
+    try {
+      cpSync(srcSlice, dstSlice, { recursive: true });
+      synced.push(`milestones/${milestoneId}/slices/${sliceId}/`);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `slice copy failed (${milestoneId}/${sliceId}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Sync compatibility artifacts from worktree back to the main external state
+ * directory. Canonical workflow state lives in the project DB; worktree .gsd
+ * content is legacy projection/diagnostic data only.
+ *
+ * Syncs:
+ *   1. Legacy worktree DBs are reconciled into the canonical project DB.
+ *   2. Runtime diagnostic files may be copied for operator visibility.
+ *
+ * Markdown milestone directories are projections and are not copied from
+ * worktrees into the project root. Current workflow state must arrive through
+ * the shared project DB or the pre-upgrade DB reconciliation path above.
+ */
+export function syncWorktreeStateBack(
+  mainBasePath: string,
+  worktreePath: string,
+  milestoneId: string,
+): { synced: string[] } {
+  return new WorktreeStateProjection().finalizeProjectionForMergePaths(
+    mainBasePath,
+    worktreePath,
+    milestoneId,
+  );
+}
+
+export { _shouldReconcileWorktreeDb } from "./auto-worktree-cleanup.js";

package/src/resources/extensions/gsd/auto-worktree-teardown.ts

@@ -0,0 +1,161 @@
+// gsd-pi — Auto-worktree teardown module.
+//
+// Owns the teardown path for milestone worktrees: returning to the project
+// root, transient state cleanup, legacy DB reconciliation, worktree/branch
+// removal, fallback orphan-directory cleanup, and active workspace registry
+// clearing.
+
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { GSDError, GSD_IO_ERROR } from "./errors.js";
+import { reconcileWorktreeDb, isDbAvailable } from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import {
+  removeWorktree,
+  worktreePath,
+  isInsideWorktreesDir,
+} from "./worktree-manager.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { autoWorktreeBranch } from "./auto-worktree-branch-lifecycle.js";
+import { setActiveWorkspace } from "./auto-worktree-session-registry.js";
+import {
+  _shouldReconcileWorktreeDb,
+  clearProjectRootStateFiles,
+} from "./auto-worktree-cleanup.js";
+import { logWarning, logError } from "./workflow-logger.js";
+
+function safeCwd(fallback: string): string {
+  try {
+    return process.cwd();
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Teardown an auto-worktree: chdir back to original base, then remove
+ * the worktree and its branch.
+ */
+export function teardownAutoWorktree(
+  originalBasePath: string,
+  milestoneId: string,
+  opts: { preserveBranch?: boolean; preserveWorktree?: boolean } = {},
+): void {
+  originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
+
+  const branch = autoWorktreeBranch(milestoneId);
+  const { preserveBranch = false, preserveWorktree = false } = opts;
+  const previousCwd = safeCwd(originalBasePath);
+  let clearActiveWorkspace = true;
+
+  // Wrap the entire teardown body in a single try/finally so activeWorkspace
+  // is cleared on completion or irrecoverable failure — even if process.chdir
+  // throws (e.g. originalBasePath was deleted before teardown ran).
+  try {
+    try {
+      process.chdir(originalBasePath);
+    } catch (err) {
+      throw new GSDError(
+        GSD_IO_ERROR,
+        `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    // Mirror cleanup steps from mergeMilestoneToMain abort path:
+
+    // 1. Remove transient state files (STATE.md, auto.lock, {MID}-META.json).
+    //    Non-fatal — must not block teardown.
+    try {
+      clearProjectRootStateFiles(originalBasePath, milestoneId);
+    } catch (err) {
+      logWarning(
+        "worktree",
+        `clearProjectRootStateFiles failed during teardown: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    // 2. Reconcile worktree-local gsd.db into project root DB if both exist.
+    //    Non-fatal — handles legacy worktrees that have a local copy.
+    if (isDbAvailable()) {
+      try {
+        const contract = resolveGsdPathContract(previousCwd, originalBasePath);
+        const worktreeDbPath = join(
+          contract.worktreeGsd ?? join(previousCwd, ".gsd"),
+          "gsd.db",
+        );
+        const mainDbPath = contract.projectDb;
+        if (_shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
+          reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+        }
+      } catch (err) {
+        /* non-fatal */
+        logError(
+          "worktree",
+          `DB reconciliation failed during teardown: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    nudgeGitBranchCache(previousCwd);
+
+    // 3. Remove the worktree unless this exit path explicitly preserves it
+    //    (slice-parallel dispatch stops the parent loop but keeps the parent
+    //    milestone worktree for restart/re-entry).
+    let worktreeRemoved = preserveWorktree;
+    if (!preserveWorktree) {
+      worktreeRemoved = removeWorktree(originalBasePath, milestoneId, {
+        branch,
+        deleteBranch: !preserveBranch,
+      });
+      if (!worktreeRemoved) {
+        logWarning(
+          "worktree",
+          `Worktree removal aborted for ${milestoneId}; uncommitted work was preserved. ` +
+            `Manual quarantine recovery may be needed before retrying teardown.`,
+          { worktree: milestoneId },
+        );
+        clearActiveWorkspace = false;
+      }
+    }
+
+    // Verify cleanup succeeded — warn if the worktree directory is still on disk.
+    // On Windows, bash-based cleanup can silently fail when paths contain
+    // backslashes (#1436), leaving ~1 GB+ orphaned directories.
+    const wtDir = worktreePath(originalBasePath, milestoneId);
+    if (!preserveWorktree && worktreeRemoved && existsSync(wtDir)) {
+      logWarning(
+        "reconcile",
+        `Worktree directory still exists after teardown: ${wtDir}. ` +
+          `This is likely an orphaned directory consuming disk space. ` +
+          `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`,
+        { worktree: milestoneId },
+      );
+      // Attempt a direct filesystem removal as a fallback — but ONLY if the
+      // path is safely inside .gsd/worktrees/ to prevent #2365 data loss.
+      if (isInsideWorktreesDir(originalBasePath, wtDir)) {
+        try {
+          rmSync(wtDir, { recursive: true, force: true });
+        } catch (err) {
+          // Non-fatal — the warning above tells the user how to clean up
+          logWarning(
+            "worktree",
+            `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      } else {
+        console.error(
+          `[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`,
+        );
+      }
+    }
+  } finally {
+    // Clear module state when teardown completed or failed irrecoverably.
+    // When removeWorktree returns false (quarantine failure), preserve the
+    // registry so recovery logic still sees the active milestone worktree.
+    if (clearActiveWorkspace) {
+      setActiveWorkspace(null);
+    }
+  }
+}