mintree 0.1.2

package/README.md

@@ -0,0 +1,188 @@
+# mintree
+
+> Issue-driven worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.
+
+mintree wraps the steps you do manually every time a feature begins:
+
+1. Pick an issue assigned to you on GitHub.
+2. Create a git worktree on a branch named after that issue, following the project's convention.
+3. Launch Claude Code inside the worktree with a session ID you can resume later.
+4. Live-track which Claude sessions are active, idle, or waiting.
+
+It is a smaller, opinionated cousin of [santree](https://github.com/santiagotoscanini/santree) — built on the same TypeScript + Ink + Pastel stack but stripped to GitHub-only and aligned with the `<type>/<issue>-<desc>` branch convention.
+
+---
+
+## Install
+
+```bash
+# mintree isn't on npm yet. Install via git clone + npm link — the
+# `npm install -g github:user/repo` flow has a known bug in npm 10+
+# where dependencies don't make it into the global install dir.
+git clone git@github.com:minex-labs/mintree.git ~/dev/mintree
+cd ~/dev/mintree
+npm install
+npm link
+
+# To upgrade later:
+#   cd ~/dev/mintree && git pull && npm install && npm run build
+
+# Verify
+mintree --version          # → 0.1.0
+mintree doctor             # checks toolchain (git, gh, claude, tmux, ...)
+
+# Enable the shell wrapper so `mintree worktree create` and the
+# dashboard can `cd` your shell into the new worktree.
+#
+# Use the cache-aware one-liner — it sources a cached copy on every
+# subsequent shell instead of spawning node, which keeps shell
+# startup fast. The cache regenerates itself when mintree is updated.
+cat >> ~/.zshrc <<'EOF'
+_MT=${XDG_CACHE_HOME:-$HOME/.cache}/mintree/init-zsh.zsh
+[[ -f $_MT ]] && source $_MT || eval "$(mintree helpers shell-init zsh)"
+EOF
+exec zsh
+
+# Bash users:
+cat >> ~/.bashrc <<'EOF'
+_MT=${XDG_CACHE_HOME:-$HOME/.cache}/mintree/init-bash.bash
+[[ -f "$_MT" ]] && source "$_MT" || eval "$(mintree helpers shell-init bash)"
+EOF
+```
+
+`mintree doctor` should report **all required checks pass** before you continue. The most common gaps are:
+
+- `gh` not authenticated → `gh auth login`
+- Claude Code not installed → `npm install -g @anthropic-ai/claude-code`
+- Shell integration not loaded → re-run the `echo … >> ~/.zshrc` step and start a new shell
+
+---
+
+## Per-repo setup
+
+In every repository where you want to use mintree:
+
+```bash
+cd path/to/repo
+mintree init                                   # creates .mintree/, updates .gitignore
+mintree helpers session-signal install         # optional: live session state in the dashboard
+```
+
+`init` is idempotent — re-running it is a no-op when everything is already in place.
+
+---
+
+## Daily flow
+
+### Interactive dashboard
+
+```bash
+mintree dashboard
+```
+
+Opens a full-screen TUI listing your assigned open issues, each row marked with the live state of its Claude session (`● active`, `! waiting`, `○ idle`, `— exited`, `· no session`). The right pane shows the issue body, labels, worktree info, PR status, and live session message.
+
+| Shortcut | Action                                                                |
+|----------|-----------------------------------------------------------------------|
+| `↑/↓` or `j/k` | Move between issues                                             |
+| `↵`      | Resume Claude in the existing worktree, or open the create overlay if there's none |
+| `w`      | Always open the create overlay (type + kebab description)             |
+| `d`      | Remove the selected worktree (confirmation overlay)                   |
+| `r`      | Manual refresh (auto-refreshes silently every 30s)                    |
+| `o`      | Open the issue in your browser                                        |
+| `q`/`Esc`| Quit (or cancel an open overlay)                                      |
+
+The dashboard runs in the alternate screen buffer, so closing it leaves your shell exactly as it was.
+
+### CLI
+
+Same building blocks, scriptable from any shell:
+
+```bash
+# Create a worktree, optionally launch Claude with an initial prompt
+mintree worktree create feat/100-validar-patente
+mintree worktree create feat/100-validar-patente --work --prompt "empezar issue #100"
+
+# Resume Claude in the worktree you're currently inside
+cd .mintree/worktrees/100-validar-patente
+mintree worktree work
+
+# Inspect / clean up
+mintree worktree list                          # tabular view, dirty + ahead/behind
+mintree worktree list --pr                     # also fetch PR status per branch (slower)
+mintree worktree remove fix/55-bug             # drop worktree but keep branch + session_id
+mintree worktree remove fix/55-bug --force     # discard uncommitted changes too
+mintree worktree clean                         # sweep worktrees whose PR is merged/closed
+```
+
+`mt`, `mtw`, `mtn` are shell aliases the wrapper installs for `mintree`, `mintree worktree`, and an interactive "name a branch" shortcut.
+
+---
+
+## Branch convention
+
+mintree enforces:
+
+```
+<type>/<issue>-<kebab-desc>
+```
+
+`<type>` is one of:
+
+> `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `build`, `ci`, `perf`, `style`, `revert`
+
+`<issue>` is the GitHub issue number (no `#`), `<desc>` is lowercase kebab-case. Examples: `feat/42-validacion-patente`, `fix/55-selfie-upload-timeout`.
+
+When the dashboard's `w` overlay opens, it suggests a kebab description capped at 5 words. If your repo has a `docs/conventions/git-workflow.md`, `CONTRIBUTING.md`, or `.claude/skills/` directory, mintree mentions it on the overlay so you can verify the suggestion against your project's rules — then edit the description to match.
+
+---
+
+## What gets stored where
+
+```
+<repo>/
+├── .gitignore                    # gets `.mintree/worktrees/` + session-states/ + metadata.json appended
+└── .mintree/
+    ├── metadata.json             # gitignored. <issue-id> → { base_branch?, session_id? }
+    ├── worktrees/                # gitignored
+    │   └── 100-validar-patente/  # one directory per active worktree (named <issue>-<desc>)
+    ├── session-states/           # gitignored
+    │   └── 100.json              # live state written by Claude hooks (active/waiting/idle/exited)
+    └── init.sh                   # opt-in. Runs in the new worktree post-create (copy .env, install deps, …)
+```
+
+`metadata.json` is gitignored because the `session_id` is local to your machine — sharing it would only generate noise.
+
+---
+
+## Claude Code integrations
+
+- **Sessions persist by issue**: each issue gets a UUID stored in `metadata.json`. Subsequent `worktree work` calls pass `--resume <uuid>` so Claude reopens the same conversation.
+- **Live state** (optional): the four hooks installed by `mintree helpers session-signal install` write the current Claude state to `.mintree/session-states/<issue>.json` on every prompt / stop / notification / session-end. The dashboard reads those files to colour each row in real time.
+- **Remote Control** (optional): `mintree doctor` checks `~/.claude.json` for `remoteControlAtStartup: true`. Enabling it lets you continue a local session from a different device.
+
+---
+
+## Troubleshooting
+
+- `mintree doctor` is the first stop. It surfaces missing tools, unauthenticated CLIs, missing hooks, and gitignore drift.
+- The shell wrapper exports `MINTREE_SHELL_INTEGRATION=1` — if doctor says it's missing, the wrapper isn't being loaded by your shell init file.
+- If the dashboard ever opens with a stale session state, press `r` to force a refetch (the auto-refresh runs every 30s).
+
+---
+
+## Why not santree
+
+mintree was written for projects that have:
+
+- GitHub Issues as the only tracker (santree supports both Linear and GitHub).
+- An established branch convention without the `gh-` prefix santree imposes.
+- Skills (`.claude/skills/`) that own the SDD + TDD flow — mintree intentionally leaves the rich PR-create / PR-review prompts out of scope.
+
+The implementation copies santree's stack (TypeScript + Ink + Pastel + Zod) and visual style (split pane, alt-screen, marker-based shell wrapper) so the two feel similar in use.
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import Pastel from "pastel";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const app = new Pastel({
+    importMeta: import.meta,
+    name: "mintree",
+    version,
+    description: "Issue-driven worktrees + Claude Code sessions for repos that already have an opinionated SDD+TDD flow.",
+});
+await app.run();

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,2 @@
+export declare const description = "Interactive dashboard listing open issues assigned to you with worktree + session state";
+export default function Dashboard(): import("react/jsx-runtime").JSX.Element;