gh-stack 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Stacked PR manager for squash-merge workflows.
 
-Manages stacked pull requests with metadata stored in `.git/gh-stack-metadata.json`. Designed for repositories that use squash-merge (where tools like Graphite break down).
+Manages stacked pull requests with metadata stored in `.git/gh-stack-metadata.json`. Designed for repositories that use squash-merge (where tools like Graphite break down). Inspired by [Graphite](https://graphite.dev/) (`gt`) but works directly against GitHub — no backend required.
 
 ## Install
 
@@ -22,68 +22,98 @@ bun install -g gh-stack
 - [GitHub CLI](https://cli.github.com/) (`gh`) — authenticated
 - Git 2.30+
 
+## Terms
+
+| Term | Definition |
+|------|-----------|
+| **trunk** | Base branch of the repository (usually `main`) |
+| **stack** | A chain of dependent branches |
+| **upstack** | Branches that depend on the current branch (children) |
+| **downstack** | Branches the current branch depends on (ancestors) |
+
 ## Quick Start
 
 ```bash
-# Create a stack from your current branch
-gh-stack init --name my-feature
+# You have branches: main → feat-1 → feat-2
+# Go to the top of the chain and init:
+git checkout feat-2
+gh-stack init                    # Auto-detects the chain!
 
-# Add more branches to the stack
-gh-stack add --create kiliman/pr2-WEB-1234
+# Or start fresh:
+git checkout kiliman/first-pr
+gh-stack init                    # Creates stack with this branch
+gh-stack create kiliman/second-pr  # Branch off current, add to stack
+
+# Push everything to GitHub and create PRs
+gh-stack submit
 
 # View the stack
-gh-stack                    # tree view (default)
-gh-stack list               # numbered list
+gh-stack log                     # tree view (default)
+gh-stack ls                      # numbered list
+
+# Navigate
+gh-stack up                      # move to child branch
+gh-stack down                    # move to parent branch
+gh-stack top                     # jump to tip of stack
+gh-stack bottom                  # jump to base of stack
 
-# Sync with main and restack all branches
+# Sync with main and restack
 gh-stack sync
 
-# Check PR status across all stacks
+# Check PR status
 gh-stack status
 ```
 
 ## Commands
 
-### Stack Management
+### Core Workflow
 
 ```
 init [--name <name>] [--description <desc>] [--parent <branch>]
-    Create a new stack and add the current branch as the first entry.
+    Create a new stack from the current branch. Auto-detects branch
+    chains — if you're at the top of main → feat-1 → feat-2, all
+    branches are added to the stack automatically.
 
-add [<branch>] [--parent <branch>] [--create <branch>] [--description <desc>]
-    Add a branch to the current stack. Defaults to the current branch.
-    --create <branch> makes a new branch off the top of stack first.
+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.
 
-remove [<branch>]
-    Remove a branch from the stack and re-parent its children.
-    If omitted, an interactive selector is shown.
+submit [-d|--draft] [-n|--no-edit] [--dry-run]
+    Push all downstack branches to GitHub, create PRs for branches
+    that don't have them, and update all PR descriptions with stack
+    visualization. Idempotent — safe to run repeatedly.
+
+    In --yes mode, auto-generates PR titles from branch names.
 ```
 
-### Navigation
+### Stack Navigation
 
 ```
-show
-    Display the current stack as a tree with branch numbers,
-    PR numbers, and descriptions. This is the default command.
+checkout [<branch>]
+    Switch to a branch by name, or interactive picker.
+    --stack    Switch between stacks instead of branches
+    (alias: co)
 
-list
-    List branches with position numbers. Lightweight output for
-    scripting and agents. (alias: ls)
+up [steps]
+    Move to child branch (upstack). Prompts if multiple children.
 
-switch [<number>]
-    Switch to a branch by position number, or interactive picker.
-    --stack    Switch between stacks instead of branches
+down [steps]
+    Move to parent branch (downstack).
 
-status [--current] [--json]
-    PR dashboard showing review state, CI status, and merge readiness.
-    --current  Show only the current stack or standalone PR
-    --json     Structured JSON output (progress goes to stderr)
+top
+    Jump to the tip (leaf) of the current stack.
+
+bottom
+    Jump to the base (first branch above trunk).
+
+ls
+    List branches with position numbers.
 ```
 
-### Rebase & Sync
+### Stack Management
 
 ```
-restack [--resume] [--dry-run] [--verbose] [--yes]
+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.
 
@@ -93,51 +123,37 @@ restack [--resume] [--dry-run] [--verbose] [--yes]
 
     (alias: rebase)
 
-sync [--dry-run] [--yes]
+sync [--dry-run]
     Fetch main, rebase the base branch onto main, then restack all
     children. Creates tags for ALL branches before any rebasing starts.
-```
-
-### Merge & Ship
 
-```
 merge [--dry-run]
-    Squash-merge the stack top-down locally (PR3 -> PR2 -> PR1),
-    then optionally rebase onto main. Keeps all commits local to
-    avoid orphaned squash commits from GitHub-only merges.
-    Can also close intermediate PRs and archives the stack on completion.
-
-update-prs
-    Update all PR descriptions with a stack visualization:
+    Squash-merge the stack top-down locally (PR3 → PR2 → PR1),
+    then optionally rebase onto main. Closes intermediate PRs and
+    archives the stack on completion.
 
-        ### 📚 Stacked on
-        ⚫ main
-        ┃
-        ┣━ ✅ #123 Backend models 👈
-        ┃
-        ┗━ ⏳ #124 Frontend UI
+delete [<branch>]
+    Remove a branch from the stack and re-parent its children.
+    Interactive selector if no branch specified.
 ```
 
-### Maintenance
+### Info & Maintenance
 
 ```
-archive [--restore <name>]
-    List archived stacks by default, or restore one by name.
+log
+    Display the current stack as a tree with branch numbers,
+    PR info, and descriptions. This is the default command.
+
+status [--current] [--json]
+    PR dashboard showing review state, CI status, and merge readiness.
+    --current  Show only the current stack or standalone PR
+    --json     Structured JSON output (progress goes to stderr)
 
 undo
     Restore the last snapshot taken before a destructive operation.
-```
 
-## Not Implemented Yet
-
-These are still intended, but not shipped in `v0.1.1`:
-
-```text
-split
-    Guided helper for splitting a branch/PR into two and updating stack metadata.
-
-insert
-    Insert a branch into the middle of an existing stack and re-parent the chain.
+archive [--restore <name>]
+    List archived stacks by default, or restore one by name.
 ```
 
 ## Global Options
@@ -157,10 +173,27 @@ GH_STACK_NO_COLOR=1    Disable colored output
 
 ## How It Works
 
+### Smart Init
+
+`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
 
 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`.
 
+### Stack Visualization
+
+`submit` automatically adds a stack section to all PR descriptions:
+
+```
+### 📚 Stacked on
+⚫ main
+┃
+┣━ ✅ #123 Backend models
+┃
+┗━ ⏳ #124 Frontend UI 👈
+```
+
 ### Metadata
 
 Stack metadata lives at `.git/gh-stack-metadata.json` (never committed):
@@ -168,21 +201,19 @@ Stack metadata lives at `.git/gh-stack-metadata.json` (never committed):
 ```json
 {
   "version": 2,
-  "current_stack": "podcast-mvp",
+  "current_stack": "kiliman/feature-2",
   "stacks": {
-    "podcast-mvp": {
-      "description": "Podcast MVP features",
-      "last_branch": "kiliman/pr2-WEB-1234",
+    "kiliman/feature-2": {
+      "description": "",
+      "last_branch": "kiliman/feature-2",
       "branches": {
-        "kiliman/pr1-WEB-1234": {
+        "kiliman/feature-1": {
           "parent": "main",
-          "pr": 21306,
-          "description": "Backend models"
+          "pr": 21729
         },
-        "kiliman/pr2-WEB-1234": {
-          "parent": "kiliman/pr1-WEB-1234",
-          "pr": 21452,
-          "description": "Frontend UI"
+        "kiliman/feature-2": {
+          "parent": "kiliman/feature-1",
+          "pr": 21730
         }
       }
     }
@@ -192,28 +223,32 @@ Stack metadata lives at `.git/gh-stack-metadata.json` (never committed):
 
 ### Snapshots
 
-Before any destructive operation (restack, sync, merge, remove), gh-stack saves a snapshot of all branch HEADs. Run `gh-stack undo` to restore.
+Before any destructive operation (restack, sync, merge, delete), gh-stack saves a snapshot of all branch HEADs. Run `gh-stack undo` to restore.
 
 ## Example Workflow
 
 ```bash
-# Start a new stack
-git checkout -b kiliman/api-layer-WEB-1234
-# ... code, commit, push, create PR ...
-gh-stack init --name api-feature
+# Start from an existing branch with a PR
+git checkout kiliman/api-layer-WEB-1234
+gh-stack init
 
-# Add second PR on top
-gh-stack add --create kiliman/frontend-WEB-1234
-# ... code, commit, push, create PR ...
+# Create second PR on top
+gh-stack create kiliman/frontend-WEB-1234
+# ... code, commit ...
 
-# Update PR descriptions with stack visualization
-gh-stack update-prs
+# Push everything and create PRs
+gh-stack submit
 
 # Later: sync everything with main
-gh-stack sync --yes
+gh-stack sync
+
+# Navigate the stack
+gh-stack up          # go to child
+gh-stack down        # go to parent
+gh-stack top         # jump to tip
 
 # Check status
-gh-stack status --current --json
+gh-stack status
 
 # When PRs are approved, merge the stack
 gh-stack merge
@@ -224,18 +259,18 @@ gh-stack merge
 gh-stack is designed to be used by AI agents and CI pipelines:
 
 ```bash
-# Non-interactive mode
+# Non-interactive mode — all prompts auto-resolved
 export GH_STACK_YES=1
+
+gh-stack init                    # No confirmations
+gh-stack submit                  # Auto-generates PR titles
 gh-stack sync
 gh-stack restack
 
 # Structured output
 gh-stack status --json
 gh-stack status --current --json
-gh-stack list
-
-# Quick branch switching
-gh-stack switch 2
+gh-stack ls
 ```
 
 ## License

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "gh-stack",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kiliman/gh-stack"
+    "url": "git+https://github.com/kiliman/gh-stack.git"
   },
   "keywords": [
     "git",
@@ -40,7 +40,7 @@
     "format:check": "oxfmt --check src/",
     "typecheck": "tsc --noEmit",
     "check": "bun run lint && bun run typecheck && bun test",
-    "prepublishOnly": "bun run check",
+    "prepublishOnly": "echo 'Checks already ran on push'",
     "prepare": "husky"
   },
   "lint-staged": {
@@ -63,4 +63,4 @@
     "@clack/prompts": "^1.1.0",
     "picocolors": "^1.1.1"
   }
-}
+}

package/src/commands/bottom.ts

@@ -0,0 +1,54 @@
+// gh-stack bottom — Jump to the base of the stack
+import * as p from "@clack/prompts";
+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";
+
+export default async function bottom(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack bottom — Jump to the base of the stack
+
+USAGE
+  gh-stack bottom
+
+Switches to the bottom-most branch of the current stack
+(the first branch above trunk).
+`);
+    return;
+  }
+
+  const meta = await ensureMetadata();
+  const currentBranch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, currentBranch);
+
+  if (!stackName) {
+    p.cancel(`Branch ${pc.yellow(currentBranch)} is not in any stack`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+  const ordered = getOrderedBranches(stack);
+
+  if (ordered.length === 0) {
+    p.log.warn("No branches in stack");
+    return;
+  }
+
+  const target = ordered[0]!;
+
+  if (target === currentBranch) {
+    p.log.info(`Already at the bottom: ${pc.yellow(currentBranch)}`);
+    return;
+  }
+
+  await git.checkout(target);
+
+  // Update tracking
+  stack.last_branch = target;
+  meta.current_stack = stackName;
+  await writeMetadata(meta);
+
+  p.log.success(`On ${pc.yellow(target)}`);
+}

package/src/commands/{switch.ts → checkout.ts}

@@ -1,4 +1,4 @@
-// gh-stack switch — Switch between branches or stacks
+// gh-stack checkout — Switch between branches or stacks
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
@@ -6,22 +6,25 @@ import { writeMetadata, getOrderedBranches, findStackForBranch } from "../lib/me
 import { ensureMetadata } from "../lib/safety.ts";
 import { selectBranch, selectStack } from "../lib/ui.ts";
 
-export default async function switchCmd(args: string[]): Promise<void> {
+export default async function checkout(args: string[]): Promise<void> {
   const isStackMode = args.includes("--stack");
   const numberArg = args.find((a) => /^\d+$/.test(a));
 
   if (args.includes("--help")) {
     console.log(`
-gh-stack switch — Switch branch or stack
+gh-stack checkout — Switch branch or stack
 
 USAGE
-  gh-stack switch <number>      Switch to branch by position (non-interactive)
-  gh-stack switch               Interactive branch picker (arrow keys)
-  gh-stack switch --stack       Switch between stacks (interactive)
+  gh-stack checkout <number>      Switch to branch by position (non-interactive)
+  gh-stack checkout               Interactive branch picker (arrow keys)
+  gh-stack checkout --stack       Switch between stacks (interactive)
+
+ALIASES
+  gh-stack co
 
 EXAMPLES
-  gh-stack switch 1             Jump to first branch in stack (base)
-  gh-stack switch 2             Jump to second branch in stack
+  gh-stack checkout 1             Jump to first branch in stack (base)
+  gh-stack checkout 2             Jump to second branch in stack
 
 TIP
   Use 'gh-stack list' to see branch numbers.

package/src/commands/create.ts

@@ -0,0 +1,83 @@
+// gh-stack create — Create a new branch and add to the stack
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import { findStackForBranch, addBranchToStack } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+import type { Branch } from "../types.ts";
+
+export default async function create(args: string[]): Promise<void> {
+  // Parse flags
+  let descFlag: string | undefined;
+  let branchArg: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--description":
+        descFlag = args[++i];
+        break;
+      case "--help":
+        console.log(`
+gh-stack create — Create a new branch and add to the stack
+
+USAGE
+  gh-stack create <branch-name> [options]
+
+Creates a new git branch off the current branch and adds it to the
+current stack. The current branch must already be tracked in a stack.
+
+OPTIONS
+  --description <desc>  Description for the branch
+
+EXAMPLES
+  gh-stack create kiliman/feature-2          # Branch off current, add to stack
+  gh-stack create kiliman/api --description "API layer"
+`);
+        return;
+      default:
+        if (!args[i]!.startsWith("--")) {
+          branchArg = args[i];
+        }
+    }
+  }
+
+  // Branch name is required
+  if (!branchArg) {
+    p.cancel("Branch name is required.\n\n  Usage: gh-stack create <branch-name>");
+    process.exit(1);
+  }
+
+  const meta = await ensureMetadata();
+  const currentBranch = await git.currentBranch();
+
+  // Current branch must be in a stack
+  const stackName = findStackForBranch(meta, currentBranch);
+  if (!stackName) {
+    p.cancel(
+      `Current branch ${pc.yellow(currentBranch)} is not in any stack.\n\n  Add it to a stack first with:\n    ${pc.green("gh-stack init")}`,
+    );
+    process.exit(1);
+  }
+
+  // New branch must not already exist
+  if (await git.localBranchExists(branchArg)) {
+    p.cancel(`Branch ${pc.yellow(branchArg)} already exists.`);
+    process.exit(1);
+  }
+
+  p.intro(pc.cyan(`Create branch in ${pc.yellow(stackName)}`));
+
+  // Create the new branch off current HEAD
+  p.log.info(`Creating ${pc.yellow(branchArg)} off ${pc.yellow(currentBranch)}`);
+  await git.createBranch(branchArg);
+
+  // Add to the stack with parent = current branch
+  const branchData: Branch = {
+    parent: currentBranch,
+    ...(descFlag && { description: descFlag }),
+  };
+
+  await addBranchToStack(meta, stackName, branchArg, branchData);
+
+  p.outro(pc.green(`Created ${pc.yellow(branchArg)} → parent ${pc.yellow(currentBranch)}`));
+}

package/src/commands/{remove.ts → delete.ts}

@@ -1,19 +1,19 @@
-// gh-stack remove — Remove a branch from the stack (re-link parent chain)
+// gh-stack delete — Delete a branch from the stack (re-link parent chain)
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { removeBranchFromStack, getChildren } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCurrentStack } from "../lib/safety.ts";
+import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { selectBranch } from "../lib/ui.ts";
 import * as git from "../lib/git.ts";
 
-export default async function remove(args: string[]): Promise<void> {
+export default async function deleteCmd(args: string[]): Promise<void> {
   if (args.includes("--help")) {
     console.log(`
-gh-stack remove — Remove a branch from the stack
+gh-stack delete — Delete a branch from the stack
 
 USAGE
-  gh-stack remove [<branch>]
+  gh-stack delete [<branch>]
 
 Removes the branch and re-parents its children to its parent.
 If no branch is specified, shows interactive selector.
@@ -23,15 +23,16 @@ If no branch is specified, shows interactive selector.
 
   const meta = await ensureMetadata();
   const stackName = ensureCurrentStack(meta);
+  await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
   const currentBranch = await git.currentBranch();
 
-  p.intro(pc.cyan("Remove Branch from Stack"));
+  p.intro(pc.cyan("Delete Branch from Stack"));
 
-  // Get branch to remove
+  // Get branch to delete
   let branchName = args[0];
   if (!branchName) {
-    branchName = (await selectBranch(stack, "Select branch to remove", currentBranch)) ?? undefined;
+    branchName = (await selectBranch(stack, "Select branch to delete", currentBranch)) ?? undefined;
     if (!branchName) {
       p.cancel("Cancelled");
       process.exit(0);
@@ -61,7 +62,7 @@ If no branch is specified, shows interactive selector.
 
   // Confirm
   const confirmed = await p.confirm({
-    message: `Remove ${pc.yellow(branchName)} from stack?`,
+    message: `Delete ${pc.yellow(branchName)} from stack?`,
   });
   if (p.isCancel(confirmed) || !confirmed) {
     p.cancel("Cancelled");
@@ -69,7 +70,7 @@ If no branch is specified, shows interactive selector.
   }
 
   // Take snapshot before destructive operation
-  await takeSnapshot(meta, stackName, "remove");
+  await takeSnapshot(meta, stackName, "delete");
 
   // Remove branch
   await removeBranchFromStack(meta, stackName, branchName);

package/src/commands/down.ts

@@ -0,0 +1,67 @@
+// gh-stack down — Move to parent branch (downstack)
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import { findStackForBranch, writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+
+export default async function down(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack down — Move to parent branch (downstack)
+
+USAGE
+  gh-stack down [steps]
+
+OPTIONS
+  [steps]    Number of levels to move down (default: 1)
+`);
+    return;
+  }
+
+  const steps = parseInt(args[0] || "1", 10);
+  if (isNaN(steps) || steps < 1) {
+    p.cancel("Invalid step count");
+    process.exit(1);
+  }
+
+  const meta = await ensureMetadata();
+  let currentBranch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, currentBranch);
+
+  if (!stackName) {
+    p.cancel(`Branch ${pc.yellow(currentBranch)} is not in any stack`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+
+  for (let i = 0; i < steps; i++) {
+    const branchMeta = stack.branches[currentBranch];
+    if (!branchMeta) {
+      p.log.warn(`${pc.yellow(currentBranch)} is not tracked in the stack`);
+      return;
+    }
+
+    const parent = branchMeta.parent;
+    if (parent === "main" || parent === "master") {
+      if (i === 0) {
+        p.log.warn(`${pc.yellow(currentBranch)} is already at the bottom of the stack`);
+      } else {
+        p.log.info(`Reached bottom of stack at ${pc.yellow(currentBranch)} after ${i} step(s)`);
+      }
+      return;
+    }
+
+    currentBranch = parent;
+  }
+
+  await git.checkout(currentBranch);
+
+  // Update tracking
+  stack.last_branch = currentBranch;
+  meta.current_stack = stackName;
+  await writeMetadata(meta);
+
+  p.log.success(`On ${pc.yellow(currentBranch)}`);
+}