cluttry 1.0.3 → 1.5.0

package/README.md

@@ -1,444 +1,347 @@
 # cluttry
 
-Git worktrees made painless for **vibecoders** running parallel AI-agent sessions.
+AI session lifecycle in git worktrees.
 
 **CLI command:** `cry`
 
-## Why This Exists
-
-When working with AI coding assistants like Claude, you often want to run multiple parallel sessions on different branches. Git worktrees are perfect for this—each worktree is a separate checkout where an agent can work independently.
-
-But managing worktrees manually is tedious:
-- You have to remember the `git worktree` commands
-- You need to copy your `.env` files and secrets to each worktree
-- You want to run setup commands like `npm install` automatically
-- You want to launch your AI agent in the new worktree
-
-**cry** solves all of this with one command.
-
-## Installation
-
-### Using Bun (recommended)
-
-```bash
-# Install globally with Bun
-bun add -g cluttry
-
-# Or clone and link
-git clone https://github.com/your-username/cluttry.git
-cd cluttry
-bun install
-bun link
-```
-
-### Using npm
+## 60-Second Quickstart
 
 ```bash
-# Install globally with npm
+# Install
 npm install -g cluttry
 
-# Or clone and link
-git clone https://github.com/your-username/cluttry.git
-cd cluttry
-npm install
-npm link
-```
-
-**Requirements:** Bun 1.0+ or Node.js 18+, Git 2.5+
-
-## Quick Start
-
-```bash
-# Initialize cry in your repository
+# Initialize in your repo
 cd your-repo
 cry init
 
-# Spawn a new worktree for a feature branch
-cry spawn feature-auth --new
-
-# List all worktrees
-cry list
-
-# Remove a worktree when done
-cry rm feature-auth --with-branch
+# One command: create worktree → launch Claude → finish when done
+cry feat-login claude --finish-on-exit
 ```
 
-## Commands
+That's it. When Claude exits, you'll see a menu to commit, create a PR, and clean up.
 
-### `cry init`
+## The Lifecycle
 
-Initialize cry configuration in your repository.
+Every AI coding session follows four phases:
 
-```bash
-cry init [--force]
 ```
-
-Creates:
-- `.cry.json` — tracked config with defaults
-- `.cry.local.json` — gitignored local overrides
-- Updates `.gitignore` to ignore local config and `.worktrees/`
-
-### `cry spawn <branch>`
-
-Create a worktree for a branch with automatic secrets handling.
-
-```bash
-cry spawn <branch> [options]
-
-Options:
-  -n, --new            Create a new branch
-  -p, --path <dir>     Explicit worktree path
-  -b, --base <dir>     Base directory for worktrees
-  -m, --mode <mode>    Secret handling: copy, symlink, or none (default: copy)
-  -r, --run <cmd>      Command to run after creation
-  -a, --agent <agent>  Launch agent: claude or none (default: none)
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│  START  │ →  │  WORK   │ →  │ FINISH  │ →  │ CLEANUP │
+└─────────┘    └─────────┘    └─────────┘    └─────────┘
+cry spawn      (agent works)   cry finish     (automatic)
 ```
 
-**Examples:**
+### 1. Start
 
-```bash
-# Create worktree for existing branch
-cry spawn feature-auth
-
-# Create new branch and worktree
-cry spawn feature-oauth --new
+Create an isolated worktree with secrets copied:
 
-# Spawn with npm install and launch Claude
-cry spawn feature-api --new --run "npm install" --agent claude
+```bash
+# Shorthand (recommended)
+cry feat-auth claude
 
-# Use symlinks instead of copying secrets
-cry spawn bugfix-123 --mode symlink
+# Explicit
+cry spawn feat-auth --new --agent claude
 
-# Custom worktree location
-cry spawn hotfix --path ~/worktrees/myrepo-hotfix
+# Full lifecycle in one command
+cry feat-auth claude --finish-on-exit
 ```
 
-### `cry list`
+### 2. Work
 
-List all worktrees with their status.
+Your AI agent works in the isolated worktree. Each worktree has:
+- Its own branch
+- Copy of your `.env` and secret files
+- Independent git state
 
-```bash
-cry list [--json]
-```
-
-Shows: branch name, commit SHA, dirty status, last modified time, and path.
+Run multiple sessions in parallel—each in its own terminal.
 
-### `cry open <branch-or-path>`
+### 3. Finish (PR-first)
 
-Navigate to or run a command in a worktree.
+From inside the worktree:
 
 ```bash
-cry open <branch-or-path> [--cmd <cmd>]
+cry finish
 ```
 
-**Examples:**
+Interactive flow:
+1. Shows session summary (branch, commits, diff stats)
+2. If dirty: offers to commit (with suggested message from branch name)
+3. Pushes branch and creates PR via `gh` CLI
+4. Offers cleanup prompt
 
+Non-interactive:
 ```bash
-# Show path and cd instructions
-cry open feature-auth
-
-# Run a command in the worktree
-cry open feature-auth --cmd "npm test"
-
-# Open in VS Code
-cry open feature-auth --cmd "code ."
+cry finish -m "Add user authentication" --cleanup
 ```
 
-### `cry rm <branch-or-path>`
+### 4. Cleanup
 
-Remove a worktree safely.
+Handled automatically by `cry finish`, or manually:
 
 ```bash
-cry rm <branch-or-path> [options]
-
-Options:
-  -b, --with-branch    Also delete the branch
-  -f, --force          Force removal even if dirty
-  -y, --yes            Skip confirmation prompts
+cry rm feat-auth --with-branch
 ```
 
-**Examples:**
+## Installation
 
 ```bash
-# Remove worktree only
-cry rm feature-auth
-
-# Remove worktree and delete branch
-cry rm feature-auth --with-branch
-
-# Force remove dirty worktree
-cry rm feature-auth --force --yes
+npm install -g cluttry
+# or
+bun add -g cluttry
 ```
 
-### `cry prune`
+**Requirements:** Node.js 18+ or Bun 1.0+, Git 2.5+
 
-Clean up stale worktree references.
+### Shell Completions
 
 ```bash
-cry prune
-```
-
-Runs `git worktree prune` and shows what was cleaned.
-
-### `cry doctor`
+# Fish
+cry completions fish > ~/.config/fish/completions/cry.fish
 
-Check your cry configuration for issues.
+# Bash
+cry completions bash >> ~/.bashrc
 
-```bash
-cry doctor
+# Zsh
+cry completions zsh > ~/.zsh/completions/_cry
 ```
 
-Checks:
-- Config file exists
-- Local config is gitignored
-- `.worktrees/` is gitignored
-- Include files are safely gitignored
-- Agent command is available
-
 ## Configuration
 
-### `.cry.json` (tracked)
+After `cry init`, edit `.cry.json`:
 
 ```json
 {
+  "include": [".env", ".env.*", "config/secrets.json"],
   "defaultMode": "copy",
-  "include": [".env", ".env.*", ".env.local", "config/secrets/*.json"],
-  "worktreeBaseDir": null,
-  "hooks": {
-    "postCreate": ["npm install"]
-  },
+  "hooks": { "postCreate": ["npm install"] },
   "agentCommand": "claude"
 }
 ```
 
-| Option | Description |
-|--------|-------------|
-| `defaultMode` | How to handle secrets: `copy`, `symlink`, or `none` |
-| `include` | Glob patterns for files to copy/symlink |
-| `worktreeBaseDir` | Base directory for worktrees (default: `.worktrees/`) |
-| `hooks.postCreate` | Commands to run after spawning |
-| `agentCommand` | Command to launch AI agent |
-
-### `.cry.local.json` (gitignored)
-
-Machine-specific overrides:
-
-```json
-{
-  "worktreeBaseDir": "/home/user/worktrees",
-  "include": ["config/local-secrets.json"],
-  "hooks": {
-    "postCreate": ["npm install", "./setup-dev.sh"]
-  },
-  "agentCommand": "cursor"
-}
-```
+| Key | Description |
+|-----|-------------|
+| `include` | Glob patterns for files to copy to worktrees |
+| `defaultMode` | `copy`, `symlink`, or `none` |
+| `hooks.postCreate` | Commands to run after spawn |
+| `agentCommand` | Agent CLI command (default: `claude`) |
+| `editorCommand` | Editor command (default: `code`) |
 
-Local config merges with tracked config:
-- `include` arrays are concatenated
-- `hooks.postCreate` arrays are concatenated
-- Other values override
+Machine-specific overrides go in `.cry.local.json` (gitignored).
 
 ## Security Model
 
-**cry is safe by default.** It enforces strict rules about which files can be copied or symlinked:
+**Tracked files are never copied.** This is enforced, not optional.
 
-### Rule 1: Never Copy Tracked Files
+For a file to be copied to a worktree, it must pass both checks:
+1. **Not tracked** by git (`git ls-files` returns nothing)
+2. **Ignored** by git (listed in `.gitignore`)
 
-Files that are tracked by git are **never** copied or symlinked. This prevents accidentally exposing source code or committing secrets that should stay local.
+This means:
+- Your `.env` files copy automatically (they're gitignored)
+- Your source code stays in git (tracked files can't be copied)
+- Accidentally tracked secrets won't propagate
+
+### Verify before spawning
 
 ```bash
-# Checked with: git ls-files --error-unmatch <file>
-# If file is tracked → REFUSED
+# See exactly what will be copied
+cry explain-copy
+
+# Preview spawn without changes
+cry spawn feat-test --new --dry-run
 ```
 
-### Rule 2: Only Copy Ignored Files
+### Copy vs Symlink
 
-Files must be explicitly ignored by git (in `.gitignore`) to be eligible for copy/symlink.
+| Mode | Behavior |
+|------|----------|
+| `copy` | Independent copies. Safe default. |
+| `symlink` | Linked to original. Changes sync everywhere. |
+| `none` | Nothing copied. Set up secrets manually. |
 
-```bash
-# Checked with: git check-ignore -q <file>
-# If file is NOT ignored → REFUSED
-```
+## Commands
 
-### Implications
+### Session Lifecycle
 
-- Your `.env` files must be in `.gitignore` ✓
-- Your OAuth JSON files must be in `.gitignore` ✓
-- Source files can never be in `include` patterns ✗
+| Command | Purpose |
+|---------|---------|
+| `cry spawn <branch>` | Create worktree |
+| `cry finish` | Commit → PR → cleanup |
+| `cry rm <branch>` | Remove worktree |
 
-### Copy vs Symlink Tradeoffs
+### Navigation
 
-| Mode | Pros | Cons |
-|------|------|------|
-| `copy` | Independent copies, safe if original changes | Takes disk space, copies can drift |
-| `symlink` | Always in sync, saves space | Changes affect all worktrees |
-| `none` | No secrets copied | Must set up secrets manually |
+| Command | Purpose |
+|---------|---------|
+| `cry list` | List all worktrees |
+| `cry open <branch>` | Open in agent/editor |
+| `cry resume <branch>` | Resume session |
 
-**Recommendation:** Use `copy` (default) for most cases. Use `symlink` if you frequently update secrets and want all worktrees to stay in sync.
+### Maintenance
 
-## Using with AI Agents
+| Command | Purpose |
+|---------|---------|
+| `cry gc` | Clean stale sessions |
+| `cry prune` | Clean git worktree refs |
+| `cry doctor` | Check configuration |
 
-### Recommended Pattern
+## Key Flags
 
-1. **Initialize once per repo:**
-   ```bash
-   cry init
-   ```
+### `cry spawn`
 
-2. **Configure your secrets:**
-   Edit `.cry.json` to include your secret files:
-   ```json
-   {
-     "include": [".env", ".env.local", "config/oauth*.json"]
-   }
-   ```
+```
+-n, --new               Create new branch
+-a, --agent <agent>     Launch agent (claude, cursor, none)
+--finish-on-exit        Show finish menu when agent exits
+--base-branch <branch>  PR target branch
+-m, --mode <mode>       Secret handling (copy, symlink, none)
+-r, --run <cmd>         Run command after spawn
+--dry-run               Preview without creating
+```
 
-3. **Spawn a worktree for each task:**
-   ```bash
-   cry spawn fix-auth-bug --new --run "npm install" --agent claude
-   ```
+### `cry finish`
 
-4. **Work with your AI agent in the worktree**
+```
+-m, --message <msg>     Commit with message (non-interactive)
+--cleanup               Auto-cleanup after PR
+--skip-commit           Skip commit step
+--non-interactive       Never prompt
+--dry-run               Preview without executing
+```
 
-5. **Clean up when done:**
-   ```bash
-   cry rm fix-auth-bug --with-branch
-   ```
+### `cry rm`
 
-### Denying AI Access to Secrets
+```
+-b, --with-branch       Also delete the branch
+-f, --force             Force remove dirty worktree
+-y, --yes               Skip confirmation
+```
 
-If you want to prevent AI agents from reading your secret files:
+## FAQ
 
-**For Claude Code:** Add to your `.clauderc`:
-```json
-{
-  "deny": [".env", ".env.*", "config/secrets/**"]
-}
-```
+### Why not just `git worktree`?
 
-**For other agents:** Check their documentation for file access controls.
+| Task | git worktree | cry |
+|------|--------------|-----|
+| Create worktree | `git worktree add -b feat ../feat` | `cry feat` |
+| Copy secrets | Manual copy | Automatic |
+| Run setup | `cd ../feat && npm install` | `--run "npm install"` |
+| Launch agent | `cd ../feat && claude` | `--agent claude` |
+| Create PR | Switch context, push, open browser | `cry finish` |
+| Cleanup | `git worktree remove`, `git branch -d` | `cry rm --with-branch` |
 
-### Multiple Parallel Sessions
+cry handles the lifecycle. git worktree is just step 1.
 
-Run multiple agents on different features simultaneously:
+### Can I use this without AI agents?
+
+Yes. Skip `--agent` and use worktrees for any parallel work:
 
 ```bash
-# Terminal 1
-cry spawn feature-auth --new --agent claude
+cry hotfix-123
+# ... work manually ...
+cry finish
+```
 
-# Terminal 2
-cry spawn feature-payments --new --agent claude
+### What if `gh` isn't installed?
 
-# Terminal 3
-cry spawn bugfix-123 --agent claude
-```
+`cry finish` prints manual PR instructions and exits cleanly (exit 0). Install `gh` for automatic PR creation:
 
-Each agent works in an isolated worktree with its own copy of secrets.
+```bash
+brew install gh && gh auth login
+```
 
-## Project Structure
+### How do I prevent AI from reading secrets?
 
+For Claude Code, add to `.clauderc`:
+```json
+{ "deny": [".env", ".env.*"] }
 ```
-.worktrees/           # Default worktree location (gitignored)
-├── feature-auth/     # Worktree for feature-auth branch
-├── feature-payments/ # Worktree for feature-payments branch
-└── bugfix-123/       # Worktree for bugfix-123 branch
 
-.cry.json             # Tracked config
-.cry.local.json       # Local overrides (gitignored)
+### Can I change the worktree location?
+
+Default is `.worktrees/` in your repo. Override:
+
+```bash
+# Per-spawn
+cry spawn feat --path ~/worktrees/myrepo-feat
+
+# Globally in .cry.local.json
+{ "worktreeBaseDir": "/home/user/worktrees" }
 ```
 
 ## Troubleshooting
 
 ### "Not a git repository"
 
-Run cry commands from within a git repository.
+Run cry from inside a git repo.
+
+### "Destination already exists"
 
-### "Worktree already exists for branch"
+The worktree path exists. Remove it or use `--path`:
 
-A worktree already exists for that branch. Remove it first:
 ```bash
-cry rm <branch>
+rm -rf .worktrees/feat-auth
+# or
+cry spawn feat-auth --path .worktrees/feat-auth-v2
 ```
 
-### "Destination already exists"
+### "A worktree already exists for branch"
+
+Remove the existing worktree first:
 
-The target directory exists. Either remove it or specify a different path:
 ```bash
-cry spawn feature --path ./different-path
+cry rm feat-auth
 ```
 
-### "File is tracked by git"
+### "File is tracked by git" / "File is not ignored"
+
+Files in `include` must be gitignored and untracked:
 
-A file in your `include` patterns is tracked by git. Remove it from tracking:
 ```bash
-git rm --cached <file>
-echo "<file>" >> .gitignore
+# Add to .gitignore
+echo "secrets.json" >> .gitignore
+
+# If already tracked, untrack it
+git rm --cached secrets.json
 ```
 
-### "File is not ignored by git"
+### "Worktree has uncommitted changes"
+
+Commit or discard changes before removing:
 
-A file in your `include` patterns isn't in `.gitignore`. Add it:
 ```bash
-echo "<file>" >> .gitignore
+cry rm feat-auth --force  # discards changes
 ```
 
 ### Agent command not found
 
-Install the AI agent CLI or update `agentCommand` in your config:
+Install the agent CLI:
+
 ```bash
-# For Claude
+# Claude
 npm install -g @anthropic-ai/claude-code
 
-# Or override in .cry.local.json
-{
-  "agentCommand": "your-agent-command"
-}
+# Or set custom command
+echo '{"agentCommand": "your-agent"}' > .cry.local.json
+```
+
+### PR creation failed
+
+Check GitHub CLI auth:
+
+```bash
+gh auth status
+gh auth login  # if needed
 ```
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Run tests
 npm test
-
-# Watch mode
-npm run dev
 ```
 
-## Tech Stack
-
-- **Language:** TypeScript (Node.js)
-- **CLI Framework:** Commander.js
-- **Testing:** Vitest
-- **Dependencies:** Minimal (commander, glob)
-
-### Why TypeScript/Node.js?
-
-1. **Accessible:** Most developers working with web projects have Node.js installed
-2. **Cross-platform:** Works on macOS, Linux, and Windows
-3. **Contribution-friendly:** TypeScript is widely known and well-typed
-4. **Rich ecosystem:** Excellent CLI tooling available
-
 ## License
 
 MIT
-
-## Contributing
-
-Contributions welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Write tests for new functionality
-4. Submit a pull request
-
-## Acknowledgments
-
-Inspired by the need to run parallel AI coding sessions efficiently. Built for vibecoders everywhere.

package/dist/commands/completions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * cry completions command
+ *
+ * Generate shell completions for bash, zsh, and fish.
+ */
+type ShellType = 'bash' | 'zsh' | 'fish';
+interface CompletionsOptions {
+    shell?: ShellType;
+}
+export declare function completions(shell: string | undefined, options: CompletionsOptions): Promise<void>;
+/**
+ * Get list of subcommands (for testing)
+ */
+export declare function getSubcommands(): string[];
+export {};
+//# sourceMappingURL=completions.d.ts.map

package/dist/commands/completions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/commands/completions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,KAAK,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzC,UAAU,kBAAkB;IAC1B,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAQD,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCvG;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC"}