tmux-ide 2.6.0 → 2.6.1

package/packages/daemon/src/lib/update.ts

@@ -0,0 +1,158 @@
+/**
+ * `tmux-ide update [--dry-run]` — act on the update the dock surfaces.
+ *
+ * The dock's `⬆ v<latest>` chip (see {@link ./update-check.ts}) tells you an
+ * update is out; this closes the loop with the ONE command that installs it. The
+ * catch is that "the command" depends on how tmux-ide was installed — a cloned
+ * dev checkout updates with `git pull`, a global install with its package
+ * manager (npm/pnpm/bun) — so the command DETECTS the install method from the
+ * running CLI's real path before printing (or, without `--dry-run`, running) it.
+ *
+ * The detection + rendering are PURE ({@link detectPackageManager},
+ * {@link planUpdate}, {@link renderPlan}), so they're unit-tested without a live
+ * filesystem; {@link findGitCheckoutRoot} and {@link runUpdate} are the io — the
+ * latter is the only place a real global install is ever spawned, and only when
+ * `--dry-run` is absent.
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getCurrentVersion, getUpdateStatus, isNewer } from "./update-check.ts";
+
+/** The package managers a global install can come from. */
+export type PackageManager = "npm" | "pnpm" | "bun";
+
+/** The resolved way to update this install. */
+export interface UpdatePlan {
+  /** `dev` = a git checkout (`git pull`); otherwise the global package manager. */
+  method: "dev" | PackageManager;
+  /** The shell command to run, or null for a dev checkout (manual `git pull`). */
+  command: string | null;
+  /** A short human note on WHY this method was chosen (the detection evidence). */
+  reason: string;
+}
+
+/** The exact global-install command per package manager. */
+export const UPDATE_COMMANDS: Record<PackageManager, string> = {
+  npm: "npm install -g tmux-ide@latest",
+  pnpm: "pnpm add -g tmux-ide@latest",
+  bun: "bun add -g tmux-ide@latest",
+};
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — infer the package manager from a global CLI path. The global bin lives
+ * under a manager-specific directory, so the path is the tell: a `bun`/`.bun`
+ * segment → bun, a `pnpm` segment → pnpm, else npm (the default global installer,
+ * incl. nvm's `.../node/vX/lib/node_modules/...`). Checked bun→pnpm→npm so the
+ * more specific segments win.
+ */
+export function detectPackageManager(cliPath: string): PackageManager {
+  const p = cliPath.toLowerCase();
+  if (/(^|\/)\.?bun(\/|$)/.test(p)) return "bun";
+  if (p.includes("pnpm")) return "pnpm";
+  return "npm";
+}
+
+/**
+ * PURE — the {@link UpdatePlan} for a CLI at `cliPath`. When `gitRoot` is set (a
+ * `.git` was found at/above the CLI — a cloned checkout) the plan is a manual
+ * `git pull`; otherwise it's the detected package manager's global-install
+ * command.
+ */
+export function planUpdate(input: { cliPath: string; gitRoot: string | null }): UpdatePlan {
+  if (input.gitRoot) {
+    return { method: "dev", command: null, reason: `git checkout at ${input.gitRoot}` };
+  }
+  const pm = detectPackageManager(input.cliPath);
+  return {
+    method: pm,
+    command: UPDATE_COMMANDS[pm],
+    reason: `global ${pm} install (${input.cliPath})`,
+  };
+}
+
+/**
+ * PURE — the human-readable block the CLI prints for a plan. Leads with the
+ * version delta (or "up to date"/"unknown"), then the command to run — for a dev
+ * checkout that's the `git pull` hint, for a global install the exact package-
+ * manager line. `dryRun` only changes the framing ("would run" vs "run"); the
+ * command shown is identical either way. Ends with the re-adopt note: the running
+ * updater keeps the OLD code until `_tmux-ide-chrome` is killed and a session
+ * re-adopted, so a fresh dock reflects the new version.
+ */
+export function renderPlan(
+  plan: UpdatePlan,
+  { current, latest, dryRun }: { current: string; latest: string | null; dryRun: boolean },
+): string {
+  const lines: string[] = [];
+  // isNewer, not inequality — the registry can lag the checkout (a dev build
+  // is AHEAD of the published version), and that must not read as an update.
+  if (latest && isNewer(latest, current)) {
+    lines.push(`tmux-ide v${current} → v${latest} available`);
+  } else if (latest) {
+    lines.push(`tmux-ide v${current} is up to date (registry: v${latest})`);
+  } else {
+    lines.push(`tmux-ide v${current} (latest version unknown — run \`tmux-ide doctor\`)`);
+  }
+  lines.push("");
+  if (plan.method === "dev") {
+    lines.push("Detected a cloned checkout — update with git:");
+    lines.push("  git pull");
+    lines.push(`  (${plan.reason})`);
+  } else {
+    const verb = dryRun ? "Would run" : "Running";
+    lines.push(`Detected a global ${plan.method} install — ${verb}:`);
+    lines.push(`  ${plan.command}`);
+  }
+  lines.push("");
+  lines.push("After updating, refresh the dock so it runs the new code:");
+  lines.push("  tmux kill-session -t _tmux-ide-chrome   # stop the old updater");
+  lines.push("  tmux-ide adopt <session>                # re-adopt to relaunch it");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/**
+ * io — walk up from `startDir` looking for a `.git` entry; return the first
+ * directory that has one (a cloned checkout root) or null at the filesystem root.
+ * A global install under `node_modules` has no `.git` above it, so this cleanly
+ * separates "dev checkout" from "installed package".
+ */
+export function findGitCheckoutRoot(startDir: string): string | null {
+  let dir = startDir;
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * io — run (or, with `dryRun`, just print) the update.
+ *
+ * `cliDir` is the directory of the running CLI (`bin/`), the anchor for both the
+ * git-checkout probe and the package-manager path heuristic. The plan is printed
+ * either way; only a non-dry-run global install actually spawns the installer
+ * (`execSync`, output inherited). A dev checkout NEVER auto-runs `git pull` — it
+ * only prints the hint. Returns the plan so the CLI/tests can assert on it.
+ */
+export function runUpdate({ cliDir, dryRun }: { cliDir: string; dryRun: boolean }): UpdatePlan {
+  const current = getCurrentVersion();
+  const { latest } = getUpdateStatus({ currentVersion: current });
+  const gitRoot = findGitCheckoutRoot(cliDir);
+  const plan = planUpdate({ cliPath: cliDir, gitRoot });
+  console.log(renderPlan(plan, { current, latest, dryRun }));
+  if (!dryRun && plan.command) {
+    console.log("");
+    execSync(plan.command, { stdio: "inherit" });
+  }
+  return plan;
+}

package/packages/daemon/src/lib/workspace-registry.ts

@@ -0,0 +1,229 @@
+/**
+ * Workspace registry — runtime list of projects the daemon is serving.
+ *
+ * Replaces the legacy single-session TMUX_IDE_SESSION env coupling so a
+ * single daemon can host N concurrent projects (goal 12, T065).
+ *
+ * Persisted at ~/.tmux-ide/workspaces.json via atomic temp+rename. On
+ * `load()` the registry reconciles itself against `tmux list-sessions`
+ * output and drops entries whose session no longer exists.
+ *
+ * Distinct from project-registry.ts — that one is a long-lived
+ * "bookmark list" of projects the user knows about (probed metadata).
+ * This one tracks live workspaces and is reconciled with tmux on boot.
+ */
+
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { WorkspaceSchemaZ, type Workspace } from "@tmux-ide/contracts";
+
+const REGISTRY_DIR_ENV = "TMUX_IDE_REGISTRY_DIR";
+
+const RegistryFileSchemaZ = z.object({
+  version: z.literal(1),
+  workspaces: z.array(WorkspaceSchemaZ),
+});
+
+type RegistryFile = z.infer<typeof RegistryFileSchemaZ>;
+
+export type ListSessionsFn = () => readonly string[];
+
+export interface WorkspaceRegistryOptions {
+  /** Override registry dir for tests. Defaults to ~/.tmux-ide. */
+  dir?: string;
+  /** Inject a tmux list-sessions implementation (defaults to bridge). */
+  listSessions?: ListSessionsFn;
+}
+
+export interface AddWorkspaceInput {
+  name: string;
+  sessionName?: string;
+  projectDir: string;
+  ideConfigPath?: string | null;
+  /** Override Date.now() for deterministic tests. */
+  now?: () => Date;
+}
+
+export class WorkspaceAlreadyExistsError extends Error {
+  readonly code = "ALREADY_EXISTS";
+  constructor(name: string) {
+    super(`Workspace "${name}" already exists`);
+    this.name = "WorkspaceAlreadyExistsError";
+  }
+}
+
+export class WorkspaceNotFoundError extends Error {
+  readonly code = "NOT_FOUND";
+  constructor(name: string) {
+    super(`Workspace "${name}" not found`);
+    this.name = "WorkspaceNotFoundError";
+  }
+}
+
+/**
+ * Thin wrapper around the shared module emitter so consumers can subscribe
+ * with typed events without depending on EventEmitter directly.
+ */
+export type WorkspaceEvent =
+  | { type: "workspace.added"; workspace: Workspace }
+  | { type: "workspace.removed"; name: string };
+
+export class WorkspaceRegistry {
+  private readonly dir: string;
+  private readonly listSessions: ListSessionsFn;
+  private readonly emitter = new EventEmitter();
+  private workspaces: Workspace[] = [];
+  private loaded = false;
+
+  constructor(options: WorkspaceRegistryOptions = {}) {
+    this.dir = options.dir ?? process.env[REGISTRY_DIR_ENV] ?? join(homedir(), ".tmux-ide");
+    this.listSessions = options.listSessions ?? defaultListSessions;
+    this.emitter.setMaxListeners(0);
+  }
+
+  /**
+   * Load workspaces from disk and reconcile against live tmux sessions.
+   * Drops entries whose tmux session is gone (silently — they were
+   * persisted by a prior daemon invocation that may have crashed).
+   *
+   * Safe to call repeatedly; subsequent calls re-reconcile.
+   */
+  async load(): Promise<void> {
+    const fromDisk = this.readDisk();
+    let live: Set<string>;
+    try {
+      live = new Set(this.listSessions());
+    } catch {
+      // tmux is unavailable — keep all entries; reconcile when we can.
+      live = new Set(fromDisk.map((w) => w.sessionName));
+    }
+    const reconciled = fromDisk.filter((w) => live.has(w.sessionName));
+    this.workspaces = reconciled;
+    this.loaded = true;
+    if (reconciled.length !== fromDisk.length) {
+      this.writeDisk();
+    }
+  }
+
+  list(): Workspace[] {
+    return [...this.workspaces];
+  }
+
+  get(name: string): Workspace | null {
+    return this.workspaces.find((w) => w.name === name) ?? null;
+  }
+
+  has(name: string): boolean {
+    return this.workspaces.some((w) => w.name === name);
+  }
+
+  add(input: AddWorkspaceInput): Workspace {
+    if (this.has(input.name)) {
+      throw new WorkspaceAlreadyExistsError(input.name);
+    }
+    const now = (input.now ?? (() => new Date()))();
+    const workspace: Workspace = {
+      name: input.name,
+      sessionName: input.sessionName ?? input.name,
+      projectDir: input.projectDir,
+      ideConfigPath: input.ideConfigPath ?? null,
+      addedAt: now.toISOString(),
+    };
+    this.workspaces = [...this.workspaces, workspace];
+    this.writeDisk();
+    this.emitter.emit("workspace.added", workspace);
+    return workspace;
+  }
+
+  remove(name: string): void {
+    if (!this.has(name)) {
+      throw new WorkspaceNotFoundError(name);
+    }
+    this.workspaces = this.workspaces.filter((w) => w.name !== name);
+    this.writeDisk();
+    this.emitter.emit("workspace.removed", name);
+  }
+
+  /** Subscribe to workspace.added | workspace.removed events. */
+  on<E extends WorkspaceEvent["type"]>(
+    event: E,
+    handler: (
+      payload: Extract<WorkspaceEvent, { type: E }> extends { workspace: Workspace }
+        ? Workspace
+        : string,
+    ) => void,
+  ): () => void {
+    this.emitter.on(event, handler as (...args: unknown[]) => void);
+    return () => this.emitter.off(event, handler as (...args: unknown[]) => void);
+  }
+
+  // ----------------- io -----------------
+
+  private filePath(): string {
+    return join(this.dir, "workspaces.json");
+  }
+
+  private readDisk(): Workspace[] {
+    const path = this.filePath();
+    if (!existsSync(path)) return [];
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(path, "utf-8"));
+    } catch {
+      return [];
+    }
+    const result = RegistryFileSchemaZ.safeParse(parsed);
+    if (!result.success) return [];
+    return result.data.workspaces;
+  }
+
+  private writeDisk(): void {
+    const path = this.filePath();
+    mkdirSync(dirname(path), { recursive: true });
+    const file: RegistryFile = { version: 1, workspaces: this.workspaces };
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n");
+    renameSync(tmp, path);
+  }
+
+  /** @internal Test-only: assert the registry is loaded. */
+  _isLoaded(): boolean {
+    return this.loaded;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default singleton — the daemon process holds one registry; HTTP handlers
+// import it via getDefaultWorkspaceRegistry().
+// ---------------------------------------------------------------------------
+
+let _default: WorkspaceRegistry | null = null;
+
+export function getDefaultWorkspaceRegistry(): WorkspaceRegistry {
+  if (!_default) _default = new WorkspaceRegistry();
+  return _default;
+}
+
+/** @internal Test hook: replace the singleton. */
+export function _setDefaultWorkspaceRegistryForTests(registry: WorkspaceRegistry | null): void {
+  _default = registry;
+}
+
+function defaultListSessions(): string[] {
+  // Lazy import keeps tmux-bridge optional for test environments that
+  // don't have tmux available; tests inject a stub instead.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
+  try {
+    const raw = execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }) as string;
+    return raw.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/packages/daemon/src/lib/worktree.ts

@@ -0,0 +1,289 @@
+/**
+ * Git worktree flow — one checkout per branch so parallel agents (or a fleet)
+ * each work on isolation. `tmux-ide worktree create <branch>` adds a git
+ * worktree in a SIBLING directory (never inside the repo) and opens a tmux
+ * session there; the CLI (`bin/cli.ts`, `worktree` case) wires the io.
+ *
+ * The pure helpers — {@link worktreeSessionName}, {@link worktreePath},
+ * {@link parseWorktreeList}, {@link mapWorktreeError} — carry no io so they're
+ * cheaply testable. The io wrappers ({@link createWorktree},
+ * {@link removeWorktree}, {@link listWorktrees}) shell out to `git` and map its
+ * stderr into a typed {@link WorktreeError} with an actionable message.
+ */
+import { execFileSync } from "node:child_process";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { IdeError } from "./errors.ts";
+
+// ---------------------------------------------------------------------------
+// Typed error
+// ---------------------------------------------------------------------------
+
+export type WorktreeErrorCode =
+  | "NOT_A_GIT_REPO"
+  | "BRANCH_EXISTS"
+  | "BRANCH_NOT_FOUND"
+  | "ALREADY_CHECKED_OUT"
+  | "WORKTREE_EXISTS"
+  | "WORKTREE_DIRTY"
+  | "WORKTREE_NOT_FOUND"
+  | "GIT_FAILED";
+
+export class WorktreeError extends IdeError {
+  constructor(message: string, code: WorktreeErrorCode) {
+    super(message, { code, exitCode: 1 });
+    this.name = "WorktreeError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — sanitize a component for a tmux session name. tmux treats `:` as a
+ * target separator and silently rewrites `.` to `_`, so we normalize both (plus
+ * whitespace) to `-` up front, keeping the name stable and predictable. `/` is
+ * left intact — tmux accepts it in session names (verified live on tmux 3.6).
+ */
+function sanitizeForTmux(part: string): string {
+  // Slashes too: `feat/x` would parse as a path-ish target in tmux commands
+  // and can't appear in the status bar's `#[range=user|sw<name>]` mouse ranges.
+  return part.replace(/[.:/\s]+/g, "-");
+}
+
+/**
+ * PURE — the tmux session name for a project's worktree on `branch`, e.g.
+ * `myapp@fix-auth`. Both sides are sanitized ({@link sanitizeForTmux}) so a
+ * dotted/colon'd branch (or project) stays a single inert session name; the
+ * `@` separator is preserved so the session reads as "project, this branch".
+ */
+export function worktreeSessionName(project: string, branch: string): string {
+  return `${sanitizeForTmux(project)}@${sanitizeForTmux(branch)}`;
+}
+
+/**
+ * PURE — the default base directory for a repo's worktrees: a SIBLING of the
+ * repo named `<repo-name>-worktrees`. Kept outside the repo so a worktree is
+ * never nested inside its own parent checkout (which git rejects and which
+ * would pollute the project tree).
+ */
+export function defaultWorktreeBaseDir(repoDir: string): string {
+  const abs = resolve(repoDir);
+  return join(dirname(abs), `${basename(abs)}-worktrees`);
+}
+
+/**
+ * PURE — the on-disk path for a worktree of `branch`. Defaults to
+ * `<repo>/../<repo-name>-worktrees/<branch>`; a non-empty `configuredDir` (the
+ * app-config `worktrees.dir` override) replaces the base, resolved relative to
+ * the repo when it isn't absolute. The branch is the final path segment (a
+ * slashed branch nests, which `git worktree add` creates).
+ */
+export function worktreePath(
+  repoDir: string,
+  branch: string,
+  configuredDir?: string | null,
+): string {
+  const base =
+    configuredDir && configuredDir.length > 0
+      ? isAbsolute(configuredDir)
+        ? configuredDir
+        : resolve(repoDir, configuredDir)
+      : defaultWorktreeBaseDir(repoDir);
+  return join(base, branch);
+}
+
+/** A single record from `git worktree list --porcelain`. */
+export interface WorktreeEntry {
+  /** Absolute path of the worktree. */
+  path: string;
+  /** The checked-out commit sha, or null (bare repo). */
+  head: string | null;
+  /** Short branch name (no `refs/heads/`), or null when detached/bare. */
+  branch: string | null;
+  /** The bare repository entry. */
+  bare: boolean;
+  /** A detached-HEAD worktree (no branch). */
+  detached: boolean;
+}
+
+/**
+ * PURE — parse `git worktree list --porcelain`. Records are separated by blank
+ * lines; each has a `worktree <path>` line, then optional `HEAD <sha>`,
+ * `branch refs/heads/<name>`, `bare`, `detached` attribute lines. Unknown
+ * attribute lines are ignored. Malformed/empty input yields `[]`.
+ */
+export function parseWorktreeList(porcelain: string): WorktreeEntry[] {
+  const entries: WorktreeEntry[] = [];
+  let current: WorktreeEntry | null = null;
+
+  const flush = () => {
+    if (current) entries.push(current);
+    current = null;
+  };
+
+  for (const rawLine of porcelain.split("\n")) {
+    const line = rawLine.replace(/\r$/, "");
+    if (line.length === 0) {
+      flush();
+      continue;
+    }
+    if (line.startsWith("worktree ")) {
+      flush();
+      current = {
+        path: line.slice("worktree ".length),
+        head: null,
+        branch: null,
+        bare: false,
+        detached: false,
+      };
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("HEAD ")) {
+      current.head = line.slice("HEAD ".length);
+    } else if (line.startsWith("branch ")) {
+      current.branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
+    } else if (line === "bare") {
+      current.bare = true;
+    } else if (line === "detached") {
+      current.detached = true;
+    }
+  }
+  flush();
+  return entries;
+}
+
+/**
+ * PURE — map a failed `git` invocation's stderr to a typed
+ * {@link WorktreeError}. Recognizes the common worktree failures so the CLI can
+ * surface an actionable message instead of a raw git dump; anything unmatched
+ * falls back to `GIT_FAILED` carrying the trimmed stderr.
+ */
+export function mapWorktreeError(stderr: string, fallbackMessage: string): WorktreeError {
+  const text = stderr.trim();
+  const lower = text.toLowerCase();
+
+  if (lower.includes("not a git repository")) {
+    return new WorktreeError(
+      "Not a git repository. Run `tmux-ide worktree` from inside a git repo.",
+      "NOT_A_GIT_REPO",
+    );
+  }
+  if (lower.includes("already exists") && lower.includes("branch")) {
+    return new WorktreeError(
+      `${text}\nUse \`tmux-ide worktree create <branch>\` without --from to check out the existing branch, or pick a new name.`,
+      "BRANCH_EXISTS",
+    );
+  }
+  if (lower.includes("is already checked out") || lower.includes("already used by worktree")) {
+    return new WorktreeError(text, "ALREADY_CHECKED_OUT");
+  }
+  if (lower.includes("already exists")) {
+    return new WorktreeError(text, "WORKTREE_EXISTS");
+  }
+  if (
+    (lower.includes("invalid reference") || lower.includes("not a valid ref")) &&
+    !lower.includes("already")
+  ) {
+    return new WorktreeError(text, "BRANCH_NOT_FOUND");
+  }
+  if (
+    lower.includes("contains modified or untracked files") ||
+    lower.includes("use --force") ||
+    lower.includes("use 'remove -f'")
+  ) {
+    return new WorktreeError(
+      `${text}\nRe-run with --force to discard those changes.`,
+      "WORKTREE_DIRTY",
+    );
+  }
+  if (lower.includes("is not a working tree") || lower.includes("not a working tree")) {
+    return new WorktreeError(text, "WORKTREE_NOT_FOUND");
+  }
+  return new WorktreeError(text.length > 0 ? text : fallbackMessage, "GIT_FAILED");
+}
+
+// ---------------------------------------------------------------------------
+// io — git shell-outs (map stderr → WorktreeError)
+// ---------------------------------------------------------------------------
+
+/** Injectable git runner so io wrappers stay unit-testable. */
+export type GitRunner = (repoDir: string, args: string[]) => string;
+
+let gitRunner: GitRunner = (repoDir, args) =>
+  execFileSync("git", args, {
+    cwd: repoDir,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+/** Swap the git runner (tests). Returns a restore fn. */
+export function _setGitRunnerForTests(fn: GitRunner): () => void {
+  const prev = gitRunner;
+  gitRunner = fn;
+  return () => {
+    gitRunner = prev;
+  };
+}
+
+interface GitExecError {
+  stderr?: Buffer | string;
+}
+
+function runGit(repoDir: string, args: string[], fallbackMessage: string): string {
+  try {
+    return gitRunner(repoDir, args);
+  } catch (error) {
+    const stderr = (error as GitExecError).stderr;
+    const text = stderr ? stderr.toString() : "";
+    throw mapWorktreeError(text, fallbackMessage);
+  }
+}
+
+export interface CreateWorktreeOptions {
+  /** Create a NEW branch (git worktree add -b). Off → check out an existing branch. */
+  newBranch?: boolean;
+  /** Base ref for the new branch (default: current HEAD). Only used with newBranch. */
+  from?: string | null;
+}
+
+/**
+ * Add a git worktree for `branch` at `worktreeAbsPath` and return that path.
+ * With `newBranch`, creates the branch (optionally off `from`); otherwise
+ * checks out an existing branch. Failures throw a typed {@link WorktreeError}.
+ */
+export function createWorktree(
+  repoDir: string,
+  branch: string,
+  worktreeAbsPath: string,
+  options: CreateWorktreeOptions = {},
+): string {
+  const args = ["worktree", "add"];
+  if (options.newBranch) {
+    args.push("-b", branch, worktreeAbsPath);
+    if (options.from && options.from.length > 0) args.push(options.from);
+  } else {
+    args.push(worktreeAbsPath, branch);
+  }
+  runGit(repoDir, args, `Failed to create worktree for ${branch}`);
+  return worktreeAbsPath;
+}
+
+/** Remove a git worktree by path. `force` discards uncommitted changes. */
+export function removeWorktree(
+  repoDir: string,
+  worktreeAbsPath: string,
+  options: { force?: boolean } = {},
+): void {
+  const args = ["worktree", "remove"];
+  if (options.force) args.push("--force");
+  args.push(worktreeAbsPath);
+  runGit(repoDir, args, `Failed to remove worktree ${worktreeAbsPath}`);
+}
+
+/** List the repo's worktrees. Throws a typed {@link WorktreeError} on failure. */
+export function listWorktrees(repoDir: string): WorktreeEntry[] {
+  const out = runGit(repoDir, ["worktree", "list", "--porcelain"], "Failed to list worktrees");
+  return parseWorktreeList(out);
+}