@dylanpiercey/work 0.2.17 → 0.2.18

package/bin/cli/topic.mjs

@@ -0,0 +1,585 @@
+// `work topic`: a workspace's topic branches (`<ws-branch>-<topic>`, each
+// in its own worktree at `<ws>/.worktrees/<topic>/<repo>`), made, listed and
+// put away as the generated workspace AGENTS.md describes, so an agent
+// never hand-types the naming, the path or the after-merge chores — the
+// places a slip loses work. Plain git in the workspace's own checkouts,
+// plus the server's workspace rows (bases) and status (PRs).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** A topic's name: a word, or `<group>.<topic>` (folded into one review
+ * chip). No `/`: it names a directory and a review section too. */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Lockfile → the command that installs it, first match wins. */
+const INSTALLERS = [
+  ["pnpm-lock.yaml", "pnpm install --frozen-lockfile"],
+  ["bun.lock", "bun install --frozen-lockfile"],
+  ["bun.lockb", "bun install --frozen-lockfile"],
+  ["yarn.lock", "yarn install --immutable"],
+  ["package-lock.json", "npm ci"],
+  ["uv.lock", "uv sync --frozen"],
+  ["poetry.lock", "poetry install"],
+  ["Gemfile.lock", "bundle install"],
+];
+
+function git(cwd, args, { allowFail = false } = {}) {
+  const r = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  if (r.status !== 0 && !allowFail) {
+    const why = (r.stderr || r.stdout || "").trim() || `exit ${r.status}`;
+    throw new Error(`git ${args.join(" ")}: ${why}`);
+  }
+  return { ok: r.status === 0, out: (r.stdout || "").trim(), err: r.stderr };
+}
+
+const has = (cwd, ref) =>
+  git(cwd, ["rev-parse", "--verify", "--quiet", ref], { allowFail: true }).ok;
+
+const oid = (cwd, ref) =>
+  git(cwd, ["rev-parse", "--verify", "--quiet", ref], { allowFail: true })
+    .out || null;
+
+/** `a` is reachable from `b` (both must exist). */
+const contains = (cwd, b, a) =>
+  git(cwd, ["merge-base", "--is-ancestor", a, b], { allowFail: true }).ok;
+
+/** Is `ref` this workspace's, given the other workspaces' branches? Its
+ * branch or a `-topic` of it, unless another workspace's branch extends
+ * this one's and the ref is that one's (server `ownsBranchOf`). */
+function owns(ref, branch, foreign) {
+  const of = (r, p) => r === p || r.startsWith(`${p}-`);
+  return of(ref, branch) && !foreign.some((x) => of(x, branch) && of(ref, x));
+}
+
+/** Where the workspace and its repos are, and the other workspaces'
+ * branches (whose topics are not this one's). */
+async function context(ctx, fresh) {
+  const { ws } = await ctx.resolveWorkspace();
+  const [list, status] = await Promise.all([
+    ctx.api.get("/api/workspaces"),
+    ctx.api.get(fresh ? "/api/status?fresh" : "/api/status"),
+  ]);
+  const foreign = list.filter((w) => w.id !== ws.id).map((w) => w.branch);
+  const prsOf = new Map(
+    (status[ws.id]?.repos || []).map((r) => [r.full_name, r.prs || []]),
+  );
+  const repos = ws.repos.map((r) => ({
+    ...r,
+    dir: path.join(ws.path, r.worktree),
+    prs: prsOf.get(r.full_name) || [],
+  }));
+  return { ws, repos, foreign };
+}
+
+const topicDir = (ws, name, repo) =>
+  path.join(ws.path, ".worktrees", name, repo.worktree);
+
+const link = (ws, repo, name) =>
+  `[${name}](/w/${ws.id}/review?section=${repo.worktree}@${name})`;
+
+/** The repo whose checkout (or one of whose topic worktrees) holds the
+ * cwd, else the workspace's only one. */
+function repoHere(ws, repos) {
+  let cwd = process.cwd();
+  try {
+    cwd = fs.realpathSync(cwd);
+  } catch {}
+  const real = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  const root = real(ws.path);
+  const inside = (dir) => cwd === dir || cwd.startsWith(dir + path.sep);
+  for (const r of repos) if (inside(real(r.dir))) return r;
+  const rel = path.relative(path.join(root, ".worktrees"), cwd).split(path.sep);
+  if (rel.length >= 2 && rel[0] !== "..") {
+    const r = repos.find((x) => x.worktree === rel[1]);
+    if (r) return r;
+  }
+  return repos.length === 1 ? repos[0] : null;
+}
+
+function pickRepos(ctx, ws, repos) {
+  const named = ctx.has("--repo") ? ctx.flags("--repo") : [];
+  if (named.length) {
+    return named.map((n) => {
+      const r = repos.find((x) => x.worktree === n || x.full_name === n);
+      if (!r)
+        ctx.die(
+          `no repo ${n} in ${ws.name} (its repos: ${repos.map((x) => x.worktree).join(", ")})`,
+        );
+      return r;
+    });
+  }
+  const here = repoHere(ws, repos);
+  if (!here)
+    ctx.die(
+      `which repo? This workspace has ${repos.map((x) => x.worktree).join(", ")}: pass --repo <name> (repeat it for several)`,
+    );
+  return [here];
+}
+
+function installFor(dir) {
+  for (const [file, cmd] of INSTALLERS)
+    if (fs.existsSync(path.join(dir, file))) return cmd;
+  return null;
+}
+
+/** The PR a branch has: an open one, else the latest. */
+function prFor(repo, branch) {
+  const mine = repo.prs.filter((p) => p.headRefName === branch);
+  return (
+    mine.find((p) => p.state === "OPEN") ||
+    mine.sort((a, b) =>
+      String(b.updatedAt || "").localeCompare(String(a.updatedAt || "")),
+    )[0] ||
+    null
+  );
+}
+
+/** Each worktree of a repo's cache, by the branch it has out. */
+function worktreesOf(dir) {
+  const out = git(dir, ["worktree", "list", "--porcelain"]).out;
+  const map = new Map();
+  let at = null;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("worktree ")) at = line.slice(9);
+    else if (line.startsWith("branch refs/heads/") && at)
+      map.set(line.slice(18), at);
+  }
+  return map;
+}
+
+const dirtyIn = (dir) =>
+  git(dir, ["status", "--porcelain"], { allowFail: true })
+    .out.split("\n")
+    .filter(Boolean);
+
+function fetch(ctx, repo) {
+  ctx.log(`fetching ${repo.full_name}…`);
+  git(repo.dir, ["fetch", "--prune", "--quiet", "origin"]);
+}
+
+// -- new ---------------------------------------------------------------------
+
+async function topicNew(ctx) {
+  const [name] = ctx.parse(["--repo", "--from"]);
+  if (!name)
+    ctx.die("usage: work topic new <name> [--repo <repo>…] [--from <ref>]");
+  if (!NAME.test(name) || name.includes(".."))
+    ctx.die(
+      `"${name}" is not a topic name: letters, digits, \`-\`, \`_\`, and \`.\` for a group (\`<group>.<topic>\`)`,
+    );
+  const { ws, repos } = await context(ctx, false);
+  const branch = `${ws.branch}-${name}`;
+  const from = ctx.has("--from") ? ctx.flag("--from") : null;
+  const picked = pickRepos(ctx, ws, repos);
+  for (const repo of picked) {
+    if (
+      !git(repo.dir, ["check-ref-format", "--branch", branch], {
+        allowFail: true,
+      }).ok
+    )
+      ctx.die(`${branch} is not a branch name git takes`);
+  }
+  // Every refusal before anything is made: half a topic is worse than none.
+  const plans = [];
+  for (const repo of picked) {
+    fetch(ctx, repo);
+    const dest = topicDir(ws, name, repo);
+    if (has(repo.dir, `refs/heads/${branch}`))
+      ctx.die(
+        `${repo.worktree}: ${branch} already exists${worktreesOf(repo.dir).get(branch) ? ` (at ${worktreesOf(repo.dir).get(branch)})` : ""} — pick another name, or work in it`,
+      );
+    if (has(repo.dir, `refs/remotes/origin/${branch}`))
+      ctx.die(
+        `${repo.worktree}: ${branch} is already on origin — check it out there (git -C ${repo.dir} worktree add ${dest} ${branch}) rather than starting it again`,
+      );
+    if (fs.existsSync(dest)) ctx.die(`${dest} already exists`);
+    const start = from ?? `origin/${repo.base_branch}`;
+    if (!has(repo.dir, `${start}^{commit}`))
+      ctx.die(`${repo.worktree}: no ${start} to start from`);
+    plans.push({ repo, dest, start });
+  }
+  const made = [];
+  for (const { repo, dest, start } of plans) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    // --no-track: its upstream is set by the first push, to its own name on
+    // origin, never to the base it was cut from.
+    git(repo.dir, ["worktree", "add", "--no-track", "-b", branch, dest, start]);
+    const install = installFor(dest);
+    const stacked = from && from !== `origin/${repo.base_branch}` ? from : null;
+    made.push({
+      repo: repo.worktree,
+      branch,
+      path: dest,
+      base: repo.base_branch,
+      from: start,
+      stacked,
+      install,
+      link: link(ws, repo, name),
+    });
+  }
+  if (ctx.has("--install")) {
+    for (const m of made) {
+      if (!m.install) continue;
+      ctx.log(`${m.repo}: ${m.install}`);
+      const r = spawnSync(m.install, {
+        cwd: m.path,
+        shell: true,
+        // Under --json stdout is the JSON alone: the install talks on stderr.
+        stdio: ["ignore", ctx.json ? 2 : "inherit", "inherit"],
+      });
+      m.installed = r.status === 0;
+      if (!m.installed) ctx.warn(`${m.repo}: \`${m.install}\` failed`);
+    }
+  }
+  ctx.out(made, (rows) => {
+    for (const m of rows) {
+      console.log(`${m.repo}/ on ${m.branch}`);
+      console.log(`  path:    ${m.path}`);
+      console.log(`  from:    ${m.from}`);
+      if (m.stacked)
+        console.log(
+          `  stacked: on ${m.stacked}, not origin/${m.base} — its PR's base is that branch, and it rebases when that one merges`,
+        );
+      if (m.install)
+        console.log(
+          `  install: ${m.install}${m.installed === undefined ? "  (run it there, or pass --install)" : m.installed ? "  (done)" : "  (failed)"}`,
+        );
+      console.log(`  review:  ${m.link}`);
+    }
+  });
+  if (made.some((m) => m.installed === false)) process.exitCode = 1;
+}
+
+// -- list --------------------------------------------------------------------
+
+/** Every topic of the workspace in one repo: local branches and origin's,
+ * this workspace's (not a longer-named workspace's), with where each
+ * stands against origin/<base>. */
+function topicsIn(ws, repo, foreign) {
+  const prefix = `${ws.branch}-`;
+  const refs = git(repo.dir, [
+    "for-each-ref",
+    "--format=%(refname)",
+    `refs/heads/${prefix}*`,
+    `refs/remotes/origin/${prefix}*`,
+  ]).out.split("\n");
+  const branches = new Set();
+  for (const ref of refs) {
+    const b = ref.replace(/^refs\/(heads|remotes\/origin)\//, "");
+    if (b && owns(b, ws.branch, foreign)) branches.add(b);
+  }
+  const trees = worktreesOf(repo.dir);
+  const base = `origin/${repo.base_branch}`;
+  const haveBase = has(repo.dir, base);
+  return [...branches].sort().map((branch) => {
+    const name = branch.slice(prefix.length);
+    const local = oid(repo.dir, `refs/heads/${branch}`);
+    const remote = oid(repo.dir, `refs/remotes/origin/${branch}`);
+    const tip = local || remote;
+    let ahead = null;
+    let behind = null;
+    if (haveBase) {
+      const [b, a] = git(repo.dir, [
+        "rev-list",
+        "--left-right",
+        "--count",
+        `${base}...${tip}`,
+      ]).out.split(/\s+/);
+      ahead = Number(a);
+      behind = Number(b);
+    }
+    const worktree = trees.get(branch) || null;
+    const pr = prFor(repo, branch);
+    return {
+      topic: name,
+      repo: repo.worktree,
+      branch,
+      base,
+      worktree,
+      ahead,
+      behind,
+      dirty: worktree ? dirtyIn(worktree).length : null,
+      local: !!local,
+      onOrigin: !!remote,
+      pushed: !!remote && (!local || local === remote),
+      // Commits here origin's copy lacks (all of them, with none there).
+      unpushed:
+        local && remote
+          ? Number(
+              git(repo.dir, ["rev-list", "--count", `${remote}..${local}`]).out,
+            )
+          : local
+            ? ahead
+            : 0,
+      pr: pr && {
+        number: pr.number,
+        state: pr.state,
+        draft: pr.isDraft,
+        url: pr.url,
+        title: pr.title,
+      },
+      merged: pr?.state === "MERGED",
+      // Nothing of its own past the base: either merged as it was, or a
+      // topic with no commits yet. Either way, nothing is lost by
+      // putting its worktree away.
+      contained: haveBase && ahead === 0,
+      link: link(ws, repo, name),
+    };
+  });
+}
+
+async function topicList(ctx) {
+  const { ws, repos, foreign } = await context(ctx, ctx.has("--fresh"));
+  const all = repos.flatMap((repo) => topicsIn(ws, repo, foreign));
+  // Put away: merged (or nothing past its base) with no worktree left —
+  // its branch kept, as the after-merge chores leave it. Listed on asking.
+  const away = (t) => !t.worktree && (t.merged || t.contained);
+  const rows = ctx.has("--all") ? all : all.filter((t) => !away(t));
+  const hidden = all.length - rows.length;
+  ctx.out(rows, (list) => {
+    if (!list.length)
+      console.log(
+        `no open topic branches in ${ws.name} (start one: work topic new <name>)`,
+      );
+    for (const t of list) {
+      const state = t.merged
+        ? "merged"
+        : t.contained
+          ? `nothing past ${t.base}`
+          : `${t.ahead} ahead, ${t.behind} behind`;
+      const flags = [
+        t.dirty ? `${t.dirty} uncommitted` : null,
+        t.local && !t.onOrigin && t.ahead ? "not pushed" : null,
+        t.local && t.onOrigin && t.unpushed ? `${t.unpushed} unpushed` : null,
+        t.local && t.onOrigin && !t.unpushed && !t.pushed
+          ? "origin has newer"
+          : null,
+        !t.local ? "only on origin" : null,
+      ].filter(Boolean);
+      const pr = t.pr
+        ? `  #${t.pr.number} ${t.pr.state === "OPEN" ? (t.pr.draft ? "draft" : "open") : t.pr.state.toLowerCase()}`
+        : "";
+      console.log(
+        `${t.repo}@${t.topic}  ${state}${pr}${flags.length ? `  (${flags.join(", ")})` : ""}`,
+      );
+      if (t.worktree) console.log(`  ${t.worktree}`);
+      console.log(`  ${t.link}`);
+    }
+    if (hidden)
+      console.log(
+        `${hidden} put away (merged, worktree removed): --all lists them`,
+      );
+  });
+}
+
+// -- done --------------------------------------------------------------------
+
+/** Why a merged-or-contained topic's local branch still holds work its
+ * merge did not take, or null when it holds none: commits past the merged
+ * PR's head, or past what origin has of it. */
+function leftover(repo, t, pr) {
+  const local = oid(repo.dir, `refs/heads/${t.branch}`);
+  if (!local || t.contained) return null;
+  let head = pr?.headRefOid || null;
+  if (head && !has(repo.dir, `${head}^{commit}`)) {
+    // A squash-merged PR's head lives on in GitHub's pull ref.
+    git(
+      repo.dir,
+      ["fetch", "--quiet", "origin", `refs/pull/${pr.number}/head`],
+      { allowFail: true },
+    );
+    if (!has(repo.dir, `${head}^{commit}`)) head = null;
+  }
+  const against =
+    head || oid(repo.dir, `refs/remotes/origin/${t.branch}`) || null;
+  if (!against)
+    return `can't tell what of ${t.branch} its merge took (no PR head or origin copy here)`;
+  if (contains(repo.dir, against, local)) return null;
+  const extra = git(repo.dir, [
+    "log",
+    "--format=%h %s",
+    `${against}..${local}`,
+  ]).out;
+  return `${t.branch} has commits its merge did not take:\n    ${extra.split("\n").join("\n    ")}`;
+}
+
+async function topicDone(ctx) {
+  const [name] = ctx.parse([]);
+  if (!name) ctx.die("usage: work topic done <name> [--rebase]");
+  const { ws, repos, foreign } = await context(ctx, true);
+  const branch = `${ws.branch}-${name}`;
+  const result = {
+    topic: name,
+    removed: [],
+    kept: [],
+    refused: [],
+    rebase: [],
+  };
+  const touched = repos.filter(
+    (r) =>
+      has(r.dir, `refs/heads/${branch}`) ||
+      has(r.dir, `refs/remotes/origin/${branch}`),
+  );
+  if (!touched.length)
+    ctx.die(`no topic ${name} in ${ws.name} (see: work topic list)`);
+  for (const repo of touched) {
+    fetch(ctx, repo);
+    const t = topicsIn(ws, repo, foreign).find((x) => x.branch === branch);
+    if (!t) continue;
+    const pr = prFor(repo, branch);
+    if (!t.merged && !t.contained) {
+      result.refused.push({
+        repo: repo.worktree,
+        why: `${branch} is not merged${t.pr ? ` (#${t.pr.number} is ${t.pr.state.toLowerCase()})` : ""} and has ${t.ahead} commit(s) its base does not`,
+      });
+      continue;
+    }
+    const why = leftover(repo, t, pr);
+    if (why) {
+      result.refused.push({ repo: repo.worktree, why });
+      continue;
+    }
+    if (t.worktree) {
+      const dirty = dirtyIn(t.worktree);
+      if (dirty.length) {
+        result.refused.push({
+          repo: repo.worktree,
+          why: `${t.worktree} has ${dirty.length} uncommitted change(s):\n    ${dirty.slice(0, 10).join("\n    ")}`,
+        });
+        continue;
+      }
+      git(repo.dir, ["worktree", "remove", t.worktree]);
+      // The topic's own folder, once its last repo's worktree is gone.
+      try {
+        fs.rmdirSync(path.dirname(t.worktree));
+      } catch {}
+      result.removed.push({ repo: repo.worktree, path: t.worktree });
+    } else {
+      result.kept.push({ repo: repo.worktree, why: "no worktree to remove" });
+    }
+    // The other open topics a squash-merge left on the old fork point.
+    const mergedTip = oid(repo.dir, `refs/heads/${branch}`);
+    for (const other of topicsIn(ws, repo, foreign)) {
+      if (other.branch === branch || other.merged || other.contained) continue;
+      if (!other.local || !other.behind) continue;
+      // Cut from the merged topic (a stack): only its own commits move.
+      const onto =
+        mergedTip && contains(repo.dir, other.branch, mergedTip) && !t.contained
+          ? mergedTip
+          : null;
+      const entry = {
+        repo: repo.worktree,
+        branch: other.branch,
+        worktree: other.worktree,
+        behind: other.behind,
+        command: onto
+          ? `git rebase --onto origin/${repo.base_branch} ${onto.slice(0, 12)}`
+          : `git rebase origin/${repo.base_branch}`,
+        state: "needs rebase",
+      };
+      if (ctx.has("--rebase")) {
+        if (!other.worktree) entry.state = "skipped: no worktree";
+        else if (dirtyIn(other.worktree).length)
+          entry.state = "skipped: uncommitted changes";
+        else {
+          const args = onto
+            ? ["rebase", "--onto", `origin/${repo.base_branch}`, onto]
+            : ["rebase", `origin/${repo.base_branch}`];
+          const r = git(other.worktree, args, { allowFail: true });
+          if (r.ok) entry.state = "rebased";
+          else {
+            // A rebase that stopped part-way is put back as it was; one that
+            // never started (no identity to commit as, a lock) says why.
+            const conflicted = /CONFLICT|could not apply/i.test(
+              `${r.out}\n${r.err}`,
+            );
+            git(other.worktree, ["rebase", "--abort"], { allowFail: true });
+            entry.state = conflicted
+              ? "conflict: left as it was"
+              : `failed: ${
+                  `${r.err}\n${r.out}`
+                    .split(/[\r\n]+/)
+                    .map((l) => l.trim())
+                    .filter((l) => l && !/^Rebasing \(/.test(l))[0] ||
+                  "git rebase failed"
+                }`;
+          }
+        }
+      }
+      result.rebase.push(entry);
+    }
+  }
+  ctx.out(result, (r) => {
+    for (const x of r.removed)
+      console.log(`${x.repo}: removed ${x.path} (branch kept)`);
+    for (const x of r.kept) console.log(`${x.repo}: ${x.why}`);
+    for (const x of r.refused)
+      console.log(`${x.repo}: left as it was — ${x.why}`);
+    for (const x of r.rebase)
+      console.log(
+        `${x.repo}: ${x.branch} ${x.behind} behind — ${x.state}${x.state === "needs rebase" ? ` (in ${x.worktree || "its checkout"}: ${x.command}, or work topic done ${name} --rebase)` : ""}`,
+      );
+  });
+  if (
+    result.refused.length ||
+    result.rebase.some((x) => /^(conflict|failed)/.test(x.state))
+  )
+    process.exitCode = 1;
+}
+
+// -- command -----------------------------------------------------------------
+
+const HELP = `work topic new <name> [--repo <repo>]… [--from <ref>] [--install]
+    start a topic branch, <ws-branch>-<name>, in its own worktree at
+    <ws>/.worktrees/<name>/<repo>, from origin/<base> (or <ref>: a stack).
+    The repo is the one the cwd is in, else the workspace's only one, else
+    --repo (repeat it for several). Prints each path, the install command
+    its lockfile wants (--install runs it) and the review link.
+    \`<group>.<topic>\` folds topics into one review chip.
+work topic list [--all] [--fresh] [--json]
+    this workspace's open topic branches: worktree, ahead/behind its base,
+    uncommitted and unpushed work, PR, merged, review link. --all adds
+    the ones put away (merged, worktree removed); --fresh asks GitHub
+    for PRs again rather than the last minutes' answer.
+work topic done <name> [--rebase] [--json]
+    after its PR merged (or with nothing past its base): fetch --prune,
+    remove its worktree (only if clean, and only if the merge took every
+    commit), keep the branch, and list the other open topics to rebase
+    onto origin/<base> — --rebase does it where the worktree is clean,
+    aborting on conflict. Never touches the workspace's own checkout.`;
+
+export const commands = [
+  {
+    name: "topic",
+    summary: "start, list and put away topic branches (work help topic)",
+    help: HELP,
+    async run(ctx) {
+      const [verb] = ctx.positional;
+      const sub = { ...ctx, positional: ctx.positional.slice(1) };
+      const parse = ctx.parse;
+      sub.parse = (valued) => parse(valued).slice(1);
+      try {
+        if (verb === "new") return await topicNew(sub);
+        if (verb === "list" || verb === "ls" || !verb)
+          return await topicList(sub);
+        if (verb === "done") return await topicDone(sub);
+      } catch (err) {
+        ctx.die(err instanceof Error ? err.message : String(err));
+      }
+      ctx.die(
+        `no \`work topic ${verb}\`: new, list or done (see: work help topic)`,
+      );
+    },
+  },
+];