@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.0

package/src/project/git-health.ts

@@ -0,0 +1,577 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context"
+import path from "path"
+import fs from "fs"
+
+export namespace GitHealth {
+  export interface Issue {
+    dimension:
+      | "diff_lines"
+      | "diff_files"
+      | "untracked"
+      | "large_files"
+      | "extra_branches"
+      | "detached_head"
+      | "gc_needed"
+      | "unpushed"
+    level: "warn" | "critical"
+    message: string
+    detail: Record<string, unknown>
+  }
+
+  interface CacheEntry {
+    issues: Issue[]
+    ts: number
+  }
+
+  interface RepoInfo {
+    root: string
+    gitDir: string
+  }
+
+  // ---------------------------------------------------------------------------
+  // Cache — per-directory with 5-minute TTL
+  // ---------------------------------------------------------------------------
+  const runtimeState = RuntimeContext.state(() => ({
+    _cache: new Map<string, CacheEntry>(),
+    _refreshing: new Map<string, Promise<Issue[]>>(),
+    _aliases: new Map<string, string>(),
+    _lastDir: undefined as string | undefined,
+    _generation: 0,
+    _revisions: new Map<string, number>(),
+    _dirty: new Set<string>(),
+    _failed: new Set<string>(),
+  }))
+
+  const CACHE_TTL_MS = 5 * 60 * 1000
+  const GIT_COMMAND_TIMEOUT_MS = 2_000
+  const SCAN_TIMEOUT_MS = 3_000
+  const LARGE_FILE_STAT_BATCH_SIZE = 64
+  const DEFAULT_GC_AUTO = 6700
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  function normalizeDir(cwd: string): string {
+    return path.resolve(cwd)
+  }
+
+  function cacheKey(cwd: string): string {
+    const instanceState = runtimeState()
+
+    const dir = normalizeDir(cwd)
+    return instanceState._aliases.get(dir) ?? dir
+  }
+
+  function remainingMs(deadline: number): number {
+    return Math.max(0, deadline - Date.now())
+  }
+
+  async function withDeadline<T>(promise: Promise<T>, ms: number): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const fallback = new Promise<T>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error("Git health scan timed out")), ms)
+    })
+    return Promise.race([promise, fallback]).finally(() => {
+      if (timer) clearTimeout(timer)
+    })
+  }
+
+  async function gitText(
+    cwd: string,
+    args: string[],
+    options?: { allowedExit?: number[]; notRepo?: boolean },
+  ): Promise<string | undefined> {
+    const proc = Bun.spawn(["git", ...args], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+      signal: AbortSignal.timeout(GIT_COMMAND_TIMEOUT_MS),
+    })
+    const stdout = new Response(proc.stdout).text()
+    const stderr = new Response(proc.stderr).text().catch(() => "")
+    const [output, exitCode] = await Promise.all([stdout, proc.exited])
+    const errorText = await stderr
+    if (exitCode !== 0) {
+      if (options?.allowedExit?.includes(exitCode) || (options?.notRepo && /not a git repository/i.test(errorText)))
+        return undefined
+      throw new Error(`Git health probe failed (${args[0]}, exit ${exitCode})`)
+    }
+    return output
+  }
+
+  async function resolveRepo(cwd: string): Promise<RepoInfo | undefined> {
+    const dir = normalizeDir(cwd)
+    const inside = await gitText(dir, ["rev-parse", "--is-inside-work-tree"], { notRepo: true })
+    if (inside?.trim() !== "true") return undefined
+
+    const [rootText, gitDirText] = await Promise.all([
+      gitText(dir, ["rev-parse", "--show-toplevel"]),
+      gitText(dir, ["rev-parse", "--git-dir"]),
+    ])
+    const root = rootText?.trim()
+    const gitDir = gitDirText?.trim()
+    if (!root || !gitDir) return undefined
+
+    const resolvedRoot = normalizeDir(root)
+    return {
+      root: resolvedRoot,
+      gitDir: path.isAbsolute(gitDir) ? gitDir : path.resolve(dir, gitDir),
+    }
+  }
+
+  function render(issues: Issue[]): string | undefined {
+    const active = issues.filter((i) => i.level === "warn" || i.level === "critical")
+    if (active.length === 0) return undefined
+
+    const lines = [
+      "<git-health>",
+      "Latest completed diagnostic check; this is a bounded historical observation, not a live guarantee of repository state.",
+    ]
+    for (const issue of active) {
+      const label = issue.level === "critical" ? "Critical" : "Warning"
+      lines.push(`${label}: ${issue.message}`)
+    }
+    lines.push("</git-health>")
+    return lines.join("\n")
+  }
+
+  function parseNumstat(text: string): { additions: number; deletions: number; files: Set<string> } {
+    let additions = 0
+    let deletions = 0
+    const files = new Set<string>()
+
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+      const parts = trimmed.split("\t")
+      const add = parseInt(parts[0])
+      const del = parseInt(parts[1])
+      if (!isNaN(add)) additions += add
+      if (!isNaN(del)) deletions += del
+      if (parts.length >= 3 && parts[2]) files.add(parts[2])
+    }
+
+    return { additions, deletions, files }
+  }
+
+  function countLooseObjectsOnDisk(gitDir: string): number {
+    const objectsDir = path.join(gitDir, "objects")
+    let count = 0
+    try {
+      for (const entry of fs.readdirSync(objectsDir)) {
+        if (entry === "pack" || entry === "info") continue
+        const subDir = path.join(objectsDir, entry)
+        const subStat = fs.statSync(subDir, { throwIfNoEntry: false })
+        if (subStat?.isDirectory()) {
+          count += fs.readdirSync(subDir).length
+        }
+      }
+    } catch {}
+    return count
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimensions 1+2: diff_lines and diff_files (single pass)
+  // diff_lines thresholds: 200→warn, 800→critical
+  // diff_files thresholds: 10→warn, 25→critical
+  // ---------------------------------------------------------------------------
+  async function checkDiff(cwd: string): Promise<Issue[]> {
+    const head = await gitText(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"], { allowedExit: [1] })
+    const reference = head ? ["HEAD"] : []
+    const [unstaged, staged] = await Promise.all([
+      gitText(cwd, ["diff", "--numstat", ...reference]).then((x) => x ?? ""),
+      gitText(cwd, ["diff", "--cached", "--numstat", ...reference]).then((x) => x ?? ""),
+    ])
+
+    const unstagedParsed = parseNumstat(unstaged)
+    const stagedParsed = parseNumstat(staged)
+
+    const issues: Issue[] = []
+
+    // diff_lines
+    const unstagedLines = unstagedParsed.additions + unstagedParsed.deletions
+    const stagedLines = stagedParsed.additions + stagedParsed.deletions
+    const total = unstagedLines + stagedLines
+
+    if (total >= 200) {
+      issues.push({
+        dimension: "diff_lines",
+        level: total >= 800 ? "critical" : "warn",
+        message: `${total} lines of uncommitted changes — commit now to avoid losing work`,
+        detail: { lines: total, staged: stagedLines, unstaged: unstagedLines },
+      })
+    }
+
+    // diff_files
+    const allFiles = new Set([...unstagedParsed.files, ...stagedParsed.files])
+    const count = allFiles.size
+
+    if (count >= 10) {
+      issues.push({
+        dimension: "diff_files",
+        level: count >= 25 ? "critical" : "warn",
+        message: `${count} files modified but not committed — split into focused commits while intent is fresh`,
+        detail: { files: count },
+      })
+    }
+
+    return issues
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimension 3: untracked
+  // Thresholds: 15→warn, 80→critical
+  // ---------------------------------------------------------------------------
+  async function checkUntracked(cwd: string): Promise<Issue | undefined> {
+    const result = (await gitText(cwd, ["ls-files", "--others", "--exclude-standard"])) ?? ""
+
+    const trimmed = result.trim()
+    const count = trimmed ? trimmed.split("\n").length : 0
+
+    if (count < 15) return undefined
+
+    const level: Issue["level"] = count >= 80 ? "critical" : "warn"
+
+    return {
+      dimension: "untracked",
+      level,
+      message: `${count} untracked files — review with git status: add, ignore, or clean up`,
+      detail: { count },
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimension 4: large_files
+  // Thresholds: >10MB→warn, >50MB→critical
+  // ---------------------------------------------------------------------------
+  async function checkLargeFiles(cwd: string, deadline: number): Promise<Issue | undefined> {
+    const result = (await gitText(cwd, ["ls-files", "-z"])) ?? ""
+
+    const fileNames = result.split("\0").filter(Boolean)
+    if (fileNames.length === 0) return undefined
+    // Cap to avoid dominating check time on repos with hundreds of thousands of files.
+    const cappedNames = fileNames.length > 10000 ? fileNames.slice(0, 10000) : fileNames
+    if (cappedNames.length === 0) return undefined
+
+    const large: { path: string; size: number }[] = []
+
+    for (let i = 0; i < cappedNames.length; i += LARGE_FILE_STAT_BATCH_SIZE) {
+      if (Date.now() >= deadline) throw new Error("Git health file scan timed out")
+      const batch = cappedNames.slice(i, i + LARGE_FILE_STAT_BATCH_SIZE)
+      const stats = await withDeadline(
+        Promise.all(
+          batch.map(async (fileName) => {
+            const filePath = path.join(cwd, fileName)
+            const stat = await fs.promises.lstat(filePath).catch((error: NodeJS.ErrnoException) => {
+              if (error.code === "ENOENT") return undefined
+              throw error
+            })
+            if (!stat || stat.isSymbolicLink()) return undefined
+            return { fileName, stat }
+          }),
+        ),
+        remainingMs(deadline),
+      )
+      for (const result of stats) {
+        if (result && result.stat.size > 10 * 1024 * 1024) {
+          large.push({ path: result.fileName, size: result.stat.size })
+        }
+      }
+    }
+
+    if (large.length === 0) return undefined
+
+    large.sort((a, b) => b.size - a.size)
+    const largest = large[0]
+
+    const level: Issue["level"] = largest.size >= 50 * 1024 * 1024 ? "critical" : "warn"
+
+    return {
+      dimension: "large_files",
+      level,
+      message: `${large.length} large file(s) tracked — largest is ${largest.path} (${Math.round(largest.size / (1024 * 1024))}MB). If committed by accident, add to .gitignore and remove from tracking`,
+      detail: {
+        count: large.length,
+        largest: largest.path,
+        largestSize: largest.size,
+        files: large.slice(0, 5).map((f) => f.path),
+      },
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimension 5: extra_branches
+  // Thresholds: 10→warn, 40→critical
+  // ---------------------------------------------------------------------------
+  async function checkExtraBranches(cwd: string): Promise<Issue | undefined> {
+    const [headBranch, branchesText] = await Promise.all([
+      gitText(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"], { allowedExit: [1] }).then((x) => x?.trim() ?? ""),
+      gitText(cwd, ["for-each-ref", "--format=%(refname:short)", "refs/heads/"]).then((x) => x ?? ""),
+    ])
+
+    const branches = branchesText.trim().split("\n").filter(Boolean)
+    if (branches.length === 0) return undefined
+
+    const count = branches.filter((b) => b !== headBranch).length
+    if (count < 10) return undefined
+
+    const level: Issue["level"] = count >= 40 ? "critical" : "warn"
+
+    return {
+      dimension: "extra_branches",
+      level,
+      message: `${count} non-current branches — archive or remove them via the worktree cleanup path; deleting is deferred there because squash- or rebase-merged branches are not detected as merged by ancestry alone, which needs content comparison`,
+      detail: { count },
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimension 6: detached_head
+  // ---------------------------------------------------------------------------
+  async function checkDetachedHead(cwd: string): Promise<Issue | undefined> {
+    const symRef = await gitText(cwd, ["symbolic-ref", "--quiet", "HEAD"], { allowedExit: [1] })
+    if (symRef !== undefined) return undefined
+
+    const headCommit = (await gitText(cwd, ["rev-parse", "HEAD"]))?.trim() ?? ""
+    if (!headCommit) return undefined
+
+    return {
+      dimension: "detached_head",
+      level: "critical",
+      message: "Detached HEAD — commits will be lost unless you create a branch",
+      detail: { headCommit },
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimension 7: gc_needed
+  // Thresholds derive from the repo's effective gc.auto (git's documented
+  // default is 6700): git auto-gcs once loose objects exceed gc.auto, so warn at
+  // a quarter of that. Uses both git count-objects and filesystem count (max of
+  // the two); git count-objects only counts valid objects, while the filesystem
+  // fallback catches hand-crafted test fixture objects.
+  // ---------------------------------------------------------------------------
+  async function checkGcNeeded(cwd: string, gitDir: string, deadline: number): Promise<Issue | undefined> {
+    const [output, gcAutoText] = await Promise.all([
+      gitText(cwd, ["count-objects", "-v"]).then((x) => x ?? ""),
+      gitText(cwd, ["config", "--get", "gc.auto"], { allowedExit: [1] }),
+    ])
+
+    const countMatch = output.match(/count:\s*(\d+)/)
+    const sizeMatch = output.match(/size:\s*(\d+)/)
+
+    const gitCount = countMatch ? parseInt(countMatch[1]) : 0
+    const diskCount = Date.now() >= deadline ? 0 : countLooseObjectsOnDisk(gitDir)
+    const looseObjects = Math.max(gitCount, diskCount)
+    const size = sizeMatch ? parseInt(sizeMatch[1]) : 0
+
+    // gc.auto <= 0 disables auto-gc, so treat it as absent rather than as a threshold.
+    const configuredGcAuto = parseInt(gcAutoText?.trim() ?? "")
+    const gcAuto = Number.isFinite(configuredGcAuto) && configuredGcAuto > 0 ? configuredGcAuto : DEFAULT_GC_AUTO
+
+    if (looseObjects < Math.floor(gcAuto / 4)) return undefined
+
+    const level: Issue["level"] = looseObjects >= gcAuto ? "critical" : "warn"
+
+    return {
+      dimension: "gc_needed",
+      level,
+      message: `Git gc recommended — ${looseObjects} loose objects (gc.auto ${gcAuto}). Run git gc to reclaim space`,
+      detail: { looseObjects, size },
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dimension 8: unpushed
+  // ---------------------------------------------------------------------------
+  async function checkUnpushed(cwd: string): Promise<Issue | undefined> {
+    // With no remote-tracking refs `--not --remotes` subtracts nothing and the
+    // count degenerates to the entire local history, so only report when the
+    // repo actually tracks a remote.
+    const remoteRefs = await gitText(cwd, ["for-each-ref", "--count=1", "--format=%(refname)", "refs/remotes/"])
+    if (!remoteRefs?.trim()) return undefined
+    if (!(await gitText(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"], { allowedExit: [1] }))) return undefined
+
+    const output = await gitText(cwd, ["rev-list", "--count", "HEAD", "--not", "--remotes"])
+
+    const count = parseInt(output?.trim() ?? "")
+    if (!Number.isFinite(count) || count <= 0) return undefined
+
+    return {
+      dimension: "unpushed",
+      level: "warn",
+      message: `${count} commit(s) not on any remote — push to preserve this work`,
+      detail: { unpushed: count },
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  async function scan(cwd: string): Promise<{ dir: string; issues: Issue[] }> {
+    const fallbackDir = normalizeDir(cwd)
+    const deadline = Date.now() + SCAN_TIMEOUT_MS
+    const repo = await resolveRepo(fallbackDir)
+    if (!repo) return { dir: fallbackDir, issues: [] }
+
+    const remaining = remainingMs(deadline)
+    if (remaining === 0) throw new Error("Git health repository probe timed out")
+
+    const checks: Promise<Issue | Issue[] | undefined>[] = [
+      checkDiff(repo.root),
+      checkUntracked(repo.root),
+      checkLargeFiles(repo.root, deadline),
+      checkExtraBranches(repo.root),
+      checkDetachedHead(repo.root),
+      checkGcNeeded(repo.root, repo.gitDir, deadline),
+      checkUnpushed(repo.root),
+    ]
+    const results = await withDeadline(Promise.all(checks), remaining)
+
+    const issues = results.flat().filter((i): i is Issue => i !== undefined)
+    return { dir: repo.root, issues }
+  }
+
+  /**
+   * Live repository probe shared with the env prompt block. Deliberately
+   * bypasses the scan cache: callers (per-turn env assembly) need the current
+   * answer, and a stale repo probe is exactly the bug this replaces.
+   */
+  export async function isGitRepo(cwd?: string): Promise<boolean> {
+    const repo = await resolveRepo(normalizeDir(cwd ?? process.cwd())).catch(() => undefined)
+    return repo !== undefined
+  }
+
+  export function refresh(cwd?: string): Promise<Issue[]> {
+    const instanceState = runtimeState()
+
+    const inputDir = normalizeDir(cwd ?? process.cwd())
+    const key = cacheKey(inputDir)
+    const existing = instanceState._refreshing.get(key) ?? instanceState._refreshing.get(inputDir)
+    if (existing) return existing
+
+    const generation = instanceState._generation
+    const revisions = new Map(instanceState._revisions)
+    const unchanged = (dir: string) => (revisions.get(dir) ?? 0) === (instanceState._revisions.get(dir) ?? 0)
+    let promise!: Promise<Issue[]>
+    promise = scan(inputDir)
+      .then((result) => {
+        const instanceState = runtimeState()
+
+        if (generation === instanceState._generation) instanceState._aliases.set(inputDir, result.dir)
+        if (generation === instanceState._generation && unchanged(key) && unchanged(result.dir)) {
+          instanceState._cache.set(result.dir, { issues: result.issues, ts: Date.now() })
+          instanceState._lastDir = result.dir
+          instanceState._dirty.delete(key)
+          instanceState._dirty.delete(result.dir)
+          instanceState._dirty.delete(inputDir)
+          instanceState._failed.delete(key)
+          instanceState._failed.delete(result.dir)
+        }
+        return result.issues
+      })
+      .catch(() => {
+        if (generation === instanceState._generation && unchanged(key)) {
+          instanceState._failed.add(key)
+          instanceState._dirty.delete(key)
+        }
+        return instanceState._cache.get(key)?.issues ?? []
+      })
+      .finally(() => {
+        const instanceState = runtimeState()
+
+        if (instanceState._refreshing.get(key) === promise) instanceState._refreshing.delete(key)
+        if (instanceState._refreshing.get(inputDir) === promise) instanceState._refreshing.delete(inputDir)
+      })
+      .then((issues) =>
+        generation === instanceState._generation && (!unchanged(key) || !unchanged(cacheKey(inputDir)))
+          ? refresh(inputDir)
+          : issues,
+      )
+
+    instanceState._refreshing.set(key, promise)
+    if (key !== inputDir) instanceState._refreshing.set(inputDir, promise)
+    return promise
+  }
+
+  export async function check(cwd?: string): Promise<Issue[]> {
+    const instanceState = runtimeState()
+
+    const dir = normalizeDir(cwd ?? process.cwd())
+    const key = cacheKey(dir)
+    const cached = instanceState._cache.get(key)
+    if (
+      cached &&
+      !instanceState._dirty.has(key) &&
+      !instanceState._failed.has(key) &&
+      Date.now() - cached.ts < CACHE_TTL_MS
+    ) {
+      instanceState._lastDir = key
+      return cached.issues
+    }
+    return refresh(dir)
+  }
+
+  export async function inject(cwd?: string): Promise<string | undefined> {
+    return render(await check(cwd))
+  }
+
+  export function injectCached(cwd?: string): string | undefined {
+    const observation = observeCached(cwd)
+    return observation.state === "present" ? observation.text : undefined
+  }
+
+  export function observeCached(
+    cwd?: string,
+  ): { state: "present"; text: string } | { state: "cleared" | "unavailable" | "pending" } {
+    const instanceState = runtimeState()
+
+    const dir = normalizeDir(cwd ?? process.cwd())
+    const key = cacheKey(dir)
+    const cached = instanceState._cache.get(key)
+    if (
+      !cached ||
+      instanceState._dirty.has(key) ||
+      instanceState._failed.has(key) ||
+      Date.now() - cached.ts >= CACHE_TTL_MS
+    ) {
+      refresh(dir).catch(() => {})
+    }
+    if (instanceState._failed.has(key)) return { state: "unavailable" }
+    if (!cached || instanceState._dirty.has(key) || Date.now() - cached.ts >= CACHE_TTL_MS) return { state: "pending" }
+    instanceState._lastDir = key
+    const text = render(cached.issues)
+    return text ? { state: "present", text } : { state: "cleared" }
+  }
+
+  export function lastReport(): Issue[] | undefined {
+    const instanceState = runtimeState()
+
+    if (!instanceState._lastDir) return undefined
+    const cached = instanceState._cache.get(instanceState._lastDir)
+    return cached?.issues.length ? cached.issues : undefined
+  }
+
+  export function invalidate(cwd?: string): void {
+    const instanceState = runtimeState()
+
+    if (cwd === undefined) {
+      instanceState._generation++
+      instanceState._refreshing.clear()
+      instanceState._cache.clear()
+      instanceState._aliases.clear()
+      instanceState._lastDir = undefined
+      instanceState._revisions.clear()
+      instanceState._dirty.clear()
+      instanceState._failed.clear()
+      return
+    }
+
+    const dir = normalizeDir(cwd)
+    const key = cacheKey(dir)
+    instanceState._revisions.set(key, (instanceState._revisions.get(key) ?? 0) + 1)
+    instanceState._dirty.add(key)
+  }
+}

package/src/project/ide.ts

@@ -0,0 +1,80 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context"
+import { BusEvent } from "@ericsanchezok/synergy-harness/bus/bus-event"
+import { Bus } from "@ericsanchezok/synergy-harness/bus"
+import { spawn } from "bun"
+import z from "zod"
+import { NamedError } from "@ericsanchezok/synergy-util/error"
+import { Log } from "@ericsanchezok/synergy-harness/util/log"
+
+const SUPPORTED_IDES = [
+  { name: "Windsurf" as const, cmd: "windsurf" },
+  { name: "Visual Studio Code - Insiders" as const, cmd: "code-insiders" },
+  { name: "Visual Studio Code" as const, cmd: "code" },
+  { name: "Cursor" as const, cmd: "cursor" },
+  { name: "VSCodium" as const, cmd: "codium" },
+]
+
+export namespace Ide {
+  const log = Log.create({ service: "ide" })
+
+  export const Event = {
+    Installed: BusEvent.define(
+      "ide.installed",
+      z.object({
+        ide: z.string(),
+      }),
+    ),
+  }
+
+  export const AlreadyInstalledError = NamedError.create("AlreadyInstalledError", z.object({}))
+
+  export const InstallFailedError = NamedError.create(
+    "InstallFailedError",
+    z.object({
+      stderr: z.string(),
+    }),
+  )
+
+  export function ide() {
+    if (RuntimeContext.current().host.env["TERM_PROGRAM"] === "vscode") {
+      const v = RuntimeContext.current().host.env["GIT_ASKPASS"]
+      for (const ide of SUPPORTED_IDES) {
+        if (v?.includes(ide.name)) return ide.name
+      }
+    }
+    return "unknown"
+  }
+
+  export function alreadyInstalled() {
+    return (
+      RuntimeContext.current().host.env["SYNERGY_CALLER"] === "vscode" ||
+      RuntimeContext.current().host.env["SYNERGY_CALLER"] === "vscode-insiders"
+    )
+  }
+
+  export async function install(ide: (typeof SUPPORTED_IDES)[number]["name"]) {
+    const cmd = SUPPORTED_IDES.find((i) => i.name === ide)?.cmd
+    if (!cmd) throw new Error(`Unknown IDE: ${ide}`)
+
+    const p = spawn([cmd, "--install-extension", "ericsanchezok.synergy"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    await p.exited
+    const stdout = await new Response(p.stdout).text()
+    const stderr = await new Response(p.stderr).text()
+
+    log.info("installed", {
+      ide,
+      stdout,
+      stderr,
+    })
+
+    if (p.exitCode !== 0) {
+      throw new InstallFailedError({ stderr })
+    }
+    if (stdout.includes("already installed")) {
+      throw new AlreadyInstalledError({})
+    }
+  }
+}

package/src/project/migration.ts

@@ -0,0 +1,24 @@
+import { MigrationRegistry } from "@ericsanchezok/synergy-harness/migration/registry"
+import { Scope } from "@ericsanchezok/synergy-harness/scope"
+import { ProjectDirectories } from "./directories"
+
+export const projectMigrations = [
+  {
+    id: "20260929-project-directories",
+    scope: "global" as const,
+    execution: "startup" as const,
+    description: "Separate project folders from historical Worktrees without changing Scope identity",
+    async up(progress: (current: number, total: number) => void) {
+      const projects = await Scope.list()
+      progress(0, projects.length)
+      for (const [index, project] of projects.entries()) {
+        await ProjectDirectories.migrateProject(project)
+        progress(index + 1, projects.length)
+      }
+    },
+  },
+]
+
+export function registerProjectMigrations() {
+  MigrationRegistry.register("workbench-projects", projectMigrations)
+}