santree 0.3.0 → 0.4.0

package/dist/lib/dashboard/external-editor.js

@@ -0,0 +1,74 @@
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+// GUI editors that detach by default and need a `--wait` flag to make spawnSync
+// block until the file is closed. Terminal editors (vim, nvim, nano, emacs -nw)
+// already block, so they aren't listed here.
+const GUI_EDITORS_NEEDING_WAIT = new Set([
+    "zed",
+    "code",
+    "code-insiders",
+    "cursor",
+    "windsurf",
+    "subl",
+]);
+/**
+ * Open the user's editor on a temp file seeded with `initial`, then return the
+ * saved content. Empty buffer is treated as cancel (matches `git commit`).
+ *
+ * Editor resolution: SANTREE_EDITOR > VISUAL > EDITOR > "vim".
+ */
+export function editExternally(initial, ext = "md") {
+    const editorRaw = process.env["SANTREE_EDITOR"] || process.env["VISUAL"] || process.env["EDITOR"] || "vim";
+    const filePath = path.join(os.tmpdir(), `santree-edit-${Date.now()}.${ext.replace(/^\./, "")}`);
+    try {
+        fs.writeFileSync(filePath, initial);
+    }
+    catch {
+        return { ok: false, content: initial, cancelled: false };
+    }
+    const parts = editorRaw.split(/\s+/).filter(Boolean);
+    const cmd = parts[0] ?? "vim";
+    const baseArgs = parts.slice(1);
+    const needsWait = GUI_EDITORS_NEEDING_WAIT.has(path.basename(cmd)) &&
+        !baseArgs.includes("--wait") &&
+        !baseArgs.includes("-w");
+    const args = [...baseArgs, ...(needsWait ? ["--wait"] : []), filePath];
+    const wasRaw = process.stdin.isTTY ? process.stdin.isRaw : false;
+    if (process.stdin.isTTY && process.stdin.setRawMode) {
+        try {
+            process.stdin.setRawMode(false);
+        }
+        catch { }
+    }
+    const result = spawnSync(cmd, args, { stdio: "inherit" });
+    if (process.stdin.isTTY && process.stdin.setRawMode) {
+        try {
+            process.stdin.setRawMode(wasRaw);
+        }
+        catch { }
+    }
+    if (result.error || result.status !== 0) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch { }
+        return { ok: false, content: initial, cancelled: false };
+    }
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return { ok: false, content: initial, cancelled: false };
+    }
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { }
+    if (content.trim().length === 0) {
+        return { ok: true, content: "", cancelled: true };
+    }
+    return { ok: true, content, cancelled: false };
+}

package/dist/lib/git.d.ts

@@ -257,11 +257,13 @@ export declare function getDiffContent(baseBranch: string): string | null;
  */
 export declare function readSessionState(repoRoot: string, ticketId: string): SessionState | null;
 /**
- * Check if a claude process is running in a tmux window for the given ticket.
- * Windows are named after ticket IDs (possibly with suffixes like " !" or " ~").
- * Gets the pane PID and walks the process tree looking for a "claude" process.
+ * Check if a session for the given ticket is still alive in the active multiplexer.
+ * Delegates to the configured multiplexer (tmux: pane_pid + pgrep claude;
+ * cmux: workspace lookup; none: always false). Callers should also consult the
+ * .santree/session-states/<ticketId>.json file — that's the authoritative signal
+ * written by Claude Code hooks, while this is the "is the terminal still up" backstop.
  */
-export declare function isSessionAliveInTmux(ticketId: string): boolean;
+export declare function isSessionAlive(ticketId: string): boolean;
 /**
  * Delete the session state file for a given ticket.
  */

package/dist/lib/git.js

@@ -3,6 +3,7 @@ import { promisify } from "util";
 import * as path from "path";
 import * as fs from "fs";
 import { run, runAsync } from "./exec.js";
+import { getMultiplexer } from "./multiplexer/index.js";
 const execAsync = promisify(exec);
 /**
  * Find the toplevel directory of the current git repository.
@@ -610,40 +611,14 @@ export function readSessionState(repoRoot, ticketId) {
     }
 }
 /**
- * Check if a claude process is running in a tmux window for the given ticket.
- * Windows are named after ticket IDs (possibly with suffixes like " !" or " ~").
- * Gets the pane PID and walks the process tree looking for a "claude" process.
+ * Check if a session for the given ticket is still alive in the active multiplexer.
+ * Delegates to the configured multiplexer (tmux: pane_pid + pgrep claude;
+ * cmux: workspace lookup; none: always false). Callers should also consult the
+ * .santree/session-states/<ticketId>.json file — that's the authoritative signal
+ * written by Claude Code hooks, while this is the "is the terminal still up" backstop.
  */
-export function isSessionAliveInTmux(ticketId) {
-    try {
-        const output = execSync('tmux list-windows -F "#{window_name}\t#{pane_pid}"', {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "ignore"],
-        }).trim();
-        for (const line of output.split("\n")) {
-            const [name, pidStr] = line.split("\t");
-            if (!name?.startsWith(ticketId))
-                continue;
-            if (!pidStr)
-                return false;
-            // Check if any descendant of the shell PID is a claude process
-            try {
-                const ps = execSync(`pgrep -P ${pidStr} -a`, {
-                    encoding: "utf-8",
-                    stdio: ["pipe", "pipe", "ignore"],
-                }).trim();
-                return ps.split("\n").some((proc) => proc.includes("claude"));
-            }
-            catch {
-                // pgrep exits 1 when no matches — shell has no children
-                return false;
-            }
-        }
-    }
-    catch {
-        // tmux not available or not in a tmux session
-    }
-    return false;
+export function isSessionAlive(ticketId) {
+    return getMultiplexer().isSessionAlive(ticketId);
 }
 /**
  * Delete the session state file for a given ticket.

package/dist/lib/multiplexer/cmux.d.ts

@@ -0,0 +1,2 @@
+import type { Multiplexer } from "./types.js";
+export declare const cmuxMultiplexer: Multiplexer;

package/dist/lib/multiplexer/cmux.js

@@ -0,0 +1,97 @@
+import { execSync } from "child_process";
+import { shellEscape } from "./types.js";
+const CMUX_TIMEOUT_MS = 2000;
+function cmuxRun(cmd) {
+    try {
+        const stdout = execSync(cmd, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "ignore"],
+            timeout: CMUX_TIMEOUT_MS,
+        });
+        return { ok: true, stdout };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function findWorkspaceByTitle(title) {
+    // `--json` is a global flag and must precede the subcommand.
+    const result = cmuxRun("cmux --json list-workspaces");
+    if (!result.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const items = parsed.workspaces ?? [];
+        return items.find((w) => w.title === title) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export const cmuxMultiplexer = {
+    kind: "cmux",
+    isActive() {
+        return !!process.env["CMUX_SURFACE_ID"];
+    },
+    async createWindow({ name, cwd, command }) {
+        // `new-workspace` accepts --name, --cwd, --command in a single atomic call.
+        // `--command` sends "<text>\n" to the new surface after creation. cmux #1472 means
+        // programmatically created workspaces have dead PTYs, so the command may not actually
+        // execute — but the workspace + name are created, which is the visible win.
+        const parts = [`cmux new-workspace --name ${shellEscape(name)} --cwd ${shellEscape(cwd)}`];
+        if (command)
+            parts.push(`--command ${shellEscape(command)}`);
+        const created = cmuxRun(parts.join(" "));
+        if (!created.ok) {
+            return { ok: false, reason: "failed", message: "cmux new-workspace failed" };
+        }
+        return { ok: true };
+    },
+    async selectWindow(name) {
+        const ws = findWorkspaceByTitle(name);
+        if (!ws?.ref) {
+            return { ok: false, reason: "failed", message: `no cmux workspace named ${name}` };
+        }
+        const result = cmuxRun(`cmux select-workspace --workspace ${shellEscape(ws.ref)}`);
+        return result.ok ? { ok: true } : { ok: false, reason: "failed" };
+    },
+    renameWindow(currentName, newName) {
+        // `workspace-action --action rename --title <text>` defaults to the caller's
+        // workspace via $CMUX_WORKSPACE_ID. When `currentName` is provided we look up
+        // that specific workspace's ref instead.
+        let target = "";
+        if (currentName) {
+            const ws = findWorkspaceByTitle(currentName);
+            if (!ws?.ref) {
+                return { ok: false, reason: "failed", message: "cmux workspace not found" };
+            }
+            target = ` --workspace ${shellEscape(ws.ref)}`;
+        }
+        const result = cmuxRun(`cmux workspace-action --action rename --title ${shellEscape(newName)}${target}`);
+        return result.ok ? { ok: true } : { ok: false, reason: "failed" };
+    },
+    sendCommand(_name, _command) {
+        // Blocked by manaflow-ai/cmux#1472 — programmatically created workspaces have
+        // dead PTYs, so post-creation `cmux send` / `send-key` silently drop input.
+        // Initial command-on-create works via `new-workspace --command`; this path is for
+        // follow-up sends to an existing workspace, which doesn't.
+        return {
+            ok: false,
+            reason: "unsupported",
+            message: "blocked by manaflow-ai/cmux#1472",
+        };
+    },
+    isSessionAlive(ticketId) {
+        const result = cmuxRun("cmux --json list-workspaces");
+        if (!result.ok)
+            return false;
+        try {
+            const parsed = JSON.parse(result.stdout);
+            const items = parsed.workspaces ?? [];
+            return items.some((w) => typeof w.title === "string" && w.title.startsWith(ticketId));
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/dist/lib/multiplexer/index.d.ts

@@ -0,0 +1,4 @@
+import type { Multiplexer, MultiplexerKind } from "./types.js";
+export type { CreateWindowOpts, Multiplexer, MultiplexerKind, SessionResult } from "./types.js";
+export declare function getMultiplexer(): Multiplexer;
+export declare function getMultiplexerKind(): MultiplexerKind;

package/dist/lib/multiplexer/index.js

@@ -0,0 +1,20 @@
+import { cmuxMultiplexer } from "./cmux.js";
+import { noneMultiplexer } from "./none.js";
+import { tmuxMultiplexer } from "./tmux.js";
+export function getMultiplexer() {
+    const explicit = process.env["SANTREE_MULTIPLEXER"]?.toLowerCase();
+    if (explicit === "tmux")
+        return tmuxMultiplexer;
+    if (explicit === "cmux")
+        return cmuxMultiplexer;
+    if (explicit === "none")
+        return noneMultiplexer;
+    if (process.env["TMUX"])
+        return tmuxMultiplexer;
+    if (process.env["CMUX_SURFACE_ID"])
+        return cmuxMultiplexer;
+    return noneMultiplexer;
+}
+export function getMultiplexerKind() {
+    return getMultiplexer().kind;
+}

package/dist/lib/multiplexer/none.d.ts

@@ -0,0 +1,2 @@
+import type { Multiplexer } from "./types.js";
+export declare const noneMultiplexer: Multiplexer;

package/dist/lib/multiplexer/none.js

@@ -0,0 +1,22 @@
+const NOT_ACTIVE = { ok: false, reason: "not-active" };
+export const noneMultiplexer = {
+    kind: "none",
+    isActive() {
+        return false;
+    },
+    async createWindow() {
+        return NOT_ACTIVE;
+    },
+    async selectWindow() {
+        return NOT_ACTIVE;
+    },
+    renameWindow() {
+        return NOT_ACTIVE;
+    },
+    sendCommand() {
+        return NOT_ACTIVE;
+    },
+    isSessionAlive() {
+        return false;
+    },
+};

package/dist/lib/multiplexer/tmux.d.ts

@@ -0,0 +1,2 @@
+import type { Multiplexer } from "./types.js";
+export declare const tmuxMultiplexer: Multiplexer;

package/dist/lib/multiplexer/tmux.js

@@ -0,0 +1,82 @@
+import { execSync } from "child_process";
+import { shellEscape } from "./types.js";
+function tmuxSync(cmd) {
+    try {
+        execSync(cmd, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const tmuxMultiplexer = {
+    kind: "tmux",
+    isActive() {
+        return !!process.env["TMUX"];
+    },
+    async createWindow({ name, cwd, command }) {
+        if (!this.isActive())
+            return { ok: false, reason: "not-active" };
+        const ok = tmuxSync(`tmux new-window -n ${shellEscape(name)} -c ${shellEscape(cwd)}`);
+        if (!ok)
+            return { ok: false, reason: "failed", message: "tmux new-window failed" };
+        if (command) {
+            // Brief race guard: tmux occasionally drops send-keys if it arrives before the
+            // window's shell is up. The dashboard has used this for years.
+            await new Promise((r) => setTimeout(r, 100));
+            const sent = tmuxSync(`tmux send-keys -t ${shellEscape(name)} ${shellEscape(command)} Enter`);
+            if (!sent)
+                return { ok: false, reason: "failed", message: "tmux send-keys failed" };
+        }
+        return { ok: true };
+    },
+    async selectWindow(name) {
+        if (!this.isActive())
+            return { ok: false, reason: "not-active" };
+        const ok = tmuxSync(`tmux select-window -t ${shellEscape(name)}`);
+        return ok ? { ok: true } : { ok: false, reason: "failed" };
+    },
+    renameWindow(_currentName, newName) {
+        if (!this.isActive())
+            return { ok: false, reason: "not-active" };
+        // tmux rename-window operates on the current window when no -t is given, which
+        // matches every existing call site in santree.
+        const ok = tmuxSync(`tmux rename-window ${shellEscape(newName)}`);
+        return ok ? { ok: true } : { ok: false, reason: "failed" };
+    },
+    sendCommand(name, command) {
+        if (!this.isActive())
+            return { ok: false, reason: "not-active" };
+        const ok = tmuxSync(`tmux send-keys -t ${shellEscape(name)} ${shellEscape(command)} Enter`);
+        return ok ? { ok: true } : { ok: false, reason: "failed" };
+    },
+    isSessionAlive(ticketId) {
+        try {
+            const output = execSync('tmux list-windows -F "#{window_name}\t#{pane_pid}"', {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "ignore"],
+            }).trim();
+            for (const line of output.split("\n")) {
+                const [name, pidStr] = line.split("\t");
+                if (!name?.startsWith(ticketId))
+                    continue;
+                if (!pidStr)
+                    return false;
+                try {
+                    const ps = execSync(`pgrep -P ${pidStr} -a`, {
+                        encoding: "utf-8",
+                        stdio: ["pipe", "pipe", "ignore"],
+                    }).trim();
+                    return ps.split("\n").some((proc) => proc.includes("claude"));
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        catch {
+            // tmux not available
+        }
+        return false;
+    },
+};

package/dist/lib/multiplexer/types.d.ts

@@ -0,0 +1,23 @@
+export type MultiplexerKind = "tmux" | "cmux" | "none";
+export type SessionResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "not-active" | "unsupported" | "failed";
+    message?: string;
+};
+export interface CreateWindowOpts {
+    name: string;
+    cwd: string;
+    command?: string;
+}
+export interface Multiplexer {
+    readonly kind: MultiplexerKind;
+    isActive(): boolean;
+    createWindow(opts: CreateWindowOpts): Promise<SessionResult>;
+    selectWindow(name: string): Promise<SessionResult>;
+    renameWindow(currentName: string, newName: string): SessionResult;
+    sendCommand(name: string, command: string): SessionResult;
+    isSessionAlive(ticketId: string): boolean;
+}
+export declare function shellEscape(s: string): string;

package/dist/lib/multiplexer/types.js

@@ -0,0 +1,3 @@
+export function shellEscape(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}

package/dist/lib/session-signal.js

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
-import { execSync, spawn } from "child_process";
+import { spawn } from "child_process";
+import { getMultiplexer } from "./multiplexer/index.js";
 export function readStdin() {
     try {
         return fs.readFileSync(0, "utf-8");
@@ -22,7 +23,8 @@ export function extractRepoAndTicket(cwd) {
     return { repoRoot, ticketId };
 }
 export function renameTmuxWindow(ticketId, state) {
-    if (!process.env.TMUX)
+    const mux = getMultiplexer();
+    if (!mux.isActive())
         return;
     let name;
     switch (state) {
@@ -36,12 +38,7 @@ export function renameTmuxWindow(ticketId, state) {
             name = ticketId;
             break;
     }
-    try {
-        execSync(`tmux rename-window "${name}"`, { stdio: "ignore" });
-    }
-    catch {
-        // Ignore tmux errors
-    }
+    mux.renameWindow("", name);
 }
 export function runHookScript(repoRoot, state, env) {
     const script = path.join(repoRoot, ".santree", "hooks", `on-${state}.sh`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "santree",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Git worktree manager",
 	"license": "MIT",
 	"author": "Santiago Toscanini",

package/shell/init.zsh.njk

@@ -1,22 +1,45 @@
-# Santree Shell Integration for Zsh
-# ==================================
+# Santree Shell Integration for Zsh — self-caching bootstrap
+# ===========================================================
 #
-# This script provides a shell wrapper around the santree CLI to enable:
-# 1. Automatic directory switching after `worktree create` and `worktree switch` commands
-# 2. Automatic recovery when the current worktree directory is deleted
+# This output is produced by `santree helpers shell-init zsh`. The santree CLI
+# cold-starts in several seconds (Node + Pastel), so eval'ing it on every shell
+# launch is too slow. To avoid that, the bootstrap below writes the rendered
+# integration body to a cache file once, then sources the cache. Subsequent
+# shells can source the cache file directly — bypassing the santree CLI
+# entirely — and the cache self-invalidates whenever the santree binary is
+# upgraded (see the self-validation header at the top of the cache content).
 #
-# Installation:
-#   Add to your .zshrc: eval "$(santree helpers shell-init zsh)"
+# .zshrc usage (one-liner with first-run fallback):
+#   _SI=${XDG_CACHE_HOME:-$HOME/.cache}/santree/init-zsh.zsh
+#   [[ -f $_SI ]] && source $_SI || eval "$(santree helpers shell-init zsh)"
 #
-# How it works:
-# -------------
-# Since child processes cannot change the parent shell's directory, the CLI
-# outputs special markers (SANTREE_CD:path) that this wrapper intercepts
-# to perform the actual `cd` command in the current shell.
+# Behavior:
+#   - First shell after install: cache miss → runs santree (slow), writes cache.
+#   - Subsequent shells: source cache directly (fast, no santree spawn).
+#   - After `npm i -g santree` upgrade: cache mtime older than new binary,
+#     self-validation triggers a one-time regeneration in that shell.
+
+_santree_cache="${SANTREE_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/santree}/init-zsh.zsh"
+mkdir -p "${_santree_cache:h}"
+
+# Write the integration body to the cache file. Single-quoted heredoc
+# delimiter ('SANTREE_INIT_BODY_EOF__') prevents parameter expansion of the
+# body — the variables and functions are evaluated only when the cache file
+# is sourced, not during this write.
+cat > "$_santree_cache" <<'SANTREE_INIT_BODY_EOF__'
+# Santree Shell Integration for Zsh
+# ==================================
+# AUTO-GENERATED CACHE — do not edit. Regenerate with:
+#   eval "$(santree helpers shell-init zsh)"
 #
-# The wrapper also handles the case where you're in a worktree directory
-# that gets deleted (e.g., after `santree worktree clean` or `santree worktree remove`),
-# automatically returning you to the main repository or home directory.
+# Self-validation: if the santree binary on $PATH is newer than this cache
+# file, fall back to the slow path: re-run santree, which overwrites this
+# cache and re-sources the fresh integration. `return` short-circuits the
+# (now-stale) body below so its definitions don't get loaded.
+if [[ ${commands[santree]:-} -nt ${(%):-%x} ]]; then
+  eval "$(command santree helpers shell-init zsh)"
+  return
+fi
 
 # Export marker so `santree doctor` can verify shell integration is loaded
 export SANTREE_SHELL_INTEGRATION=1
@@ -172,3 +195,10 @@ if (( $+functions[compdef] )); then
     compdef _santree santree
     compdef _santree st
 fi
+SANTREE_INIT_BODY_EOF__
+
+# Source the cache we just wrote so this shell gets the integration immediately.
+# Future shells can skip the santree CLI and source the cache directly via the
+# .zshrc one-liner shown in the comment block at the top of this output.
+source "$_santree_cache"
+unset _santree_cache