gh-stack 0.10.0 → 0.11.0

package/README.md

@@ -163,11 +163,13 @@ merge [--dry-run] [-d|--delete-branch] [--collapse]
                 `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.
+    Cut a 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). The target stack is the one
+    containing <branch>, so this works from anywhere — not only while
+    standing on it. Purely a metadata operation — no git branches are
+    moved or rebased. Interactive selector (current stack) 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
@@ -189,9 +191,11 @@ rename [<old-name>] <new-name>
     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
+    Remove a branch from its stack and re-parent its children, then
     delete the underlying local git branch (and the remote branch if
-    it was pushed). Interactive selector if no branch specified.
+    it was pushed). The <branch> argument names its own stack, so this
+    works from anywhere. Interactive selector (current stack) if none
+    specified.
     --keep-branch leaves the git branches untouched (metadata only);
     --no-remote deletes the local branch but keeps the remote.
 ```
@@ -203,6 +207,11 @@ log
     Display the current stack as a tree with branch numbers,
     PR info, and descriptions. This is the default command.
 
+    If the current branch isn't tracked yet, log inspects its ancestry
+    and points at the next step: if it sits on top of an existing stack,
+    `gh-stack submit` to add it; if it's stacked on untracked branches,
+    submit to create the stack and open PRs; if it's on trunk, `init`.
+
 update-prs [--force]
     Refresh the "📚 Stacked on" visualization block in every PR
     description for the current stack. PRs whose rendered block is
@@ -299,7 +308,7 @@ per-stack files plus git-native branch config, rather than a single JSON blob:
 
 ```
 .git/.gh-stack/
-  current                      hint: last-active stack name
+  current                      derived stack of the current branch (self-heals on read)
   active/<stack>.json          topology of a live stack (ordered branches, base, description)
   archived/<stack>.json        merged/closed stacks
   deleted/<stack>.json         tombstones (recoverable)
@@ -337,8 +346,10 @@ 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 `current_stack` drift** — the stack you're on is derived from the branch
+  you've checked out (its own membership, or the nearest tracked ancestor for a
+  new branch stacked on top), re-resolved and self-healed on every read, so a
+  written pointer can never 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

package/package.json

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

package/src/commands/delete.ts

@@ -2,7 +2,12 @@
 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";
+import {
+  ensureMetadata,
+  ensureCurrentStack,
+  ensureValidStack,
+  resolveStackForBranchArg,
+} from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { selectBranch, confirmAction } from "../lib/ui.ts";
 import * as git from "../lib/git.ts";
@@ -34,7 +39,12 @@ OPTIONS
   const positional = args.filter((a) => !a.startsWith("-"));
 
   const meta = await ensureMetadata();
-  const stackName = ensureCurrentStack(meta);
+  // The branch to delete names its own stack — resolve from it so
+  // `delete <branch>` works from anywhere. Only fall back to the current stack
+  // (the branch you're on) in interactive mode, when no branch was given.
+  const stackName = positional[0]
+    ? resolveStackForBranchArg(meta, positional[0]!)
+    : ensureCurrentStack(meta);
   await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
   const currentBranch = await git.currentBranch();

package/src/commands/list.ts

@@ -25,24 +25,22 @@ ALIASES
   const meta = await ensureMetadata();
   const currentBranch = await git.currentBranch();
 
-  // Find which stack contains the current branch
-  const branchStackName = findStackForBranch(meta, currentBranch);
-  let stackName = branchStackName;
-  if (!stackName) stackName = meta.current_stack;
+  // The current stack is whichever stack the checked-out branch belongs to —
+  // never the persisted `current_stack` hint. If this branch is in no stack,
+  // there is no current stack; don't resurface a previously-used one.
+  const stackName = findStackForBranch(meta, currentBranch);
 
   if (!stackName || !meta.stacks[stackName]) {
-    console.log("No active stack found.");
+    console.log("Branch is not in any stack.");
     process.exit(1);
   }
 
   const stack = meta.stacks[stackName]!;
   const ordered = getOrderedBranches(stack);
 
-  // Update tracking
+  // We're on a branch in this stack — record it as current + its last_branch.
   meta.current_stack = stackName;
-  if (branchStackName === stackName) {
-    stack.last_branch = currentBranch;
-  }
+  stack.last_branch = currentBranch;
   await writeMetadata(meta);
 
   // Header

package/src/commands/log.ts

@@ -10,6 +10,8 @@ import {
 } from "../lib/metadata.ts";
 import { renderStackTree } from "../lib/ui.ts";
 import { gateLegacyMetadata } from "../lib/safety.ts";
+import { detectBranchChain } from "../lib/chain.ts";
+import type { StackMetadata } from "../types.ts";
 
 export default async function log(_args: string[]): Promise<void> {
   // Check if metadata exists
@@ -30,33 +32,21 @@ export default async function log(_args: string[]): Promise<void> {
 
   const branch = await git.currentBranch();
 
-  // Find which stack contains the current branch
-  const branchStackName = findStackForBranch(meta, branch);
-  let stackName = branchStackName;
-
-  if (!stackName) {
-    // Fall back to current_stack
-    stackName = meta.current_stack;
-  }
+  // The current stack is whichever stack the checked-out branch belongs to —
+  // never the persisted `current_stack` hint. If this branch is in no stack,
+  // there is no current stack; don't resurface a previously-used one.
+  const stackName = findStackForBranch(meta, branch);
 
   if (!stackName || !meta.stacks[stackName]) {
-    p.log.warn(`Branch ${pc.blue(branch)} is not in any stack`);
-    console.log();
-    console.log(`  Add it to a stack with:`);
-    console.log(`    ${pc.green("gh-stack add")}`);
-    console.log();
-    console.log(`  Or create a new stack:`);
-    console.log(`    ${pc.green("gh-stack init")}`);
+    await suggestNextStep(meta, branch);
     process.exit(1);
   }
 
   const stack = meta.stacks[stackName]!;
 
-  // Update current_stack and last_branch
+  // We're on a branch in this stack — record it as current + its last_branch.
   meta.current_stack = stackName;
-  if (branchStackName === stackName) {
-    stack.last_branch = branch;
-  }
+  stack.last_branch = branch;
   await writeMetadata(meta);
 
   // Header
@@ -76,3 +66,93 @@ export default async function log(_args: string[]): Promise<void> {
   console.log(pc.dim(`Tip: Switch stacks with 'gh-stack checkout --stack'`));
   console.log();
 }
+
+/**
+ * The current branch isn't a tracked stack member. Inspect its local ancestry —
+ * the same chain `submit` would self-heal — and point at the lowest-friction
+ * next step:
+ *   - sits on top of an existing stack  → `submit` to ADD it to that stack;
+ *   - stacked on untracked branches only → `submit` to CREATE a new stack;
+ *   - based directly on trunk            → `submit` to push + open a PR;
+ *   - on trunk                           → `init`.
+ */
+async function suggestNextStep(meta: StackMetadata, branch: string): Promise<void> {
+  const trunk = await git.trunkBranch();
+
+  if (branch === trunk || branch === "main" || branch === "master") {
+    p.log.warn(`You're on ${pc.blue(branch)} — not a stack branch`);
+    console.log();
+    console.log(`  Checkout a feature branch, then start a stack with:`);
+    console.log(`    ${pc.green("gh-stack init")}`);
+    console.log();
+    return;
+  }
+
+  // Reconstruct trunk→current the way `submit` does (local branches whose tips
+  // are ancestors of HEAD). [current] alone means it's based right off trunk.
+  let chain: string[] = [branch];
+  try {
+    chain = await detectBranchChain(branch, trunk);
+  } catch {
+    // Fall back to treating it as a single branch off trunk.
+  }
+
+  // Is this chain sitting on top of an existing tracked stack? Find the nearest
+  // ancestor in the chain that's already a stack member.
+  let attachStack: string | null = null;
+  for (let i = chain.length - 2; i >= 0; i--) {
+    const owner = findStackForBranch(meta, chain[i]!);
+    if (owner) {
+      attachStack = owner;
+      break;
+    }
+  }
+
+  p.log.warn(`Branch ${pc.blue(branch)} isn't tracked in a stack yet`);
+  console.log();
+
+  if (attachStack) {
+    // Extends an existing stack — submit ADDS the untracked tail to it.
+    console.log(`  It sits on top of stack ${pc.yellow(attachStack)}:`);
+    console.log();
+    console.log(`  ${pc.dim(trunk)}`);
+    for (let i = 0; i < chain.length; i++) {
+      const b = chain[i]!;
+      const isLast = i === chain.length - 1;
+      const tree = isLast ? "  ┗━" : "  ┣━";
+      const label = b === branch ? pc.yellow(b) + pc.dim(" (current)") : b;
+      const tag = findStackForBranch(meta, b) ? pc.dim(" (in stack)") : pc.green(" +");
+      console.log(`${tree} ${label}${tag}`);
+      if (!isLast) console.log("  ┃");
+    }
+    console.log();
+    console.log(`  Add it to the stack:`);
+    console.log(`    ${pc.green("gh-stack submit")}`);
+    console.log();
+    return;
+  }
+
+  if (chain.length > 1) {
+    // Stacked on untracked branches only — submit CREATES a new stack.
+    console.log(`  It's stacked on ${chain.length - 1} other local branch(es):`);
+    console.log();
+    console.log(`  ${pc.dim(trunk)}`);
+    for (let i = 0; i < chain.length; i++) {
+      const b = chain[i]!;
+      const isLast = i === chain.length - 1;
+      const tree = isLast ? "  ┗━" : "  ┣━";
+      const label = b === branch ? pc.yellow(b) + pc.dim(" (current)") : b;
+      console.log(`${tree} ${label}`);
+      if (!isLast) console.log("  ┃");
+    }
+    console.log();
+    console.log(`  Create the stack and open PRs for the whole chain:`);
+  } else {
+    // A single branch based directly on trunk.
+    console.log(`  It's based directly on ${pc.dim(trunk)}.`);
+    console.log();
+    console.log(`  Push it and open a PR — this also starts the stack:`);
+  }
+  console.log(`    ${pc.green("gh-stack submit")}`);
+  console.log();
+}

package/src/commands/merge.ts

@@ -513,8 +513,10 @@ OPTIONS
   meta.archive[stackName] = { ...stack };
   delete meta.stacks[stackName];
   if (meta.current_stack === stackName) {
-    const remaining = Object.keys(meta.stacks);
-    meta.current_stack = remaining.length > 0 ? remaining[0]! : null;
+    // Don't auto-pick a random leftover stack as "current" — that switches you
+    // to a stack you never checked out. The current stack is derived from the
+    // branch you're on; after a merge you're on main, so default to none.
+    meta.current_stack = null;
   }
   await writeMetadata(meta);
 

package/src/commands/split.ts

@@ -12,7 +12,12 @@
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { buildRebaseChain, getOrderedBranches, stackBase, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";
+import {
+  ensureMetadata,
+  ensureCurrentStack,
+  ensureValidStack,
+  resolveStackForBranchArg,
+} from "../lib/safety.ts";
 import { selectBranch, confirmAction } from "../lib/ui.ts";
 import * as git from "../lib/git.ts";
 import type { Stack } from "../types.ts";
@@ -55,7 +60,12 @@ export default async function split(args: string[]): Promise<void> {
   const positional = args.filter((a) => !a.startsWith("-"));
 
   const meta = await ensureMetadata();
-  const stackName = ensureCurrentStack(meta);
+  // The cut branch names its own stack — resolve from it so `split <branch>`
+  // works from anywhere. Only fall back to the current stack (the branch you're
+  // on) in interactive mode, when no branch was given.
+  const stackName = positional[0]
+    ? resolveStackForBranchArg(meta, positional[0]!)
+    : ensureCurrentStack(meta);
   await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
   const currentBranch = await git.currentBranch();

package/src/commands/stacks.ts

@@ -11,7 +11,6 @@ import {
   metadataExists,
   legacyMetadataExists,
   getOrderedBranches,
-  findStackForBranch,
   stackBase,
 } from "../lib/metadata.ts";
 
@@ -72,7 +71,10 @@ metadata. Use --json as a stable interface so scripts don't parse the
     // Detached HEAD or not on a branch — fine, just no "current" context.
   }
 
-  const currentStackName = currentBranch ? findStackForBranch(meta, currentBranch) : null;
+  // readMetadata already resolved the current stack authoritatively: the
+  // branch's own stack, or — for a new branch built on top of one — the nearest
+  // tracked ancestor's stack, or null. Trust it rather than re-deriving.
+  const currentStackName = meta.current_stack;
 
   const entries = Object.entries(meta.stacks)
     .filter(([name]) => !currentOnly || name === currentStackName)
@@ -99,7 +101,7 @@ metadata. Use --json as a stable interface so scripts don't parse the
     console.log(
       JSON.stringify(
         {
-          current_stack: currentStackName ?? meta.current_stack ?? null,
+          current_stack: currentStackName,
           current_branch: currentBranch,
           stacks: entries,
         },

package/src/lib/metadata.ts

@@ -31,6 +31,7 @@ import {
   type BranchMembership,
 } from "./branch-config.ts";
 import { loadSnapshots } from "./snapshot.ts";
+import * as git from "./git.ts";
 
 async function pathExists(p: string): Promise<boolean> {
   try {
@@ -136,9 +137,91 @@ export async function readMetadata(): Promise<StackMetadata | null> {
   // (which also repoints renamed branches' child config). Keeping reads
   // side-effect-free avoids surprising writes from `status`/`--dry-run`.
   await reconcileRenames(meta);
+  // The current stack is *derived* from the branch you're on, never trusted
+  // from the stored hint. Every read re-verifies it (and corrects the on-disk
+  // pointer) so no command can act on a stack you've already left.
+  await reconcileCurrentStack(meta);
   return meta;
 }
 
+/**
+ * Resolve and pin `meta.current_stack` to whichever active stack owns the
+ * checked-out branch — the single source of truth for "what stack am I on."
+ *
+ * Resolution, mirroring the on-disk authority order:
+ *   1. The branch's git config (`branch.<name>.ghstack-stack`) — rename-proof
+ *      membership — *if* the named stack is active and still lists the branch.
+ *   2. Otherwise scan the assembled active stacks for the branch by name.
+ *   3. Otherwise walk up the branch's ancestry: a new branch built on top of a
+ *      stack belongs to that stack (until submitted), so the nearest *tracked*
+ *      ancestor's stack is the current one. Only tracked branches are probed,
+ *      so this stays cheap even with many local branches.
+ *   4. Otherwise (ancestry reaches trunk with nothing tracked, or HEAD
+ *      detached) there is no current stack → null.
+ *
+ * The resolved value is also written back to the `current` pointer file when it
+ * drifts, so a stale hint left by a prior session, a merge, or a plain
+ * `git checkout` self-heals on the very next command. Only the pointer file is
+ * touched — stack topology, refs, and snapshots are never written here, so this
+ * stays safe for read-only / `--dry-run` commands.
+ */
+async function reconcileCurrentStack(meta: StackMetadata): Promise<void> {
+  let branch: string | null = null;
+  try {
+    branch = await git.currentBranch();
+  } catch {
+    // Detached HEAD / not on a branch → no current stack.
+  }
+
+  let resolved: string | null = null;
+  if (branch) {
+    // 1. Trust branch config only if the topology still backs it up.
+    const config = await allBranchMemberships();
+    const configStack = config.get(branch)?.stack;
+    if (configStack && meta.stacks[configStack]?.branches[branch]) {
+      resolved = configStack;
+    } else {
+      // 2. Fall back to scanning the active stacks for direct membership.
+      resolved = findStackForBranch(meta, branch);
+    }
+    // 3. Untracked branch — inherit the stack of its nearest tracked ancestor.
+    if (!resolved) {
+      resolved = await nearestTrackedAncestorStack(meta, branch);
+    }
+  }
+
+  if (meta.current_stack !== resolved) {
+    meta.current_stack = resolved;
+    await Bun.write(await currentFile(), (resolved ?? "") + "\n");
+  }
+}
+
+/**
+ * Walk up `branch`'s ancestry and return the stack of the nearest branch that's
+ * already a tracked member of an active stack — i.e. the stack this branch sits
+ * on top of. Probes only tracked branches (small N), picking the closest one by
+ * commit distance, so a chain that spans two stacks resolves to the nearer one.
+ * Returns null when no tracked branch is an ancestor (the branch traces back to
+ * trunk without crossing a stack).
+ */
+export async function nearestTrackedAncestorStack(
+  meta: StackMetadata,
+  branch: string,
+): Promise<string | null> {
+  let best: { stack: string; distance: number } | null = null;
+  for (const [stackName, stack] of Object.entries(meta.stacks)) {
+    for (const member of Object.keys(stack.branches)) {
+      if (member === branch) continue;
+      if (!(await git.isAncestor(member, branch))) continue;
+      const distance = await git.commitCount(member, branch);
+      if (distance > 0 && (!best || distance < best.distance)) {
+        best = { stack: stackName, distance };
+      }
+    }
+  }
+  return best?.stack ?? null;
+}
+
 /**
  * The ref a stack is rooted on. Defaults to "main" for stacks created before
  * the `base` field existed.

package/src/lib/safety.ts

@@ -71,6 +71,23 @@ export function ensureCurrentStack(meta: StackMetadata): string {
   return stack;
 }
 
+/**
+ * Resolve the stack to operate on from a branch argument. The branch names its
+ * own stack unambiguously, so commands that take a branch (split, delete) use
+ * this instead of trusting the current stack — letting `<cmd> <branch>` work
+ * from anywhere, not only while standing on that stack.
+ */
+export function resolveStackForBranchArg(meta: StackMetadata, branch: string): string {
+  const stackName = findStackForBranch(meta, branch);
+  if (!stackName) {
+    p.cancel(
+      `Branch ${pc.yellow(branch)} is not in any stack.\n\n  See your stacks with:\n    ${pc.green("gh-stack stacks")}`,
+    );
+    process.exit(1);
+  }
+  return stackName;
+}
+
 /**
  * Ensure current branch is in a stack. Returns the stack name.
  */