@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

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

@@ -0,0 +1,154 @@
+// gsd-pi — Auto-worktree entry and presence detection module.
+//
+// Owns the small interface for finding, entering, and identifying milestone
+// worktrees. The legacy auto-worktree barrel re-exports these functions for
+// compatibility while lifecycle callers can depend on this focused module.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { GSDError, GSD_GIT_ERROR, GSD_IO_ERROR } from "./errors.js";
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import { worktreePath } from "./worktree-manager.js";
+import { worktreePathFor } from "./worktree-placement.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import {
+  isGsdWorktreePath,
+  normalizeWorktreePathForCompare,
+  resolveWorktreeProjectRoot,
+} from "./worktree-root.js";
+import {
+  getAutoWorktreeOriginalBase,
+  setActiveWorkspace,
+} from "./auto-worktree-session-registry.js";
+import { createWorkspace } from "./workspace.js";
+import { logWarning } from "./workflow-logger.js";
+
+function safeCwd(fallback: string): string {
+  try {
+    return process.cwd();
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Detect if the process is currently inside an auto-worktree.
+ * Uses the current directory structure plus git branch prefix so detection
+ * still works after process restart when module state has been reset.
+ */
+export function isInAutoWorktree(basePath: string): boolean {
+  const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
+  if (!isGsdWorktreePath(targetPath)) return false;
+
+  const storedBase = getAutoWorktreeOriginalBase();
+  const projectRoot = resolveWorktreeProjectRoot(basePath, storedBase);
+  const targetProjectRoot = resolveWorktreeProjectRoot(targetPath, storedBase);
+  if (
+    normalizeWorktreePathForCompare(projectRoot) !==
+    normalizeWorktreePathForCompare(targetProjectRoot)
+  ) {
+    return false;
+  }
+
+  try {
+    const branch = nativeGetCurrentBranch(targetPath);
+    return branch.startsWith("milestone/");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the filesystem path for an auto-worktree, or null if it doesn't exist
+ * or is not a valid git worktree.
+ *
+ * Validates that the path is a real git worktree (has a .git file with a
+ * gitdir: pointer) rather than just a stray directory. This prevents
+ * mis-detection of leftover directories as active worktrees (#695).
+ */
+export function getAutoWorktreePath(
+  basePath: string,
+  milestoneId: string,
+): string | null {
+  basePath = resolveWorktreeProjectRoot(basePath);
+
+  // basePath is already the resolved project root — go straight to placement
+  // instead of worktreePath(), which would re-resolve the root.
+  const p = worktreePathFor(basePath, milestoneId);
+  if (!existsSync(p)) return null;
+
+  // Validate this is a real git worktree, not a stray directory.
+  // A git worktree has a .git *file* (not directory) containing "gitdir: <path>".
+  const gitPath = join(p, ".git");
+  if (!existsSync(gitPath)) return null;
+  try {
+    const content = readFileSync(gitPath, "utf8").trim();
+    if (!content.startsWith("gitdir: ")) return null;
+  } catch (e) {
+    logWarning("worktree", `getAutoWorktreePath .git read failed: ${(e as Error).message}`);
+    return null;
+  }
+
+  return p;
+}
+
+/**
+ * Enter an existing auto-worktree (chdir into it, store originalBase).
+ * Use for resume -- the worktree already exists from a prior create.
+ *
+ * Atomic: chdir + originalBase update in same try block.
+ */
+export function enterAutoWorktree(
+  basePath: string,
+  milestoneId: string,
+): string {
+  basePath = resolveWorktreeProjectRoot(basePath);
+
+  const p = worktreePath(basePath, milestoneId);
+  if (!existsSync(p)) {
+    throw new GSDError(
+      GSD_IO_ERROR,
+      `Auto-worktree for ${milestoneId} does not exist at ${p}`,
+    );
+  }
+
+  // Validate this is a real git worktree, not a stray directory (#695)
+  const gitPath = join(p, ".git");
+  if (!existsSync(gitPath)) {
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Auto-worktree path ${p} exists but is not a git worktree (no .git)`,
+    );
+  }
+  try {
+    const content = readFileSync(gitPath, "utf8").trim();
+    if (!content.startsWith("gitdir: ")) {
+      throw new GSDError(
+        GSD_GIT_ERROR,
+        `Auto-worktree path ${p} has a .git but it is not a worktree gitdir pointer`,
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("worktree")) throw err;
+    throw new GSDError(
+      GSD_IO_ERROR,
+      `Auto-worktree path ${p} exists but .git is unreadable`,
+    );
+  }
+
+  const previousCwd = process.cwd();
+
+  try {
+    process.chdir(p);
+    setActiveWorkspace(createWorkspace(basePath));
+  } catch (err) {
+    throw new GSDError(
+      GSD_IO_ERROR,
+      `Failed to enter auto-worktree at ${p}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  nudgeGitBranchCache(previousCwd);
+  return p;
+}

package/src/resources/extensions/gsd/auto-worktree-merge-already-merged.ts

@@ -0,0 +1,161 @@
+// gsd-pi — Already-merged milestone merge fast path.
+//
+// Owns the safety invariant for milestone branches already reachable from the
+// integration branch: skip the squash merge only when milestone-touched code is
+// still anchored on the current integration branch, then run normal cleanup.
+
+import { execFileSync } from "node:child_process";
+
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  nativeDiffNumstat,
+  nativeIsAncestor,
+} from "./native-git-bridge.js";
+import { cleanupMergedMilestoneWorktree } from "./auto-worktree-merge-cleanup.js";
+import { logWarning } from "./workflow-logger.js";
+
+export interface AlreadyMergedMilestoneRequest {
+  projectRoot: string;
+  milestoneId: string;
+  milestoneBranch: string;
+  mainBranch: string;
+  previousCwd: string;
+  commitMessage: string;
+}
+
+export interface AlreadyMergedMilestoneResult {
+  commitMessage: string;
+  pushed: false;
+  prCreated: false;
+  codeFilesChanged: true;
+}
+
+export function finalizeAlreadyMergedMilestoneIfReachable(
+  request: AlreadyMergedMilestoneRequest,
+): AlreadyMergedMilestoneResult | null {
+  const {
+    projectRoot,
+    milestoneId,
+    milestoneBranch,
+    mainBranch,
+    previousCwd,
+    commitMessage,
+  } = request;
+
+  if (!nativeIsAncestor(projectRoot, milestoneBranch, mainBranch)) {
+    return null;
+  }
+
+  assertNoUnanchoredRegularMergeCodeChanges({
+    projectRoot,
+    milestoneBranch,
+    mainBranch,
+    previousCwd,
+  });
+
+  debugLog("mergeMilestoneToMain", {
+    action: "skip-squash-already-merged",
+    milestoneId,
+    milestoneBranch,
+    mainBranch,
+  });
+  cleanupMergedMilestoneWorktree({
+    projectRoot,
+    milestoneId,
+    milestoneBranch,
+    previousCwd,
+    clearProjectRootState: true,
+    chdirWarningContext: "after already-merged cleanup",
+  });
+  return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
+}
+
+function assertNoUnanchoredRegularMergeCodeChanges(request: {
+  projectRoot: string;
+  milestoneBranch: string;
+  mainBranch: string;
+  previousCwd: string;
+}): void {
+  const { projectRoot, milestoneBranch, mainBranch, previousCwd } = request;
+  const codeChanges = nativeDiffNumstat(
+    projectRoot,
+    mainBranch,
+    milestoneBranch,
+  ).filter((entry) => !entry.path.startsWith(".gsd/"));
+  if (codeChanges.length === 0) return;
+
+  const regularMergeChangedPaths = findRegularMergeChangedPaths(
+    projectRoot,
+    milestoneBranch,
+    mainBranch,
+  );
+  const unanchoredCodeChanges = codeChanges.filter((entry) =>
+    regularMergeChangedPaths.has(entry.path)
+  );
+  if (unanchoredCodeChanges.length === 0) return;
+
+  process.chdir(previousCwd);
+  throw new GSDError(
+    GSD_GIT_ERROR,
+    `Milestone branch "${milestoneBranch}" is reachable from "${mainBranch}" ` +
+      `but has ${unanchoredCodeChanges.length} milestone-touched code file(s) not on current "${mainBranch}". ` +
+      `Aborting worktree teardown to prevent data loss.`,
+  );
+}
+
+function findRegularMergeChangedPaths(
+  basePath: string,
+  milestoneBranch: string,
+  mainBranch: string,
+): Set<string> {
+  const changedPaths = new Set<string>();
+  let mergeLog = "";
+  try {
+    mergeLog = execFileSync(
+      "git",
+      ["rev-list", "--merges", "--parents", mainBranch],
+      {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      },
+    ).trim();
+  } catch (err) {
+    logWarning("worktree", `regular merge lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    return changedPaths;
+  }
+
+  for (const line of mergeLog.split("\n").filter(Boolean)) {
+    const [mergeCommit, firstParent, ...otherParents] = line.split(" ");
+    if (!mergeCommit || !firstParent || otherParents.length === 0) continue;
+    const mergedMilestone = otherParents.some((parent) => {
+      try {
+        return nativeIsAncestor(basePath, milestoneBranch, parent);
+      } catch {
+        return false;
+      }
+    });
+    if (!mergedMilestone) continue;
+
+    try {
+      const output = execFileSync(
+        "git",
+        ["diff", "--name-only", firstParent, mergeCommit],
+        {
+          cwd: basePath,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        },
+      ).trim();
+      for (const path of output.split("\n").filter(Boolean)) {
+        if (!path.startsWith(".gsd/")) changedPaths.add(path);
+      }
+    } catch (err) {
+      logWarning("worktree", `regular merge diff lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return changedPaths;
+  }
+
+  return changedPaths;
+}

package/src/resources/extensions/gsd/auto-worktree-merge-branch-head.ts

@@ -0,0 +1,83 @@
+// gsd-pi — Milestone branch/head reconciliation before merge.
+//
+// Owns the data-loss guard that keeps the named milestone branch aligned with
+// the actual worktree HEAD. Detached worktree commits can otherwise sit beyond
+// the branch ref and be silently omitted from the integration merge.
+
+import { execFileSync } from "node:child_process";
+
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  nativeIsAncestor,
+  nativeUpdateRef,
+} from "./native-git-bridge.js";
+
+export type MilestoneBranchHeadReconciliationResult =
+  | { checked: false; updated: false; reason: "not-worktree" | "lookup-failed" }
+  | { checked: true; updated: false; reason: "already-current" }
+  | { checked: true; updated: true; reason: "fast-forwarded" };
+
+export interface MilestoneBranchHeadReconciliationRequest {
+  projectRoot: string;
+  worktreeCwd: string;
+  milestoneBranch: string;
+  previousCwd: string;
+}
+
+export function reconcileMilestoneBranchHead(
+  request: MilestoneBranchHeadReconciliationRequest,
+): MilestoneBranchHeadReconciliationResult {
+  const { projectRoot, worktreeCwd, milestoneBranch, previousCwd } = request;
+
+  if (worktreeCwd === projectRoot) {
+    return { checked: false, updated: false, reason: "not-worktree" };
+  }
+
+  try {
+    const worktreeHead = gitRevParse(worktreeCwd, "HEAD");
+    const branchHead = gitRevParse(projectRoot, milestoneBranch);
+
+    if (!worktreeHead || !branchHead || worktreeHead === branchHead) {
+      return { checked: true, updated: false, reason: "already-current" };
+    }
+
+    if (nativeIsAncestor(projectRoot, branchHead, worktreeHead)) {
+      nativeUpdateRef(
+        projectRoot,
+        `refs/heads/${milestoneBranch}`,
+        worktreeHead,
+      );
+      debugLog("mergeMilestoneToMain", {
+        action: "fast-forward-branch-ref",
+        milestoneBranch,
+        oldRef: branchHead.slice(0, 8),
+        newRef: worktreeHead.slice(0, 8),
+      });
+      return { checked: true, updated: true, reason: "fast-forwarded" };
+    }
+
+    process.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Worktree HEAD (${worktreeHead.slice(0, 8)}) diverged from ` +
+        `${milestoneBranch} (${branchHead.slice(0, 8)}). ` +
+        `Manual reconciliation required before merge.`,
+    );
+  } catch (err) {
+    if (err instanceof GSDError) throw err;
+    debugLog("mergeMilestoneToMain", {
+      action: "reconcile-skipped",
+      reason: String(err),
+    });
+    return { checked: false, updated: false, reason: "lookup-failed" };
+  }
+}
+
+function gitRevParse(cwd: string, ref: string): string {
+  return execFileSync("git", ["rev-parse", ref], {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}

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

@@ -0,0 +1,132 @@
+// gsd-pi — Milestone merge cleanup module.
+//
+// Owns the teardown ordering after a milestone has safely reached the
+// integration branch: clear transient state, remove the worktree, delete the
+// milestone branch only after removal succeeds, clear process-local workspace
+// state, and anchor cwd back at the project root.
+
+import { nativeBranchDelete } from "./native-git-bridge.js";
+import { clearProjectRootStateFiles } from "./auto-worktree-cleanup.js";
+import { setActiveWorkspace } from "./auto-worktree-session-registry.js";
+import { removeWorktree } from "./worktree-manager.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
+
+export interface MilestoneMergeCleanupRequest {
+  projectRoot: string;
+  milestoneId: string;
+  milestoneBranch: string;
+  previousCwd: string;
+  clearProjectRootState?: boolean;
+  chdirWarningContext?: string;
+}
+
+export interface MilestoneMergeCleanupResult {
+  worktreeRemoved: boolean;
+  branchDeleteAttempted: boolean;
+  activeWorkspaceCleared: boolean;
+}
+
+interface MilestoneMergeCleanupDeps {
+  clearProjectRootStateFiles: typeof clearProjectRootStateFiles;
+  removeWorktree: typeof removeWorktree;
+  nativeBranchDelete: typeof nativeBranchDelete;
+  setActiveWorkspace: typeof setActiveWorkspace;
+  nudgeGitBranchCache: typeof nudgeGitBranchCache;
+  chdir: (path: string) => void;
+}
+
+const defaultDeps: MilestoneMergeCleanupDeps = {
+  clearProjectRootStateFiles,
+  removeWorktree,
+  nativeBranchDelete,
+  setActiveWorkspace,
+  nudgeGitBranchCache,
+  chdir: process.chdir.bind(process),
+};
+
+let deps: MilestoneMergeCleanupDeps = defaultDeps;
+
+export function _setMilestoneCleanupDepsForTests(overrides: Partial<MilestoneMergeCleanupDeps>): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMilestoneCleanupDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+export function cleanupMergedMilestoneWorktree(
+  request: MilestoneMergeCleanupRequest,
+): MilestoneMergeCleanupResult {
+  const {
+    projectRoot,
+    milestoneId,
+    milestoneBranch,
+    previousCwd,
+    clearProjectRootState = false,
+    chdirWarningContext = "after milestone cleanup",
+  } = request;
+
+  if (clearProjectRootState) {
+    try {
+      deps.clearProjectRootStateFiles(projectRoot, milestoneId);
+    } catch (err) {
+      logWarning("worktree", `clearProjectRootStateFiles failed during milestone cleanup: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  let worktreeRemoved = true;
+  try {
+    worktreeRemoved = deps.removeWorktree(projectRoot, milestoneId, {
+      branch: milestoneBranch,
+      deleteBranch: false,
+    });
+  } catch (err) {
+    worktreeRemoved = false;
+    logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!worktreeRemoved) {
+    logWarning(
+      "worktree",
+      `Skipping milestone branch deletion for ${milestoneBranch}; worktree removal was aborted to preserve uncommitted milestone work.`,
+    );
+    deps.nudgeGitBranchCache(previousCwd);
+    chdirToProjectRoot(projectRoot, chdirWarningContext);
+    return {
+      worktreeRemoved: false,
+      branchDeleteAttempted: false,
+      activeWorkspaceCleared: false,
+    };
+  }
+
+  try {
+    deps.nativeBranchDelete(projectRoot, milestoneBranch);
+  } catch (err) {
+    logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  deps.setActiveWorkspace(null);
+  deps.nudgeGitBranchCache(previousCwd);
+  chdirToProjectRoot(projectRoot, chdirWarningContext);
+
+  return {
+    worktreeRemoved: true,
+    branchDeleteAttempted: true,
+    activeWorkspaceCleared: true,
+  };
+}
+
+function chdirToProjectRoot(projectRoot: string, context: string): void {
+  try {
+    deps.chdir(projectRoot);
+  } catch (err) {
+    logWarning("worktree", `chdir to project root ${context} failed: ${err instanceof Error ? err.message : String(err)}`);
+    debugLog("mergeMilestoneToMain", {
+      phase: "post-merge-chdir-failed",
+      target: projectRoot,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/resources/extensions/gsd/auto-worktree-merge-code-changes.ts

@@ -0,0 +1,71 @@
+// gsd-pi — Code-change safety checks for auto-worktree merge closeout.
+//
+// Owns the git diff policy that decides whether a completed milestone actually
+// changed user code, and whether an empty merge result is safe to clean up.
+
+import { execFileSync } from "node:child_process";
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { nativeDiffNumstat } from "./native-git-bridge.js";
+import { logWarning } from "./workflow-logger.js";
+
+const GIT_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+export function assertNoUnanchoredCodeChangesAfterEmptyMerge(
+  basePath: string,
+  mainBranch: string,
+  milestoneBranch: string,
+  effectiveStrategy: "merge" | "squash",
+  nothingToCommit: boolean,
+): void {
+  if (!nothingToCommit) return;
+
+  const codeChanges = nativeDiffNumstat(basePath, mainBranch, milestoneBranch)
+    .filter((entry) => !entry.path.startsWith(".gsd/"));
+  if (codeChanges.length === 0) return;
+
+  throw new GSDError(
+    GSD_GIT_ERROR,
+    `${effectiveStrategy === "merge" ? "Merge" : "Squash merge"} produced nothing to commit but milestone branch "${milestoneBranch}" ` +
+      `has ${codeChanges.length} code file(s) not on "${mainBranch}". ` +
+      `Aborting worktree teardown to prevent data loss.`,
+  );
+}
+
+export function detectMergedCodeFilesChanged(basePath: string, nothingToCommit: boolean): boolean {
+  if (nothingToCommit) return false;
+
+  try {
+    const diffTreeOutput = execFileSync(
+      "git",
+      ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"],
+      { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trim();
+    return containsCodeFile(diffTreeOutput);
+  } catch (err) {
+    return detectCodeFilesChangedFromEmptyTree(basePath, err);
+  }
+}
+
+function detectCodeFilesChangedFromEmptyTree(basePath: string, originalError: unknown): boolean {
+  try {
+    const fallbackOutput = execFileSync(
+      "git",
+      ["diff", "--name-only", GIT_EMPTY_TREE, "HEAD"],
+      { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trim();
+    return containsCodeFile(fallbackOutput);
+  } catch {
+    // Truly unable to determine — assume code was changed to avoid silent data loss.
+    logWarning(
+      "worktree",
+      `diff-tree and empty-tree fallback both failed (assuming code changed): ${originalError instanceof Error ? originalError.message : String(originalError)}`,
+    );
+    return true;
+  }
+}
+
+function containsCodeFile(output: string): boolean {
+  const files = output ? output.split("\n").filter(Boolean) : [];
+  return files.some((file) => !file.startsWith(".gsd/"));
+}