gh-stack 0.15.0 → 0.17.0

package/src/index.ts

@@ -46,8 +46,12 @@ if (parsed.plain) {
   setPlain(true);
 }
 
-// Ensure we're in a git repo for all commands
-await ensureGitRepo();
+// Ensure we're in a git repo for all commands — except `learn`, which just
+// emits/installs the agent skill and is useful outside any repo (e.g. an agent
+// onboarding before cloning, or `learn --skill --global`).
+if (command !== "learn") {
+  await ensureGitRepo();
+}
 
 // Route to subcommand — strip global flags from command args
 const commandArgs = parsed.commandArgs;
@@ -65,6 +69,10 @@ switch (command) {
     await (await import("./commands/create.ts")).default(commandArgs);
     break;
 
+  case "add":
+    await (await import("./commands/add.ts")).default(commandArgs);
+    break;
+
   case "delete":
     await (await import("./commands/delete.ts")).default(commandArgs);
     break;
@@ -143,6 +151,10 @@ switch (command) {
     await (await import("./commands/bottom.ts")).default(commandArgs);
     break;
 
+  case "learn":
+    await (await import("./commands/learn.ts")).default(commandArgs);
+    break;
+
   case "--help":
   case "help":
     printHelp();
@@ -170,6 +182,7 @@ ${bold("TERMS")}
 ${bold("CORE WORKFLOW")}
   ${green("init")}           Create a new stack from the current branch
   ${green("create")}         Create a new branch and add to the stack
+  ${green("add")}            Track the current local branch in a stack ${dim("(no push/PR)")}
   ${green("submit")}         Push branches and create/update PRs
   ${green("log")}            Display current stack tree ${dim("(default)")}
 
@@ -196,6 +209,7 @@ ${bold("INFO & MAINTENANCE")}
   ${green("archive")}        Manage archived stacks
   ${green("update-prs")}     Refresh stack visualization in PR descriptions
   ${green("doctor")}         Migrate & repair stack metadata
+  ${green("learn")}          Print the agent skill (--skill installs it)
 
 ${bold("GLOBAL OPTIONS")}
   --yes, -y        Skip confirmations ${dim("(for agents/CI)")}

package/src/lib/git.ts

@@ -38,6 +38,14 @@ export async function gitDir(): Promise<string> {
   return result.trim();
 }
 
+/**
+ * Get the absolute path to the repository's working-tree root.
+ */
+export async function repoRoot(): Promise<string> {
+  const result = await $`git rev-parse --show-toplevel`.text();
+  return result.trim();
+}
+
 /**
  * Check if working tree is clean (no uncommitted changes).
  * Refreshes the index first to avoid false positives from stale stat info.
@@ -78,12 +86,25 @@ export async function isRebaseInProgress(): Promise<boolean> {
 }
 
 /**
- * Checkout a branch.
+ * Checkout a branch. Throws a raw ShellError on failure — only use this where a
+ * failure is unexpected (e.g. after ensureCleanWorkingTree). For user-facing
+ * branch switching, prefer tryCheckout so a dirty-tree refusal can be rendered
+ * as a clean message instead of a stack trace.
  */
 export async function checkout(branch: string): Promise<void> {
   await $`git checkout ${branch}`.quiet();
 }
 
+/**
+ * Attempt to checkout a branch without throwing. Returns whether it succeeded
+ * and git's stderr (which carries the "local changes would be overwritten"
+ * message and the offending file list when a dirty tree blocks the switch).
+ */
+export async function tryCheckout(branch: string): Promise<{ ok: boolean; stderr: string }> {
+  const { exitCode, stderr } = await $`git checkout ${branch}`.quiet().nothrow();
+  return { ok: exitCode === 0, stderr: stderr.toString() };
+}
+
 /**
  * Create and checkout a new branch from the current HEAD.
  */
@@ -149,6 +170,29 @@ export async function pushStackedBranch(branch: string): Promise<boolean> {
   return exitCode === 0;
 }
 
+/**
+ * Read the actual tip sha of every branch on origin in a single `ls-remote`
+ * call. This queries the remote directly, so it is **authoritative** — unlike
+ * `rev-parse origin/<branch>`, which reads the local remote-tracking ref that a
+ * force-push can leave stale (a fresh fetch would correct it). Use this when a
+ * correct answer about the remote's real state matters (e.g. the post-restack
+ * sync verification — #23). Returns a map of branch name → sha.
+ */
+export async function remoteHeads(): Promise<Map<string, string>> {
+  const heads = new Map<string, string>();
+  const { exitCode, stdout } = await $`git ls-remote --heads origin`.nothrow().quiet();
+  if (exitCode !== 0) return heads;
+  const prefix = "refs/heads/";
+  for (const line of stdout.toString().split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab === -1) continue;
+    const sha = line.slice(0, tab).trim();
+    const ref = line.slice(tab + 1).trim();
+    if (sha && ref.startsWith(prefix)) heads.set(ref.slice(prefix.length), sha);
+  }
+  return heads;
+}
+
 /**
  * Check if a branch exists on the remote.
  */

package/src/lib/md.d.ts

@@ -0,0 +1,7 @@
+// Bun bundles `*.md` files imported with `{ type: "text" }` into the binary as
+// their raw string contents (survives `bun build --compile`). This declaration
+// lets TypeScript type those imports.
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/lib/safety.ts

@@ -115,6 +115,37 @@ export async function ensureCleanWorkingTree(): Promise<void> {
   }
 }
 
+/**
+ * Switch branches for a user-facing navigation command, rendering a clean
+ * message (and exiting 1) when git refuses — most commonly because local
+ * changes would be overwritten. Avoids leaking a raw ShellError stack trace.
+ *
+ * Note: this deliberately does NOT pre-check for a clean tree. git happily
+ * carries uncommitted changes across a switch when they don't conflict with the
+ * target branch, and stack navigation often wants to bring WIP along — so we
+ * let git decide and only intervene on an actual refusal.
+ */
+export async function checkoutOrExit(branch: string): Promise<void> {
+  const { ok, stderr } = await git.tryCheckout(branch);
+  if (ok) return;
+
+  if (stderr.includes("would be overwritten by checkout")) {
+    const files = stderr
+      .split("\n")
+      .filter((line) => line.startsWith("\t"))
+      .map((line) => `    ${pc.yellow(line.trim())}`)
+      .join("\n");
+    p.cancel(
+      `Can't switch to ${pc.yellow(branch)} — local changes would be overwritten:\n\n${files}\n\n  Commit or stash them first:\n    ${pc.green("git stash")} ${pc.dim("(or git commit)")}`,
+    );
+  } else {
+    p.cancel(
+      `Can't switch to ${pc.yellow(branch)}:\n\n  ${stderr.trim() || "git checkout failed"}`,
+    );
+  }
+  process.exit(1);
+}
+
 /**
  * Ensure we're not on main.
  */

package/src/lib/skill.ts

@@ -0,0 +1,22 @@
+// Canonical, version-stamped agent skill for gh-stack.
+//
+// The skill text is a plain Markdown file — `using-gh-stack.md` — bundled into
+// the binary at build time via Bun's `type: "text"` import (it survives
+// `bun build --compile`). Editing the skill means editing that .md file; this
+// module only stamps the running version into the `{{VERSION}}` placeholder.
+//
+// It is the SINGLE SOURCE OF TRUTH for "how an agent should drive gh-stack":
+// `gh-stack learn` prints it, `gh-stack learn --skill` installs it. Update the
+// .md whenever a command or flag changes and the next release ships it.
+import skillTemplate from "./using-gh-stack.md" with { type: "text" };
+
+export const SKILL_NAME = "using-gh-stack";
+
+/**
+ * Build the full skill document, stamped with the running gh-stack version so
+ * an installed copy always records which release generated it (and can be
+ * refreshed with `gh-stack learn --skill`).
+ */
+export function skillContent(version: string): string {
+  return skillTemplate.replaceAll("{{VERSION}}", version);
+}

package/src/lib/using-gh-stack.md

@@ -0,0 +1,260 @@
+---
+name: using-gh-stack
+description: "MUST be used when working with stacked PRs. gh-stack is a CLI tool for managing stacked PR workflows in squash-merge repos (a Graphite alternative). Covers creating stacks, pushing/creating PRs with submit, navigating (up/down/top/bottom), syncing with main, restacking, merging, and agent/CI usage. Triggers on: stacked PR, gh-stack, create stack, submit stack, push stack, restack, sync stack, stack navigation, up down top bottom, PR dependencies, stack visualization, manage PRs, stacked branches."
+---
+
+# Using gh-stack
+
+> Generated by `gh-stack learn` from **gh-stack v{{VERSION}}**.
+> This file is produced by the binary — don't hand-edit it. Refresh after
+> upgrading with `gh-stack learn --skill`.
+
+`gh-stack` is a CLI for managing **stacked PRs** in squash-merge repositories
+(a Graphite/`gt` alternative). A _stack_ is a chain of dependent branches, each
+its own PR, sitting on top of the trunk (usually `main`).
+
+**Install:** `npm install -g gh-stack` (or `bun install -g gh-stack`)
+
+## Terms
+
+| Term          | Meaning                              |
+| ------------- | ------------------------------------ |
+| **trunk**     | Base branch (usually `main`)         |
+| **stack**     | A chain of dependent branches        |
+| **upstack**   | Child branches (depend on current)   |
+| **downstack** | Parent branches (current depends on) |
+
+## The current stack follows your current branch
+
+There is no "switch stack" state to manage — **gh-stack always operates on the
+stack that contains the branch you're on.** It resolves this from your current
+git branch: the branch's own stack, or (for a new branch built on top of one)
+the nearest tracked ancestor's stack. Every command (`log`, `submit`, `status`,
+`restack`, …) acts on that stack automatically.
+
+So to switch stacks, just switch branches — there's nothing gh-stack-specific to
+run:
+
+```bash
+git switch other-feature-branch   # any branch on the other stack
+gh-stack log                       # now shows that stack
+```
+
+Or use the interactive picker when you don't remember the branch names:
+
+```bash
+gh-stack checkout --stack          # pick a stack, jump to it (alias: co --stack)
+```
+
+(Plain `gh-stack checkout` picks a _branch within the current stack_; add
+`--stack` to pick a _different stack_.)
+
+## Agent/CI mode — read this first
+
+Run non-interactively with `--yes`/`-y` or `GH_STACK_YES=1` (also enables
+`--plain`: no spinners/colors/box-drawing — clean for log capture).
+
+```bash
+export GH_STACK_YES=1     # skip every confirmation, plain output
+```
+
+- **Discover topology without parsing internals:** `gh-stack stacks --json`
+  (network-free) or `gh-stack status --json` (adds PR/CI/review state).
+- **Always pass `-t`/`-b` to `submit`** so PRs get real titles/bodies instead
+  of generic auto-generated ones (see below).
+- Commands that rebase (`restack`, `sync`, `merge`) **refuse to run on a dirty
+  tree** — commit or stash first.
+
+## Core workflow
+
+### 1. Start a stack
+
+**From existing branches** (e.g. `main → feat-1 → feat-2`) — go to the TOP;
+`init` walks down and reconstructs the chain automatically:
+
+```bash
+git checkout feat-2
+gh-stack init            # detects main → feat-1 → feat-2, adopts existing PRs
+```
+
+**From scratch:**
+
+```bash
+git checkout -b kiliman/first-WEB-1234
+gh-stack init                              # create stack, add current branch
+gh-stack create kiliman/second-WEB-5678    # new branch stacked on top
+# ...work, commit...
+gh-stack create kiliman/third-WEB-9012     # stack another
+```
+
+`init` options: `--name <stack>`, `--parent <trunk>`, `--description <text>`.
+
+**Track a local WIP branch without publishing it — `gh-stack add`.** If you
+created a branch with `git checkout -b` and want to `sync`/`restack` it _before_
+opening a PR, `add` registers it in a stack (network-free — no push, no PR):
+
+```bash
+gh-stack add           # track the current branch
+gh-stack add <branch>  # track a named branch
+```
+
+It walks local ancestry: a branch sitting on top of an existing stack is adopted
+into it (parent auto-detected); otherwise a new stack is created from the chain.
+This resolves the catch-22 where `sync`/`restack` said "not in any stack" for a
+tip you hadn't submitted yet. (`submit` still auto-tracks too — `add` is just the
+no-publish path.)
+
+### 2. Push & create PRs — `submit`
+
+`submit` is the workhorse: **idempotent, scope-aware, self-healing**. It pushes
+changed branches with `--force-with-lease` (skips up-to-date ones), creates
+missing PRs with the correct base, fixes PR bases, and refreshes the stack
+visualization in every PR body.
+
+```bash
+gh-stack submit                       # push downstack + create/update PRs
+gh-stack submit -d                    # create new PRs as drafts
+gh-stack submit --dry-run             # preview, no side effects
+gh-stack submit --restack             # then propagate up to children (see below)
+gh-stack submit -t "<title>" -b "<body>"   # explicit title/body for new PRs
+gh-stack submit -t "<title>" --body-file /tmp/body.md
+gh-stack submit -n                    # auto-generate titles (generic — avoid)
+```
+
+**Agents: provide title + body explicitly.** `--title` implies `--no-edit`
+(no prompts); title/body apply to all new PRs created in scope:
+
+```bash
+gh-stack submit \
+  -t "Store raw transcription JSON and WebVTT [WEB-7409]" \
+  -b "$(cat <<'EOF'
+## Summary
+- Store raw transcription JSON alongside pre-rendered WebVTT
+
+## Test plan
+- [ ] Verify both formats persist
+EOF
+)"
+```
+
+**`submit -t`/`-b` also updates an existing PR in place** — pass them while on a
+branch that already has a PR to change just that one (visualization-safe).
+
+**`--restack`** chains a restack after submit. `submit` owns DOWNSTACK (trunk →
+current); `restack` owns UPSTACK (the children). Together they're the everyday
+downstack-fix loop in one command: _drop downstack → fix → commit →
+`gh-stack submit --restack`_ pushes the fix AND rebases the children onto it.
+
+### 3. Navigate
+
+```bash
+gh-stack log           # stack tree (default command)
+gh-stack ls            # numbered branch list
+gh-stack up [n]        # toward children (upstack)
+gh-stack down [n]      # toward parents (downstack)
+gh-stack top           # tip (leaf)
+gh-stack bottom        # base (first branch above trunk)
+gh-stack checkout      # interactive picker (alias: co)
+```
+
+### 4. Sync & restack
+
+```bash
+gh-stack sync          # fetch trunk, rebase base onto it, restack ALL children
+gh-stack restack       # rebase current branch + descendants onto their parents
+gh-stack restack --dry-run
+```
+
+**⚠️ Restack propagates UPWARD from the current branch.** Run it from the
+**lowest branch you changed**, never from the top:
+
+```bash
+gh-stack bottom        # go to the changed branch
+# ...edit, commit...
+gh-stack submit        # push it
+gh-stack restack       # propagates the change UP through children
+```
+
+**Changing multiple branches?** Finish each one fully before moving up —
+`edit → test → commit → push → restack`, then `gh-stack up` and repeat. Don't
+edit several branches then restack once at the end (only the last branch ends
+up pushed).
+
+**On rebase conflict:** resolve, `git add <files>`, `git rebase --continue`,
+then `gh-stack restack --resume` to finish the remaining branches.
+
+**`sync` is self-correcting:** if you merged the bottom PR in the GitHub UI,
+`sync` detects it and advances the stack past the merged branch (re-rooting onto
+trunk) instead of replaying squashed commits and conflicting.
+
+### 5. Status
+
+```bash
+gh-stack status            # PR dashboard: CI, reviews, merge readiness
+gh-stack status --current  # current stack only
+gh-stack status --json     # structured, for agents
+```
+
+### 6. Merge & ship
+
+```bash
+gh-stack merge             # collapse the WHOLE stack into one squash commit → trunk
+gh-stack merge --approved  # collapse only the approved run (base..highest-approved)
+                           # into one commit; leave the unapproved tail in place
+gh-stack merge --base      # land ONLY the bottom PR → trunk, re-root the next branch
+gh-stack merge --dry-run
+```
+
+Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, then base → trunk):
+
+- **`merge`**: the whole stack is approved → lands as a single squash commit.
+- **`merge --approved`**: collapse the **contiguous-from-base approved run** into
+  one commit on trunk. Approval is read from the base up — the first un-approved
+  PR caps the run (unapproved PR4 stops at PR3 even if PR5 is approved). The
+  unapproved tail is left in place; after the base lands, run `gh-stack sync` to
+  re-root the tail onto trunk (it does not block on CI).
+- **`merge --base`**: squash-merge **only the bottom PR** into trunk and re-root
+  the next branch onto trunk — one PR per run, re-run for the next. Use this to
+  land reviewed PRs one at a time. Auto-advances past a bottom PR already merged
+  outside gh-stack.
+- **`--collapse`** (with `merge` or `merge --approved`): stop after collapsing
+  into the base PR — review on GitHub, then re-run `merge` to finish.
+
+### 7. Maintenance
+
+```bash
+gh-stack delete        # remove a branch from the stack (re-parents children)
+gh-stack split         # cut a stack into two at a branch
+gh-stack rename        # rename a tracked branch (keeps metadata in sync)
+gh-stack undo          # restore from the last snapshot
+gh-stack archive       # manage archived stacks
+gh-stack doctor        # migrate & repair stack metadata
+gh-stack update-prs    # refresh stack visualization in PR descriptions
+```
+
+## Stack visualization
+
+`submit` auto-maintains a `### 📚 Stacked on` footer in every PR body. **Do not
+hand-write your own stack list** — it's regenerated each run, so a manual copy
+just goes stale and contradicts the auto footer. Describe _this_ PR in its body;
+let `submit` describe the stack. Link a specific sibling inline in prose if
+needed.
+
+## Safety model
+
+- **Snapshots** before every destructive op (restack/sync/merge/remove); roll
+  back with `gh-stack undo`. Think of them as a reflog for stack operations.
+- **Squash-merge safe** — uses temporary tags for stable rebasing (handles the
+  merge-base problem squash-merge creates).
+- **Never force-pushes trunk.**
+- **Metadata is local and never committed:** per-stack files under
+  `.git/.gh-stack/` plus git branch config. Inspect it via `gh-stack stacks
+--json`, not by reading the store. (`gh-stack doctor` migrates the old v2
+  `.git/gh-stack-metadata.json` monolith.)
+
+## Don'ts
+
+- **Don't use `gt`/Graphite commands** — this is `gh-stack`.
+- **Don't restack from the top** of the stack — restack flows upward.
+- **Don't edit multiple branches then restack once** — finish each branch first.
+- **Don't hand-write a stack section** in PR bodies — `submit` owns it.