gh-stack 0.3.1 → 0.7.0

package/README.md

@@ -83,6 +83,13 @@ submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file
     that don't have them, and update all PR descriptions with stack
     visualization. Idempotent — safe to run repeatedly.
 
+    Self-healing: if the current branch isn't tracked in a stack yet,
+    submit auto-detects the chain from trunk → current, registers (or
+    reconciles into) a stack, then pushes + creates PRs for the whole
+    chain. You never need to run `gh-stack init` first — running submit
+    from the top of a bare chain of local branches converges to the
+    expected end state (stack registered, branches pushed, PRs created).
+
     --title/-t and --body/-b provide PR details directly (skips prompts).
     --body-file reads body from a file. In --yes mode without --title,
     auto-generates PR titles from branch names.
@@ -117,7 +124,8 @@ ls
 ```
 restack [--resume] [--dry-run] [--verbose]
     Rebase the current branch and all descendants onto their parents.
-    Uses tag-based references for stable rebasing across the chain.
+    Uses metadata snapshots to recover the correct rebase base even
+    after a parent's history has been rewritten.
 
     On conflict:
         git rebase --continue
@@ -127,14 +135,19 @@ restack [--resume] [--dry-run] [--verbose]
 
 sync [--dry-run]
     Fetch main, rebase the base branch onto main, then restack all
-    children. Creates tags for ALL branches before any rebasing starts.
+    children. Snapshots every branch's pre-sync tip so children can be
+    correctly rebased even though their parent's history was rewritten.
 
-merge [--dry-run] [-d|--delete-branch]
+merge [--dry-run] [-d|--delete-branch] [--collapse]
     Squash-merge the stack top-down via GitHub (PR3 → PR2 → PR1),
     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.
+    --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.
 
 delete [<branch>]
     Remove a branch from the stack and re-parent its children.
@@ -164,14 +177,18 @@ archive [--restore <name>]
 
 ```
 --yes, -y      Skip all confirmations (for agents/CI)
+--plain        Plain output — no spinners, colors, or banner boxes
 --help         Show help for a command
 --version, -V  Show version
 ```
 
+`--plain` is auto-enabled when `--yes` / `GH_STACK_YES=1` is set, so agents get clean, easily-filtered output by default. Use `--plain` alone if you want plain output but still interactive prompts.
+
 ## Environment Variables
 
 ```
-GH_STACK_YES=1         Skip all confirmations (same as --yes)
+GH_STACK_YES=1         Skip all confirmations (same as --yes; also enables --plain)
+GH_STACK_PLAIN=1       Plain output (same as --plain)
 GH_STACK_NO_COLOR=1    Disable colored output
 ```
 
@@ -181,9 +198,13 @@ GH_STACK_NO_COLOR=1    Disable colored output
 
 `gh-stack init` auto-detects branch chains by walking git ancestry. From the top branch, it finds all local branches whose tips are strict ancestors (but not already merged into trunk) and reconstructs the chain with correct parent relationships.
 
-### Tag-Based Rebasing
+### Snapshot-Based Rebasing
+
+The critical insight: after a parent branch's history is rewritten (e.g., rebased onto a new main), `git merge-base(child, parent)` falls all the way back to the original main — and using that as a rebase base would replay the parent's old commits onto the child, producing ghost-conflicts on the parent's own work.
 
-The critical insight: after rebasing a parent branch, `git merge-base` returns wrong results for its children. gh-stack solves this by creating temporary `stack-sync-*` tags marking each branch's divergence point **before** any rebasing starts, then using those stable references for `git rebase --onto`.
+gh-stack solves this by snapshotting every branch's tip **before** any destructive operation. When restacking a child whose parent has been rewritten, gh-stack walks the snapshots newest-first and finds the most recent recorded tip that's no longer an ancestor of the parent's current tip. That orphaned SHA is the correct rebase base — `git rebase --onto <new-parent-tip> <orphaned-old-tip> <child>` replays only the child's unique commits.
+
+Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
 ### Stack Visualization
 
@@ -256,6 +277,11 @@ gh-stack status
 
 # When PRs are approved, merge the stack
 gh-stack merge       # squash-merges down, pushes, enables auto-merge
+
+# Or: collapse first to review the cumulative diff before shipping
+gh-stack merge --collapse   # squash-merges PRn..PR2 into PR1, stops there
+# ...review base PR on GitHub...
+gh-stack merge              # finishes base PR → main + archives the stack
 ```
 
 ## Agent/CI Usage

package/package.json

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

package/src/commands/archive.ts

@@ -1,5 +1,5 @@
 // gh-stack archive — Manage archived stacks
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { writeMetadata } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";

package/src/commands/bottom.ts

@@ -1,5 +1,5 @@
 // gh-stack bottom — Jump to the base of the stack
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";

package/src/commands/checkout.ts

@@ -1,5 +1,5 @@
 // gh-stack checkout — Switch between branches or stacks
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { writeMetadata, getOrderedBranches, findStackForBranch } from "../lib/metadata.ts";

package/src/commands/create.ts

@@ -1,5 +1,5 @@
 // gh-stack create — Create a new branch and add to the stack
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, addBranchToStack } from "../lib/metadata.ts";

package/src/commands/delete.ts

@@ -1,5 +1,5 @@
 // gh-stack delete — Delete a branch from the stack (re-link parent chain)
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { removeBranchFromStack, getChildren } from "../lib/metadata.ts";
 import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";

package/src/commands/down.ts

@@ -1,5 +1,5 @@
 // gh-stack down — Move to parent branch (downstack)
-import * as p from "@clack/prompts";
+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";

package/src/commands/init.ts

@@ -1,5 +1,5 @@
 // gh-stack init — Create a new stack, auto-detecting branch chains
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {
@@ -12,6 +12,7 @@ import {
 } from "../lib/metadata.ts";
 import { getPrNumber } from "../lib/github.ts";
 import { isAutoYes } from "../lib/ui.ts";
+import { detectBranchChain } from "../lib/chain.ts";
 import type { StackMetadata, Branch } from "../types.ts";
 
 const HELP = `
@@ -37,50 +38,6 @@ EXAMPLES
   gh-stack init --parent develop             # Different trunk branch
 `;
 
-/**
- * Detect a chain of branches from trunk to the current branch.
- *
- * Walks down from the current branch by finding local branches whose
- * tips are strict ancestors of the current branch. Sorts by commit
- * distance (closest = direct parent) to reconstruct the chain.
- *
- * Returns branches in bottom-up order: [closest-to-trunk, ..., current]
- */
-async function detectBranchChain(currentBranch: string, trunk: string): Promise<string[]> {
-  const allBranches = await git.allLocalBranches();
-
-  // Branches to exclude: current, trunk, and always main/master
-  const excluded = new Set([currentBranch, trunk, "main", "master"]);
-
-  // Find branches that are strict ancestors of current (and not trunk)
-  const ancestors: { name: string; distance: number }[] = [];
-
-  for (const branch of allBranches) {
-    if (excluded.has(branch)) continue;
-
-    // Is this branch's tip an ancestor of current?
-    if (await git.isAncestor(branch, currentBranch)) {
-      // Skip branches already merged into trunk (stale/old branches)
-      if (await git.isAncestor(branch, trunk)) continue;
-
-      // How many commits between this branch and current?
-      const distance = await git.commitCount(branch, currentBranch);
-      if (distance > 0) {
-        ancestors.push({ name: branch, distance });
-      }
-    }
-  }
-
-  // Sort by distance descending (furthest from current = closest to trunk)
-  ancestors.sort((a, b) => b.distance - a.distance);
-
-  // Build chain: ancestors (sorted trunk→current) + current branch
-  const chain = ancestors.map((a) => a.name);
-  chain.push(currentBranch);
-
-  return chain;
-}
-
 export default async function init(args: string[]): Promise<void> {
   // Parse flags
   let nameFlag: string | undefined;

package/src/commands/log.ts

@@ -1,5 +1,5 @@
 // gh-stack log — Display current stack tree (default command)
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {

package/src/commands/merge.ts

@@ -1,5 +1,5 @@
 // gh-stack merge — Squash-merge stack top-down via GitHub
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { $ } from "bun";
 import * as git from "../lib/git.ts";
@@ -41,13 +41,14 @@ async function waitForMergeable(
 export default async function merge(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
   const deleteFlag = args.includes("--delete-branch") || args.includes("-d");
+  const collapse = args.includes("--collapse") || args.includes("--stop-at-base");
 
   if (args.includes("--help")) {
     console.log(`
 gh-stack merge — Squash-merge stack via GitHub
 
 USAGE
-  gh-stack merge [--dry-run] [-d|--delete-branch]
+  gh-stack merge [--dry-run] [-d|--delete-branch] [--collapse]
 
 Squash-merges the stack from top to bottom via GitHub:
   PR3 → squash into PR2, PR2 → squash into PR1, PR1 → auto-merge into main.
@@ -61,6 +62,11 @@ Waits for GitHub to process between merges if needed.
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
       --dry-run        Show what would happen without doing anything
+      --collapse       Stop after collapsing the stack into the base PR;
+                       do NOT merge base PR into main. Lets you review the
+                       cumulative diff on GitHub first. Re-run ${pc.green("gh-stack merge")}
+                       (without --collapse) to finish the job.
+      --stop-at-base   Alias for --collapse
 `);
     return;
   }
@@ -81,6 +87,12 @@ OPTIONS
   if (ordered.length <= 1) {
     // Single branch — just enable auto-merge
     const basePr = stack.branches[ordered[0]!]?.pr;
+    if (collapse) {
+      p.log.info(
+        `Single-branch stack — nothing to collapse. The base PR${basePr ? ` (#${basePr})` : ""} already targets main.`,
+      );
+      return;
+    }
     if (basePr) {
       p.log.info("Single branch stack — enabling auto-merge on GitHub.");
       if (!dryRun) {
@@ -97,8 +109,13 @@ OPTIONS
     return;
   }
 
-  p.intro(pc.cyan("Stack Merge (via GitHub)"));
+  p.intro(pc.cyan(collapse ? "Stack Collapse (via GitHub)" : "Stack Merge (via GitHub)"));
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
+  if (collapse) {
+    p.log.info(
+      pc.dim("--collapse: will stop after collapsing into base PR; base will NOT merge to main."),
+    );
+  }
   console.log();
 
   // Check PR states and build the merge plan
@@ -121,9 +138,15 @@ OPTIONS
       `    ${pc.yellow(child)}${childPr ? ` (#${childPr})` : ""} → squash into ${pc.blue(parent)}${mergedLabel}`,
     );
   }
-  console.log(
-    `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.green("main")} (auto-merge)`,
-  );
+  if (collapse) {
+    console.log(
+      `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.dim("(stop — review on GitHub, then re-run merge to finish)")}`,
+    );
+  } else {
+    console.log(
+      `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.green("main")} (auto-merge)`,
+    );
+  }
   console.log();
 
   if (dryRun) {
@@ -140,14 +163,18 @@ OPTIONS
     process.exit(1);
   }
 
-  const confirmed = await confirmAction("Squash-merge stack top-down via GitHub?");
+  const confirmed = await confirmAction(
+    collapse
+      ? "Collapse stack top-down via GitHub (stop at base PR)?"
+      : "Squash-merge stack top-down via GitHub?",
+  );
   if (!confirmed) {
     p.cancel("Cancelled");
     process.exit(0);
   }
 
   // Take snapshot
-  await takeSnapshot(meta, stackName, "merge");
+  await takeSnapshot(meta, stackName, collapse ? "collapse" : "merge");
 
   // Merge top-down via GitHub: for each PR from top, squash-merge into parent
   for (let i = 0; i < reversed.length - 1; i++) {
@@ -205,6 +232,74 @@ OPTIONS
     }
   }
 
+  // ─── --collapse: stop here. Base PR holds the cumulative diff; let the
+  //     user review on GitHub and re-run `gh-stack merge` to finish.
+  if (collapse) {
+    console.log();
+
+    // Park the user on the base branch — mirrors how normal merge lands you
+    // on `main`. Fetch origin so they can see how far behind their local
+    // base branch is (the squashed commits live only on origin/<base> now).
+    const checkoutSpinner = p.spinner();
+    checkoutSpinner.start(`Checking out base branch ${pc.yellow(baseBranch)}...`);
+    let localBehind = false;
+    try {
+      await $`git fetch origin`.quiet();
+      await git.checkout(baseBranch);
+
+      // Compare local vs origin to flag the user if their local base is stale
+      try {
+        const localSha = await git.revParse(baseBranch);
+        const remoteSha = await git.revParse(`origin/${baseBranch}`);
+        localBehind = localSha !== remoteSha;
+      } catch {}
+
+      checkoutSpinner.stop(`On base branch ${pc.yellow(baseBranch)}`);
+    } catch {
+      checkoutSpinner.stop(pc.dim(`Could not checkout ${baseBranch} — switch manually if needed`));
+    }
+
+    console.log();
+    console.log(pc.cyan("━".repeat(40)));
+    console.log(pc.green("  Stack collapsed into base PR"));
+    console.log(pc.cyan("━".repeat(40)));
+    console.log();
+
+    // Fetch the base PR URL for a clickable summary line
+    let baseUrl: string | null = null;
+    try {
+      const proc = Bun.spawn(["gh", "pr", "view", String(basePr), "--json", "url", "-q", ".url"], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const out = (await new Response(proc.stdout).text()).trim();
+      if ((await proc.exited) === 0 && out) baseUrl = out;
+    } catch {}
+
+    console.log(
+      `  ${pc.blue("Base PR:")} #${basePr} ${pc.yellow(baseBranch)} → ${pc.green("main")}`,
+    );
+    if (baseUrl) console.log(`  ${pc.dim(baseUrl)}`);
+    if (localBehind) {
+      console.log();
+      console.log(
+        `  ${pc.yellow("⚠")} Local ${pc.yellow(baseBranch)} is behind ${pc.dim(`origin/${baseBranch}`)}`,
+      );
+      console.log(
+        `    ${pc.dim("(squashed commits from upper PRs live on origin only — review the diff on GitHub)")}`,
+      );
+    }
+    console.log();
+    console.log(`  ${pc.dim("Review the cumulative diff on GitHub. When ready to ship:")}`);
+    console.log(
+      `    ${pc.green("gh-stack merge")}    ${pc.dim("# finishes base PR → main + archives")}`,
+    );
+    console.log();
+
+    p.outro(pc.green("Collapse complete — stack left intact for review."));
+    return;
+  }
+
   // Base PR → enable auto-merge into main
   console.log();
   console.log(pc.cyan("━".repeat(40)));