@cvr/stacked 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# stacked
+
+Branch-based stacked PR manager. Tracks parent-child branch relationships, automates rebasing, and creates/updates GitHub PRs via `gh`.
+
+Built with [Effect v4](https://effect.website) and [Bun](https://bun.sh).
+
+## Install
+
+```sh
+bun run build   # compiles binary to bin/stacked + symlinks to ~/.bun/bin/
+```
+
+## Usage
+
+```sh
+# Set trunk branch (default: main)
+stacked trunk develop
+
+# Create a stack: branch from trunk
+stacked create feat-auth
+
+# Stack another branch on top
+stacked create feat-auth-ui
+
+# See the stack
+stacked list
+
+# Navigate
+stacked top
+stacked bottom
+stacked checkout feat-auth
+
+# After editing mid-stack, rebase children
+stacked restack
+
+# Sync entire stack with latest trunk
+stacked sync
+
+# Push all branches + create/update PRs
+stacked submit
+stacked submit --draft
+stacked submit --dry-run
+
+# Adopt an existing branch into the stack
+stacked adopt existing-branch --after feat-auth
+
+# View commits per branch
+stacked log
+
+# Remove a branch from the stack
+stacked delete feat-auth-ui
+```
+
+## Commands
+
+| Command           | Description                              |
+| ----------------- | ---------------------------------------- |
+| `trunk [name]`    | Get/set trunk branch                     |
+| `create <name>`   | Create branch on top of current          |
+| `list`            | Show stack with current branch indicator |
+| `checkout <name>` | Switch to branch                         |
+| `top`             | Jump to top of stack                     |
+| `bottom`          | Jump to bottom of stack                  |
+| `sync`            | Fetch + rebase entire stack on trunk     |
+| `restack`         | Rebase children after mid-stack edits    |
+| `delete <name>`   | Remove branch from stack + git           |
+| `submit`          | Push all + create/update PRs via `gh`    |
+| `adopt <branch>`  | Add existing branch to stack             |
+| `log`             | Show commits grouped by branch           |
+
+## Data Model
+
+Stack metadata lives in `.git/stacked.json`. Each branch's parent is implied by array position — `branches[0]`'s parent is trunk, `branches[n]`'s parent is `branches[n-1]`.
+
+## Development
+
+```sh
+bun run dev -- --help    # run from source
+bun run gate             # typecheck + lint + fmt + test + build
+bun test                 # tests only
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@cvr/stacked",
+  "version": "0.1.0",
+  "bin": {
+    "stacked": "./bin/stacked"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "skills",
+    "tsconfig.json"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "build": "bun run scripts/build.ts",
+    "link": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "test": "bun test",
+    "gate": "concurrently -n type,lint,fmt,test,build -c blue,yellow,magenta,green,cyan \"bun run typecheck\" \"bun run lint\" \"bun run fmt\" \"bun run test\" \"bun run build\"",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "postinstall": "bun run build",
+    "prepare": "effect-language-service patch && lefthook install"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "4.0.0-beta.12",
+    "effect": "4.0.0-beta.12"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@effect/language-service": "^0.76.0",
+    "@types/bun": "^1.3.9",
+    "concurrently": "^9.2.1",
+    "effect-bun-test": "^0.2.1",
+    "lefthook": "^2.1.1",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/build.ts

@@ -0,0 +1,53 @@
+import { mkdirSync, lstatSync, unlinkSync, symlinkSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import * as os from "node:os";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, "..");
+
+console.log("Building stacked...");
+
+const binDir = join(rootDir, "bin");
+mkdirSync(binDir, { recursive: true });
+
+const platform =
+  process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux";
+const arch = process.arch === "arm64" ? "arm64" : "x64";
+
+const buildResult = await Bun.build({
+  entrypoints: [join(rootDir, "src/main.ts")],
+  target: "bun",
+  minify: false,
+  compile: {
+    target: `bun-${platform}-${arch}`,
+    outfile: join(binDir, "stacked"),
+    autoloadBunfig: false,
+  },
+});
+
+if (!buildResult.success) {
+  console.error("Build failed:");
+  for (const log of buildResult.logs) {
+    console.error(log);
+  }
+  process.exit(1);
+}
+
+console.log(`Binary built: ${join(binDir, "stacked")}`);
+
+const home = process.env["HOME"] ?? os.homedir();
+const bunBin = join(home, ".bun", "bin", "stacked");
+try {
+  try {
+    lstatSync(bunBin);
+    unlinkSync(bunBin);
+  } catch {
+    // doesn't exist
+  }
+  symlinkSync(join(binDir, "stacked"), bunBin);
+  console.log(`Symlinked to: ${bunBin}`);
+} catch (e) {
+  console.log(`Could not symlink to ${bunBin}: ${e}`);
+}

package/skills/stacked/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: stacked
+description: Use the `stacked` CLI to manage stacked PRs. Use when the user wants to create branch stacks, rebase, sync, submit PRs, or navigate stacked branches. Triggers on "stacked", "stack", "stacked PRs", branch stacking workflows, or any git workflow involving parent-child branch relationships.
+---
+
+# stacked
+
+Branch-based stacked PR manager. Manages parent-child branch relationships, automates rebasing, creates/updates GitHub PRs via `gh`.
+
+Key idea: **branches** are the unit, not commits. Each branch in a stack has exactly one parent — position in the stack determines lineage.
+
+## Navigation
+
+```
+What do you need?
+├─ Start a new stack          → §Creating a Stack
+├─ Add branches to a stack    → §Creating a Stack
+├─ See current stack          → §Viewing the Stack
+├─ Navigate between branches  → §Navigation
+├─ Rebase after changes       → §Rebasing
+├─ Push + create PRs          → §Submitting
+├─ Adopt existing branches    → §Adopting Branches
+├─ Remove a branch            → §Deleting
+└─ Troubleshooting            → §Gotchas
+```
+
+## Quick Reference
+
+| Command                   | What it does                                   |
+| ------------------------- | ---------------------------------------------- |
+| `stacked trunk [name]`    | Get/set trunk branch (default: main)           |
+| `stacked create <name>`   | Create branch on top of current branch         |
+| `stacked list`            | Show stack with current branch indicator       |
+| `stacked checkout <name>` | Switch to branch in stack                      |
+| `stacked top`             | Jump to top of stack                           |
+| `stacked bottom`          | Jump to bottom of stack                        |
+| `stacked sync`            | Fetch + rebase entire stack on trunk           |
+| `stacked restack`         | Rebase children after mid-stack edits          |
+| `stacked delete <name>`   | Remove branch from stack + delete git branch   |
+| `stacked submit`          | Push all branches + create/update PRs via `gh` |
+| `stacked adopt <branch>`  | Add existing git branch into the stack         |
+| `stacked log`             | Show commits grouped by branch                 |
+
+## Setup
+
+```sh
+# Set trunk if not "main"
+stacked trunk develop
+```
+
+Requires `gh` CLI installed and authenticated for `submit`.
+
+## Creating a Stack
+
+Start from trunk, build upward. Each `create` branches off the current branch.
+
+```sh
+git checkout main
+stacked create feat-auth          # branches off main
+# ... make commits ...
+stacked create feat-auth-ui       # branches off feat-auth
+# ... make commits ...
+stacked create feat-auth-tests    # branches off feat-auth-ui
+```
+
+Result: `main → feat-auth → feat-auth-ui → feat-auth-tests`
+
+Use `--from` to branch from a specific branch instead of current:
+
+```sh
+stacked create hotfix --from feat-auth
+```
+
+## Viewing the Stack
+
+```sh
+stacked list     # shows branches with ► on current
+stacked log      # shows commits grouped by branch
+```
+
+## Navigation
+
+```sh
+stacked checkout feat-auth    # switch to specific branch
+stacked top                   # jump to top of stack
+stacked bottom                # jump to bottom (trunk-adjacent)
+```
+
+## Rebasing
+
+### After mid-stack changes
+
+Edit a branch mid-stack, then rebase everything above it:
+
+```sh
+stacked checkout feat-auth
+# ... make changes, commit ...
+stacked restack                # rebases feat-auth-ui and feat-auth-tests
+```
+
+### Sync with trunk
+
+Pull latest trunk and rebase the entire stack bottom-to-top:
+
+```sh
+stacked sync
+```
+
+This fetches, then rebases each branch onto its parent starting from the bottom.
+
+## Submitting
+
+Push all stack branches and create/update GitHub PRs with correct base branches:
+
+```sh
+stacked submit              # push + create/update PRs
+stacked submit --draft      # create as draft PRs
+stacked submit --force      # force push
+stacked submit --dry-run    # show what would happen
+```
+
+Each PR targets its parent branch (not trunk), preserving the stack structure on GitHub.
+
+## Adopting Branches
+
+Bring an existing git branch into the stack:
+
+```sh
+stacked adopt existing-branch                    # append to top
+stacked adopt existing-branch --after feat-auth  # insert after specific branch
+```
+
+## Deleting
+
+```sh
+stacked delete feat-auth-ui            # removes from stack + deletes git branch
+stacked delete feat-auth-ui --force    # skip confirmation
+```
+
+## Data Model
+
+Stack metadata lives in `.git/stacked.json`. Each branch's parent is implied by array position:
+
+- `branches[0]` → parent is trunk
+- `branches[n]` → parent is `branches[n-1]`
+
+A repo can have multiple independent stacks. The current stack is determined by which branch you're on.
+
+## Typical Workflow
+
+```sh
+# 1. Start a stack
+stacked create feat-auth
+# ... work, commit ...
+
+# 2. Stack more branches
+stacked create feat-auth-ui
+# ... work, commit ...
+
+# 3. Need to fix something mid-stack
+stacked checkout feat-auth
+# ... fix, commit ...
+stacked restack              # rebase children
+
+# 4. Sync with latest main
+stacked sync
+
+# 5. Submit for review
+stacked submit --draft
+
+# 6. After review, final submit
+stacked submit
+```
+
+## Gotchas
+
+- `stacked sync` rebases bottom-to-top — resolve conflicts one branch at a time
+- `stacked submit` requires `gh` CLI authenticated (`gh auth login`)
+- PRs target parent branches, not trunk — this is intentional for stacked review
+- Trunk defaults to `main` — use `stacked trunk <name>` if your default branch differs
+- Rebase conflicts mid-stack will pause the operation — resolve and re-run

package/src/commands/adopt.ts

@@ -0,0 +1,39 @@
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, Effect, Option } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+import { StackError } from "../errors/index.js";
+
+const branchArg = Argument.string("branch");
+const afterFlag = Flag.string("after").pipe(Flag.optional, Flag.withAlias("a"));
+
+export const adopt = Command.make("adopt", { branch: branchArg, after: afterFlag }).pipe(
+  Command.withDescription("Adopt existing git branch into current stack"),
+  Command.withHandler(({ branch, after }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const exists = yield* git.branchExists(branch);
+      if (!exists) {
+        return yield* new StackError({ message: `Branch "${branch}" does not exist` });
+      }
+
+      const result = yield* stacks.currentStack();
+      if (result === null) {
+        const trunk = yield* stacks.getTrunk();
+        const currentBranch = yield* git.currentBranch();
+        if (currentBranch === trunk) {
+          yield* stacks.createStack(branch, [branch]);
+        } else {
+          yield* stacks.createStack(currentBranch, [currentBranch, branch]);
+        }
+      } else {
+        const afterBranch = Option.isSome(after) ? after.value : undefined;
+        yield* stacks.addBranch(result.name, branch, afterBranch);
+      }
+
+      yield* Console.log(`Adopted ${branch} into stack`);
+    }),
+  ),
+);

package/src/commands/bottom.ts

@@ -0,0 +1,29 @@
+import { Command } from "effect/unstable/cli";
+import { Console, Effect } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+
+export const bottom = Command.make("bottom").pipe(
+  Command.withDescription("Checkout bottom branch of stack"),
+  Command.withHandler(() =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const result = yield* stacks.currentStack();
+      if (result === null) {
+        yield* Console.error("Not on a stacked branch");
+        return;
+      }
+
+      const bottomBranch = result.stack.branches[0];
+      if (bottomBranch === undefined) {
+        yield* Console.error("Stack is empty");
+        return;
+      }
+
+      yield* git.checkout(bottomBranch);
+      yield* Console.log(`Switched to ${bottomBranch}`);
+    }),
+  ),
+);

package/src/commands/checkout.ts

@@ -0,0 +1,15 @@
+import { Argument, Command } from "effect/unstable/cli";
+import { Effect } from "effect";
+import { GitService } from "../services/Git.js";
+
+const nameArg = Argument.string("name");
+
+export const checkout = Command.make("checkout", { name: nameArg }).pipe(
+  Command.withDescription("Switch to branch in current stack"),
+  Command.withHandler(({ name }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      yield* git.checkout(name);
+    }),
+  ),
+);

package/src/commands/create.ts

@@ -0,0 +1,46 @@
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, Effect, Option } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+
+const nameArg = Argument.string("name");
+const fromFlag = Flag.string("from").pipe(Flag.optional, Flag.withAlias("f"));
+
+export const create = Command.make("create", { name: nameArg, from: fromFlag }).pipe(
+  Command.withDescription("Create a new branch on top of current branch in stack"),
+  Command.withHandler(({ name, from }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const currentBranch = yield* git.currentBranch();
+      const baseBranch = Option.isSome(from) ? from.value : currentBranch;
+      const trunk = yield* stacks.getTrunk();
+
+      const data = yield* stacks.load();
+      let stackName: string | null = null;
+
+      for (const [sName, stack] of Object.entries(data.stacks)) {
+        if (stack.branches.includes(baseBranch)) {
+          stackName = sName;
+          break;
+        }
+      }
+
+      if (stackName === null) {
+        if (baseBranch === trunk) {
+          stackName = name;
+          yield* stacks.createStack(name, []);
+        } else {
+          stackName = baseBranch;
+          yield* stacks.createStack(baseBranch, [baseBranch]);
+        }
+      }
+
+      yield* git.createBranch(name, baseBranch);
+      yield* stacks.addBranch(stackName, name, baseBranch === trunk ? undefined : baseBranch);
+
+      yield* Console.log(`Created branch ${name} on top of ${baseBranch}`);
+    }),
+  ),
+);

package/src/commands/delete.ts

@@ -0,0 +1,55 @@
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, Effect } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+import { StackError } from "../errors/index.js";
+
+const nameArg = Argument.string("name");
+const forceFlag = Flag.boolean("force").pipe(Flag.withAlias("f"));
+
+export const deleteCmd = Command.make("delete", { name: nameArg, force: forceFlag }).pipe(
+  Command.withDescription("Remove branch from stack and delete git branch"),
+  Command.withHandler(({ name, force }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const currentBranch = yield* git.currentBranch();
+      const data = yield* stacks.load();
+
+      let stackName: string | null = null;
+      for (const [sName, stack] of Object.entries(data.stacks)) {
+        if (stack.branches.includes(name)) {
+          stackName = sName;
+          break;
+        }
+      }
+
+      if (stackName === null) {
+        return yield* new StackError({ message: `Branch "${name}" not found in any stack` });
+      }
+
+      const stack = data.stacks[stackName];
+      if (stack === undefined) {
+        return yield* new StackError({ message: `Stack "${stackName}" not found` });
+      }
+      const idx = stack.branches.indexOf(name);
+
+      if (idx < stack.branches.length - 1 && !force) {
+        return yield* new StackError({
+          message: `Branch "${name}" has children. Use --force to delete anyway.`,
+        });
+      }
+
+      if (currentBranch === name) {
+        const parent = idx === 0 ? data.trunk : (stack.branches[idx - 1] ?? data.trunk);
+        yield* git.checkout(parent);
+      }
+
+      yield* stacks.removeBranch(stackName, name);
+      yield* git.deleteBranch(name, force);
+
+      yield* Console.log(`Deleted ${name}`);
+    }),
+  ),
+);

package/src/commands/index.ts

@@ -0,0 +1,34 @@
+import { Command } from "effect/unstable/cli";
+import { trunk } from "./trunk.js";
+import { create } from "./create.js";
+import { list } from "./list.js";
+import { checkout } from "./checkout.js";
+import { top } from "./top.js";
+import { bottom } from "./bottom.js";
+import { sync } from "./sync.js";
+import { restack } from "./restack.js";
+import { deleteCmd } from "./delete.js";
+import { submit } from "./submit.js";
+import { adopt } from "./adopt.js";
+import { log } from "./log.js";
+
+const root = Command.make("stacked").pipe(
+  Command.withDescription("Branch-based stacked PR manager"),
+);
+
+export const command = root.pipe(
+  Command.withSubcommands([
+    trunk,
+    create,
+    list,
+    checkout,
+    top,
+    bottom,
+    sync,
+    restack,
+    deleteCmd,
+    submit,
+    adopt,
+    log,
+  ]),
+);

package/src/commands/list.ts

@@ -0,0 +1,50 @@
+import { Command } from "effect/unstable/cli";
+import { Console, Effect } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+
+export const list = Command.make("list").pipe(
+  Command.withDescription("Show current stack with branch status"),
+  Command.withHandler(() =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const currentBranch = yield* git.currentBranch();
+      const data = yield* stacks.load();
+      const trunk = data.trunk;
+
+      let currentStackName: string | null = null;
+      for (const [name, stack] of Object.entries(data.stacks)) {
+        if (stack.branches.includes(currentBranch)) {
+          currentStackName = name;
+          break;
+        }
+      }
+
+      if (currentStackName === null) {
+        yield* Console.log("Not on a stacked branch");
+        return;
+      }
+
+      const stack = data.stacks[currentStackName];
+      if (stack === undefined) return;
+      const lines: string[] = [];
+
+      lines.push(`Stack: ${currentStackName}`);
+      lines.push(`Trunk: ${trunk}`);
+      lines.push("");
+
+      for (let i = stack.branches.length - 1; i >= 0; i--) {
+        const branch = stack.branches[i];
+        if (branch === undefined) continue;
+        const isCurrent = branch === currentBranch;
+        const marker = isCurrent ? "* " : "  ";
+        const prefix = i === 0 ? "└─" : "├─";
+        lines.push(`${marker}${prefix} ${branch}`);
+      }
+
+      yield* Console.log(lines.join("\n"));
+    }),
+  ),
+);

package/src/commands/log.ts

@@ -0,0 +1,34 @@
+import { Command } from "effect/unstable/cli";
+import { Console, Effect } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+
+export const log = Command.make("log").pipe(
+  Command.withDescription("Show commits across all branches in stack"),
+  Command.withHandler(() =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const result = yield* stacks.currentStack();
+      if (result === null) {
+        yield* Console.error("Not on a stacked branch");
+        return;
+      }
+
+      const trunk = yield* stacks.getTrunk();
+      const { branches } = result.stack;
+
+      for (let i = 0; i < branches.length; i++) {
+        const branch = branches[i];
+        if (branch === undefined) continue;
+        const base = i === 0 ? trunk : (branches[i - 1] ?? trunk);
+        yield* Console.log(`\n── ${branch} ──`);
+        const rangeLog = yield* git
+          .log(`${base}..${branch}`, { oneline: true })
+          .pipe(Effect.catch(() => Effect.succeed("(no commits)")));
+        yield* Console.log(rangeLog || "(no new commits)");
+      }
+    }),
+  ),
+);