sidebranch 0.2.0

package/src/gitops.js

@@ -0,0 +1,264 @@
+/**
+ * gitops.js — every git interaction in the tool.
+ *
+ * Rules:
+ *   - execFile with argument arrays only. There is no shell anywhere in
+ *     this file, so metacharacters in branch names cannot become commands.
+ *   - Ref names are validated twice: our conservative isSafeRefName(),
+ *     then git's own `check-ref-format --branch`.
+ *   - Review worktrees are treated as append-only environments: they are
+ *     never expected to be dirty. If one is dirty (someone hand-edited it),
+ *     we refuse to touch it unless the caller passes { discard: true }.
+ *     Nothing in this tool ever stashes or resets the user's primary
+ *     working tree — we never even run commands against it beyond reads.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fsp from "node:fs/promises";
+
+import { isSafeRefName } from "./security.js";
+
+const execFileP = promisify(execFile);
+
+const GIT_ENV = {
+  ...process.env,
+  GIT_TERMINAL_PROMPT: "0", // never hang on credential prompts
+  GIT_CONFIG_NOSYSTEM: process.env.GIT_CONFIG_NOSYSTEM ?? "",
+};
+
+async function git(cwd, args, opts = {}) {
+  try {
+    const { stdout } = await execFileP("git", args, {
+      cwd,
+      env: GIT_ENV,
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: opts.timeout ?? 120_000,
+      windowsHide: true,
+    });
+    return stdout;
+  } catch (err) {
+    const msg = (err.stderr || err.message || "git error").toString().trim();
+    const e = new Error(msg);
+    e.code = "EGIT";
+    throw e;
+  }
+}
+
+/** Throws unless `name` is a plausible, safe branch name per git itself. */
+export async function assertValidBranchName(repo, name) {
+  if (!isSafeRefName(name)) {
+    const e = new Error(`Invalid branch name: ${JSON.stringify(String(name).slice(0, 80))}`);
+    e.code = "EBADREF";
+    throw e;
+  }
+  await git(repo, ["check-ref-format", "--branch", name]);
+}
+
+export async function repoRoot(dir) {
+  return (await git(dir, ["rev-parse", "--show-toplevel"])).trim();
+}
+
+export async function currentBranch(dir) {
+  return (await git(dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+}
+
+export async function headCommit(dir) {
+  const out = await git(dir, ["log", "-1", "--format=%H%x1f%h%x1f%ci%x1f%s"]);
+  const [sha, short, date, subject] = out.trim().split("\x1f");
+  return { sha, short, date, subject };
+}
+
+export async function isClean(dir) {
+  const out = await git(dir, ["status", "--porcelain"]);
+  return out.trim() === "";
+}
+
+/** True if the repo is mid-merge/rebase/etc. — refuse to operate. */
+export async function inProgressOperation(dir) {
+  const out = await git(dir, [
+    "rev-parse", "--git-path", "MERGE_HEAD",
+    "--git-path", "REBASE_HEAD",
+    "--git-path", "CHERRY_PICK_HEAD",
+  ]);
+  const gitDirPaths = out.trim().split("\n");
+  const fs = await import("node:fs");
+  return gitDirPaths.some((p) => fs.existsSync(path.resolve(dir, p)));
+}
+
+/**
+ * List local and remote branches, most recently committed first.
+ * Remote refs are reported without the remote prefix, deduped against
+ * local branches.
+ */
+export async function listBranches(repo) {
+  const fmt = "%(refname)%1f%(refname:short)%1f%(committerdate:iso-strict)%1f%(objectname:short)%1f%(subject)";
+  const out = await git(repo, [
+    "for-each-ref", "--sort=-committerdate", `--format=${fmt.replaceAll("%1f", "%01")}`,
+    "refs/heads", "refs/remotes",
+  ]);
+  const seen = new Map();
+  for (const line of out.split("\n")) {
+    if (!line.trim()) continue;
+    const [refname, short, date, sha, subject] = line.split("\x01");
+    if (short.endsWith("/HEAD")) continue;
+    let name = short;
+    let remote = null;
+    if (refname.startsWith("refs/remotes/")) {
+      const parts = short.split("/");
+      remote = parts.shift();
+      name = parts.join("/");
+    }
+    if (!isSafeRefName(name)) continue; // skip anything we would refuse to check out
+    const existing = seen.get(name);
+    if (!existing) {
+      seen.set(name, { name, sha, date, subject, local: !remote, remotes: remote ? [remote] : [] });
+    } else if (remote) {
+      existing.remotes.push(remote);
+    } else {
+      existing.local = true;
+      existing.sha = sha;
+      existing.date = date;
+      existing.subject = subject;
+    }
+  }
+  return [...seen.values()];
+}
+
+export async function fetchAll(repo) {
+  await git(repo, ["fetch", "--all", "--prune"], { timeout: 180_000 });
+}
+
+/* ------------------------------- worktrees ------------------------------- */
+
+export async function listWorktrees(repo) {
+  const out = await git(repo, ["worktree", "list", "--porcelain"]);
+  const items = [];
+  let cur = null;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      if (cur) items.push(cur);
+      cur = { path: line.slice(9), branch: null, head: null, detached: false };
+    } else if (cur && line.startsWith("HEAD ")) {
+      cur.head = line.slice(5);
+    } else if (cur && line.startsWith("branch ")) {
+      cur.branch = line.slice(7).replace(/^refs\/heads\//, "");
+    } else if (cur && line === "detached") {
+      cur.detached = true;
+    }
+  }
+  if (cur) items.push(cur);
+  return items;
+}
+
+/**
+ * Resolve `dir` through the filesystem (symlinks and all — notably macOS's
+ * /var -> /private/var) so paths built from os.tmpdir() compare equal to
+ * what `git worktree list` reports. A deleted directory can't be realpathed
+ * directly, so walk up to the deepest ancestor that still exists, realpath
+ * that, and re-append the missing tail — otherwise a stale registration for
+ * a removed worktree silently fails to match on macOS tmp paths, and the
+ * heal in ensurePane never fires.
+ */
+async function resolvedPath(dir) {
+  const abs = path.resolve(dir);
+  let base = abs;
+  const missing = [];
+  for (;;) {
+    try {
+      return path.join(await fsp.realpath(base), ...missing.reverse());
+    } catch {
+      const parent = path.dirname(base);
+      if (parent === base) return abs;
+      missing.push(path.basename(base));
+      base = parent;
+    }
+  }
+}
+
+/**
+ * Find the `git worktree list` entry for `dir`, if any. Realpath-safe (see
+ * `resolvedPath`) — a plain path.resolve() comparison silently fails to
+ * match on macOS whenever the caller's path crosses the /var symlink.
+ */
+export async function findWorktree(worktrees, dir) {
+  const target = await resolvedPath(dir);
+  for (const w of worktrees) {
+    if ((await resolvedPath(w.path)) === target) return w;
+  }
+  return null;
+}
+
+/**
+ * Create a review worktree at `dir` checked out to `branch`.
+ * If the branch only exists on a remote, a local tracking branch is created.
+ * Uses --detach + switch so a branch already checked out elsewhere (e.g. the
+ * user's own working tree) doesn't block worktree creation.
+ */
+export async function addWorktree(repo, dir, branch) {
+  await assertValidBranchName(repo, branch);
+  await git(repo, ["worktree", "add", "--detach", "--", dir]);
+  await checkoutInWorktree(repo, dir, branch);
+}
+
+export async function removeWorktree(repo, dir) {
+  await git(repo, ["worktree", "remove", "--force", "--", dir]);
+}
+
+/**
+ * Clear registrations whose directories no longer exist on disk. Metadata
+ * only — prune never touches a working tree, ours or the user's.
+ */
+export async function pruneWorktrees(repo) {
+  await git(repo, ["worktree", "prune"]);
+}
+
+/**
+ * Point an existing review worktree at `branch`.
+ * Review worktrees are never hand-edited, so a dirty tree here means
+ * something unexpected happened; refuse unless the caller opts into
+ * discarding, and even then only files inside the *review* tree are touched.
+ */
+export async function checkoutInWorktree(repo, dir, branch, { discard = false } = {}) {
+  await assertValidBranchName(repo, branch);
+  if (await inProgressOperation(dir)) {
+    const e = new Error("Worktree has an in-progress merge/rebase; resolve or recreate it.");
+    e.code = "EBUSYTREE";
+    throw e;
+  }
+  if (!(await isClean(dir))) {
+    if (!discard) {
+      const e = new Error(
+        "Review worktree has uncommitted changes (it should never be edited by hand). " +
+        "Re-run with discard=true to reset it, or clean it up manually."
+      );
+      e.code = "EDIRTY";
+      throw e;
+    }
+    await git(dir, ["reset", "--hard"]);
+    await git(dir, ["clean", "-fd"]);
+  }
+
+  const localExists = (await git(dir, ["branch", "--list", "--format=%(refname:short)", branch]))
+    .split("\n").map((s) => s.trim()).includes(branch);
+
+  if (localExists) {
+    // Branch may be checked out in the user's main tree; review trees track
+    // the same commit in detached mode in that case rather than stealing it.
+    try {
+      await git(dir, ["switch", "--no-guess", branch]);
+    } catch (err) {
+      if (/already used by worktree|already checked out/i.test(err.message)) {
+        await git(dir, ["switch", "--detach", branch]);
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    // Creates a local branch tracking the remote one (guess mode), which is
+    // exactly the PR-review case.
+    await git(dir, ["switch", branch]);
+  }
+  return headCommit(dir);
+}

package/src/install.js

@@ -0,0 +1,115 @@
+/**
+ * install.js — decide when a checkout requires re-installing dependencies,
+ * and run the project's configured install command when it does.
+ *
+ * Framework-agnostic: we don't know or care what the package manager is.
+ * We hash a set of well-known dependency manifests (extendable via config)
+ * and run `config.install` only when the combined hash changes. The install
+ * command itself comes from the project's own config file, which is the
+ * same trust level as its package.json scripts.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+export const DEFAULT_LOCKFILES = [
+  "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "bun.lock",
+  "requirements.txt", "poetry.lock", "uv.lock", "Pipfile.lock",
+  "Gemfile.lock", "go.sum", "Cargo.lock", "composer.lock", "mix.lock",
+];
+
+/** Stable hash of all present lockfiles in a worktree (name + content). */
+export async function lockfileHash(dir, lockfiles = DEFAULT_LOCKFILES) {
+  const h = crypto.createHash("sha256");
+  let any = false;
+  for (const name of [...lockfiles].sort()) {
+    const p = path.join(dir, name);
+    try {
+      const buf = await fs.readFile(p);
+      any = true;
+      h.update(name);
+      h.update("\x00");
+      h.update(buf);
+      h.update("\x00");
+    } catch {
+      /* file absent — fine */
+    }
+  }
+  return any ? h.digest("hex") : "no-lockfiles";
+}
+
+/**
+ * Run the configured install command inside a worktree.
+ * The command is split into argv ourselves (no shell) — quoting in the
+ * config supports simple "word word" splitting only, which covers every
+ * real install command and avoids handing config a shell.
+ *
+ * `ring`, if supplied, accumulates raw stdout/stderr chunks (the caller owns
+ * it and can inspect it later, e.g. to serve a pane's full install log) and
+ * also backs the tail baked into a failure's error message, so "exited with
+ * code 1" becomes "exited with code 1: npm ERR! 404 Not Found — ..." without
+ * requiring a caller to go re-run the command by hand to see why.
+ */
+export function runInstall(dir, installCmd, { onOutput, ring = [], timeoutMs = 15 * 60_000 } = {}) {
+  const argv = splitCommand(installCmd);
+  if (argv.length === 0) return Promise.resolve({ skipped: true });
+  return new Promise((resolve, reject) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: dir,
+      env: { ...process.env, CI: "1" },
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+      windowsHide: true,
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error(`Install timed out after ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+    const forward = (buf) => {
+      const text = buf.toString();
+      pushRing(ring, text);
+      onOutput?.(text);
+    };
+    child.stdout.on("data", forward);
+    child.stderr.on("data", forward);
+    child.on("error", (err) => { clearTimeout(timer); reject(err); });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      if (code === 0) return resolve({ skipped: false });
+      const tail = tailText(ring);
+      reject(new Error(`Install command exited with code ${code}${tail ? `: ${tail}` : ""}`));
+    });
+  });
+}
+
+/** Bounded ring buffer: push a chunk, drop the oldest once over `max` entries. */
+export function pushRing(ring, chunk, max = 400) {
+  ring.push(chunk);
+  if (ring.length > max) ring.shift();
+}
+
+/**
+ * Join a ring buffer's captured chunks and return the trailing `maxChars`,
+ * with newlines/runs of whitespace collapsed to " › " so a multi-line tool
+ * error still reads as one line for inline display (e.g. a status bubble).
+ * Callers that want the untouched, multi-line log (e.g. a log-viewing
+ * endpoint) should read the ring directly instead of going through this.
+ */
+export function tailText(ring, maxChars = 300) {
+  const joined = ring.join("").trim();
+  if (!joined) return "";
+  const slice = joined.length > maxChars ? joined.slice(-maxChars) : joined;
+  return slice.trim().replace(/\s*\n\s*/g, " › ");
+}
+
+/** Minimal argv splitter: whitespace-separated, with double-quote grouping. */
+export function splitCommand(cmd) {
+  if (typeof cmd !== "string") return [];
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(cmd))) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}

package/src/manager.js

@@ -0,0 +1,260 @@
+/**
+ * manager.js — orchestration layer.
+ *
+ * A "pane" is a persistent review environment: one worktree + one dev
+ * server on its own port. Panes are reused across branch switches; the
+ * expensive parts (worktree creation, dependency install) happen only when
+ * needed. The user's own working tree is read-only territory: we list its
+ * branches and copy configured env files out of it, and that is all.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+
+import * as gitops from "./gitops.js";
+import { lockfileHash, runInstall } from "./install.js";
+import { allocatePort, DevServer } from "./processes.js";
+import { FrameProxy } from "./proxy.js";
+import { projectDataDir } from "./config.js";
+
+export class Manager extends EventEmitter {
+  constructor({ repoRoot, config }) {
+    super();
+    this.repoRoot = repoRoot;
+    this.config = config;
+    // Set by the Daemon once it knows its own port. Panes need it only to
+    // answer "would this app let the shell embed it?" — see probeFraming().
+    this.daemonPort = null;
+    this.dataDir = projectDataDir(repoRoot);
+    this.panes = new Map(); // id -> pane
+    this.takenPorts = new Set();
+    this.queue = Promise.resolve(); // serialize mutating operations
+  }
+
+  emitEvent(type, payload = {}) {
+    this.emit("event", { type, at: Date.now(), ...payload });
+  }
+
+  /** Serialize mutations so concurrent widget clicks can't interleave git ops. */
+  run(fn) {
+    const next = this.queue.then(fn, fn);
+    this.queue = next.catch(() => {});
+    return next;
+  }
+
+  paneDir(id) {
+    return path.join(this.dataDir, "panes", id);
+  }
+
+  async state() {
+    const [branch, head, branches] = await Promise.all([
+      gitops.currentBranch(this.repoRoot),
+      gitops.headCommit(this.repoRoot),
+      gitops.listBranches(this.repoRoot),
+    ]);
+    return {
+      repo: this.repoRoot,
+      main: { branch, head },
+      branches,
+      panes: [...this.panes.values()].map(paneInfo),
+    };
+  }
+
+  async fetch() {
+    this.emitEvent("fetch:start");
+    await gitops.fetchAll(this.repoRoot);
+    this.emitEvent("fetch:done");
+  }
+
+  /**
+   * Ensure a pane exists and is serving `branch`. This is the core loop:
+   * worktree → checkout → conditional install → (re)start server → ready.
+   */
+  ensurePane(id, branch, { discard = false } = {}) {
+    if (!/^[ab12]$/.test(id)) throw Object.assign(new Error("Pane id must be one of a/b"), { code: "EBADPANE" });
+    return this.run(async () => {
+      await gitops.assertValidBranchName(this.repoRoot, branch);
+      let pane = this.panes.get(id);
+      const dir = pane?.dir ?? this.paneDir(id);
+      const dirExists = await fs.access(dir).then(() => true, () => false);
+
+      if (!pane || !dirExists) {
+        await fs.mkdir(path.dirname(dir), { recursive: true });
+        const worktrees = await gitops.listWorktrees(this.repoRoot);
+        let existing = await gitops.findWorktree(worktrees, dir);
+        // Registered but gone from disk (a crash, a hand-run rm -rf): without
+        // healing, git runs with a missing cwd and dies with a misleading
+        // "spawn git ENOENT". Prune the stale registration and recreate.
+        if (existing && !dirExists) {
+          this.emitEvent("pane:healing", { pane: id });
+          await gitops.pruneWorktrees(this.repoRoot);
+          existing = null;
+        }
+        if (!existing) {
+          this.emitEvent("pane:creating", { pane: id, branch });
+          await gitops.addWorktree(this.repoRoot, dir, branch);
+          await this.copyEnvFiles(dir);
+        }
+        if (pane && !dirExists) {
+          // The old server's cwd is gone; so is node_modules. Start over.
+          await pane.server?.stop().catch(() => {});
+          await pane.viewProxy?.stop().catch(() => {});
+          if (pane.server) this.takenPorts.delete(pane.server.port);
+          if (pane.viewProxy) this.takenPorts.delete(pane.viewProxy.port);
+          pane.server = null;
+          pane.viewProxy = null;
+          pane.installedHash = null;
+        }
+        if (!pane) {
+          pane = {
+            id, dir, branch: null, head: null,
+            server: null, installedHash: null, status: "new", error: null,
+            installLog: [], // raw install stdout/stderr, retained for GET /api/pane/:id/log
+          };
+          this.panes.set(id, pane);
+        }
+      }
+
+      try {
+        pane.error = null;
+        pane.status = "switching";
+        this.emitEvent("pane:switching", { pane: id, branch });
+        pane.head = await gitops.checkoutInWorktree(this.repoRoot, pane.dir, branch, { discard });
+        pane.branch = branch;
+
+        const hash = await lockfileHash(pane.dir, this.config.lockfiles);
+        const needsInstall = hash !== pane.installedHash;
+        if (needsInstall) {
+          pane.status = "installing";
+          pane.installLog = [];
+          this.emitEvent("pane:installing", { pane: id, branch });
+          await runInstall(pane.dir, this.config.install, {
+            ring: pane.installLog,
+            onOutput: (chunk) => this.emitEvent("pane:install-output", { pane: id, chunk: chunk.slice(0, 2000) }),
+          });
+          pane.installedHash = hash;
+        }
+
+        if (!pane.server) {
+          const port = await allocatePort(this.config.basePort, this.takenPorts);
+          this.takenPorts.add(port);
+          pane.server = new DevServer({
+            command: this.config.dev,
+            cwd: pane.dir,
+            port,
+            env: this.config.env,
+            readyPath: this.config.ready.path,
+            readyStatuses: this.config.ready.statuses,
+            daemonPort: this.daemonPort,
+          });
+        }
+        if (!pane.viewProxy && this.config.frameProxy) {
+          const viewPort = await allocatePort(this.config.basePort, this.takenPorts);
+          this.takenPorts.add(viewPort);
+          pane.viewProxy = await new FrameProxy({ port: viewPort, targetPort: pane.server.port }).start();
+        }
+
+        pane.status = "starting";
+        this.emitEvent("pane:starting", { pane: id, branch, port: pane.server.port });
+        if (pane.server.state === "ready" && !needsInstall) {
+          // Dev server keeps running; its watcher sees the checkout. HMR or
+          // full reload is the frontend's job — nothing for us to do.
+        } else if (pane.server.state === "ready" && needsInstall) {
+          await pane.server.restart();
+        } else {
+          await pane.server.start();
+        }
+
+        pane.status = "ready";
+        this.emitEvent("pane:ready", { pane: id, branch, port: pane.server.port });
+        return paneInfo(pane);
+      } catch (err) {
+        pane.status = "error";
+        pane.error = err.message;
+        this.emitEvent("pane:error", { pane: id, branch, error: err.message, code: err.code });
+        throw err;
+      }
+    });
+  }
+
+  async stopPane(id) {
+    return this.run(async () => {
+      const pane = this.panes.get(id);
+      if (!pane) return;
+      await pane.server?.stop();
+      await pane.viewProxy?.stop();
+      if (pane.server) this.takenPorts.delete(pane.server.port);
+      if (pane.viewProxy) this.takenPorts.delete(pane.viewProxy.port);
+      pane.server = null;
+      pane.viewProxy = null;
+      pane.status = "stopped";
+      this.emitEvent("pane:stopped", { pane: id });
+    });
+  }
+
+  async destroyPane(id) {
+    await this.stopPane(id);
+    return this.run(async () => {
+      const pane = this.panes.get(id);
+      if (!pane) return;
+      try { await gitops.removeWorktree(this.repoRoot, pane.dir); } catch { /* best effort */ }
+      this.panes.delete(id);
+      this.emitEvent("pane:destroyed", { pane: id });
+    });
+  }
+
+  async shutdown() {
+    for (const id of this.panes.keys()) {
+      const pane = this.panes.get(id);
+      await pane.server?.stop().catch(() => {});
+      await pane.viewProxy?.stop().catch(() => {});
+    }
+  }
+
+  /**
+   * Full-detail diagnostics for a pane: raw install output plus the dev
+   * server's own stdout/stderr ring, both untouched (real newlines kept)
+   * unlike the collapsed single-line tail baked into `pane.error`. Returns
+   * null for an unknown pane so the route can 404 instead of guessing.
+   */
+  getPaneLog(id, { maxChars = 20_000 } = {}) {
+    const pane = this.panes.get(id);
+    if (!pane) return null;
+    const clip = (s) => (s.length > maxChars ? s.slice(-maxChars) : s);
+    return {
+      pane: id,
+      status: pane.status,
+      error: pane.error,
+      install: clip(pane.installLog.join("")),
+      server: clip((pane.server?.logRing ?? []).join("")),
+    };
+  }
+
+  /** Copy configured untracked files (e.g. .env) from the main tree. */
+  async copyEnvFiles(dir) {
+    for (const rel of this.config.copy) {
+      const src = path.join(this.repoRoot, rel);
+      const dst = path.join(dir, rel);
+      try {
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.copyFile(src, dst);
+      } catch { /* absent — fine */ }
+    }
+  }
+}
+
+function paneInfo(p) {
+  return {
+    id: p.id,
+    branch: p.branch,
+    head: p.head,
+    status: p.status,
+    error: p.error,
+    port: p.server?.port ?? null,
+    serverState: p.server?.state ?? "stopped",
+    framing: p.server?.framing ?? null,
+    url: p.server ? `http://localhost:${p.server.port}/` : null,
+    viewUrl: p.viewProxy ? `http://localhost:${p.viewProxy.port}/` : null,
+  };
+}