@cvr/stacked 0.2.0 → 0.4.0

package/README.md

@@ -10,12 +10,19 @@ Built with [Effect v4](https://effect.website) and [Bun](https://bun.sh).
 bun run build   # compiles binary to bin/stacked + symlinks to ~/.bun/bin/
 ```
 
-## Usage
+## Setup
 
 ```sh
-# Set trunk branch (default: main)
+# Trunk is auto-detected (main > master > develop). Override if needed:
 stacked trunk develop
 
+# Install the Claude skill (optional):
+stacked init
+```
+
+## Usage
+
+```sh
 # Create a stack: branch from trunk
 stacked create feat-auth
 
@@ -24,17 +31,26 @@ stacked create feat-auth-ui
 
 # See the stack
 stacked list
+stacked list --json      # machine-readable output
 
 # See a specific stack by name
 stacked list feat-auth
 
+# Quick orientation
+stacked status
+stacked status --json
+
 # List all stacks in the repo
 stacked stacks
+stacked stacks --json
 
 # Navigate
-stacked top
-stacked bottom
+stacked up               # move up one branch
+stacked down             # move down one branch
+stacked top              # jump to top of stack
+stacked bottom           # jump to bottom of stack
 stacked checkout feat-auth
+stacked checkout any-branch  # falls through to git for non-stacked branches
 
 # Sync entire stack with latest trunk
 stacked sync
@@ -42,9 +58,13 @@ stacked sync
 # After editing mid-stack, rebase only children
 stacked sync --from feat-auth
 
-# Push all branches + create/update PRs
+# Push all branches + create/update PRs (force-pushes by default)
 stacked submit
 stacked submit --draft
+stacked submit --title "Add auth" --body "Implements OAuth2 flow"
+stacked submit --title "Auth,Validation,Tests"  # per-branch titles (comma-delimited)
+stacked submit --only         # process only the current branch
+stacked submit --no-force    # disable force-push
 stacked submit --dry-run
 
 # Adopt an existing branch into the stack
@@ -52,37 +72,73 @@ stacked adopt existing-branch --after feat-auth
 
 # View commits per branch
 stacked log
+stacked log --json
+
+# Detect existing branch chains and register as stacks
+stacked detect
+stacked detect --dry-run
 
-# Remove merged branches from stacks
+# Remove merged branches from stacks (prompts for confirmation)
 stacked clean
 stacked clean --dry-run
+stacked clean --yes          # skip confirmation
 
-# Remove a branch from the stack
+# Remove a branch from the stack (prompts for confirmation)
 stacked delete feat-auth-ui
+stacked delete feat-auth-ui --keep-remote  # keep the remote branch
+stacked delete feat-auth-ui --yes          # skip confirmation
+
+# Global flags (work with any command)
+stacked --verbose list   # debug output
+stacked --quiet sync     # suppress non-essential output
+stacked --no-color list  # disable colored output
+stacked --yes clean      # skip confirmation prompts
 ```
 
 ## Commands
 
-| Command           | Description                                                   |
-| ----------------- | ------------------------------------------------------------- |
-| `trunk [name]`    | Get/set trunk branch                                          |
-| `create <name>`   | Create branch on top of current                               |
-| `list [stack]`    | Show stack branches (defaults to current stack)               |
-| `stacks`          | List all stacks in the repo                                   |
-| `checkout <name>` | Switch to branch                                              |
-| `top`             | Jump to top of stack                                          |
-| `bottom`          | Jump to bottom of stack                                       |
-| `sync`            | Fetch + rebase stack on trunk (--from to start from a branch) |
-| `clean`           | Remove merged branches from stacks (--dry-run to preview)     |
-| `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                                |
+| Command           | Description                                                                    |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `trunk [name]`    | Get/set trunk branch (`--json`)                                                |
+| `create <name>`   | Create branch on top of current (`--from`, `--json`)                           |
+| `list [stack]`    | Show stack branches (`--json`)                                                 |
+| `stacks`          | List all stacks (`--json`)                                                     |
+| `status`          | Show current branch, stack position, working tree state (`--json`)             |
+| `checkout <name>` | Switch to branch (falls through to git for non-stacked branches)               |
+| `up`              | Move up one branch in the stack                                                |
+| `down`            | Move down one branch in the stack                                              |
+| `top`             | Jump to top of stack                                                           |
+| `bottom`          | Jump to bottom of stack                                                        |
+| `sync`            | Fetch + rebase stack on trunk (`--from` to start from a branch)                |
+| `detect`          | Detect branch chains and register as stacks (`--dry-run`, `--json`)            |
+| `clean`           | Remove merged branches + remote branches (`--dry-run`, `--json`)               |
+| `delete <name>`   | Remove branch from stack + git + remote (`--keep-remote`, `--force`, `--json`) |
+| `submit`          | Push + create/update PRs (`--title`, `--body`, `--only`, `--draft`, `--json`)  |
+| `adopt <branch>`  | Add existing branch to stack (`--after`, `--json`)                             |
+| `log`             | Show commits grouped by branch (`--json`)                                      |
+| `init`            | Install the stacked Claude skill to ~/.claude/skills                           |
+
+### Global Flags
+
+| Flag           | Description                   |
+| -------------- | ----------------------------- |
+| `--verbose`    | Enable debug output           |
+| `--quiet`/`-q` | Suppress non-essential output |
+| `--no-color`   | Disable colored output        |
+| `--yes`/`-y`   | Skip confirmation prompts     |
 
 ## 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]`.
 
+Trunk is auto-detected on first use by checking for `main`, `master`, or `develop` branches. Override with `stacked trunk <name>`.
+
+## Output Conventions
+
+- **stdout**: data output only (JSON, branch names, tree views) — safe for piping
+- **stderr**: progress messages, spinners, success/warning/error messages
+- All commands support `--json` for structured output
+
 ## Development
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cvr/stacked",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/stacked"
@@ -33,7 +33,8 @@
   },
   "dependencies": {
     "@effect/platform-bun": "4.0.0-beta.12",
-    "effect": "4.0.0-beta.12"
+    "effect": "4.0.0-beta.12",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",

package/scripts/build.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, lstatSync, unlinkSync, symlinkSync } from "fs";
+import { mkdirSync, lstatSync, unlinkSync, symlinkSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import * as os from "node:os";
@@ -7,6 +7,9 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const rootDir = join(__dirname, "..");
 
+const pkg = JSON.parse(readFileSync(join(rootDir, "package.json"), "utf-8"));
+const skillContent = readFileSync(join(rootDir, "skills", "stacked", "SKILL.md"), "utf-8");
+
 console.log("Building stacked...");
 
 const binDir = join(rootDir, "bin");
@@ -20,6 +23,10 @@ const buildResult = await Bun.build({
   entrypoints: [join(rootDir, "src/main.ts")],
   target: "bun",
   minify: false,
+  define: {
+    __VERSION__: JSON.stringify(pkg.version),
+    __SKILL_CONTENT__: JSON.stringify(skillContent),
+  },
   compile: {
     target: `bun-${platform}-${arch}`,
     outfile: join(binDir, "stacked"),

package/skills/stacked/SKILL.md

@@ -16,40 +16,69 @@ 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
+├─ Quick orientation          → §Status
 ├─ Navigate between branches  → §Navigation
 ├─ Rebase after changes       → §Rebasing
+├─ Amend + auto-rebase        → §Amending
 ├─ Push + create PRs          → §Submitting
 ├─ Adopt existing branches    → §Adopting Branches
+├─ Detect existing branches   → §Detecting Existing Branches
+├─ Clean up merged branches   → §Cleaning Up Merged Branches
 ├─ Remove a branch            → §Deleting
+├─ Reorganize stack           → §Stack Management
+├─ Check metadata health      → §Doctor
+├─ Install Claude skill       → §Setup
 └─ 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 [stack]`    | Show stack branches (defaults to current stack)               |
-| `stacked stacks`          | List all stacks in the repo                                   |
-| `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 stack on trunk (--from to start from a branch) |
-| `stacked clean`           | Remove merged branches from stacks (--dry-run to preview)     |
-| `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                                |
+| Command                      | What it does                                                                                |
+| ---------------------------- | ------------------------------------------------------------------------------------------- |
+| `stacked trunk [name]`       | Get/set trunk branch (`--json`)                                                             |
+| `stacked create <name>`      | Create branch on top of current (`--from`, `--json`)                                        |
+| `stacked list [stack]`       | Show stack branches (`--json`)                                                              |
+| `stacked stacks`             | List all stacks in the repo (`--json`)                                                      |
+| `stacked status`             | Show current branch, stack position, working tree state (`--json`)                          |
+| `stacked checkout <name>`    | Switch to branch (falls through to git for non-stacked branches)                            |
+| `stacked up`                 | Move up one branch in the stack                                                             |
+| `stacked down`               | Move down one branch in the stack                                                           |
+| `stacked top`                | Jump to top of stack                                                                        |
+| `stacked bottom`             | Jump to bottom of stack                                                                     |
+| `stacked sync`               | Fetch + rebase stack on trunk (`--from`, `--dry-run`, `--json`)                             |
+| `stacked detect`             | Detect branch chains and register as stacks (`--dry-run`, `--json`)                         |
+| `stacked clean`              | Remove merged branches + remote branches (`--dry-run`, `--json`)                            |
+| `stacked delete <name>`      | Remove branch from stack + git + remote (`--keep-remote`, `--force`, `--dry-run`, `--json`) |
+| `stacked submit`             | Push + create/update PRs (`--title`, `--body`, `--only`, `--draft`, `--json`)               |
+| `stacked adopt <branch>`     | Add existing git branch into the stack (`--after`, `--json`)                                |
+| `stacked log`                | Show commits grouped by branch (`--json`)                                                   |
+| `stacked amend`              | Amend current commit and rebase children (`--edit`, `--from`, `--json`)                     |
+| `stacked doctor`             | Check stack metadata for issues (`--fix`, `--json`)                                         |
+| `stacked rename <old> <new>` | Rename a stack (`--json`)                                                                   |
+| `stacked reorder <branch>`   | Move a branch within the stack (`--before`, `--after`, `--json`)                            |
+| `stacked split <branch>`     | Split stack at a branch point (`--dry-run`, `--json`)                                       |
+| `stacked init`               | Install the stacked Claude skill to ~/.claude/skills                                        |
+
+### Global Flags
+
+| Flag           | Description                   |
+| -------------- | ----------------------------- |
+| `--verbose`    | Enable debug output           |
+| `--quiet`/`-q` | Suppress non-essential output |
+| `--no-color`   | Disable colored output        |
+| `--yes`/`-y`   | Skip confirmation prompts     |
 
 ## Setup
 
 ```sh
-# Set trunk if not "main"
+# Trunk is auto-detected (main > master > develop). Override if needed:
 stacked trunk develop
+
+# Install the Claude skill (optional, compiled binary only):
+stacked init
 ```
 
-Requires `gh` CLI installed and authenticated for `submit`.
+Requires `gh` CLI installed and authenticated for `submit` and `clean`.
 
 ## Creating a Stack
 
@@ -75,26 +104,50 @@ stacked create hotfix --from feat-auth
 ## Viewing the Stack
 
 ```sh
-stacked list              # shows current stack's branches
+stacked list              # shows current stack's branches (colored tree view)
 stacked list feat-auth    # shows a specific stack by name
+stacked list --json       # machine-readable JSON output
 stacked stacks            # lists all stacks in the repo
+stacked stacks --json     # machine-readable JSON output
 stacked log               # shows commits grouped by branch
+stacked log --json        # machine-readable JSON output
+```
+
+## Status
+
+Quick orientation — shows current branch, working tree state, and stack position:
+
+```sh
+stacked status
+# Branch: feat-auth-ui
+# Working tree: clean
+# Stack: feat-auth (2 of 3)
+
+stacked status --json
+# { "branch": "feat-auth-ui", "clean": true, "stack": { "name": "feat-auth", "position": 2, "total": 3 } }
 ```
 
 ## Navigation
 
 ```sh
-stacked checkout feat-auth    # switch to specific branch
-stacked top                   # jump to top of stack
-stacked bottom                # jump to bottom (trunk-adjacent)
+stacked up                   # move up one branch
+stacked down                 # move down one branch
+stacked checkout feat-auth   # switch to specific branch
+stacked checkout any-branch  # falls through to git for non-stacked branches
+stacked top                  # jump to top of stack
+stacked bottom               # jump to bottom (trunk-adjacent)
 ```
 
+All navigation commands support `--json` for structured output. `checkout` falls through to `git checkout` for branches not in any stack.
+
 ## Syncing / Rebasing
 
 Fetch latest trunk and rebase the entire stack bottom-to-top:
 
 ```sh
 stacked sync
+stacked sync --dry-run    # preview rebase plan without executing
+stacked sync --json       # structured output: { branches: [{ name, action, base }] }
 ```
 
 After mid-stack changes, rebase only the branches above a specific point:
@@ -105,18 +158,45 @@ stacked checkout feat-auth
 stacked sync --from feat-auth    # rebases only children of feat-auth
 ```
 
+**Note:** `sync` requires a clean working tree — commit or stash before running (except with `--dry-run`). On rebase conflict, the rebase is left in progress so you can resolve it:
+
+```sh
+# On conflict:
+git rebase --continue    # after resolving conflicts
+stacked sync --from <parent-branch>    # resume syncing remaining branches
+```
+
+## Amending
+
+Amend the current commit and auto-rebase child branches:
+
+```sh
+stacked amend                     # amend + rebase children
+stacked amend --edit              # open editor for commit message
+stacked amend --from feat-auth    # start rebasing from a specific branch
+stacked amend --json              # structured output
+```
+
 ## 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
+stacked submit                                        # push + create/update PRs
+stacked submit --draft                                # create as draft PRs
+stacked submit --title "Add auth" --body "OAuth2"     # with title and body
+stacked submit --title "Auth,Validation,Tests"        # per-branch titles (comma-delimited)
+stacked submit --only                                 # process only the current branch
+stacked submit --no-force                             # disable force-push
+stacked submit --dry-run                              # show what would happen
+stacked submit --json                                 # structured JSON output
 ```
 
-Each PR targets its parent branch (not trunk), preserving the stack structure on GitHub.
+Force-push (with lease) is the default because stacked branches are always rebased. Use `--no-force` if you haven't rebased.
+
+Each PR targets its parent branch (not trunk), preserving the stack structure on GitHub. PRs include auto-generated stack metadata showing position and navigation links. The metadata is refreshed on every `submit`.
+
+**Output:** `submit` prints one line per branch to stdout: `<branch> #<number> <url> <action>`. With `--json`, outputs a structured `{ results: [...] }` array.
 
 ## Adopting Branches
 
@@ -127,24 +207,107 @@ stacked adopt existing-branch                    # append to top
 stacked adopt existing-branch --after feat-auth  # insert after specific branch
 ```
 
+## Detecting Existing Branches
+
+Auto-detect linear branch chains from git history and register them as stacks:
+
+```sh
+stacked detect              # scan and register branch chains
+stacked detect --dry-run    # preview what would be registered
+stacked detect --json       # structured JSON output
+```
+
+Only linear chains are detected. Forked branches (one parent with multiple children) are reported but skipped. Already-tracked branches are excluded.
+
 ## Cleaning Up Merged Branches
 
-After PRs are merged on GitHub, clean up the local branches and stack metadata:
+After PRs are merged on GitHub, clean up the local and remote branches and stack metadata:
 
 ```sh
-stacked clean              # removes all merged branches from all stacks
+stacked clean              # removes all merged branches (prompts for confirmation)
 stacked clean --dry-run    # preview what would be removed
+stacked clean --json       # structured JSON output
+stacked clean --yes        # skip confirmation prompt
 ```
 
-`list` also shows merge status per branch (`[merged]`, `[closed]`, `[#N]` for open PRs).
+`clean` also deletes the corresponding remote branches. `list` shows merge status per branch (`[merged]`, `[closed]`, `[#N]` for open PRs). After cleaning, run `stacked sync` to rebase remaining branches.
 
 ## Deleting
 
 ```sh
-stacked delete feat-auth-ui            # removes from stack + deletes git branch
-stacked delete feat-auth-ui --force    # skip confirmation
+stacked delete feat-auth-ui                # removes from stack + deletes local + remote branch
+stacked delete feat-auth-ui --force        # skip children check
+stacked delete feat-auth-ui --keep-remote  # don't delete remote branch
+stacked delete feat-auth-ui --dry-run      # show what would happen
+stacked delete feat-auth-ui --json         # structured JSON output
 ```
 
+Deleting a mid-stack branch with `--force` warns about potentially lost commits and recommends running `stacked sync` to rebase child branches onto the new parent.
+
+## Stack Management
+
+Rename, reorder, and split stacks:
+
+```sh
+# Rename a stack (metadata only, doesn't rename branches)
+stacked rename old-name new-name
+
+# Move a branch to a different position in the stack
+stacked reorder feat-b --before feat-a
+stacked reorder feat-b --after feat-c
+
+# Split a stack at a branch point (branches at/above become a new stack)
+stacked split feat-b
+stacked split feat-b --dry-run    # preview the split
+```
+
+After reordering, run `stacked sync` to rebase branches in new order.
+
+## Doctor
+
+Check stack metadata for issues (stale branches, missing trunk, duplicates):
+
+```sh
+stacked doctor            # report issues
+stacked doctor --fix      # auto-fix where possible (remove stale branches, auto-detect trunk)
+stacked doctor --json     # structured output
+```
+
+## Error Codes
+
+All errors include a machine-readable code for programmatic handling:
+
+| Code                  | Meaning                                     |
+| --------------------- | ------------------------------------------- |
+| `BRANCH_EXISTS`       | Branch already exists                       |
+| `BRANCH_NOT_FOUND`    | Branch not found in any stack               |
+| `NOT_IN_STACK`        | Current branch not tracked in a stack       |
+| `DIRTY_WORKTREE`      | Working tree has uncommitted changes        |
+| `REBASE_CONFLICT`     | Rebase conflict during sync/amend           |
+| `GH_NOT_INSTALLED`    | `gh` CLI not installed or not authenticated |
+| `STACK_NOT_FOUND`     | Stack not found                             |
+| `STACK_EXISTS`        | Stack name already taken                    |
+| `INVALID_BRANCH_NAME` | Branch name fails validation                |
+| `ALREADY_AT_TOP`      | Already at top of stack                     |
+| `ALREADY_AT_BOTTOM`   | Already at bottom of stack                  |
+| `TRUNK_ERROR`         | Trunk-related error                         |
+
+Usage errors (invalid args, bad state) exit code 2. Operational errors (git/gh failures) exit code 1.
+
+## Idempotent Commands
+
+`create` and `adopt` are idempotent:
+
+- `create` succeeds silently if the branch already exists and is tracked
+- `adopt` succeeds silently if the branch is already in the current stack (errors only if in a different stack)
+
+## Output Conventions
+
+- **stdout**: data output only (JSON, branch names, tree views) — safe for piping
+- **stderr**: progress messages, spinners, success/warning/error messages
+- All write commands support `--json` for structured output
+- Colored output respects `NO_COLOR`, `FORCE_COLOR`, and `--no-color`
+
 ## Data Model
 
 Stack metadata lives in `.git/stacked.json`. Each branch's parent is implied by array position:
@@ -152,6 +315,8 @@ Stack metadata lives in `.git/stacked.json`. Each branch's parent is implied by
 - `branches[0]` → parent is trunk
 - `branches[n]` → parent is `branches[n-1]`
 
+Trunk is auto-detected on first use by checking for `main`, `master`, or `develop` branches. Override with `stacked trunk <name>`.
+
 A repo can have multiple independent stacks. The current stack is determined by which branch you're on.
 
 ## Typical Workflow
@@ -165,25 +330,42 @@ stacked create feat-auth
 stacked create feat-auth-ui
 # ... work, commit ...
 
-# 3. Need to fix something mid-stack
+# 3. Quick check
+stacked status
+
+# 4. Need to fix something mid-stack
 stacked checkout feat-auth
 # ... fix, commit ...
 stacked sync --from feat-auth  # rebase children
 
-# 4. Sync with latest main
+# 5. Sync with latest main
 stacked sync
 
-# 5. Submit for review
-stacked submit --draft
+# 6. Submit for review
+stacked submit --draft --title "Add auth" --body "Implements OAuth2 flow"
 
-# 6. After review, final submit
+# 7. After review, final submit
 stacked submit
+
+# 8. Navigate quickly
+stacked up    # go to next branch
+stacked down  # go to previous branch
 ```
 
 ## Gotchas
 
+- `stacked sync` requires a clean working tree — commit or stash first (except `--dry-run`)
 - `stacked sync` rebases bottom-to-top — resolve conflicts one branch at a time
-- `stacked submit` requires `gh` CLI authenticated (`gh auth login`)
+- `stacked sync` leaves rebase in progress on conflict — resolve with `git rebase --continue`, then resume with `stacked sync --from <parent>`
+- `stacked submit` force-pushes by default (use `--no-force` to disable)
+- `stacked submit` and `stacked clean` require `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
+- PRs include auto-generated stack metadata (position, navigation links)
+- Trunk is auto-detected (`main` > `master` > `develop`) — use `stacked trunk <name>` to override
+- Forked branches (one parent, multiple children) are not supported — `detect` reports them but skips
+- `stacked delete --force` on a mid-stack branch requires `stacked sync` afterward
+- `stacked checkout` falls through to `git checkout` for branches not in a stack
+- Detached HEAD is detected and produces a clear error — checkout a branch first
+- Stack file writes are atomic (write to tmp, then rename) to prevent corruption
+- `create` and `adopt` are idempotent — safe to re-run after transient failures
+- Use `stacked doctor` to detect and fix metadata drift (stale branches, missing trunk)