mintree 0.1.2

package/dist/lib/session-signal.js

@@ -0,0 +1,160 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Synchronously slurps stdin to a string. Used by hook handlers to read the
+ * JSON payload Claude pipes in. Returns "" on any failure so the caller can
+ * exit silently — a hook crash would interrupt Claude.
+ */
+export function readStdin() {
+    try {
+        return fs.readFileSync(0, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Extracts the main repo root and worktree directory name from an absolute
+ * cwd that lives under `<repo>/.mintree/worktrees/<dir>/...`. Returns null
+ * when the cwd is outside that pattern (Claude was launched somewhere else
+ * or the worktree was already removed).
+ */
+export function extractRepoAndDir(cwd) {
+    const marker = "/.mintree/worktrees/";
+    const idx = cwd.indexOf(marker);
+    if (idx === -1)
+        return null;
+    const repoRoot = cwd.slice(0, idx);
+    const rest = cwd.slice(idx + marker.length);
+    const worktreeDir = rest.split("/")[0];
+    if (!worktreeDir)
+        return null;
+    return { repoRoot, worktreeDir };
+}
+/**
+ * Pulls the issue number out of a `<issue>-<desc>` worktree directory name.
+ * Returns null when the directory name doesn't follow the convention (e.g.
+ * a manually-created worktree dropped under .mintree/worktrees/).
+ */
+export function issueIdFromWorktreeDir(worktreeDir) {
+    const m = worktreeDir.match(/^(\d+)-/);
+    return m && m[1] ? m[1] : null;
+}
+/**
+ * Writes the state file for an issue under `<repo>/.mintree/session-states/`.
+ * Creates the directory if missing. Atomic-ish: same write pattern as
+ * metadata.json — fine for state probing from the dashboard, fast to refresh.
+ */
+export function writeStateFile(repoRoot, issueId, payload) {
+    const statesDir = path.join(repoRoot, ".mintree", "session-states");
+    fs.mkdirSync(statesDir, { recursive: true });
+    const file = path.join(statesDir, `${issueId}.json`);
+    fs.writeFileSync(file, JSON.stringify(payload, null, 2) + "\n");
+    return file;
+}
+/**
+ * The only entry point the hook sub-commands call. Reads the JSON payload
+ * Claude piped in, locates the worktree+issue from the payload's `cwd`, and
+ * writes the state file. Exits 0 unconditionally — the worst case is a
+ * silent no-op, never an error that would interrupt Claude.
+ */
+export function signalState(state) {
+    const input = readStdin();
+    let data = {};
+    if (input) {
+        try {
+            data = JSON.parse(input);
+        }
+        catch {
+            process.exit(0);
+        }
+    }
+    const cwd = data.cwd || process.cwd();
+    const info = extractRepoAndDir(cwd);
+    if (!info)
+        process.exit(0);
+    const { repoRoot, worktreeDir } = info;
+    const issueId = issueIdFromWorktreeDir(worktreeDir);
+    if (!issueId)
+        process.exit(0);
+    writeStateFile(repoRoot, issueId, {
+        state,
+        session_id: data.session_id ?? "",
+        issue_id: issueId,
+        worktree_dir: worktreeDir,
+        message: state === "waiting" ? (data.message ?? null) : null,
+        at: new Date().toISOString(),
+    });
+    process.exit(0);
+}
+/**
+ * The hook tree mintree wants to see in `~/.claude/settings.json`. Each
+ * inner command runs async with a 10s timeout — slow hooks would otherwise
+ * block Claude's UI thread. The Notification entry is gated on the
+ * `permission_prompt` matcher so the dashboard's "waiting" state only
+ * lights up when Claude is actually waiting for a permission decision,
+ * not for every notification.
+ */
+export function getHooksJson() {
+    const base = "mintree helpers session-signal";
+    const opts = { async: true, timeout: 10 };
+    return {
+        Notification: [
+            {
+                matcher: "permission_prompt",
+                hooks: [{ type: "command", command: `${base} notification`, ...opts }],
+            },
+        ],
+        Stop: [{ hooks: [{ type: "command", command: `${base} stop`, ...opts }] }],
+        UserPromptSubmit: [{ hooks: [{ type: "command", command: `${base} prompt`, ...opts }] }],
+        SessionEnd: [{ hooks: [{ type: "command", command: `${base} end`, ...opts }] }],
+    };
+}
+/**
+ * Installs (or replaces) the four mintree hooks in `~/.claude/settings.json`.
+ * Existing non-mintree hooks for the same events are preserved; previous
+ * mintree entries are filtered out and re-added so re-running this is safe.
+ * Returns the path of the file we wrote.
+ */
+export function installHooks() {
+    const home = process.env["HOME"] || "";
+    const claudeDir = path.join(home, ".claude");
+    const settingsPath = path.join(claudeDir, "settings.json");
+    const created = !fs.existsSync(settingsPath);
+    let settings = {};
+    try {
+        if (!created)
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        // Corrupt settings — start fresh rather than refusing to install.
+        settings = {};
+    }
+    const required = getHooksJson();
+    const existingHooks = typeof settings["hooks"] === "object" && settings["hooks"] !== null
+        ? settings["hooks"]
+        : {};
+    for (const [event, hookEntries] of Object.entries(required)) {
+        const existing = existingHooks[event];
+        if (!Array.isArray(existing)) {
+            existingHooks[event] = hookEntries;
+            continue;
+        }
+        const filtered = existing.filter(entry => {
+            if (!entry || typeof entry !== "object")
+                return true;
+            const inner = entry.hooks ?? [];
+            return !inner.some(h => {
+                return (h !== null &&
+                    typeof h === "object" &&
+                    typeof h.command === "string" &&
+                    (h.command).includes("mintree helpers session-signal"));
+            });
+        });
+        existingHooks[event] = [...filtered, ...hookEntries];
+    }
+    settings["hooks"] = existingHooks;
+    fs.mkdirSync(claudeDir, { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    return { settingsPath, created };
+}

package/dist/lib/worktreeCreate.d.ts

@@ -0,0 +1,36 @@
+import type { PermissionMode } from "./claude.js";
+export type CreateStepKind = "ok" | "skip" | "warn";
+export type CreateStep = {
+    kind: CreateStepKind;
+    label: string;
+    detail?: string;
+};
+export type CreateOpts = {
+    base?: string;
+    work: boolean;
+    prompt?: string;
+    permissionMode?: PermissionMode;
+};
+export type CreateResult = {
+    ok: true;
+    steps: CreateStep[];
+    worktreePath: string;
+    branch: string;
+    issueId: string;
+    base?: string;
+    work: boolean;
+    promptFile?: string;
+    permissionMode?: PermissionMode;
+} | {
+    ok: false;
+    message: string;
+    hint?: string;
+};
+/**
+ * The whole `worktree create` flow as a pure function — same code path used
+ * by the CLI command and by the dashboard's `w` overlay. Validates input,
+ * resolves a base branch, runs `git worktree add`, persists metadata, runs
+ * the optional `.mintree/init.sh`, and stages the --prompt to a temp file
+ * for the work hand-off when relevant.
+ */
+export declare function runCreate(branchArg: string, opts: CreateOpts): CreateResult;

package/dist/lib/worktreeCreate.js

@@ -0,0 +1,184 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { execSync } from "child_process";
+import { parseBranch, isParseError } from "./branch.js";
+import { findMainRepoRoot, getMintreeDir, getWorktreesDir, getInitScriptPath, getDefaultBranch, branchExists, worktreeForBranch, addWorktree, pathExists, isExecutable, } from "./git.js";
+import { upsertIssue } from "./metadata.js";
+function tryRunInitScript(scriptPath, worktreePath, repoRoot) {
+    if (!pathExists(scriptPath))
+        return { ran: false };
+    if (!isExecutable(scriptPath)) {
+        return { ran: false, error: `init.sh exists but is not executable (chmod +x ${scriptPath})` };
+    }
+    try {
+        execSync(scriptPath, {
+            cwd: worktreePath,
+            env: { ...process.env, MINTREE_WORKTREE_PATH: worktreePath, MINTREE_REPO_ROOT: repoRoot },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ran: true };
+    }
+    catch (err) {
+        return {
+            ran: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Stashes a `--prompt` value into a temp file so the shell wrapper can hand
+ * it back to `worktree work` via `--prompt-file`. Plain stdout markers can't
+ * carry multi-line / shell-special text safely, hence the file.
+ */
+function writePromptFile(prompt) {
+    const fileName = `mintree-prompt-${process.pid}-${Date.now()}.txt`;
+    const filePath = path.join(os.tmpdir(), fileName);
+    fs.writeFileSync(filePath, prompt);
+    return filePath;
+}
+/**
+ * The whole `worktree create` flow as a pure function — same code path used
+ * by the CLI command and by the dashboard's `w` overlay. Validates input,
+ * resolves a base branch, runs `git worktree add`, persists metadata, runs
+ * the optional `.mintree/init.sh`, and stages the --prompt to a temp file
+ * for the work hand-off when relevant.
+ */
+export function runCreate(branchArg, opts) {
+    const root = findMainRepoRoot();
+    if (!root) {
+        return {
+            ok: false,
+            message: "Not in a git repository.",
+            hint: "Run `git init` and then `mintree init`.",
+        };
+    }
+    if (!pathExists(getMintreeDir(root))) {
+        return {
+            ok: false,
+            message: ".mintree/ not found in this repo.",
+            hint: "Run `mintree init` first.",
+        };
+    }
+    const parsed = parseBranch(branchArg);
+    if (isParseError(parsed)) {
+        return { ok: false, message: parsed.error, hint: parsed.hint };
+    }
+    const existingWorktree = worktreeForBranch(root, parsed.branch);
+    if (existingWorktree) {
+        return {
+            ok: false,
+            message: `Branch ${parsed.branch} is already checked out at ${existingWorktree}`,
+            hint: "Use `mintree worktree work` to resume, or `mintree worktree remove` to delete.",
+        };
+    }
+    const worktreePath = path.join(getWorktreesDir(root), parsed.worktreeDirName);
+    if (pathExists(worktreePath)) {
+        return {
+            ok: false,
+            message: `Worktree directory already exists: ${worktreePath}`,
+            hint: "Remove it first or pick a different branch description.",
+        };
+    }
+    const existence = branchExists(root, parsed.branch);
+    let base;
+    if (existence === null) {
+        base = opts.base ?? getDefaultBranch(root) ?? undefined;
+        if (!base) {
+            return {
+                ok: false,
+                message: "Could not determine a base branch (no origin/HEAD, no main/master).",
+                hint: "Pass --base <branch> explicitly.",
+            };
+        }
+        if (branchExists(root, base) === null) {
+            return {
+                ok: false,
+                message: `Base branch \`${base}\` does not exist locally or on origin.`,
+                hint: "Pick a different --base or fetch the missing branch first.",
+            };
+        }
+    }
+    const steps = [];
+    steps.push({
+        kind: "ok",
+        label: "parsed branch",
+        detail: `type=${parsed.type}, issue=${parsed.issueId}, desc=${parsed.desc}`,
+    });
+    try {
+        addWorktree({ repoRoot: root, branch: parsed.branch, worktreePath, base });
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err
+            ? String(err.stderr).trim()
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { ok: false, message: `git worktree add failed: ${stderr}` };
+    }
+    if (existence === "remote") {
+        steps.push({
+            kind: "ok",
+            label: "checked out tracking branch",
+            detail: `from origin/${parsed.branch}`,
+        });
+    }
+    else if (existence === "local") {
+        steps.push({
+            kind: "ok",
+            label: "checked out existing local branch",
+            detail: parsed.branch,
+        });
+    }
+    else {
+        steps.push({
+            kind: "ok",
+            label: "created new branch",
+            detail: `${parsed.branch} (from ${base})`,
+        });
+    }
+    steps.push({ kind: "ok", label: "worktree created", detail: worktreePath });
+    upsertIssue(root, parsed.issueId, base ? { base_branch: base } : {});
+    steps.push({ kind: "ok", label: "metadata updated", detail: `issue ${parsed.issueId}` });
+    const initShPath = getInitScriptPath(root);
+    const initResult = tryRunInitScript(initShPath, worktreePath, root);
+    if (initResult.ran) {
+        steps.push({ kind: "ok", label: "ran .mintree/init.sh", detail: worktreePath });
+    }
+    else if (initResult.error) {
+        steps.push({ kind: "warn", label: "init.sh failed", detail: initResult.error });
+    }
+    else if (!pathExists(initShPath)) {
+        steps.push({ kind: "skip", label: "no init.sh (skipping post-create hook)" });
+    }
+    let promptFile;
+    if (opts.work && opts.prompt && opts.prompt.length > 0) {
+        try {
+            promptFile = writePromptFile(opts.prompt);
+        }
+        catch (err) {
+            steps.push({
+                kind: "warn",
+                label: "failed to stage --prompt for hand-off",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (!opts.work && (opts.prompt || opts.permissionMode)) {
+        steps.push({
+            kind: "warn",
+            label: "ignoring --prompt / --permission-mode (only meaningful with --work)",
+        });
+    }
+    return {
+        ok: true,
+        steps,
+        worktreePath,
+        branch: parsed.branch,
+        issueId: parsed.issueId,
+        base,
+        work: opts.work,
+        promptFile,
+        permissionMode: opts.permissionMode,
+    };
+}

package/dist/lib/worktreeRemove.d.ts

@@ -0,0 +1,21 @@
+export type RemoveResult = {
+    ok: true;
+    branch: string;
+    worktreePath: string;
+    variant: "removed" | "pruned-orphan";
+    wasDirty: boolean;
+} | {
+    ok: false;
+    message: string;
+    hint?: string;
+};
+/**
+ * Removes the worktree backing `branchArg`. Same behavior as the CLI command:
+ *  - dirty + !force → refuse
+ *  - directory missing on disk → prune the dangling git reference
+ *  - otherwise → `git worktree remove` (with --force when asked)
+ *
+ * Branch and metadata are deliberately preserved so a later re-attach can
+ * resume the same Claude session.
+ */
+export declare function runRemove(branchArg: string, force: boolean): RemoveResult;

package/dist/lib/worktreeRemove.js

@@ -0,0 +1,84 @@
+import { parseBranch, isParseError } from "./branch.js";
+import { findMainRepoRoot, getMintreeDir, worktreeForBranch, isDirty, removeWorktree, pruneWorktrees, pathExists, } from "./git.js";
+/**
+ * Removes the worktree backing `branchArg`. Same behavior as the CLI command:
+ *  - dirty + !force → refuse
+ *  - directory missing on disk → prune the dangling git reference
+ *  - otherwise → `git worktree remove` (with --force when asked)
+ *
+ * Branch and metadata are deliberately preserved so a later re-attach can
+ * resume the same Claude session.
+ */
+export function runRemove(branchArg, force) {
+    const root = findMainRepoRoot();
+    if (!root) {
+        return {
+            ok: false,
+            message: "Not in a git repository.",
+            hint: "Run `git init` and then `mintree init`.",
+        };
+    }
+    if (!pathExists(getMintreeDir(root))) {
+        return {
+            ok: false,
+            message: ".mintree/ not found in this repo.",
+            hint: "Run `mintree init` first.",
+        };
+    }
+    const parsed = parseBranch(branchArg);
+    if (isParseError(parsed)) {
+        return { ok: false, message: parsed.error, hint: parsed.hint };
+    }
+    const worktreePath = worktreeForBranch(root, parsed.branch);
+    if (!worktreePath) {
+        return {
+            ok: false,
+            message: `No worktree found for branch ${parsed.branch}.`,
+            hint: "Use `mintree worktree list` to see existing worktrees.",
+        };
+    }
+    if (!pathExists(worktreePath)) {
+        try {
+            pruneWorktrees(root);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                message: `git worktree prune failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        return {
+            ok: true,
+            branch: parsed.branch,
+            worktreePath,
+            variant: "pruned-orphan",
+            wasDirty: false,
+        };
+    }
+    const dirty = isDirty(worktreePath);
+    if (dirty && !force) {
+        return {
+            ok: false,
+            message: `Worktree at ${worktreePath} has uncommitted changes.`,
+            hint: "Commit/stash first, or pass --force to discard them.",
+        };
+    }
+    try {
+        removeWorktree({ repoRoot: root, worktreePath, force });
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err
+            ? String(err.stderr).trim()
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { ok: false, message: `git worktree remove failed: ${stderr}` };
+    }
+    return {
+        ok: true,
+        branch: parsed.branch,
+        worktreePath,
+        variant: "removed",
+        wasDirty: dirty,
+    };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "mintree",
+	"version": "0.1.2",
+	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
+	"license": "MIT",
+	"author": "Martin Mineo <mmineo@canarytechnologies.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/minex-labs/mintree.git"
+	},
+	"bugs": {
+		"url": "https://github.com/minex-labs/mintree/issues"
+	},
+	"homepage": "https://github.com/minex-labs/mintree#readme",
+	"keywords": [
+		"git",
+		"worktree",
+		"cli",
+		"github",
+		"issues",
+		"claude",
+		"ai"
+	],
+	"bin": {
+		"mintree": "dist/cli.js"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"build": "rm -rf dist && node ./node_modules/typescript/bin/tsc && chmod +x dist/cli.js",
+		"dev": "node ./node_modules/typescript/bin/tsc --watch",
+		"start": "node dist/cli.js",
+		"lint": "eslint source",
+		"lint:fix": "eslint source --fix",
+		"format": "prettier --write source"
+	},
+	"files": [
+		"dist",
+		"shell",
+		"README.md"
+	],
+	"dependencies": {
+		"ink": "^6.0.0",
+		"ink-spinner": "^5.0.0",
+		"ink-text-input": "^6.0.0",
+		"pastel": "^4.0.0",
+		"react": "^19.0.0",
+		"zod": "^4.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"@types/react": "^19.0.0",
+		"@typescript-eslint/eslint-plugin": "^8.52.0",
+		"@typescript-eslint/parser": "^8.52.0",
+		"eslint": "^9.39.2",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-prettier": "^5.5.5",
+		"prettier": "^3.7.4",
+		"typescript": "^5.7.0"
+	}
+}

package/shell/init.bash

@@ -0,0 +1,106 @@
+# Mintree Shell Integration for Bash
+# ===================================
+#
+# Generated by `mintree helpers shell-init bash`. Eval this in your ~/.bashrc:
+#   eval "$(mintree helpers shell-init bash)"
+#
+# What it does:
+#  1. Wraps the `mintree` binary so the parent shell can `cd` into a freshly
+#     created worktree. The binary itself can't change the parent's cwd, so
+#     it emits `MINTREE_CD:<path>` markers on stdout that this wrapper picks
+#     up and translates into a real `cd`.
+#  2. Recovers the current shell when its cwd was deleted (e.g. after
+#     `mintree worktree remove`) — falls back to the main repo, then to $HOME.
+#  3. Exposes the `mt` / `mtw` / `mtn` aliases (`mtn` prompts for a branch).
+#  4. Exports MINTREE_SHELL_INTEGRATION=1 so `mintree doctor` can verify the
+#     wrapper is loaded.
+
+export MINTREE_SHELL_INTEGRATION=1
+
+function mintree() {
+    if [[ ! -d "$(pwd 2>/dev/null)" ]]; then
+        local current_path="$(pwd 2>/dev/null)"
+        if [[ "$current_path" == */.mintree/worktrees/* ]]; then
+            local main_repo="${current_path%%/.mintree/worktrees/*}"
+            if [[ -d "$main_repo" ]]; then
+                echo "⚠ Worktree directory deleted. Returning to main repo."
+                cd "$main_repo" || cd ~ || return 1
+            else
+                cd ~ || return 1
+            fi
+        else
+            echo "⚠ Current directory no longer exists. Returning to home."
+            cd ~ || return 1
+        fi
+    fi
+
+    _mintree_handle_markers() {
+        local clean_output="$1"
+        local target_dir
+        target_dir=$(echo "$clean_output" | grep "MINTREE_CD:" | sed 's/.*MINTREE_CD://')
+        if [[ -z "$target_dir" || ! -d "$target_dir" ]]; then
+            return 1
+        fi
+        cd "$target_dir" && echo "Switched to: $target_dir"
+
+        if [[ "$clean_output" != *MINTREE_WORK:* ]]; then
+            return 0
+        fi
+        local extra=()
+        local prompt_file
+        prompt_file=$(echo "$clean_output" | grep "MINTREE_WORK_PROMPT_FILE:" | sed 's/.*MINTREE_WORK_PROMPT_FILE://')
+        local perm_mode
+        perm_mode=$(echo "$clean_output" | grep "MINTREE_PERMISSION_MODE:" | sed 's/.*MINTREE_PERMISSION_MODE://')
+        [[ -n "$prompt_file" ]] && extra+=(--prompt-file "$prompt_file")
+        [[ -n "$perm_mode" ]] && extra+=(--permission-mode "$perm_mode")
+        command mintree worktree work "${extra[@]}"
+        return $?
+    }
+
+    if [[ "$1" == "worktree" && "$2" == "create" ]]; then
+        local output
+        output=$(command mintree "$@" 2>&1)
+        local exit_code=$?
+
+        if [[ "$output" == *MINTREE_CD:* ]]; then
+            echo "$output" | grep -vE "MINTREE_(CD|WORK|WORK_PROMPT_FILE|PERMISSION_MODE):"
+            local clean_output=$(echo "$output" | sed 's/\x1b\[[0-9;]*m//g')
+            _mintree_handle_markers "$clean_output"
+        else
+            echo "$output"
+        fi
+        return $exit_code
+    fi
+
+    if [[ "$1" == "dashboard" ]]; then
+        local marker_file
+        marker_file=$(mktemp -t mintree-markers)
+        MINTREE_MARKER_FILE="$marker_file" command mintree "$@"
+        local exit_code=$?
+        if [[ -s "$marker_file" ]]; then
+            local clean_output=$(cat "$marker_file" | sed 's/\x1b\[[0-9;]*m//g')
+            _mintree_handle_markers "$clean_output"
+        fi
+        rm -f "$marker_file"
+        return $exit_code
+    fi
+
+    command mintree "$@"
+}
+
+# Aliases as functions so they work in non-interactive shells too (bash
+# expands aliases only in interactive mode; functions always work).
+function mt() {
+    mintree "$@"
+}
+
+function mtw() {
+    mintree worktree "$@"
+}
+
+function mtn() {
+    local branch
+    read -p "Branch name: " branch
+    [[ -z "$branch" ]] && echo "Branch name required" && return 1
+    mintree worktree create "$branch" --work
+}