gh-stack 0.7.0 → 0.9.0

package/src/lib/branch-config.ts

@@ -0,0 +1,126 @@
+// Git-native branch membership index.
+//
+// Each branch records which stack it belongs to (plus its parent and PR) in
+// git's own config under the `branch.<name>` section:
+//
+//   branch.<name>.ghstack-stack   <stack>
+//   branch.<name>.ghstack-parent  <parent-branch>
+//   branch.<name>.ghstack-pr      <number>
+//
+// Why config and not JSON: git maintains the `branch.<name>` section for us.
+//   • `git branch -m old new`  → the section moves      → rename tracking free
+//   • `git branch -D name`     → the section is deleted  → no orphaned membership
+//
+// So this is a self-cleaning, rename-safe index that runs alongside the
+// `.gh-stack/` topology files and lets `doctor` cross-check the two. We use
+// dash-separated, all-lowercase variable names on purpose: git only permits
+// alphanumerics and `-` in config keys (underscores are rejected outright),
+// and it lowercases the variable portion on read — so `ghstack-stack` round
+// -trips exactly while a camelCase key would read back mangled.
+import { $ } from "bun";
+
+export interface BranchMembership {
+  stack?: string;
+  parent?: string;
+  pr?: number;
+}
+
+const KEY_PREFIX = "ghstack-";
+const STACK_KEY = "ghstack-stack";
+const PARENT_KEY = "ghstack-parent";
+const PR_KEY = "ghstack-pr";
+
+function configKey(branch: string, key: string): string {
+  return `branch.${branch}.${key}`;
+}
+
+/**
+ * Set (or clear) the membership config for a single branch. Any field left
+ * undefined is removed, so callers can pass a full desired state and trust the
+ * branch ends up matching it exactly.
+ */
+export async function setBranchMembership(
+  branch: string,
+  membership: BranchMembership,
+): Promise<void> {
+  await setOrUnset(branch, STACK_KEY, membership.stack);
+  await setOrUnset(branch, PARENT_KEY, membership.parent);
+  await setOrUnset(branch, PR_KEY, membership.pr != null ? String(membership.pr) : undefined);
+}
+
+async function setOrUnset(branch: string, key: string, value: string | undefined): Promise<void> {
+  if (value === undefined || value === "") {
+    await unsetKey(branch, key);
+    return;
+  }
+  await $`git config ${configKey(branch, key)} ${value}`.quiet().nothrow();
+}
+
+async function unsetKey(branch: string, key: string): Promise<void> {
+  // `--unset` exits 5 when the key is already absent — harmless, so nothrow.
+  await $`git config --unset ${configKey(branch, key)}`.quiet().nothrow();
+}
+
+/**
+ * Read one branch's membership. Returns an empty object if the branch has no
+ * gh-stack config.
+ */
+export async function getBranchMembership(branch: string): Promise<BranchMembership> {
+  const all = await allBranchMemberships();
+  return all.get(branch) ?? {};
+}
+
+/**
+ * Remove all gh-stack membership keys from a branch (leaves the branch and its
+ * other config untouched).
+ */
+export async function clearBranchMembership(branch: string): Promise<void> {
+  await unsetKey(branch, STACK_KEY);
+  await unsetKey(branch, PARENT_KEY);
+  await unsetKey(branch, PR_KEY);
+}
+
+/**
+ * Read every branch's gh-stack membership in one shot, keyed by branch name.
+ *
+ * Branch names may legally contain dots (`feat.x`), so we can't naively split
+ * the config key on `.`. We anchor on the known `.ghstack-<field>` suffix and
+ * treat everything between `branch.` and that suffix as the branch name.
+ */
+export async function allBranchMemberships(): Promise<Map<string, BranchMembership>> {
+  const out = new Map<string, BranchMembership>();
+
+  const { stdout, exitCode } = await $`git config --get-regexp ${"^branch\\..*\\.ghstack-"}`
+    .quiet()
+    .nothrow();
+  // exit 1 simply means no matching keys — an empty repo, not an error.
+  if (exitCode !== 0) return out;
+
+  const text = stdout.toString().trim();
+  if (!text) return out;
+
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(" ");
+    if (sep === -1) continue;
+    const fullKey = line.slice(0, sep);
+    const value = line.slice(sep + 1);
+
+    // fullKey looks like: branch.<name>.ghstack-<field>
+    if (!fullKey.startsWith("branch.")) continue;
+    const dotField = fullKey.lastIndexOf(`.${KEY_PREFIX}`);
+    if (dotField === -1) continue;
+    const branch = fullKey.slice("branch.".length, dotField);
+    const field = fullKey.slice(dotField + 1); // ghstack-<field>
+
+    const m = out.get(branch) ?? {};
+    if (field === STACK_KEY) m.stack = value;
+    else if (field === PARENT_KEY) m.parent = value;
+    else if (field === PR_KEY) {
+      const n = Number(value);
+      if (Number.isFinite(n)) m.pr = n;
+    }
+    out.set(branch, m);
+  }
+
+  return out;
+}

package/src/lib/chain.ts

@@ -4,7 +4,7 @@
 // auto-create/register a stack from a bare set of local branches so the
 // end state is always stack registered + branches pushed + PRs created).
 import * as git from "./git.ts";
-import { findStackForBranch } from "./metadata.ts";
+import { findStackForBranch, getOrderedBranches, stackBase } from "./metadata.ts";
 import type { StackMetadata, Branch } from "../types.ts";
 
 /**
@@ -55,7 +55,8 @@ export async function detectBranchChain(currentBranch: string, trunk: string): P
 
 export interface StackResolution {
   stackName: string;
-  chain: string[]; // trunk→current order
+  base: string; // effective base of the resulting stack (for display)
+  chain: string[]; // resulting stack's branches, base→tip (for display)
   created: boolean; // true if a brand-new stack was created
   addedBranches: string[]; // branches newly registered into the stack
 }
@@ -67,74 +68,106 @@ export interface StackResolution {
  * effects).
  *
  * Behavior:
- *   - Detects the chain trunk→current.
- *   - If any branch in the chain already belongs to a stack, reconciles
- *     into that existing stack (adds only the missing branches).
- *   - Otherwise creates a new stack named after the current branch
- *     (auto-suffixed if that name is taken).
- *   - Registers missing branches with correct parent links (chain[0]'s
- *     parent is trunk; each subsequent branch's parent is the prior one).
+ *   - Detects the ancestry chain trunk→current.
+ *   - Finds the NEAREST tracked ancestor of `branch`. If one exists, adopts
+ *     the untracked tail above it into that ancestor's stack — stopping at
+ *     that stack's boundary. This is what lets a stack with a non-main base
+ *     (one stacked on top of another stack) keep accepting new branches: the
+ *     walk never crosses into the parent stack, so it can't mistake a clean
+ *     stacked-on-a-stack layout for an ambiguous multi-stack chain. (#11)
+ *   - Otherwise creates a new stack rooted at `trunk`, named after the current
+ *     branch (auto-suffixed if that name is taken). (#7)
  *
- * Throws if the chain spans more than one existing stack (ambiguous).
+ * Throws only if the untracked tail genuinely interleaves another stack's
+ * branches — which a clean stacked-on-a-stack layout never does.
  */
 export async function resolveOrCreateStack(
   meta: StackMetadata,
   branch: string,
   trunk: string,
 ): Promise<StackResolution> {
-  const chain = await detectBranchChain(branch, trunk);
-
-  // Which existing stacks (if any) already own branches in this chain?
-  const owningStacks = new Set<string>();
-  for (const b of chain) {
-    const owner = findStackForBranch(meta, b);
-    if (owner) owningStacks.add(owner);
+  const fullChain = await detectBranchChain(branch, trunk); // trunk→current
+
+  // Walk from just below `branch` downward; the first tracked ancestor is the
+  // attachment point. Everything above it (up to `branch`) is the untracked
+  // tail we adopt — by definition not tracked, since this is the *nearest*
+  // tracked ancestor.
+  let anchorIndex = -1;
+  let anchorStack: string | null = null;
+  for (let i = fullChain.length - 2; i >= 0; i--) {
+    const owner = findStackForBranch(meta, fullChain[i]!);
+    if (owner) {
+      anchorIndex = i;
+      anchorStack = owner;
+      break;
+    }
   }
 
-  if (owningStacks.size > 1) {
-    throw new Error(
-      `Branches in this chain span multiple stacks (${[...owningStacks].join(
-        ", ",
-      )}). Resolve manually with gh-stack init / delete.`,
-    );
-  }
+  if (anchorStack) {
+    const stack = meta.stacks[anchorStack]!;
+    const tail = fullChain.slice(anchorIndex); // [anchor, ...untracked..., current]
+    const addedBranches: string[] = [];
+
+    for (let i = 1; i < tail.length; i++) {
+      const name = tail[i]!;
+      const parent = tail[i - 1]!;
+
+      // Safety net: a clean stacked-on-a-stack layout never trips this, but if
+      // the tail somehow already belongs to a different stack, it's genuinely
+      // ambiguous — refuse rather than silently move branches between stacks.
+      const existingOwner = findStackForBranch(meta, name);
+      if (existingOwner && existingOwner !== anchorStack) {
+        throw new Error(
+          `Branches in this chain span multiple stacks (${anchorStack}, ${existingOwner}). Resolve manually with gh-stack init / delete.`,
+        );
+      }
 
-  let stackName: string;
-  let created = false;
-
-  if (owningStacks.size === 1) {
-    // Reconcile into the existing stack
-    stackName = [...owningStacks][0]!;
-  } else {
-    // Create a new stack named after the current branch (auto-suffix on clash)
-    stackName = branch;
-    let n = 2;
-    while (meta.stacks[stackName]) {
-      stackName = `${branch}-${n++}`;
+      if (stack.branches[name]) continue; // already tracked — leave as-is
+      stack.branches[name] = { parent };
+      stack.last_branch = name;
+      addedBranches.push(name);
     }
-    meta.stacks[stackName] = {
-      description: "",
-      last_branch: null,
-      branches: {},
+
+    return {
+      stackName: anchorStack,
+      base: stackBase(stack),
+      chain: getOrderedBranches(stack),
+      created: false,
+      addedBranches,
     };
-    meta.current_stack = stackName;
-    created = true;
   }
 
+  // No tracked ancestor — create a new stack rooted at trunk.
+  let stackName = branch;
+  let n = 2;
+  while (meta.stacks[stackName]) {
+    stackName = `${branch}-${n++}`;
+  }
+  meta.stacks[stackName] = {
+    description: "",
+    last_branch: null,
+    branches: {},
+    base: trunk,
+  };
+  meta.current_stack = stackName;
+
   const stack = meta.stacks[stackName]!;
   const addedBranches: string[] = [];
-
-  // Register missing branches with correct parent links.
-  for (let i = 0; i < chain.length; i++) {
-    const name = chain[i]!;
-    if (stack.branches[name]) continue; // already tracked — leave as-is
-
-    const parent = i === 0 ? trunk : chain[i - 1]!;
+  for (let i = 0; i < fullChain.length; i++) {
+    const name = fullChain[i]!;
+    if (stack.branches[name]) continue;
+    const parent = i === 0 ? trunk : fullChain[i - 1]!;
     const branchData: Branch = { parent };
     stack.branches[name] = branchData;
     stack.last_branch = name;
     addedBranches.push(name);
   }
 
-  return { stackName, chain, created, addedBranches };
+  return {
+    stackName,
+    base: trunk,
+    chain: getOrderedBranches(stack),
+    created: true,
+    addedBranches,
+  };
 }

package/src/lib/git.ts

@@ -138,6 +138,17 @@ export async function forcePushWithLease(branch?: string): Promise<boolean> {
   }
 }
 
+/**
+ * Push a stacked branch's ref to origin, setting upstream and using
+ * force-with-lease. Works whether or not the remote branch already exists
+ * (creates it on first push) — so restack can reconcile every ref, including
+ * a branch that was never pushed before.
+ */
+export async function pushStackedBranch(branch: string): Promise<boolean> {
+  const { exitCode } = await $`git push -u --force-with-lease origin ${branch}`.nothrow().quiet();
+  return exitCode === 0;
+}
+
 /**
  * Check if a branch exists on the remote.
  */
@@ -158,6 +169,24 @@ export async function localBranchExists(branch: string): Promise<boolean> {
   return exitCode === 0;
 }
 
+/**
+ * Delete a local branch. Uses -D (force) since stacked branches are
+ * routinely rebased and won't appear "merged" to git. Returns false if
+ * the branch didn't exist or the delete failed.
+ */
+export async function deleteLocalBranch(branch: string): Promise<boolean> {
+  const { exitCode } = await $`git branch -D ${branch}`.nothrow().quiet();
+  return exitCode === 0;
+}
+
+/**
+ * Delete a branch on the remote (origin). Returns false on failure.
+ */
+export async function deleteRemoteBranch(branch: string): Promise<boolean> {
+  const { exitCode } = await $`git push origin --delete ${branch}`.nothrow().quiet();
+  return exitCode === 0;
+}
+
 /**
  * Create a temporary tag at a specific commit.
  */

package/src/lib/github.ts

@@ -2,6 +2,30 @@
 import { $ } from "bun";
 import type { PrInfo, PrStatus } from "../types.ts";
 
+let cachedNwo: string | null | undefined; // undefined = not yet looked up
+
+/**
+ * Get the repository's `owner/name` (once, cached for the process). Used to
+ * construct PR URLs locally — `https://github.com/<nwo>/pull/<n>` — so the
+ * stack visualization doesn't need a per-PR API call just for links.
+ * Returns null if it can't be resolved (links degrade to plain `#<n>`).
+ */
+export async function getRepoNwo(): Promise<string | null> {
+  if (cachedNwo !== undefined) return cachedNwo;
+  try {
+    const out = (await $`gh repo view --json nameWithOwner --jq .nameWithOwner`.text()).trim();
+    cachedNwo = out.length > 0 ? out : null;
+  } catch {
+    cachedNwo = null;
+  }
+  return cachedNwo;
+}
+
+/** Build a PR URL from a cached nwo (or null if nwo is unknown). */
+export function prUrlFor(nwo: string | null, prNumber: number): string | null {
+  return nwo ? `https://github.com/${nwo}/pull/${prNumber}` : null;
+}
+
 /**
  * Get PR number for a branch (auto-detect via gh).
  * Returns null if no PR exists.