gh-stack 0.15.0 → 0.17.0

package/README.md

@@ -83,6 +83,18 @@ create <branch-name> [--description <desc>]
     Create a new git branch off the current branch and add it to
     the stack. The current branch must already be tracked.
 
+add [branch]
+    Track an EXISTING local branch (default: the current branch) in a
+    stack — without pushing or opening a PR. Walks local ancestry: if the
+    branch sits on top of an existing stack it's adopted into it (parent
+    auto-detected); otherwise a new stack is created from the chain.
+
+    Use this for a WIP branch you've created with `git checkout -b` but
+    aren't ready to submit. It fills the gap between creating a branch and
+    `submit`: until a branch is tracked, `sync`/`restack`/navigation don't
+    know about it, and `add` is how you track it without publishing. (When
+    you do run `submit`, it auto-tracks too — `add` is the no-push path.)
+
 submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
     that don't have them, number each PR title with its stack position
@@ -168,9 +180,10 @@ sync [--dry-run]
     and conflicting.
 
 merge [--dry-run] [-d|--delete-branch] [--collapse]
-merge --approved [--dry-run] [-d|--delete-branch]
-    Default (top-down collapse): squash-merge the stack top-down via
-    GitHub (PR3 → PR2 → PR1), then enables auto-merge for the base PR
+merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
+merge --base [--dry-run] [-d|--delete-branch]
+    Default (top-down collapse): squash-merge the whole stack top-down
+    via GitHub (PR3 → PR2 → PR1), then enables auto-merge for the base PR
     into main. The whole stack lands on main as a single squash commit.
     All merges happen on GitHub so PRs show as "Merged", Linear tickets
     close automatically, and GitHub Actions fire normally. Skips already-
@@ -181,20 +194,25 @@ merge --approved [--dry-run] [-d|--delete-branch]
     real conflict with main stops the merge (the stack is left intact —
     resolve with `gh-stack sync`, then re-run), while merely waiting on
     pending checks is fine (auto-merge gates on them).
-    --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.
-
-    --approved (bottom-up, merge what's ready): merge approved PRs from
-    the BOTTOM up, each as its own squash commit on main, and leave the
-    unreviewed tail as a clean stack re-rooted on main. Stops at the
-    first PR that isn't approved. For each approved bottom PR it squash-
-    merges to main, re-roots the next branch onto main (replaying only
-    its own commits), pushes it, and repoints its PR base to main. A PR
-    already merged outside gh-stack is detected and advanced past, not
-    re-merged. For the "merge PRs as they get reviewed, keep stacking
-    the rest" workflow.
+
+    --approved  Collapse only the approved run. Walks approval from the
+                BASE up and stops at the first PR that isn't approved
+                (contiguous — an unapproved PR4 caps the run at PR3 even
+                if PR5 is approved). Collapses base..highest-approved into
+                a single squash commit on main and leaves the unapproved
+                tail in place; after the base PR lands, run `gh-stack sync`
+                to re-root the tail onto main. All approved ⇒ same as a
+                full merge.
+    --base      Squash-merge ONLY the bottom PR into main as its own
+                commit, then re-root the next branch onto main (replaying
+                just its own commits). One PR per run — run it again to
+                land the next. Approval is enforced by GitHub branch
+                protection, not gh-stack. A base PR already merged outside
+                gh-stack is detected and advanced past.
+    --collapse  With the default or --approved, stop after collapsing into
+                the base PR WITHOUT merging it to main, so you can review
+                the cumulative diff on GitHub. Re-run `gh-stack merge` to
+                finish. Alias: --stop-at-base.
 
 split [<branch>] [--name <name>]
     Cut a stack into two at <branch>. The cut branch and every branch
@@ -278,6 +296,19 @@ 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.
+
+learn [--skill] [--harness <name>] [--global] [--force]
+    Teach a coding agent how to drive gh-stack. By default prints the
+    canonical skill (Markdown, stamped with the running version) to
+    stdout — the text is compiled into the binary, so it never drifts
+    out of sync with the installed version. --skill installs it as a
+    skill file instead, choosing the path from the harness:
+      Claude Code  <root>/.claude/skills/using-gh-stack/SKILL.md
+      Codex        <root>/.codex/skills/using-gh-stack/SKILL.md
+      Cursor       <root>/.cursor/skills/using-gh-stack/SKILL.md
+    --harness  claude | codex | cursor (skips the interactive prompt)
+    --global   Install under ~/.<harness>/ instead of the project root
+    --force    Overwrite an existing skill file without confirming
 ```
 
 ## Global Options
@@ -449,8 +480,12 @@ gh-stack status
 # When the whole stack is approved, merge it down as one squash commit
 gh-stack merge       # squash-merges down, pushes, enables auto-merge
 
-# Or: merge PRs as they get approved, bottom-up, keep stacking the rest
-gh-stack merge --approved   # merges approved bottom PRs, re-roots the tail on main
+# Or: only the approved part is ready — collapse the approved run into one
+# commit and leave the rest stacked (re-root the tail later with `sync`)
+gh-stack merge --approved   # collapses base..highest-approved → main, keeps the tail
+
+# Or: land just the bottom PR, one at a time
+gh-stack merge --base       # merges the bottom PR → main, re-roots the next
 
 # Or: collapse first to review the cumulative diff before shipping
 gh-stack merge --collapse   # squash-merges PRn..PR2 into PR1, stops there
@@ -460,7 +495,16 @@ gh-stack merge              # finishes base PR → main + archives the stack
 
 ## Agent/CI Usage
 
-gh-stack is designed to be used by AI agents and CI pipelines:
+gh-stack is designed to be used by AI agents and CI pipelines. The fastest way
+to onboard an agent is `gh-stack learn` — it prints a version-matched skill (or
+installs one with `--skill`) so the agent learns the current commands, flags,
+and gotchas straight from the binary:
+
+```bash
+# Teach an agent the current API (always in sync with the installed version)
+gh-stack learn                              # print the skill to stdout
+gh-stack learn --skill --harness claude     # install it for Claude Code
+```
 
 ```bash
 # Non-interactive mode — all prompts auto-resolved

package/package.json

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

package/src/commands/add.ts

@@ -0,0 +1,107 @@
+// gh-stack add — register an existing local branch into a stack (no push, no PR).
+//
+// Fills the gap between `git checkout -b <wip>` and `submit`: it tracks the
+// branch (and any untracked ancestors) in the right stack by walking local
+// ancestry, so `sync` / `restack` / navigation work BEFORE you're ready to open
+// a PR. Network-free — nothing is pushed and no PR is created. That's the whole
+// point: `submit` is the command that publishes; `add` only updates metadata.
+//
+// Resolves the "catch-22" where a local WIP tip couldn't be synced because it
+// wasn't in a stack, and the only way into a stack was `submit` (which pushes).
+import * as p from "../lib/output.ts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import { gateLegacyMetadata } from "../lib/safety.ts";
+import { readMetadata, writeMetadata, findStackForBranch, stackBase } from "../lib/metadata.ts";
+import { resolveOrCreateStack } from "../lib/chain.ts";
+import type { StackMetadata } from "../types.ts";
+
+export default async function add(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack add — track an existing local branch in a stack (no push, no PR)
+
+USAGE
+  gh-stack add [branch]
+
+Registers the branch (default: the current branch) into a stack so sync,
+restack, and navigation work before you've submitted it. Walks local ancestry:
+if the branch sits on top of an existing stack it's adopted into that stack;
+otherwise a new stack is created from the chain, rooted at the trunk.
+
+Network-free — nothing is pushed and no PR is opened. Run ${"`"}gh-stack submit${"`"} when
+you're ready to publish.
+
+EXAMPLES
+  gh-stack add                    Track the current branch
+  gh-stack add my-wip-branch      Track a specific local branch
+`);
+    return;
+  }
+
+  await gateLegacyMetadata();
+
+  const positional = args.find((a) => !a.startsWith("-"));
+  const branch = positional ?? (await git.currentBranch());
+
+  if (!(await git.localBranchExists(branch))) {
+    p.cancel(`Branch ${pc.yellow(branch)} doesn't exist locally.`);
+    process.exit(1);
+  }
+
+  const trunk = await git.trunkBranch();
+  if (branch === trunk || branch === "main" || branch === "master") {
+    p.cancel(
+      `${pc.yellow(branch)} is the trunk — nothing to add.\n\n  Checkout a feature branch first.`,
+    );
+    process.exit(1);
+  }
+
+  // submit self-heals from an empty store, so a missing metadata file is fine —
+  // resolveOrCreateStack will create the first stack from local ancestry.
+  const meta: StackMetadata = (await readMetadata()) ?? {
+    version: 2,
+    current_stack: null,
+    stacks: {},
+  };
+
+  const already = findStackForBranch(meta, branch);
+  if (already) {
+    p.log.info(`${pc.yellow(branch)} is already tracked in stack ${pc.yellow(already)}.`);
+    return;
+  }
+
+  let resolution;
+  try {
+    resolution = await resolveOrCreateStack(meta, branch, trunk);
+  } catch (err) {
+    p.cancel((err as Error).message);
+    process.exit(1);
+  }
+
+  meta.current_stack = resolution.stackName;
+  await writeMetadata(meta);
+
+  p.intro(pc.cyan("Add to Stack"));
+
+  const stack = meta.stacks[resolution.stackName]!;
+  const base = stackBase(stack);
+  const baseNote = base === "main" || base === "master" ? "" : ` ${pc.dim(`(base: ${base})`)}`;
+
+  if (resolution.created) {
+    p.log.success(
+      `Created stack ${pc.yellow(resolution.stackName)} from ${resolution.addedBranches.length} local branch(es)${baseNote}`,
+    );
+  } else {
+    p.log.success(
+      `Added ${resolution.addedBranches.length} branch(es) to ${pc.yellow(resolution.stackName)}${baseNote}`,
+    );
+  }
+  for (const b of resolution.addedBranches) {
+    console.log(`  ${pc.green("+")} ${b}`);
+  }
+
+  p.outro(
+    `Tracked — ${pc.green("gh-stack sync")}/${pc.green("restack")} now work. ${pc.dim("Run")} ${pc.green("gh-stack submit")} ${pc.dim("to open PRs.")}`,
+  );
+}

package/src/commands/bottom.ts

@@ -3,7 +3,7 @@ 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";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 
 export default async function bottom(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -43,7 +43,7 @@ Switches to the bottom-most branch of the current stack
     return;
   }
 
-  await git.checkout(target);
+  await checkoutOrExit(target);
 
   // Update tracking
   stack.last_branch = target;

package/src/commands/checkout.ts

@@ -3,7 +3,7 @@ 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";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 import { selectBranch, selectStack } from "../lib/ui.ts";
 
 export default async function checkout(args: string[]): Promise<void> {
@@ -45,20 +45,21 @@ TIP
       process.exit(0);
     }
 
-    // Update current_stack
-    meta.current_stack = stackName;
-    await writeMetadata(meta);
-
-    // Checkout last branch in stack
+    // Checkout the stack's last branch FIRST — only persist current_stack once
+    // the switch actually lands, so a refused checkout (e.g. dirty tree) leaves
+    // metadata pointing at the stack we're still on rather than the target.
     const stack = meta.stacks[stackName]!;
     const lastBranch = stack.last_branch;
 
     if (lastBranch && lastBranch !== currentBranch) {
       p.log.info(`Switching to stack ${pc.yellow(stackName)}`);
       p.log.info(`Checking out ${pc.yellow(lastBranch)}`);
-      await git.checkout(lastBranch);
+      await checkoutOrExit(lastBranch);
     }
 
+    meta.current_stack = stackName;
+    await writeMetadata(meta);
+
     p.outro(pc.green(`Switched to stack ${pc.yellow(stackName)}`));
   } else {
     // ── Branch switching ──
@@ -105,7 +106,7 @@ TIP
     }
 
     p.log.info(`Switching to ${pc.yellow(targetBranch)}`);
-    await git.checkout(targetBranch);
+    await checkoutOrExit(targetBranch);
 
     // Update last_branch
     stack.last_branch = targetBranch;

package/src/commands/down.ts

@@ -3,7 +3,7 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, stackBase, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 
 export default async function down(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -64,7 +64,7 @@ OPTIONS
     moved++;
   }
 
-  await git.checkout(currentBranch);
+  await checkoutOrExit(currentBranch);
 
   // Update tracking
   stack.last_branch = currentBranch;

package/src/commands/learn.ts

@@ -0,0 +1,152 @@
+// gh-stack learn — teach agents how to drive gh-stack.
+//
+//   gh-stack learn            Print the canonical, version-stamped skill to stdout.
+//   gh-stack learn --skill    Install it as a skill file for a coding harness.
+//
+// The skill text is compiled into the binary (src/lib/skill.ts), so it's always
+// in lockstep with the installed version — no hand-maintained skill to drift.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import pc from "picocolors";
+import * as p from "../lib/output.ts";
+import * as git from "../lib/git.ts";
+import { isAutoYes } from "../lib/ui.ts";
+import { SKILL_NAME, skillContent } from "../lib/skill.ts";
+
+const { version: VERSION } = await import("../../package.json");
+
+interface Harness {
+  key: string;
+  label: string;
+  dir: string; // the per-harness config dir, e.g. ".claude"
+}
+
+// Project-root install locations per harness. Global installs swap the repo
+// root for the home directory (same `<dir>/skills/<name>/SKILL.md` shape).
+const HARNESSES: Harness[] = [
+  { key: "claude", label: "Claude Code", dir: ".claude" },
+  { key: "codex", label: "Codex", dir: ".codex" },
+  { key: "cursor", label: "Cursor", dir: ".cursor" },
+];
+
+function flagValue(args: string[], name: string): string | undefined {
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq) return eq.slice(name.length + 1);
+  const i = args.indexOf(name);
+  if (i !== -1 && args[i + 1] && !args[i + 1]!.startsWith("-")) return args[i + 1];
+  return undefined;
+}
+
+export default async function learn(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack learn — teach an agent how to use gh-stack
+
+USAGE
+  gh-stack learn [--skill] [options]
+
+By default, prints the canonical gh-stack skill (Markdown, stamped with the
+current version) to stdout. The text is compiled into the binary, so it never
+drifts out of sync with the installed version.
+
+OPTIONS
+  --skill                 Install the skill into a project (or --global) instead
+                          of printing it
+  --harness <name>        Target harness: claude | codex | cursor
+                          (skips the interactive prompt)
+  --global, -g            Install under your home dir (~/.<harness>/skills/...)
+                          instead of the project root
+  --force                 Overwrite an existing skill file without confirming
+  --help                  Show this help
+
+INSTALL PATHS
+  Claude Code   <root>/.claude/skills/${SKILL_NAME}/SKILL.md
+  Codex         <root>/.codex/skills/${SKILL_NAME}/SKILL.md
+  Cursor        <root>/.cursor/skills/${SKILL_NAME}/SKILL.md
+
+EXAMPLES
+  gh-stack learn                          # print the skill to stdout
+  gh-stack learn > AGENTS.md              # capture it however you like
+  gh-stack learn --skill                  # interactive install (pick harness)
+  gh-stack learn --skill --harness claude # install for Claude Code, no prompt
+  gh-stack learn --skill --global -g      # install into your home dir
+`);
+    return;
+  }
+
+  const content = skillContent(VERSION);
+
+  // Default: just print the skill. No chrome — pipe-friendly for agents.
+  if (!args.includes("--skill")) {
+    console.log(content);
+    return;
+  }
+
+  // ── Install mode ──
+  const global = args.includes("--global") || args.includes("-g");
+  const force = args.includes("--force");
+  const autoYes = isAutoYes();
+
+  // Resolve harness: explicit flag, else interactive prompt.
+  let harness: Harness | undefined;
+  const harnessFlag = flagValue(args, "--harness");
+  if (harnessFlag) {
+    harness = HARNESSES.find((h) => h.key === harnessFlag.toLowerCase());
+    if (!harness) {
+      p.log.error(
+        `Unknown harness "${harnessFlag}". Choose one of: ${HARNESSES.map((h) => h.key).join(", ")}.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  } else if (autoYes) {
+    p.log.error("Non-interactive mode needs an explicit harness: --harness <claude|codex|cursor>.");
+    process.exitCode = 1;
+    return;
+  } else {
+    const selected = await p.select({
+      message: "Which harness is this skill for?",
+      options: HARNESSES.map((h) => ({
+        value: h.key,
+        label: h.label,
+        hint: `${global ? "~" : "."}/${h.dir}/skills/${SKILL_NAME}/`,
+      })),
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Cancelled.");
+      return;
+    }
+    harness = HARNESSES.find((h) => h.key === selected)!;
+  }
+
+  // Resolve install root: home dir (--global) or repo working-tree root.
+  let root: string;
+  if (global) {
+    root = homedir();
+  } else if (await git.isGitRepo()) {
+    root = await git.repoRoot();
+  } else {
+    p.log.error("Not inside a git repository. Run from a project, or use --global.");
+    process.exitCode = 1;
+    return;
+  }
+  const target = join(root, harness.dir, "skills", SKILL_NAME, "SKILL.md");
+
+  // Confirm overwrite unless --force / auto-yes.
+  if ((await Bun.file(target).exists()) && !force && !autoYes) {
+    const ok = await p.confirm({
+      message: `${pc.yellow(target)} already exists. Overwrite?`,
+    });
+    if (p.isCancel(ok) || !ok) {
+      p.cancel("Left existing skill in place.");
+      return;
+    }
+  }
+
+  await Bun.write(target, content); // creates parent dirs as needed
+
+  p.log.success(`Installed ${harness.label} skill → ${pc.cyan(target)}`);
+  p.log.info(
+    `Stamped from gh-stack v${VERSION}. Refresh after upgrading with ${pc.dim("gh-stack learn --skill")}.`,
+  );
+}