gh-stack 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kiliman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# gh-stack
+
+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).
+
+## Install
+
+```bash
+# From source (requires Bun)
+bun install
+bun run build
+ln -s $(pwd)/dist/gh-stack ~/.local/bin/gh-stack
+
+# Or install globally
+bun install -g gh-stack
+```
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime
+- [GitHub CLI](https://cli.github.com/) (`gh`) — authenticated
+- Git 2.30+
+
+## Quick Start
+
+```bash
+# Create a stack from your current branch
+gh-stack init --name my-feature
+
+# Add more branches to the stack
+gh-stack add --create kiliman/pr2-WEB-1234
+
+# View the stack
+gh-stack                    # tree view (default)
+gh-stack list               # numbered list
+
+# Sync with main and restack all branches
+gh-stack sync
+
+# Check PR status across all stacks
+gh-stack status
+```
+
+## Commands
+
+### Stack Management
+
+```
+init [--name <name>] [--description <desc>]
+    Create a new stack and add the current branch as the first entry.
+
+add [<branch>] [--parent <branch>] [--create] [--description <desc>]
+    Add a branch to the current stack. Defaults to the current branch.
+    --create makes a new branch off the top of stack first.
+
+remove <branch>
+    Remove a branch from the stack and re-parent its children.
+```
+
+### Navigation
+
+```
+show
+    Display the current stack as a tree with PR numbers, titles,
+    review status, and CI state. This is the default command.
+
+list
+    List branches with position numbers. Lightweight output for
+    scripting and agents. (alias: ls)
+
+switch [<number>]
+    Switch to a branch by position number, or interactive picker.
+    --stack    Switch between stacks instead of branches
+
+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)
+```
+
+### Rebase & Sync
+
+```
+restack [--resume] [--dry-run] [--verbose] [--yes]
+    Rebase the current branch and all descendants onto their parents.
+    Uses tag-based references for stable rebasing across the chain.
+
+    On conflict:
+        git rebase --continue
+        gh-stack restack --resume
+
+    (alias: rebase)
+
+sync [--dry-run] [--yes]
+    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.
+
+update-prs
+    Update all PR descriptions with a stack visualization:
+
+        ### 📚 Stacked on
+        ⚫ main
+        ┃
+        ┣━ ✅ #123 Backend models 👈
+        ┃
+        ┗━ ⏳ #124 Frontend UI
+```
+
+### Maintenance
+
+```
+archive [--list] [--restore <name>]
+    Manage archived stacks.
+
+undo
+    Restore the last snapshot taken before a destructive operation.
+```
+
+## Global Options
+
+```
+--yes, -y      Skip all confirmations (for agents/CI)
+--help         Show help for a command
+--version, -V  Show version
+```
+
+## Environment Variables
+
+```
+GH_STACK_YES=1         Skip all confirmations (same as --yes)
+GH_STACK_NO_COLOR=1    Disable colored output
+```
+
+## How It Works
+
+### 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`.
+
+### Metadata
+
+Stack metadata lives at `.git/gh-stack-metadata.json` (never committed):
+
+```json
+{
+  "version": 2,
+  "current_stack": "podcast-mvp",
+  "stacks": {
+    "podcast-mvp": {
+      "description": "Podcast MVP features",
+      "last_branch": "kiliman/pr2-WEB-1234",
+      "branches": {
+        "kiliman/pr1-WEB-1234": {
+          "parent": "main",
+          "pr": 21306,
+          "description": "Backend models"
+        },
+        "kiliman/pr2-WEB-1234": {
+          "parent": "kiliman/pr1-WEB-1234",
+          "pr": 21452,
+          "description": "Frontend UI"
+        }
+      }
+    }
+  }
+}
+```
+
+### Snapshots
+
+Before any destructive operation (restack, sync, merge, remove), 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
+
+# Add second PR on top
+gh-stack add --create kiliman/frontend-WEB-1234
+# ... code, commit, push, create PR ...
+
+# Update PR descriptions with stack visualization
+gh-stack update-prs
+
+# Later: sync everything with main
+gh-stack sync --yes
+
+# Check status
+gh-stack status --current --json
+
+# When PRs are approved, merge the stack
+gh-stack merge
+```
+
+## Agent/CI Usage
+
+gh-stack is designed to be used by AI agents and CI pipelines:
+
+```bash
+# Non-interactive mode
+export GH_STACK_YES=1
+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
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "gh-stack",
+  "version": "0.1.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"
+  },
+  "keywords": [
+    "git",
+    "github",
+    "stacked-prs",
+    "squash-merge",
+    "cli",
+    "pull-requests",
+    "rebase",
+    "bun"
+  ],
+  "type": "module",
+  "bin": {
+    "gh-stack": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/__tests__",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build --compile src/index.ts --outfile dist/gh-stack",
+    "test": "bun test",
+    "lint": "oxlint src/",
+    "format": "oxfmt --write src/",
+    "format:check": "oxfmt --check src/",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run lint && bun run typecheck && bun test",
+    "prepublishOnly": "bun run check",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "oxlint",
+      "oxfmt --write"
+    ]
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.3",
+    "oxfmt": "^0.40.0",
+    "oxlint": "^1.55.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,137 @@
+// gh-stack add — Add a branch to the current stack
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import { addBranchToStack, getTopOfStack, getOrderedBranches } from "../lib/metadata.ts";
+import { ensureMetadata, ensureCurrentStack } from "../lib/safety.ts";
+import { getPrNumber } from "../lib/github.ts";
+import { selectParent } from "../lib/ui.ts";
+import type { Branch } from "../types.ts";
+
+export default async function add(args: string[]): Promise<void> {
+  // Parse flags
+  let parentFlag: string | undefined;
+  let descFlag: string | undefined;
+  let createFlag: string | undefined;
+  let branchArg: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--parent":
+        parentFlag = args[++i];
+        break;
+      case "--description":
+        descFlag = args[++i];
+        break;
+      case "--create":
+        createFlag = args[++i];
+        break;
+      case "--help":
+        console.log(`
+gh-stack add — Add a branch to the current stack
+
+USAGE
+  gh-stack add [<branch>] [options]
+
+OPTIONS
+  --parent <branch>     Parent branch (default: top of stack)
+  --create <branch>     Create new branch off top of stack and add it
+  --description <desc>  Description for the branch
+`);
+        return;
+      default:
+        if (!args[i]!.startsWith("--")) {
+          branchArg = args[i];
+        }
+    }
+  }
+
+  const meta = await ensureMetadata();
+  const stackName = ensureCurrentStack(meta);
+  const stack = meta.stacks[stackName]!;
+
+  p.intro(pc.cyan(`Add branch to ${pc.yellow(stackName)}`));
+
+  let branchToAdd: string;
+
+  // --create: make a new branch off the top of the stack
+  if (createFlag) {
+    const topBranch = getTopOfStack(stack);
+    if (!topBranch) {
+      p.cancel("Stack has no branches yet. Add the base branch first.");
+      process.exit(1);
+    }
+
+    const currentBranch = await git.currentBranch();
+    if (currentBranch !== topBranch) {
+      p.log.info(`Switching to ${pc.yellow(topBranch)}...`);
+      await git.checkout(topBranch);
+    }
+
+    p.log.info(`Creating branch off top of stack: ${pc.yellow(topBranch)}`);
+    await git.createBranch(createFlag);
+    p.log.success(`Created branch: ${pc.yellow(createFlag)}`);
+
+    branchToAdd = createFlag;
+    parentFlag = topBranch;
+  } else {
+    branchToAdd = branchArg || (await git.currentBranch());
+  }
+
+  // Check if branch is already in the stack
+  if (stack.branches[branchToAdd]) {
+    p.cancel(`Branch ${pc.yellow(branchToAdd)} is already in stack ${pc.blue(stackName)}`);
+    process.exit(1);
+  }
+
+  console.log(`  Adding: ${pc.yellow(branchToAdd)}`);
+  console.log();
+
+  // Get parent
+  let parent = parentFlag;
+  if (!parent) {
+    // Default to top of stack
+    const ordered = getOrderedBranches(stack);
+
+    if (ordered.length === 0) {
+      parent = "main";
+    } else {
+      parent = (await selectParent(stack, branchToAdd)) ?? undefined;
+      if (!parent) {
+        p.cancel("Cancelled");
+        process.exit(0);
+      }
+    }
+  }
+
+  p.log.info(`Parent: ${pc.yellow(parent)}`);
+
+  // Auto-detect PR number
+  const s = p.spinner();
+  s.start("Looking for PR...");
+  const prNumber = await getPrNumber(branchToAdd);
+  s.stop(prNumber ? `Found PR #${prNumber}` : "No PR found");
+
+  // Get description
+  let description = descFlag;
+  if (description === undefined && !createFlag) {
+    const result = await p.text({
+      message: "Branch description (optional)",
+      placeholder: "e.g., API layer",
+    });
+    if (!p.isCancel(result)) {
+      description = (result as string) || undefined;
+    }
+  }
+
+  // Add branch
+  const branchData: Branch = {
+    parent,
+    ...(prNumber && { pr: prNumber }),
+    ...(description && { description }),
+  };
+
+  await addBranchToStack(meta, stackName, branchToAdd, branchData);
+
+  p.outro(pc.green(`Added ${pc.yellow(branchToAdd)} to stack ${pc.blue(stackName)}`));
+}

package/src/commands/archive.ts

@@ -0,0 +1,60 @@
+// gh-stack archive — Manage archived stacks
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+
+export default async function archive(args: string[]): Promise<void> {
+  const restoreIdx = args.indexOf("--restore");
+  const restoreName = restoreIdx !== -1 ? args[restoreIdx + 1] : undefined;
+
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack archive — Manage archived stacks
+
+USAGE
+  gh-stack archive [--list]            List archived stacks
+  gh-stack archive --restore <name>    Restore an archived stack
+`);
+    return;
+  }
+
+  const meta = await ensureMetadata();
+
+  if (restoreName) {
+    // Restore an archived stack
+    if (!meta.archive || !meta.archive[restoreName]) {
+      p.cancel(`Archived stack "${restoreName}" not found`);
+      process.exit(1);
+    }
+
+    meta.stacks[restoreName] = meta.archive[restoreName]!;
+    delete meta.archive[restoreName];
+    meta.current_stack = restoreName;
+    await writeMetadata(meta);
+
+    p.log.success(`Restored stack ${pc.yellow(restoreName)} from archive`);
+    return;
+  }
+
+  // List archived stacks
+  p.intro(pc.cyan("Archived Stacks"));
+
+  if (!meta.archive || Object.keys(meta.archive).length === 0) {
+    p.log.info("No archived stacks");
+    return;
+  }
+
+  for (const [name, stack] of Object.entries(meta.archive)) {
+    const branchCount = Object.keys(stack.branches).length;
+    console.log(
+      `  ${pc.blue("○")} ${pc.yellow(name)} (${branchCount} branch${branchCount !== 1 ? "es" : ""})`,
+    );
+    if (stack.description) {
+      console.log(`    ${pc.dim(stack.description)}`);
+    }
+    console.log();
+  }
+
+  console.log(pc.dim(`  Restore with: gh-stack archive --restore <name>`));
+}

package/src/commands/init.ts

@@ -0,0 +1,156 @@
+// gh-stack init — Create a new stack with the current branch
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import {
+  readMetadata,
+  initMetadata,
+  createStack,
+  addBranchToStack,
+  metadataExists,
+} from "../lib/metadata.ts";
+import { getPrNumber } from "../lib/github.ts";
+import { selectParent } from "../lib/ui.ts";
+import type { StackMetadata, Branch } from "../types.ts";
+
+export default async function init(args: string[]): Promise<void> {
+  const branch = await git.currentBranch();
+
+  // Parse flags
+  let nameFlag: string | undefined;
+  let descFlag: string | undefined;
+  let parentFlag: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--name":
+        nameFlag = args[++i];
+        break;
+      case "--description":
+        descFlag = args[++i];
+        break;
+      case "--parent":
+        parentFlag = args[++i];
+        break;
+      case "--help":
+        console.log(`
+gh-stack init — Create a new stack
+
+USAGE
+  gh-stack init [--name <name>] [--description <desc>] [--parent <branch>]
+
+OPTIONS
+  --name <name>         Stack name (skip prompt)
+  --description <desc>  Stack description
+  --parent <branch>     Parent branch for current branch (default: main)
+`);
+        return;
+    }
+  }
+
+  p.intro(pc.cyan("Create New Stack"));
+
+  console.log(`  Initializing stack with: ${pc.yellow(branch)}`);
+  console.log();
+
+  // Get or create metadata
+  let meta: StackMetadata;
+  if (await metadataExists()) {
+    meta = (await readMetadata())!;
+  } else {
+    meta = await initMetadata();
+    p.log.success("Initialized empty stack metadata");
+  }
+
+  // Get stack name
+  let stackName = nameFlag;
+  if (!stackName) {
+    const result = await p.text({
+      message: "Stack name",
+      placeholder: "e.g., podcast-mvp",
+      validate: (val = "") => {
+        if (!val.trim()) return "Stack name is required";
+        if (meta.stacks[val.trim()]) return `Stack "${val}" already exists`;
+      },
+    });
+    if (p.isCancel(result)) {
+      p.cancel("Cancelled");
+      process.exit(0);
+    }
+    stackName = result as string;
+  }
+
+  // Check if stack already exists
+  if (meta.stacks[stackName]) {
+    p.cancel(`Stack "${stackName}" already exists`);
+    process.exit(1);
+  }
+
+  // Get stack description
+  let description = descFlag;
+  if (description === undefined) {
+    const result = await p.text({
+      message: "Stack description (optional)",
+      placeholder: "e.g., Podcast MVP features",
+    });
+    if (p.isCancel(result)) {
+      p.cancel("Cancelled");
+      process.exit(0);
+    }
+    description = (result as string) || "";
+  }
+
+  // Create the stack
+  meta = await createStack(meta, stackName, description);
+  p.log.success(`Created stack: ${pc.blue(stackName)}`);
+
+  // Get parent branch
+  let parent: string | undefined = parentFlag;
+  if (!parent) {
+    parent = (await selectParent(null, branch)) ?? undefined;
+    if (!parent) {
+      p.cancel("Cancelled");
+      process.exit(0);
+    }
+  }
+
+  p.log.info(`Parent: ${pc.yellow(parent)}`);
+
+  // Auto-detect PR number
+  const s = p.spinner();
+  s.start("Looking for PR...");
+  const prNumber = await getPrNumber(branch);
+  s.stop(prNumber ? `Found PR #${prNumber}` : "No PR found");
+
+  // Get branch description
+  let branchDesc: string | undefined;
+  if (!nameFlag) {
+    // Only prompt for branch description in interactive mode
+    const result = await p.text({
+      message: "Branch description (optional)",
+      placeholder: "e.g., Backend models",
+    });
+    if (!p.isCancel(result)) {
+      branchDesc = (result as string) || undefined;
+    }
+  }
+
+  // Add branch to stack
+  const branchData: Branch = {
+    parent,
+    ...(prNumber && { pr: prNumber }),
+    ...(branchDesc && { description: branchDesc }),
+  };
+
+  meta = await addBranchToStack(meta, stackName, branch, branchData);
+
+  p.log.success(`Added ${pc.yellow(branch)} to stack`);
+
+  p.outro(pc.green("Stack initialized!"));
+
+  console.log();
+  console.log("  Next steps:");
+  console.log(`    ${pc.blue("gh-stack add")}          — Add more branches`);
+  console.log(`    ${pc.blue("gh-stack")}              — View stack`);
+  console.log(`    ${pc.blue("gh-stack restack")}      — Sync stack`);
+}