gh-stack 0.7.1 → 0.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 Stacked PR manager for squash-merge workflows.
 
-Manages stacked pull requests with metadata stored in `.git/gh-stack-metadata.json`. Designed for repositories that use squash-merge (where tools like Graphite break down). Inspired by [Graphite](https://graphite.dev/) (`gt`) but works directly against GitHub — no backend required.
+Manages stacked pull requests with metadata stored locally under `.git/.gh-stack/` (never committed). Designed for repositories that use squash-merge (where tools like Graphite break down). Inspired by [Graphite](https://graphite.dev/) (`gt`) but works directly against GitHub — no backend required.
 
 ## Install
 
@@ -62,6 +62,11 @@ gh-stack sync
 
 # Check PR status
 gh-stack status
+
+# Split a long in-review chain so new work becomes its own stack
+gh-stack split feat-12           # feat-12.. → new stack based on feat-11
+# ...later, after the original stack merges to main:
+gh-stack restack --onto main     # re-root the split stack onto main
 ```
 
 ## Commands
@@ -133,6 +138,12 @@ restack [--resume] [--dry-run] [--verbose]
 
     (alias: rebase)
 
+restack --onto <ref>
+    Re-root the current stack onto a new base ref, changing the stack's
+    base. Use this to move a split stack off its parent-stack branch and
+    onto main once the parent stack has merged — only the stack's own
+    commits replay onto the new base.
+
 sync [--dry-run]
     Fetch main, rebase the base branch onto main, then restack all
     children. Snapshots every branch's pre-sync tip so children can be
@@ -143,12 +154,40 @@ merge [--dry-run] [-d|--delete-branch] [--collapse]
     then enables auto-merge for the base PR into main. All merges
     happen on GitHub so PRs show as "Merged", Linear tickets close
     automatically, and GitHub Actions fire normally. Skips already-
-    merged PRs (safe to re-run). Waits for GitHub between merges.
+    merged PRs (safe to re-run). Waits for GitHub between merges, and
+    self-heals its spurious "Head branch is out of date" (a stale PR
+    head pointer after a child squash) by re-syncing and retrying.
     --collapse  Stop after collapsing the stack into the base PR;
                 leaves the base PR open against main so you can
                 review the cumulative diff on GitHub. Re-run
                 `gh-stack merge` (without --collapse) to finish.
 
+split [<branch>] [--name <name>]
+    Cut the current stack into two at <branch>. The cut branch and every
+    branch above it move into a NEW stack whose base is the cut branch's
+    parent (which stays in the original stack). Purely a metadata
+    operation — no git branches are moved or rebased. Interactive
+    selector if no branch is given; you can't split at the stack's root.
+
+    Use it when a long chain is in review and can't merge yet, but new
+    work is piling on top: split at the first "new work" branch so the
+    original stack stays the review unit and the new stack rides on its
+    tip. Once the original stack merges, re-root the new stack with
+    `gh-stack restack --onto main`.
+
+rename [<old-name>] <new-name>
+    Rename a tracked branch (runs `git branch -m`) and re-key the stack
+    topology so it stays tracked, re-parenting any children that pointed
+    at the old name. With one argument, renames the current branch. Built
+    for the throwaway-branch → ticketed-PR flow (`feature-wip` →
+    `feature-BEE-1234`) without hand-editing metadata.
+
+    You don't strictly need this command: gh-stack also auto-reconciles
+    after a plain `git branch -m` (the per-branch git config is rename-
+    proof, so the next gh-stack command heals the name-keyed topology).
+    Renaming a branch that already has a PR is local-only — the GitHub PR
+    still tracks the old remote branch.
+
 delete [<branch>] [-k|--keep-branch] [--no-remote]
     Remove a branch from the stack and re-parent its children, then
     delete the underlying local git branch (and the remote branch if
@@ -164,8 +203,25 @@ log
     Display the current stack as a tree with branch numbers,
     PR info, and descriptions. This is the default command.
 
+update-prs [--force]
+    Refresh the "📚 Stacked on" visualization block in every PR
+    description for the current stack. PRs whose rendered block is
+    unchanged are skipped; --force rewrites all of them. (submit does
+    this automatically — use this to refresh without pushing.)
+
+stacks [--current] [--json]
+    List all stacks and their topology. Read-only and network-free —
+    emits stack membership straight from local metadata, so external
+    tools (status scripts, dashboards) can consume --json as a stable
+    interface instead of parsing the .git/.gh-stack/ store directly.
+    --current  Only the stack containing the current branch
+    --json     Topology as JSON: { current_stack, current_branch,
+               stacks: [{ name, description, base, is_current,
+               branches: [{ branch, parent, pr, description }] }] }
+
 status [--current] [--json]
     PR dashboard showing review state, CI status, and merge readiness.
+    Unlike `stacks`, this hits the network to fetch live PR/CI status.
     --current  Show only the current stack or standalone PR
     --json     Structured JSON output (progress goes to stderr)
 
@@ -174,6 +230,11 @@ undo
 
 archive [--restore <name>]
     List archived stacks by default, or restore one by name.
+
+doctor
+    Migrate old (v2) metadata to the v3 layout, reconcile git branch
+    config against the topology files, and flag stacks whose base
+    stack appears already-merged into main. Safe to run repeatedly.
 ```
 
 ## Global Options
@@ -211,47 +272,92 @@ Snapshots also power `gh-stack undo`, so the same data structure does double dut
 
 ### Stack Visualization
 
-`submit` automatically adds a stack section to all PR descriptions:
+`submit` automatically adds a stack section to all PR descriptions, with each
+branch numbered by its position in the stack (handy for spotting "which one is
+PR 6 of 12"):
 
 ```
 ### 📚 Stacked on
 ⚫ main
 ┃
-┣━ ✅ #123 Backend models
+┣━ 1. #123 Backend models
 ┃
-┗━ ⏳ #124 Frontend UI 👈
+┗━ 2. #124 Frontend UI 👈
 ```
 
-### Metadata
+The block is rendered entirely from local metadata plus one repo-identity
+lookup for links — no per-PR API call — and `submit` only rewrites a PR
+description whose block actually changed (membership/order/title), so a
+re-submit that touched one branch on a 12-PR stack does ~1 update, not 12.
+Review/CI status is intentionally not shown here. Run `gh-stack update-prs`
+(`--force` to rewrite all) to refresh manually.
+
+### Metadata (v3)
 
-Stack metadata lives at `.git/gh-stack-metadata.json` (never committed):
+Stack metadata lives under `.git/.gh-stack/` (never committed) — a folder of
+per-stack files plus git-native branch config, rather than a single JSON blob:
+
+```
+.git/.gh-stack/
+  current                      hint: last-active stack name
+  active/<stack>.json          topology of a live stack (ordered branches, base, description)
+  archived/<stack>.json        merged/closed stacks
+  deleted/<stack>.json         tombstones (recoverable)
+  snapshots/<ts>__<stack>.json append-only, retained per-stack
+  restack-state.json           in-flight restack/sync resume state
+```
+
+A single `active/<stack>.json` looks like:
 
 ```json
 {
-  "version": 2,
-  "current_stack": "kiliman/feature-2",
-  "stacks": {
-    "kiliman/feature-2": {
-      "description": "",
-      "last_branch": "kiliman/feature-2",
-      "branches": {
-        "kiliman/feature-1": {
-          "parent": "main",
-          "pr": 21729
-        },
-        "kiliman/feature-2": {
-          "parent": "kiliman/feature-1",
-          "pr": 21730
-        }
-      }
-    }
+  "description": "",
+  "last_branch": "kiliman/feature-2",
+  "base": "main",
+  "branches": {
+    "kiliman/feature-1": { "parent": "main", "pr": 21729 },
+    "kiliman/feature-2": { "parent": "kiliman/feature-1", "pr": 21730 }
   }
 }
 ```
 
+Per-branch membership is *also* recorded in git's own config, so renaming or
+deleting a branch updates/cleans it automatically:
+
+```
+branch.<name>.ghstack-stack   <stack>
+branch.<name>.ghstack-parent  <parent-branch>
+branch.<name>.ghstack-pr      <number>
+branch.<name>.ghstack-id      <uuid>   stable identity (survives rename)
+```
+
+The two representations cross-check each other; `gh-stack doctor` reconciles
+any drift. Why this shape:
+
+- **A stack can't silently vanish** — lifecycle transitions are file moves
+  (`active/ → archived/ → deleted/`), and a stale stack file is tombstoned, never
+  just unlinked.
+- **No `current_stack` drift** — the stack you're on is derivable from the
+  branch's own config, so a written pointer can't contradict reality.
+- **No all-or-nothing blast radius** — one bad write can't corrupt other stacks.
+- **Renames heal themselves** — `git branch -m old new` moves the whole
+  `branch.<old>` config section to `branch.<new>` (id and all), but the JSON is
+  keyed by name and goes stale. On the next command, gh-stack matches the moved
+  config to its stale JSON entry by `ghstack-id` (or PR number for older
+  branches), re-keys it, and re-points any children. So `gh-stack rename` — or
+  even a raw `git branch -m` — never needs manual metadata surgery.
+
+#### Migrating from v2
+
+Repos created before v3 store a single `.git/gh-stack-metadata.json`. Run
+`gh-stack doctor` once — it fans the monolith out into the layout above,
+backfills branch config, explodes snapshots into per-file records, and keeps a
+`.bak` of the old file. Commands refuse to run on unmigrated metadata and point
+you at `doctor`.
+
 ### Snapshots
 
-Before any destructive operation (restack, sync, merge, delete), gh-stack saves a snapshot of all branch HEADs. Run `gh-stack undo` to restore.
+Before any destructive operation (restack, sync, merge, delete), gh-stack saves a snapshot of all branch HEADs as an append-only file under `snapshots/`, retained per-stack. Run `gh-stack undo` to restore.
 
 ## Example Workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.7.1",
+  "version": "0.10.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

package/src/commands/doctor.ts

@@ -0,0 +1,268 @@
+// gh-stack doctor — migrate v2 → v3, reconcile branch config ↔ topology,
+// and flag stacks whose base stack appears to have merged.
+import * as p from "../lib/output.ts";
+import pc from "picocolors";
+import { rename, unlink } from "node:fs/promises";
+import * as git from "../lib/git.ts";
+import type { StackMetadata, Snapshot, Stack } from "../types.ts";
+import {
+  readMetadata,
+  writeMetadata,
+  v3Exists,
+  legacyMetadataExists,
+  stackBase,
+} from "../lib/metadata.ts";
+import { legacyMetadataPath, legacyRestackStatePath, restackStateFile } from "../lib/paths.ts";
+import { writeSnapshotFile } from "../lib/snapshot.ts";
+import { allBranchMemberships } from "../lib/branch-config.ts";
+
+const HELP = `
+gh-stack doctor — Migrate & repair stack metadata
+
+USAGE
+  gh-stack doctor
+
+Migrates old (v2) metadata to the v3 layout (per-stack files under
+.git/.gh-stack/ + git branch config), then reconciles branch config
+against the topology files and flags stacks whose base stack looks
+already-merged into main.
+
+Safe to run repeatedly — it's idempotent.
+`;
+
+export default async function doctor(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  p.intro(pc.cyan("gh-stack doctor"));
+
+  // ── 1. Migrate v2 → v3 if needed ──
+  const migrated = await migrateIfNeeded();
+
+  if (!(await v3Exists())) {
+    p.cancel(
+      `No stack metadata found.\n\n  Create your first stack with:\n    ${pc.green("gh-stack init")}`,
+    );
+    process.exit(1);
+  }
+
+  const meta = await readMetadata();
+  if (!meta) {
+    p.cancel("Failed to read stack metadata after migration");
+    process.exit(1);
+  }
+
+  // ── 2. Reconcile branch config ↔ topology ──
+  await reconcile(meta);
+
+  // ── 3. Flag base-stack-merged situations (issue #13) ──
+  await flagMergedBaseStacks(meta);
+
+  if (migrated) {
+    p.outro(pc.green("Migration complete — metadata is now v3."));
+  } else {
+    p.outro(pc.green("Metadata looks healthy."));
+  }
+}
+
+// ── Migration ──
+
+async function migrateIfNeeded(): Promise<boolean> {
+  if (!(await legacyMetadataExists())) return false;
+
+  const legacyPath = await legacyMetadataPath();
+
+  // If a v3 store already exists alongside the legacy file, don't clobber it —
+  // just retire the stale legacy file.
+  if (await v3Exists()) {
+    p.log.warn(
+      `Both v3 metadata and a legacy file exist. Keeping v3 and backing up the legacy file.`,
+    );
+    await rename(legacyPath, `${legacyPath}.bak`).catch(() => {});
+    return false;
+  }
+
+  const s = p.spinner();
+  s.start("Migrating v2 metadata → v3...");
+
+  const raw = (await Bun.file(legacyPath).json()) as Partial<StackMetadata>;
+  const stacks: Record<string, Stack> = raw.stacks ?? {};
+  const archive: Record<string, Stack> = raw.archive ?? {};
+  const snapshots: Snapshot[] = raw.snapshots ?? [];
+
+  // Backfill base for stacks written before the split feature.
+  for (const stack of [...Object.values(stacks), ...Object.values(archive)]) {
+    if (stack.base == null) stack.base = "main";
+  }
+
+  const meta: StackMetadata = {
+    version: 3,
+    current_stack: raw.current_stack ?? null,
+    stacks,
+  };
+  if (Object.keys(archive).length > 0) meta.archive = archive;
+
+  // Fan out topology + backfill branch config.
+  await writeMetadata(meta);
+
+  // Explode the snapshots[] array into per-file records, inferring each
+  // snapshot's owning stack from its recorded branch set (v2 didn't store it).
+  for (const snap of snapshots) {
+    const owner = inferStack(snap, stacks, archive) ?? meta.current_stack ?? undefined;
+    await writeSnapshotFile({ ...snap, stack: owner });
+  }
+
+  // Migrate the legacy restack-state file, if present.
+  const legacyState = await legacyRestackStatePath();
+  if (await Bun.file(legacyState).exists()) {
+    const content = await Bun.file(legacyState).text();
+    await Bun.write(await restackStateFile(), content);
+    await unlink(legacyState).catch(() => {});
+  }
+
+  // Retire the legacy monolith (keep a .bak for safety).
+  await rename(legacyPath, `${legacyPath}.bak`).catch(() => {});
+
+  s.stop("Migrated to v3");
+
+  const stackCount = Object.keys(stacks).length;
+  const archiveCount = Object.keys(archive).length;
+  p.log.info(
+    `  ${pc.dim("→")} ${stackCount} active, ${archiveCount} archived, ${snapshots.length} snapshot(s)`,
+  );
+  p.log.info(`  ${pc.dim("→")} Backed up legacy file to ${pc.dim(`${legacyPath}.bak`)}`);
+  return true;
+}
+
+/** Pick the stack whose branch set best overlaps a snapshot's branches. */
+function inferStack(
+  snap: Snapshot,
+  stacks: Record<string, Stack>,
+  archive: Record<string, Stack>,
+): string | null {
+  const recorded = new Set(Object.keys(snap.branches));
+  let best: string | null = null;
+  let bestOverlap = 0;
+  for (const [name, stack] of Object.entries({ ...archive, ...stacks })) {
+    let overlap = 0;
+    for (const b of Object.keys(stack.branches)) if (recorded.has(b)) overlap++;
+    if (overlap > bestOverlap) {
+      bestOverlap = overlap;
+      best = name;
+    }
+  }
+  return best;
+}
+
+// ── Reconciliation ──
+
+async function reconcile(meta: StackMetadata): Promise<void> {
+  // Re-syncing config is what writeMetadata already does: set desired
+  // membership, clear stale. Snapshot the before-state so we can report what
+  // drifted, then apply.
+  const before = await allBranchMemberships();
+
+  // Report topology branches that no longer exist locally (can't auto-fix
+  // safely — re-parenting children is a judgement call).
+  const deadBranches: { stack: string; branch: string }[] = [];
+  for (const [name, stack] of Object.entries(meta.stacks)) {
+    for (const branch of Object.keys(stack.branches)) {
+      if (!(await git.localBranchExists(branch))) {
+        deadBranches.push({ stack: name, branch });
+      }
+    }
+  }
+
+  // Build desired membership to diff against `before`.
+  const desired = new Set<string>();
+  let drift = 0;
+  for (const [name, stack] of Object.entries(meta.stacks)) {
+    for (const [branch, b] of Object.entries(stack.branches)) {
+      desired.add(branch);
+      const cur = before.get(branch);
+      if (!cur || cur.stack !== name || cur.parent !== b.parent || cur.pr !== b.pr) drift++;
+    }
+  }
+  let orphans = 0;
+  for (const branch of before.keys()) {
+    if (!desired.has(branch)) orphans++;
+  }
+
+  // Apply the reconciliation (idempotent).
+  await writeMetadata(meta);
+
+  if (drift > 0 || orphans > 0) {
+    p.log.success(
+      `Reconciled branch config: ${drift} updated, ${orphans} stale membership(s) cleared.`,
+    );
+  } else {
+    p.log.info("Branch config already in sync with topology.");
+  }
+
+  if (deadBranches.length > 0) {
+    console.log();
+    p.log.warn(`${deadBranches.length} branch(es) in topology no longer exist locally:`);
+    for (const { stack, branch } of deadBranches) {
+      console.log(`  ${pc.red("•")} ${pc.yellow(branch)} ${pc.dim(`(stack: ${stack})`)}`);
+    }
+    console.log(
+      `  ${pc.dim(`Prune with ${pc.green("gh-stack delete <branch>")} or restore the branch.`)}`,
+    );
+  }
+}
+
+// ── Base-stack-merged detection (issue #13) ──
+
+async function flagMergedBaseStacks(meta: StackMetadata): Promise<void> {
+  const trunk = await git.trunkBranch();
+  const flagged: { stack: string; base: string; reason: string }[] = [];
+
+  for (const [name, stack] of Object.entries(meta.stacks)) {
+    const base = stackBase(stack);
+    if (base === "main" || base === "master") continue; // trunk-rooted: not affected
+
+    const baseExists = await git.localBranchExists(base);
+    if (!baseExists) {
+      flagged.push({
+        stack: name,
+        base,
+        reason: `base branch ${pc.yellow(base)} is gone (parent stack likely merged)`,
+      });
+      continue;
+    }
+
+    // Base still exists — has it already landed in trunk?
+    let baseInTrunk = false;
+    for (const ref of [`origin/${trunk}`, trunk]) {
+      try {
+        if (await git.isAncestor(base, ref)) {
+          baseInTrunk = true;
+          break;
+        }
+      } catch {
+        // ref not available locally — ignore
+      }
+    }
+    if (baseInTrunk) {
+      flagged.push({
+        stack: name,
+        base,
+        reason: `base ${pc.yellow(base)} is already in ${pc.cyan(trunk)}`,
+      });
+    }
+  }
+
+  if (flagged.length === 0) return;
+
+  console.log();
+  p.log.warn("Stacks whose base appears merged into main:");
+  for (const { stack, reason } of flagged) {
+    console.log(`  ${pc.yellow("⚠")} ${pc.yellow(stack)} — ${reason}`);
+  }
+  console.log();
+  console.log(`  ${pc.dim("Re-root each onto main once its parent has merged:")}`);
+  console.log(`    ${pc.green("gh-stack checkout <stack>")}`);
+  console.log(`    ${pc.green("gh-stack restack --onto main")}`);
+}

package/src/commands/down.ts

@@ -2,7 +2,7 @@
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, writeMetadata } from "../lib/metadata.ts";
+import { findStackForBranch, stackBase, writeMetadata } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
 
 export default async function down(args: string[]): Promise<void> {
@@ -35,6 +35,8 @@ OPTIONS
   }
 
   const stack = meta.stacks[stackName]!;
+  const base = stackBase(stack);
+  let moved = 0;
 
   for (let i = 0; i < steps; i++) {
     const branchMeta = stack.branches[currentBranch];
@@ -43,17 +45,23 @@ OPTIONS
       return;
     }
 
+    // The stack bottoms out at its base (main for a normal stack, or the base
+    // branch for a split stack). The root's parent IS the base — stop there
+    // rather than crossing into a parent stack.
     const parent = branchMeta.parent;
-    if (parent === "main" || parent === "master") {
-      if (i === 0) {
+    if (parent === base) {
+      if (moved === 0) {
         p.log.warn(`${pc.yellow(currentBranch)} is already at the bottom of the stack`);
-      } else {
-        p.log.info(`Reached bottom of stack at ${pc.yellow(currentBranch)} after ${i} step(s)`);
+        return;
       }
-      return;
+      // Reached the bottom partway through a multi-step move — stop here but
+      // still check out as far as we got.
+      p.log.info(`Reached bottom of stack after ${moved} step(s)`);
+      break;
     }
 
     currentBranch = parent;
+    moved++;
   }
 
   await git.checkout(currentBranch);

package/src/commands/init.ts

@@ -13,6 +13,7 @@ import {
 import { getPrNumber } from "../lib/github.ts";
 import { isAutoYes } from "../lib/ui.ts";
 import { detectBranchChain } from "../lib/chain.ts";
+import { gateLegacyMetadata } from "../lib/safety.ts";
 import type { StackMetadata, Branch } from "../types.ts";
 
 const HELP = `
@@ -71,6 +72,8 @@ export default async function init(args: string[]): Promise<void> {
   if (await metadataExists()) {
     meta = (await readMetadata())!;
   } else {
+    // Don't create a fresh v3 store on top of an unmigrated v2 file.
+    await gateLegacyMetadata();
     meta = await initMetadata();
   }
 
@@ -121,7 +124,7 @@ export default async function init(args: string[]): Promise<void> {
   }
 
   // ── Create stack ──
-  meta = await createStack(meta, stackName, descFlag || "");
+  meta = await createStack(meta, stackName, descFlag || "", trunk);
 
   // ── Add branches with PR detection ──
   const prSpinner = p.spinner();

package/src/commands/log.ts

@@ -9,10 +9,12 @@ import {
   writeMetadata,
 } from "../lib/metadata.ts";
 import { renderStackTree } from "../lib/ui.ts";
+import { gateLegacyMetadata } from "../lib/safety.ts";
 
 export default async function log(_args: string[]): Promise<void> {
   // Check if metadata exists
   if (!(await metadataExists())) {
+    await gateLegacyMetadata(); // exits with a migrate hint if a v2 file remains
     p.log.warn("No stack metadata found");
     console.log();
     console.log(`  Create your first stack with:`);