@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

package/src/resources/extensions/gsd/auto-worktree-conflict-auto-resolve.ts

@@ -0,0 +1,37 @@
+// gsd-pi — Conflict auto-resolve policy for auto-worktree merges.
+//
+// Owns the pure path policy for conflict paths that are safe to resolve
+// mechanically. Git mutation stays in git-conflict-resolve.ts.
+
+/** Patterns for machine-generated build artifacts that can be safely
+ * auto-resolved by accepting --theirs during merge. These files are
+ * regenerable and never contain meaningful manual edits. */
+export const SAFE_AUTO_RESOLVE_PATTERNS: RegExp[] = [
+  /\.tsbuildinfo$/,
+  /\.pyc$/,
+  /\/__pycache__\//,
+  /\.DS_Store$/,
+  /\.map$/,
+  // Regenerable dependency lockfiles. These are fully derivable from their
+  // manifests by the package manager, so accepting the merge side during
+  // auto-resolve clears the conflict markers without losing meaningful edits —
+  // and stops auto-mode from hard-pausing on a lockfile conflict (issue #828).
+  /(?:^|\/)pnpm-lock\.yaml$/,
+  /(?:^|\/)package-lock\.json$/,
+  /(?:^|\/)npm-shrinkwrap\.json$/,
+  /(?:^|\/)yarn\.lock$/,
+  /(?:^|\/)bun\.lockb?$/,
+  /(?:^|\/)Cargo\.lock$/,
+  /(?:^|\/)composer\.lock$/,
+  /(?:^|\/)Gemfile\.lock$/,
+  /(?:^|\/)Pipfile\.lock$/,
+  /(?:^|\/)poetry\.lock$/,
+];
+
+/** Returns true if the file path is safe to auto-resolve during merge.
+ * Covers `.gsd/` state files, common build artifacts, and regenerable
+ * dependency lockfiles. */
+export function isSafeToAutoResolve(filePath: string): boolean {
+  return filePath.startsWith(".gsd/")
+    || SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
+}

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

@@ -0,0 +1,171 @@
+// gsd-pi — Auto-worktree creation module.
+//
+// Owns the creation path for milestone worktrees: repository readiness,
+// branch reuse/start-point selection, initial untracked-content import,
+// post-create hook, cwd transition, and session registry update.
+
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { classifyProject } from "./detection.js";
+import { GSDError, GSD_GIT_ERROR, GSD_IO_ERROR } from "./errors.js";
+import { readIntegrationBranch } from "./git-service.js";
+import { nativeBranchExists } from "./native-git-bridge.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import {
+  autoWorktreeBranch,
+  fastForwardReusedMilestoneBranchIfSafe,
+  _resolveAutoWorktreeStartPoint,
+} from "./auto-worktree-branch-lifecycle.js";
+import { setActiveWorkspace } from "./auto-worktree-session-registry.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
+import { createWorktree } from "./worktree-manager.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { createWorkspace } from "./workspace.js";
+import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
+
+function importUntrackedProjectRootContentIntoEmptyWorktree(
+  projectRoot: string,
+  worktreeRoot: string,
+  milestoneId: string,
+): number {
+  const worktreeClassification = classifyProject(worktreeRoot);
+  if (worktreeClassification.kind !== "greenfield") return 0;
+
+  const projectRootClassification = classifyProject(projectRoot);
+  if (
+    projectRootClassification.kind === "greenfield" ||
+    projectRootClassification.kind === "invalid-repo" ||
+    projectRootClassification.untrackedFiles.length === 0
+  ) {
+    return 0;
+  }
+
+  let copied = 0;
+  for (const relPath of projectRootClassification.untrackedFiles) {
+    const src = join(projectRoot, relPath);
+    if (!existsSync(src)) continue;
+
+    const dst = join(worktreeRoot, relPath);
+    if (existsSync(dst)) continue;
+
+    mkdirSync(dirname(dst), { recursive: true });
+    cpSync(src, dst, { recursive: true, force: false });
+    copied++;
+  }
+
+  if (copied > 0) {
+    debugLog("createAutoWorktree", {
+      phase: "import-untracked-project-content",
+      milestoneId,
+      copied,
+    });
+  }
+
+  return copied;
+}
+
+export function createAutoWorktree(
+  basePath: string,
+  milestoneId: string,
+): string {
+  basePath = resolveWorktreeProjectRoot(basePath);
+
+  // Check if repo has commits — git worktree requires a valid HEAD.
+  try {
+    execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+      cwd: basePath,
+      stdio: "pipe",
+    });
+  } catch {
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      "Cannot create worktree: repository has no commits yet. Worktree isolation requires at least one commit.",
+    );
+  }
+
+  const branch = autoWorktreeBranch(milestoneId);
+
+  // Check if the milestone branch already exists — it survives auto-mode
+  // stop/pause and contains committed work from prior sessions. If it exists,
+  // re-attach the worktree to it WITHOUT resetting. Only create a fresh branch
+  // from the integration branch when no prior work exists.
+  const branchExists = nativeBranchExists(basePath, branch);
+
+  let info: { name: string; path: string; branch: string; exists: boolean };
+  if (branchExists) {
+    // #5538-followup: fast-forward the reused branch onto the integration
+    // branch when safe so the next milestone forks from up-to-date code.
+    // Without this, a milestone that was created before another milestone
+    // merged into main would carry a stale base into its worktree.
+    fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch);
+
+    // Re-attach worktree to the existing milestone branch (preserving commits).
+    info = createWorktree(basePath, milestoneId, {
+      branch,
+      reuseExistingBranch: true,
+    });
+  } else {
+    // Fresh start — create branch from integration branch.
+    // Use the same 3-tier fallback as mergeMilestoneToMain (#3461):
+    //   1. META.json integration branch (explicit per-milestone override)
+    //   2. git.main_branch preference (user's configured working branch)
+    //   3. nativeDetectMainBranch (origin/HEAD auto-detection)
+    // Without tier 2, projects with main_branch=dev but origin/HEAD→master
+    // would fork worktrees from the wrong (stale) branch.
+    const integrationBranch = readIntegrationBranch(basePath, milestoneId)
+      ?? undefined;
+    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    const startPoint = _resolveAutoWorktreeStartPoint(
+      integrationBranch,
+      gitPrefs?.main_branch,
+      (branchName) => nativeBranchExists(basePath, branchName),
+    );
+    info = createWorktree(basePath, milestoneId, {
+      branch,
+      startPoint,
+    });
+  }
+
+  // Phase C: copyPlanningArtifacts and reconcilePlanCheckboxes were
+  // deleted. Both addressed the same problem (worktree-local .gsd/
+  // projection lagging behind project-root state) by maintaining a stale
+  // copy. Now that auto-mode writers in workflow-projections.ts,
+  // triage-resolution.ts, rule-registry.ts, and auto-post-unit.ts route
+  // through s.canonicalProjectRoot, the worktree never needs a local
+  // .gsd/ — both reads and writes converge on the project-root .gsd/.
+  // The original concerns (#759, #778) no longer apply because there is
+  // no second copy to drift.
+  importUntrackedProjectRootContentIntoEmptyWorktree(
+    basePath,
+    info.path,
+    milestoneId,
+  );
+
+  // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets.
+  const hookError = runWorktreePostCreateHook(basePath, info.path);
+  if (hookError) {
+    // Non-fatal — log but don't prevent worktree usage.
+    logWarning("reconcile", hookError, { worktree: info.name });
+  }
+
+  const previousCwd = process.cwd();
+
+  try {
+    process.chdir(info.path);
+    setActiveWorkspace(createWorkspace(basePath));
+  } catch (err) {
+    // If chdir fails, the worktree was created but we couldn't enter it.
+    // Don't set activeWorkspace -- caller can retry or clean up.
+    throw new GSDError(
+      GSD_IO_ERROR,
+      `Auto-worktree created at ${info.path} but chdir failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  nudgeGitBranchCache(previousCwd);
+  return info.path;
+}

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();
+}