@opengsd/gsd-pi 1.0.0

package/src/resources/extensions/gsd/detection.ts

@@ -0,0 +1,1339 @@
+/**
+ * GSD Detection — Project state and ecosystem detection.
+ *
+ * Pure functions, zero UI dependencies, zero side effects.
+ * Used by init-wizard.ts and guided-flow.ts to determine what onboarding
+ * flow to show when entering a project directory.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, parse as parsePath } from "node:path";
+import { homedir } from "node:os";
+import { gsdRoot } from "./paths.js";
+import { gsdHome } from "./gsd-home.js";
+
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface ProjectDetection {
+  /** What kind of GSD state exists in this directory */
+  state: "none" | "v1-planning" | "v2-gsd" | "v2-gsd-empty";
+
+  /** Is this the first time GSD has been used on this machine? */
+  isFirstEverLaunch: boolean;
+
+  /** Does ~/.gsd/ exist with preferences? */
+  hasGlobalSetup: boolean;
+
+  /** v1 details (only when state === 'v1-planning') */
+  v1?: V1Detection;
+
+  /** v2 details (only when state === 'v2-gsd' or 'v2-gsd-empty') */
+  v2?: V2Detection;
+
+  /** Detected project ecosystem signals */
+  projectSignals: ProjectSignals;
+}
+
+export interface V1Detection {
+  path: string;
+  hasPhasesDir: boolean;
+  hasRoadmap: boolean;
+  phaseCount: number;
+}
+
+export interface V2Detection {
+  milestoneCount: number;
+  hasPreferences: boolean;
+  hasContext: boolean;
+}
+
+/** Apple platform SDKROOTs found in Xcode project.pbxproj files. */
+export type XcodePlatform = "iphoneos" | "macosx" | "watchos" | "appletvos" | "xros";
+
+export interface ProjectSignals {
+  /** Detected project/package files */
+  detectedFiles: string[];
+  /** Is this already a git repo? */
+  isGitRepo: boolean;
+  /** Is this a monorepo? */
+  isMonorepo: boolean;
+  /** Primary language hint */
+  primaryLanguage?: string;
+  /** Apple platform SDKROOTs detected from *.xcodeproj/project.pbxproj */
+  xcodePlatforms: XcodePlatform[];
+  /** Has existing CI configuration? */
+  hasCI: boolean;
+  /** Has existing test setup? */
+  hasTests: boolean;
+  /** Detected package manager */
+  packageManager?: string;
+  /** Auto-detected verification commands */
+  verificationCommands: string[];
+}
+
+export type ProjectClassificationKind =
+  | "invalid-repo"
+  | "greenfield"
+  | "untyped-existing"
+  | "typed-existing";
+
+export interface ProjectClassification {
+  kind: ProjectClassificationKind;
+  signals: ProjectSignals;
+  trackedFiles: string[];
+  untrackedFiles: string[];
+  contentFiles: string[];
+  markers: string[];
+  reason: string;
+}
+
+// ─── Project File Markers ───────────────────────────────────────────────────────
+
+export const PROJECT_FILES = [
+  "package.json",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "setup.py",
+  "Gemfile",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "CMakeLists.txt",
+  "Makefile",
+  "composer.json",
+  "pubspec.yaml",
+  "Package.swift",
+  "mix.exs",
+  "deno.json",
+  "deno.jsonc",
+  // .NET
+  ".sln",
+  ".csproj",
+  "Directory.Build.props",
+  // Git submodules
+  ".gitmodules",
+  // Xcode
+  "project.yml",
+  ".xcodeproj",
+  ".xcworkspace",
+  // Cloud platform config files
+  "firebase.json",
+  "cdk.json",
+  "samconfig.toml",
+  "serverless.yml",
+  "serverless.yaml",
+  "azure-pipelines.yml",
+  // Database / ORM config files
+  "prisma/schema.prisma",
+  "supabase/config.toml",
+  "drizzle.config.ts",
+  "drizzle.config.js",
+  "redis.conf",
+  // React Native markers
+  "metro.config.js",
+  "metro.config.ts",
+  "react-native.config.js",
+  // Frontend framework config files
+  "angular.json",
+  "next.config.js",
+  "next.config.ts",
+  "next.config.mjs",
+  "nuxt.config.ts",
+  "nuxt.config.js",
+  "svelte.config.js",
+  "svelte.config.ts",
+  // Vue CLI config files
+  "vue.config.js",
+  "vue.config.ts",
+  // Frontend tooling
+  "tailwind.config.js",
+  "tailwind.config.ts",
+  "tailwind.config.mjs",
+  "tailwind.config.cjs",
+  // Android project markers
+  "app/build.gradle",
+  "app/build.gradle.kts",
+  // Container / DevOps config files
+  "Dockerfile",
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  // Infrastructure as Code
+  "main.tf",
+  // Kubernetes / Helm markers
+  "Chart.yaml",
+  "kustomization.yaml",
+  // CI/CD markers
+  ".github/workflows",
+  // Blockchain / Web3 markers
+  "hardhat.config.js",
+  "hardhat.config.ts",
+  "foundry.toml",
+  // Data engineering markers
+  "dbt_project.yml",
+  "airflow.cfg",
+  // Game engine markers
+  "ProjectSettings/ProjectVersion.txt",
+  "project.godot",
+  // Python framework markers
+  "manage.py",
+  "requirements.txt",
+] as const;
+
+/** File extensions that indicate SQLite databases in the project. */
+const SQLITE_EXTENSIONS = [".sqlite", ".sqlite3", ".db"] as const;
+
+/** File extensions that indicate SQL usage (migrations, schemas, seeds). */
+const SQL_EXTENSIONS = [".sql"] as const;
+
+/** File extensions that indicate .NET / C# projects. */
+const DOTNET_EXTENSIONS = [".csproj", ".sln", ".fsproj"] as const;
+
+/** File extensions that indicate Vue.js single-file components. */
+const VUE_EXTENSIONS = [".vue"] as const;
+
+const LANGUAGE_MAP: Record<string, string> = {
+  "package.json": "javascript/typescript",
+  "Cargo.toml": "rust",
+  "go.mod": "go",
+  "pyproject.toml": "python",
+  "setup.py": "python",
+  "Gemfile": "ruby",
+  "pom.xml": "java",
+  "build.gradle": "java/kotlin",
+  "build.gradle.kts": "kotlin",
+  "app/build.gradle": "java/kotlin",
+  "app/build.gradle.kts": "kotlin",
+  "CMakeLists.txt": "c/c++",
+  "composer.json": "php",
+  "pubspec.yaml": "dart/flutter",
+  "Package.swift": "swift",
+  "mix.exs": "elixir",
+  "deno.json": "typescript/deno",
+  "deno.jsonc": "typescript/deno",
+  ".sln": "dotnet",
+  ".csproj": "dotnet",
+  "Directory.Build.props": "dotnet",
+  "project.yml": "swift/xcode",
+  ".xcodeproj": "swift/xcode",
+  ".xcworkspace": "swift/xcode",
+  "Dockerfile": "docker",
+  "manage.py": "python",
+  "requirements.txt": "python",
+};
+
+const MONOREPO_MARKERS = [
+  "lerna.json",
+  "nx.json",
+  "turbo.json",
+  "pnpm-workspace.yaml",
+] as const;
+
+const CI_MARKERS = [
+  ".github/workflows",
+  ".gitlab-ci.yml",
+  "Jenkinsfile",
+  ".circleci",
+  ".travis.yml",
+  "azure-pipelines.yml",
+  "bitbucket-pipelines.yml",
+] as const;
+
+const TEST_MARKERS = [
+  "__tests__",
+  "tests",
+  "test",
+  "spec",
+  "jest.config.js",
+  "jest.config.ts",
+  "vitest.config.ts",
+  "vitest.config.js",
+  ".mocharc.yml",
+  "pytest.ini",
+  "conftest.py",
+  "phpunit.xml",
+] as const;
+
+/** Directories skipped during bounded recursive project scans. */
+const RECURSIVE_SCAN_IGNORED_DIRS = new Set([
+  ".git",
+  ".gsd",
+  ".bg-shell",
+  ".planning",
+  ".plans",
+  ".claude",
+  ".cursor",
+  ".vscode",
+  "node_modules",
+  ".venv",
+  "venv",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".nuxt",
+  "target",
+  "vendor",
+  ".turbo",
+  "Pods",
+  "bin",
+  "obj",
+  ".gradle",
+  "DerivedData",
+  "out",
+]) as ReadonlySet<string>;
+
+const PROJECT_CONTENT_EXCLUDE_DIRS = RECURSIVE_SCAN_IGNORED_DIRS;
+
+/** Project file markers safe to detect recursively via suffix matching. */
+const ROOT_ONLY_PROJECT_FILES = new Set<string>([
+  ".github/workflows",
+  "package.json",
+  "Gemfile",
+  "Makefile",
+  "CMakeLists.txt",
+  "build.gradle",
+  "build.gradle.kts",
+  "deno.json",
+  "deno.jsonc",
+]);
+
+const MAX_RECURSIVE_SCAN_FILES = 2000;
+const MAX_RECURSIVE_SCAN_DEPTH = 6;
+
+// ─── Core Detection ─────────────────────────────────────────────────────────────
+
+/**
+ * Detect the full project state for a given directory.
+ * This is the main entry point — calls all sub-detectors.
+ */
+export function detectProjectState(basePath: string): ProjectDetection {
+  const v1 = detectV1Planning(basePath);
+  const v2 = detectV2Gsd(basePath);
+  const projectSignals = detectProjectSignals(basePath);
+  const globalSetup = hasGlobalSetup();
+  const firstEver = isFirstEverLaunch();
+
+  let state: ProjectDetection["state"];
+  if (v2 && v2.milestoneCount > 0) {
+    state = "v2-gsd";
+  } else if (v2 && v2.milestoneCount === 0) {
+    state = "v2-gsd-empty";
+  } else if (v1) {
+    state = "v1-planning";
+  } else {
+    state = "none";
+  }
+
+  return {
+    state,
+    isFirstEverLaunch: firstEver,
+    hasGlobalSetup: globalSetup,
+    v1: v1 ?? undefined,
+    v2: v2 ?? undefined,
+    projectSignals,
+  };
+}
+
+// ─── V1 Planning Detection ──────────────────────────────────────────────────────
+
+/**
+ * Detect a v1 .planning/ directory with GSD v1 markers.
+ * Returns null if no .planning/ directory found.
+ */
+export function detectV1Planning(basePath: string): V1Detection | null {
+  const planningPath = join(basePath, ".planning");
+
+  if (!existsSync(planningPath)) return null;
+
+  try {
+    const stat = statSync(planningPath);
+    if (!stat.isDirectory()) return null;
+  } catch {
+    return null;
+  }
+
+  const hasRoadmap = existsSync(join(planningPath, "ROADMAP.md"));
+  const phasesPath = join(planningPath, "phases");
+  const hasPhasesDir = existsSync(phasesPath);
+
+  let phaseCount = 0;
+  if (hasPhasesDir) {
+    try {
+      const entries = readdirSync(phasesPath, { withFileTypes: true });
+      phaseCount = entries.filter(e => e.isDirectory()).length;
+    } catch {
+      // unreadable — report 0
+    }
+  }
+
+  return {
+    path: planningPath,
+    hasPhasesDir,
+    hasRoadmap,
+    phaseCount,
+  };
+}
+
+// ─── V2 GSD Detection ──────────────────────────────────────────────────────────
+
+function detectV2Gsd(basePath: string): V2Detection | null {
+  const gsdPath = gsdRoot(basePath);
+
+  if (!existsSync(gsdPath)) return null;
+
+  const hasPreferences =
+    existsSync(join(gsdPath, "PREFERENCES.md")) ||
+    existsSync(join(gsdPath, "preferences.md"));
+
+  const hasContext = existsSync(join(gsdPath, "CONTEXT.md"));
+
+  let milestoneCount = 0;
+  const milestonesPath = join(gsdPath, "milestones");
+  if (existsSync(milestonesPath)) {
+    try {
+      const entries = readdirSync(milestonesPath, { withFileTypes: true });
+      milestoneCount = entries.filter(e => e.isDirectory()).length;
+    } catch {
+      // unreadable — report 0
+    }
+  }
+
+  return { milestoneCount, hasPreferences, hasContext };
+}
+
+// ─── Project Signals Detection ──────────────────────────────────────────────────
+
+/**
+ * Quick filesystem scan for project ecosystem markers.
+ * Reads only file existence + minimal content (package.json for monorepo/scripts).
+ */
+export function detectProjectSignals(basePath: string): ProjectSignals {
+  const detectedFiles: string[] = [];
+  let primaryLanguage: string | undefined;
+
+  // Detect project files
+  for (const file of PROJECT_FILES) {
+    if (existsSync(join(basePath, file))) {
+      detectedFiles.push(file);
+      if (!primaryLanguage) {
+        primaryLanguage = LANGUAGE_MAP[file];
+      }
+    }
+  }
+
+  // Bounded recursive scan for nested markers and dependency files.
+  // This covers common brownfield layouts like src/App/App.csproj,
+  // db/migrations/*.sql, src/components/*.vue, and services/api/pyproject.toml
+  // without walking the entire repo or diving into heavyweight folders.
+  const scannedFiles = scanProjectFiles(basePath);
+
+  for (const file of PROJECT_FILES) {
+    if (detectedFiles.includes(file) || ROOT_ONLY_PROJECT_FILES.has(file)) continue;
+    const hasMatch = file === "requirements.txt"
+      ? scannedFiles.some(isPythonRequirementsFile)
+      : scannedFiles.some((scannedFile) => matchesProjectFileMarker(scannedFile, file));
+    if (hasMatch) {
+      pushUnique(detectedFiles, file);
+      if (!primaryLanguage && LANGUAGE_MAP[file]) {
+        primaryLanguage = LANGUAGE_MAP[file];
+      }
+    }
+  }
+
+  if (scannedFiles.some((file) => SQLITE_EXTENSIONS.some((ext) => file.endsWith(ext)))) {
+    pushUnique(detectedFiles, "*.sqlite");
+  }
+  if (scannedFiles.some((file) => SQL_EXTENSIONS.some((ext) => file.endsWith(ext)))) {
+    pushUnique(detectedFiles, "*.sql");
+  }
+
+  const hasCsproj = scannedFiles.some((file) => file.endsWith(".csproj"));
+  const hasFsproj = scannedFiles.some((file) => file.endsWith(".fsproj"));
+  const hasSln = scannedFiles.some((file) => file.endsWith(".sln"));
+
+  if (hasCsproj) {
+    pushUnique(detectedFiles, "*.csproj");
+    if (!primaryLanguage) primaryLanguage = "csharp";
+  }
+  if (hasFsproj) {
+    pushUnique(detectedFiles, "*.fsproj");
+    if (!primaryLanguage) primaryLanguage = "fsharp";
+  }
+  if (hasSln) {
+    pushUnique(detectedFiles, "*.sln");
+    if (!primaryLanguage) primaryLanguage = "dotnet";
+  }
+
+  if (scannedFiles.some((file) => VUE_EXTENSIONS.some((ext) => file.endsWith(ext)))) {
+    pushUnique(detectedFiles, "*.vue");
+  }
+
+  // Python framework detection — scan dependency files for framework-specific packages.
+  // Adds synthetic markers (e.g. "dep:fastapi") so skill catalog matchFiles can reference them.
+  const dependencyFiles = scannedFiles.filter((file) =>
+    isPythonRequirementsFile(file) || file.endsWith("pyproject.toml"),
+  );
+  if (containsFastapiDependency(basePath, dependencyFiles)) {
+    pushUnique(detectedFiles, "dep:fastapi");
+  }
+
+  const springBootBuildFiles = scannedFiles.filter((file) =>
+    file.endsWith("pom.xml") || file.endsWith("build.gradle") || file.endsWith("build.gradle.kts"),
+  );
+  const springBootVersionCatalogs = scannedFiles.filter((file) => file.endsWith(".versions.toml"));
+  const springBootSettingsFiles = scannedFiles.filter((file) =>
+    file.endsWith("settings.gradle") || file.endsWith("settings.gradle.kts"),
+  );
+  if (containsSpringBootMarker(basePath, springBootBuildFiles, springBootVersionCatalogs, springBootSettingsFiles)) {
+    pushUnique(detectedFiles, "dep:spring-boot");
+    if (!primaryLanguage) {
+      primaryLanguage = "java/kotlin";
+    }
+  }
+
+  // Git repo detection
+  const isGitRepo = existsSync(join(basePath, ".git"));
+
+  // Xcode platform detection — parse SDKROOT from project.pbxproj
+  const xcodePlatforms = detectXcodePlatforms(basePath);
+
+  // Set primaryLanguage to swift when an Xcode project is found but no
+  // Package.swift was detected (CocoaPods or SPM-less projects).
+  if (!primaryLanguage && xcodePlatforms.length > 0) {
+    primaryLanguage = "swift";
+  }
+
+  // Monorepo detection
+  let isMonorepo = false;
+  for (const marker of MONOREPO_MARKERS) {
+    if (existsSync(join(basePath, marker))) {
+      isMonorepo = true;
+      break;
+    }
+  }
+  // Also check package.json workspaces
+  if (!isMonorepo && detectedFiles.includes("package.json")) {
+    isMonorepo = packageJsonHasWorkspaces(basePath);
+  }
+
+  // CI detection
+  let hasCI = false;
+  for (const marker of CI_MARKERS) {
+    if (existsSync(join(basePath, marker))) {
+      hasCI = true;
+      break;
+    }
+  }
+
+  // Test detection
+  let hasTests = false;
+  for (const marker of TEST_MARKERS) {
+    if (existsSync(join(basePath, marker))) {
+      hasTests = true;
+      break;
+    }
+  }
+
+  // Package manager detection
+  const packageManager = detectPackageManager(basePath);
+
+  // Verification commands
+  const verificationCommands = detectVerificationCommands(basePath, detectedFiles, packageManager);
+
+  return {
+    detectedFiles,
+    isGitRepo,
+    isMonorepo,
+    primaryLanguage,
+    xcodePlatforms,
+    hasCI,
+    hasTests,
+    packageManager,
+    verificationCommands,
+  };
+}
+
+function normalizeGitPath(file: string): string {
+  return file.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function isProjectContentFile(file: string): boolean {
+  const normalized = normalizeGitPath(file);
+  if (!normalized || normalized.endsWith("/")) return false;
+  if (normalized === ".gitignore" || normalized === ".gitattributes") return false;
+  const parts = normalized.split("/");
+  if (parts.some((part) => PROJECT_CONTENT_EXCLUDE_DIRS.has(part))) return false;
+  if (normalized.endsWith(".DS_Store")) return false;
+  return true;
+}
+
+function runGitLines(basePath: string, args: string[]): string[] {
+  try {
+    const output = execFileSync("git", args, {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+    }).trim();
+    return output ? output.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+function listTrackedProjectFiles(basePath: string): string[] {
+  return runGitLines(basePath, ["ls-files"])
+    .map(normalizeGitPath)
+    .filter(isProjectContentFile);
+}
+
+function listUntrackedProjectFiles(basePath: string): string[] {
+  return runGitLines(basePath, ["ls-files", "--others", "--exclude-standard"])
+    .map(normalizeGitPath)
+    .filter(isProjectContentFile);
+}
+
+function hasKnownProjectMarkers(basePath: string, signals: ProjectSignals): boolean {
+  if (signals.detectedFiles.length > 0) return true;
+  if (signals.xcodePlatforms.length > 0) return true;
+  return false;
+}
+
+/**
+ * Classify repo presence separately from ecosystem/tooling markers.
+ *
+ * Known project files identify tooling. Git-tracked/non-ignored content
+ * identifies whether this is an existing project at all. This keeps small
+ * static or documentation repos from being mislabeled as greenfield.
+ */
+export function classifyProject(basePath: string): ProjectClassification {
+  const signals = detectProjectSignals(basePath);
+  const markers = [...signals.detectedFiles];
+
+  if (!signals.isGitRepo) {
+    return {
+      kind: "invalid-repo",
+      signals,
+      trackedFiles: [],
+      untrackedFiles: [],
+      contentFiles: [],
+      markers,
+      reason: "missing .git",
+    };
+  }
+
+  const trackedFiles = listTrackedProjectFiles(basePath);
+  const untrackedFiles = listUntrackedProjectFiles(basePath);
+  const contentFiles = [...new Set([...trackedFiles, ...untrackedFiles])];
+  const hasMarkers = hasKnownProjectMarkers(basePath, signals);
+
+  if (hasMarkers) {
+    return {
+      kind: "typed-existing",
+      signals,
+      trackedFiles,
+      untrackedFiles,
+      contentFiles,
+      markers,
+      reason: markers.length > 0 ? `detected markers: ${markers.join(", ")}` : "detected project structure",
+    };
+  }
+
+  if (contentFiles.length > 0) {
+    return {
+      kind: "untyped-existing",
+      signals,
+      trackedFiles,
+      untrackedFiles,
+      contentFiles,
+      markers,
+      reason: "project content exists but no recognized tooling markers were found",
+    };
+  }
+
+  return {
+    kind: "greenfield",
+    signals,
+    trackedFiles,
+    untrackedFiles,
+    contentFiles,
+    markers,
+    reason: "no tracked or non-ignored project content",
+  };
+}
+
+// ─── Xcode Platform Detection ───────────────────────────────────────────────────
+
+/** Known SDKROOT values → canonical platform names. */
+const SDKROOT_MAP: Record<string, XcodePlatform> = {
+  iphoneos: "iphoneos",
+  iphonesimulator: "iphoneos",      // simulator builds still target iOS
+  macosx: "macosx",
+  watchos: "watchos",
+  watchsimulator: "watchos",
+  appletvos: "appletvos",
+  appletvsimulator: "appletvos",
+  xros: "xros",
+  xrsimulator: "xros",
+};
+
+/** Regex for SUPPORTED_PLATFORMS — fallback when SDKROOT = auto (Xcode 15+). */
+const SUPPORTED_PLATFORMS_RE = /SUPPORTED_PLATFORMS\s*=\s*"([^"]+)"/gi;
+
+/** Read at most `maxBytes` from a file without loading the full file into memory. */
+function readBounded(filePath: string, maxBytes: number): string {
+  const buf = Buffer.alloc(maxBytes);
+  const fd = openSync(filePath, "r");
+  try {
+    const bytesRead = readSync(fd, buf, 0, maxBytes, 0);
+    return buf.toString("utf-8", 0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Common subdirectories where .xcodeproj may live in monorepos / standard layouts. */
+const XCODE_SUBDIRS = ["ios", "macos", "app", "apps"] as const;
+
+/**
+ * Scan *.xcodeproj directories for project.pbxproj and extract SDKROOT values.
+ * Returns deduplicated, canonical platform list (e.g. ["iphoneos"]).
+ *
+ * Reading the pbxproj is a lightweight regex scan — no full plist parsing needed.
+ * We read at most 1 MB per file to keep detection fast.
+ * Searches both the project root and common subdirectories (ios/, macos/, app/).
+ */
+function detectXcodePlatforms(basePath: string): XcodePlatform[] {
+  const platforms = new Set<XcodePlatform>();
+
+  // Directories to scan: project root + common subdirs
+  const dirsToScan = [basePath];
+  for (const sub of XCODE_SUBDIRS) {
+    const subPath = join(basePath, sub);
+    if (existsSync(subPath)) dirsToScan.push(subPath);
+  }
+
+  for (const dir of dirsToScan) {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.endsWith(".xcodeproj")) continue;
+        const pbxprojPath = join(dir, entry.name, "project.pbxproj");
+        try {
+          const content = readBounded(pbxprojPath, 1024 * 1024);
+          // Match SDKROOT = <value>; — both quoted and unquoted forms
+          const sdkRe = /SDKROOT\s*=\s*"?([a-z]+)"?\s*;/gi;
+          let m: RegExpExecArray | null;
+          let foundExplicit = false;
+          while ((m = sdkRe.exec(content)) !== null) {
+            const val = m[1].toLowerCase();
+            if (val === "auto") continue; // handled below via SUPPORTED_PLATFORMS
+            const canonical = SDKROOT_MAP[val];
+            if (canonical) {
+              platforms.add(canonical);
+              foundExplicit = true;
+            }
+          }
+          // Xcode 15+ defaults SDKROOT to "auto"; fall back to SUPPORTED_PLATFORMS
+          if (!foundExplicit) {
+            let sp: RegExpExecArray | null;
+            while ((sp = SUPPORTED_PLATFORMS_RE.exec(content)) !== null) {
+              for (const tok of sp[1].split(/\s+/)) {
+                const canonical = SDKROOT_MAP[tok.toLowerCase()];
+                if (canonical) platforms.add(canonical);
+              }
+            }
+            SUPPORTED_PLATFORMS_RE.lastIndex = 0;
+          }
+        } catch {
+          // unreadable pbxproj — skip
+        }
+      }
+    } catch {
+      // unreadable directory
+    }
+  }
+  return [...platforms];
+}
+
+// ─── Package Manager Detection ──────────────────────────────────────────────────
+
+function detectPackageManager(basePath: string): string | undefined {
+  if (existsSync(join(basePath, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(basePath, "yarn.lock"))) return "yarn";
+  if (existsSync(join(basePath, "bun.lockb")) || existsSync(join(basePath, "bun.lock"))) return "bun";
+  if (existsSync(join(basePath, "package-lock.json"))) return "npm";
+  if (existsSync(join(basePath, "package.json"))) return "npm";
+  return undefined;
+}
+
+// ─── Verification Command Detection ─────────────────────────────────────────────
+
+/**
+ * Auto-detect verification commands from project files.
+ * Returns commands in priority order (test first, then build, then lint).
+ */
+function detectVerificationCommands(
+  basePath: string,
+  detectedFiles: string[],
+  packageManager?: string,
+): string[] {
+  const commands: string[] = [];
+  const pm = packageManager ?? "npm";
+  const run = pm === "npm" ? "npm run" : pm === "yarn" ? "yarn" : pm === "bun" ? "bun run" : `${pm} run`;
+
+  if (detectedFiles.includes("package.json")) {
+    const scripts = readPackageJsonScripts(basePath);
+    if (scripts) {
+      // Test commands (highest priority)
+      if (scripts.test && scripts.test !== "echo \"Error: no test specified\" && exit 1") {
+        commands.push(pm === "npm" ? "npm test" : `${pm} test`);
+      }
+      // Build commands
+      if (scripts.build) {
+        commands.push(`${run} build`);
+      }
+      // Lint commands
+      if (scripts.lint) {
+        commands.push(`${run} lint`);
+      }
+      // Typecheck commands
+      if (scripts.typecheck) {
+        commands.push(`${run} typecheck`);
+      } else if (scripts.tsc) {
+        commands.push(`${run} tsc`);
+      }
+    }
+  }
+
+  if (detectedFiles.includes("Cargo.toml")) {
+    commands.push("cargo test");
+    commands.push("cargo clippy");
+  }
+
+  if (detectedFiles.includes("go.mod")) {
+    commands.push("go test ./...");
+    commands.push("go vet ./...");
+  }
+
+  if (detectedFiles.includes("pyproject.toml") || detectedFiles.includes("setup.py") || detectedFiles.includes("requirements.txt")) {
+    commands.push("pytest");
+  }
+
+  if (detectedFiles.includes("Gemfile")) {
+    // Check for rspec vs minitest
+    if (existsSync(join(basePath, "spec"))) {
+      commands.push("bundle exec rspec");
+    } else {
+      commands.push("bundle exec rake test");
+    }
+  }
+
+  if (detectedFiles.includes("Makefile")) {
+    const makeTargets = readMakefileTargets(basePath);
+    if (makeTargets.includes("test")) {
+      commands.push("make test");
+    }
+  }
+
+  return commands;
+}
+
+// ─── Global Setup Detection ─────────────────────────────────────────────────────
+
+/**
+ * Check if global GSD setup exists (has ~/.gsd/ with preferences).
+ */
+export function hasGlobalSetup(): boolean {
+  return (
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
+  );
+}
+
+/**
+ * Check if this is the very first time GSD has been used on this machine.
+ * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
+ */
+export function isFirstEverLaunch(): boolean {
+  if (!existsSync(gsdHome())) return true;
+
+  // If we have preferences, not first launch
+  if (
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
+  ) {
+    return false;
+  }
+
+  // If we have auth.json, not first launch (onboarding.ts already ran)
+  if (existsSync(join(gsdHome(), "agent", "auth.json"))) return false;
+
+  // Check legacy path too
+  const legacyPath = join(homedir(), ".pi", "agent", "gsd-preferences.md");
+  if (existsSync(legacyPath)) return false;
+
+  return true;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────────
+
+function packageJsonHasWorkspaces(basePath: string): boolean {
+  try {
+    const raw = readFileSync(join(basePath, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    return Array.isArray(pkg.workspaces) || (pkg.workspaces && typeof pkg.workspaces === "object");
+  } catch {
+    return false;
+  }
+}
+
+function readPackageJsonScripts(basePath: string): Record<string, string> | null {
+  try {
+    const raw = readFileSync(join(basePath, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    return pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : null;
+  } catch {
+    return null;
+  }
+}
+
+function readMakefileTargets(basePath: string): string[] {
+  try {
+    const raw = readFileSync(join(basePath, "Makefile"), "utf-8");
+    const targets: string[] = [];
+    for (const line of raw.split("\n")) {
+      const match = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):/);
+      if (match) targets.push(match[1]);
+    }
+    return targets;
+  } catch {
+    return [];
+  }
+}
+
+function pushUnique(arr: string[], value: string): void {
+  if (!arr.includes(value)) arr.push(value);
+}
+
+function matchesProjectFileMarker(scannedFile: string, marker: string): boolean {
+  const normalized = scannedFile.replaceAll("\\", "/");
+  return (
+    normalized === marker ||
+    normalized.endsWith(`/${marker}`)
+  );
+}
+
+function isPythonRequirementsFile(relativePath: string): boolean {
+  const normalized = relativePath.replaceAll("\\", "/");
+  const basename = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return (
+    basename === "requirements.txt" ||
+    basename === "requirements.in" ||
+    /^requirements([-.].+)?\.(txt|in)$/i.test(basename) ||
+    /(^|\/)requirements\/.+\.(txt|in)$/i.test(normalized)
+  );
+}
+
+function containsFastapiDependency(basePath: string, relativePaths: string[]): boolean {
+  for (const relativePath of relativePaths) {
+    try {
+      const raw = readBounded(join(basePath, relativePath), 64 * 1024);
+      const content = extractDependencyContent(relativePath, raw);
+      if (isPythonRequirementsFile(relativePath)) {
+        for (const line of content.split("\n")) {
+          if (extractRequirementName(line) === "fastapi") return true;
+        }
+        continue;
+      }
+
+      if (relativePath.endsWith("pyproject.toml")) {
+        if (containsFastapiInPyproject(content)) return true;
+      }
+    } catch {
+      // unreadable file — continue scanning other candidate files
+    }
+  }
+
+  return false;
+}
+
+function containsSpringBootMarker(
+  basePath: string,
+  buildFiles: string[],
+  versionCatalogFiles: string[],
+  settingsFiles: string[],
+): boolean {
+  const usedPluginAliases = new Set<string>();
+  const usedLibraryAliases = new Set<string>();
+  const catalogAccessors = resolveVersionCatalogAccessors(basePath, versionCatalogFiles, settingsFiles);
+
+  for (const relativePath of buildFiles) {
+    try {
+      const raw = readBounded(join(basePath, relativePath), 64 * 1024);
+      const content = stripDependencyComments(relativePath, raw);
+      if (containsDirectSpringBootReference(relativePath, content)) {
+        return true;
+      }
+
+      const normalized = content.toLowerCase();
+      let match: RegExpExecArray | null;
+      for (const accessor of catalogAccessors) {
+        const aliasRe = new RegExp(`alias\\(\\s*${accessor}\\.plugins\\.([a-z0-9_.-]+)\\s*\\)`, "gi");
+        while ((match = aliasRe.exec(normalized)) !== null) {
+          usedPluginAliases.add(normalizePluginAlias(match[1]));
+        }
+
+        const libraryAliasRe = new RegExp(`\\b${accessor}\\.((?!plugins\\b)[a-z0-9_.-]+)`, "gi");
+        while ((match = libraryAliasRe.exec(normalized)) !== null) {
+          usedLibraryAliases.add(normalizePluginAlias(match[1]));
+        }
+      }
+    } catch {
+      // unreadable build file — continue scanning others
+    }
+  }
+
+  if (usedPluginAliases.size === 0 && usedLibraryAliases.size === 0) {
+    return false;
+  }
+  if (versionCatalogFiles.length === 0) {
+    return false;
+  }
+
+  const springBootAliases = new Set<string>();
+  const springBootLibraries = new Set<string>();
+  const pendingSpringBootBundles: Array<{ bundleAlias: string; referencedAliases: string[] }> = [];
+  for (const relativePath of versionCatalogFiles) {
+    try {
+      const raw = readBounded(join(basePath, relativePath), 64 * 1024);
+      const content = stripDependencyComments(relativePath, raw);
+      const aliasRe = /^\s*([A-Za-z0-9_.-]+)\s*=\s*\{[^\n}]*\bid\s*=\s*["']org\.springframework\.boot["'][^\n}]*\}/gm;
+      let match: RegExpExecArray | null;
+      while ((match = aliasRe.exec(content)) !== null) {
+        springBootAliases.add(normalizePluginAlias(match[1]));
+      }
+
+      const libraryRe = /^\s*([A-Za-z0-9_.-]+)\s*=\s*\{[^\n}]*\b(module\s*=\s*["']org\.springframework\.boot:[^"']+["']|group\s*=\s*["']org\.springframework\.boot["'][^\n}]*\bname\s*=\s*["']spring-boot[^"']*["'])[^\n}]*\}/gm;
+      while ((match = libraryRe.exec(content)) !== null) {
+        springBootLibraries.add(normalizePluginAlias(match[1]));
+      }
+
+      const bundleRe = /^\s*([A-Za-z0-9_.-]+)\s*=\s*\[([\s\S]*?)\]/gm;
+      while ((match = bundleRe.exec(content)) !== null) {
+        pendingSpringBootBundles.push({
+          bundleAlias: normalizePluginAlias(`bundles.${match[1]}`),
+          referencedAliases: match[2]
+            .split(",")
+            .map((part) => normalizePluginAlias(part.replace(/["'\s]/g, "")))
+            .filter(Boolean),
+        });
+      }
+    } catch {
+      // unreadable version catalog — continue scanning others
+    }
+  }
+
+  const springBootBundles = new Set<string>();
+  for (const pendingBundle of pendingSpringBootBundles) {
+    if (pendingBundle.referencedAliases.some((alias) => springBootLibraries.has(alias))) {
+      springBootBundles.add(pendingBundle.bundleAlias);
+    }
+  }
+
+  for (const alias of usedPluginAliases) {
+    if (springBootAliases.has(alias)) return true;
+  }
+  for (const alias of usedLibraryAliases) {
+    if (springBootLibraries.has(alias) || springBootBundles.has(alias)) return true;
+  }
+
+  return false;
+}
+
+function stripDependencyComments(relativePath: string, content: string): string {
+  if (relativePath.endsWith("requirements.txt")) {
+    return content.replace(/(^|\s)#.*$/gm, "");
+  }
+  if (relativePath.endsWith("pyproject.toml")) {
+    return content.replace(/(^|\s)#.*$/gm, "");
+  }
+  if (relativePath.endsWith(".versions.toml")) {
+    return content.replace(/(^|\s)#.*$/gm, "");
+  }
+  if (relativePath.endsWith("settings.gradle") || relativePath.endsWith("settings.gradle.kts")) {
+    return content
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/.*$/gm, "");
+  }
+  if (relativePath.endsWith("pom.xml")) {
+    return content.replace(/<!--[\s\S]*?-->/g, "");
+  }
+  if (relativePath.endsWith("build.gradle") || relativePath.endsWith("build.gradle.kts")) {
+    return content
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/.*$/gm, "");
+  }
+  return content;
+}
+
+function extractDependencyContent(relativePath: string, content: string): string {
+  const stripped = stripDependencyComments(relativePath, content);
+  if (relativePath.endsWith("pyproject.toml")) {
+    return extractPyprojectDependencySections(stripped);
+  }
+  return stripped;
+}
+
+function extractRequirementName(spec: string): string | null {
+  const trimmed = spec.trim().replace(/^["']|["']$/g, "");
+  if (!trimmed) return null;
+
+  const match = trimmed.match(/^([A-Za-z0-9_.-]+)(?:\[[^\]]+\])?(?=\s*(?:@|[<>=!~;]|$))/);
+  if (!match) return null;
+  return normalizePackageName(match[1]);
+}
+
+function containsFastapiInPyproject(content: string): boolean {
+  for (const line of content.split("\n")) {
+    const keyMatch = line.match(/^\s*([A-Za-z0-9_.-]+)\s*=/);
+    if (keyMatch) {
+      const key = normalizePackageName(keyMatch[1]);
+      if (key === "fastapi") {
+        return true;
+      }
+      if (key !== "dependencies") {
+        continue;
+      }
+    }
+
+    const quotedSpecRe = /["']([^"']+)["']/g;
+    let match: RegExpExecArray | null;
+    while ((match = quotedSpecRe.exec(line)) !== null) {
+      if (extractRequirementName(match[1]) === "fastapi") {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function containsDirectSpringBootReference(relativePath: string, content: string): boolean {
+  if (relativePath.endsWith("pom.xml")) {
+    return /<groupId>\s*org\.springframework\.boot\s*<\/groupId>/i.test(content);
+  }
+
+  if (relativePath.endsWith("build.gradle") || relativePath.endsWith("build.gradle.kts")) {
+    return /(id\s*\(?\s*["']org\.springframework\.boot["']|apply\s*\(?\s*plugin\s*[:=]\s*["']org\.springframework\.boot["']|(?:implementation|api|compileOnly|runtimeOnly|testImplementation|annotationProcessor|kapt)\s*\(?\s*["'][^"']*org\.springframework\.boot:[^"']*spring-boot[^"']*["'])/i.test(content);
+  }
+
+  return false;
+}
+
+function extractPyprojectDependencySections(content: string): string {
+  const lines = content.split("\n");
+  const collected: string[] = [];
+  let section = "";
+  let collectingProjectDeps = false;
+  let collectingOptionalDeps = false;
+  let bracketDepth = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (collectingProjectDeps) {
+      collected.push(line);
+      bracketDepth += countChar(line, "[") - countChar(line, "]");
+      if (bracketDepth <= 0) {
+        collectingProjectDeps = false;
+      }
+      continue;
+    }
+
+    if (collectingOptionalDeps) {
+      collected.push(line);
+      bracketDepth += countChar(line, "[") - countChar(line, "]");
+      if (bracketDepth <= 0) {
+        collectingOptionalDeps = false;
+      }
+      continue;
+    }
+
+    const sectionMatch = trimmed.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1].trim();
+      continue;
+    }
+
+    if (section === "project" && /^dependencies\s*=\s*\[/.test(trimmed)) {
+      collected.push(line);
+      bracketDepth = countChar(line, "[") - countChar(line, "]");
+      collectingProjectDeps = bracketDepth > 0;
+      continue;
+    }
+
+    if (
+      section === "project.optional-dependencies" ||
+      section === "tool.poetry.dependencies"
+    ) {
+      if (section === "project.optional-dependencies") {
+        const equalsIndex = line.indexOf("=");
+        if (equalsIndex !== -1) {
+          const value = line.slice(equalsIndex + 1);
+          collected.push(value);
+          bracketDepth = countChar(value, "[") - countChar(value, "]");
+          collectingOptionalDeps = bracketDepth > 0;
+        }
+      } else {
+        collected.push(line);
+      }
+    }
+  }
+
+  return collected.join("\n");
+}
+
+function countChar(text: string, char: string): number {
+  return [...text].filter((c) => c === char).length;
+}
+
+function normalizePackageName(name: string): string {
+  return name.toLowerCase().replace(/[_.]/g, "-");
+}
+
+function normalizePluginAlias(alias: string): string {
+  return alias.toLowerCase().replace(/[-_]/g, ".");
+}
+
+function versionCatalogAccessorName(relativePath: string): string {
+  const normalized = relativePath.replaceAll("\\", "/");
+  const basename = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return basename.replace(/\.versions\.toml$/i, "").toLowerCase();
+}
+
+function resolveVersionCatalogAccessors(
+  basePath: string,
+  versionCatalogFiles: string[],
+  settingsFiles: string[],
+): Set<string> {
+  const accessors = new Set(versionCatalogFiles.map(versionCatalogAccessorName).filter(Boolean));
+  if (versionCatalogFiles.length === 0 || settingsFiles.length === 0) {
+    return accessors;
+  }
+
+  for (const settingsFile of settingsFiles) {
+    try {
+      const raw = readBounded(join(basePath, settingsFile), 64 * 1024);
+      const content = stripDependencyComments(settingsFile, raw);
+      const createRe = /create\(\s*["']([A-Za-z0-9_]+)["']\s*\)\s*\{[\s\S]*?([A-Za-z0-9_.-]+\.versions\.toml)["']?\s*\)\s*\)/g;
+      let match: RegExpExecArray | null;
+      while ((match = createRe.exec(content)) !== null) {
+        const accessor = match[1].toLowerCase();
+        const catalogBasename = match[2].replaceAll("\\", "/").split("/").pop()!;
+        if (versionCatalogFiles.some((file) => {
+          const normalized = file.replaceAll("\\", "/");
+          return normalized === catalogBasename || normalized.endsWith(`/${catalogBasename}`);
+        })) {
+          accessors.add(accessor);
+        }
+      }
+    } catch {
+      // unreadable settings file — ignore
+    }
+  }
+
+  return accessors;
+}
+
+/**
+ * Walk ancestor directories of `startDir` looking for any file in
+ * `PROJECT_FILES`. Stops at the filesystem root or at a `.git` boundary
+ * (so ancestors above a git repo root — e.g. `$HOME` or `/usr/local` —
+ * can't trigger false positives). Returns true if an ancestor contains
+ * one of the project markers.
+ *
+ * Used by the worktree health check (#2347) to avoid warning about
+ * monorepos where package.json / Cargo.toml / etc. live in a parent
+ * directory rather than in the worktree's own checkout.
+ *
+ * `existsFn` is injectable so this remains deterministically testable
+ * without touching the real filesystem; defaults to `fs.existsSync`.
+ */
+export function hasProjectFileInAncestor(
+  startDir: string,
+  existsFn: (p: string) => boolean = existsSync,
+): boolean {
+  let checkDir = dirname(startDir);
+  const { root } = parsePath(checkDir);
+  while (checkDir !== root) {
+    if (PROJECT_FILES.some((f) => existsFn(join(checkDir, f)))) {
+      return true;
+    }
+    // Stop at git repository boundary — ancestors above the repo root
+    // may contain unrelated project files. Check AFTER project-file scan
+    // so a repo root containing both .git and a marker is still recognized.
+    if (existsFn(join(checkDir, ".git"))) return false;
+    checkDir = dirname(checkDir);
+  }
+  return false;
+}
+
+/**
+ * Check whether a project's `.gsd/` directory contains the bootstrap artifacts
+ * (`PREFERENCES.md` or `milestones/`) that indicate a completed init run.
+ *
+ * A zombie `.gsd/` state — symlink exists but neither artifact is present —
+ * must be treated as "needs init wizard". The previous guard checked only
+ * `existsSync(gsdRoot(basePath))`, which accepted zombie states and skipped
+ * the wizard (#2942).
+ *
+ * `existsFn` is injectable so tests can run deterministically; defaults to
+ * `fs.existsSync`.
+ */
+export function hasGsdBootstrapArtifacts(
+  gsdPath: string,
+  existsFn: (p: string) => boolean = existsSync,
+): boolean {
+  return (
+    existsFn(gsdPath) &&
+    (existsFn(join(gsdPath, "PREFERENCES.md")) ||
+      existsFn(join(gsdPath, "preferences.md")) ||
+      existsFn(join(gsdPath, "milestones")))
+  );
+}
+
+export function scanProjectFiles(basePath: string): string[] {
+  const files: string[] = [];
+  const queue: Array<{ path: string; depth: number }> = [{ path: basePath, depth: 0 }];
+
+  while (queue.length > 0 && files.length < MAX_RECURSIVE_SCAN_FILES) {
+    const current = queue.shift()!;
+    let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;
+    try {
+      entries = readdirSync(current.path, { withFileTypes: true, encoding: "utf8" });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const entryPath = join(current.path, entry.name);
+      const relativePath = entryPath.slice(basePath.length + 1);
+
+      if (entry.isDirectory()) {
+        if (current.depth < MAX_RECURSIVE_SCAN_DEPTH && !RECURSIVE_SCAN_IGNORED_DIRS.has(entry.name)) {
+          queue.push({ path: entryPath, depth: current.depth + 1 });
+        }
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+      files.push(relativePath);
+      if (files.length >= MAX_RECURSIVE_SCAN_FILES) break;
+    }
+  }
+
+  return files;
+}