santree 0.3.0 → 0.5.0

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/dist/lib/version.d.ts

@@ -0,0 +1,55 @@
+export declare const CURRENT_VERSION: string;
+export declare const SANTREE_PACKAGE = "santree";
+export declare const CLAUDE_CODE_PACKAGE = "@anthropic-ai/claude-code";
+export type PackageManager = "npm" | "pnpm" | "yarn";
+/**
+ * Fetch the latest published version of an npm package from the registry.
+ * Returns null on network/parse failure so callers can fall back to cache.
+ * The npm registry accepts scoped names (`@scope/name`) verbatim in the path.
+ */
+export declare function fetchLatestVersionFor(pkgName: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * Returns the cached latest version of a package when fresh, otherwise refetches.
+ * Falls back to a stale cache if the network call fails.
+ */
+export declare function getLatestVersionFor(pkgName: string, opts?: {
+    force?: boolean;
+}): Promise<string | null>;
+/** Read a cached latest version without hitting the network. */
+export declare function getCachedLatestVersionFor(pkgName: string): string | null;
+export declare const fetchLatestVersion: (timeoutMs?: number) => Promise<string | null>;
+export declare const getLatestVersion: (opts?: {
+    force?: boolean;
+}) => Promise<string | null>;
+export declare const getCachedLatestVersion: () => string | null;
+/**
+ * Compare semver-ish versions (major.minor.patch). Pre-release tags ignored.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ */
+export declare function compareVersions(a: string, b: string): number;
+export declare function isUpdateAvailable(current: string, latest: string): boolean;
+/**
+ * Read the locally installed Claude Code CLI version. Probes the resolved
+ * Claude binary first (which prefers cmux's bundled copy when running inside
+ * cmux — see lib/ai.ts:resolveClaudeBinary), then falls back to `claude` on
+ * PATH and the Anthropic installer location.
+ */
+export declare function getInstalledClaudeVersion(): string | null;
+/**
+ * Detect which package manager owns the running santree binary by inspecting
+ * the resolved path of `process.argv[1]`. Falls back to npm when uncertain.
+ *
+ * Common install paths:
+ *   pnpm  → ~/Library/pnpm/global/..., .../node_modules/.pnpm/santree@.../
+ *   yarn  → ~/.config/yarn/global/..., ~/.yarn/...
+ *   npm   → /usr/local/lib/node_modules/santree/..., /opt/homebrew/...
+ */
+export declare function detectPackageManager(): PackageManager;
+export interface InstallCommand {
+    cmd: string;
+    args: string[];
+    display: string;
+}
+export declare function getInstallCommandFor(pm: PackageManager, packageSpec: string): InstallCommand;
+/** Convenience: install the latest santree via the detected manager. */
+export declare function getInstallCommand(pm: PackageManager): InstallCommand;

package/dist/lib/version.js

@@ -0,0 +1,224 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as https from "https";
+import { execSync } from "child_process";
+import { createRequire } from "module";
+import { resolveClaudeBinary } from "./ai.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+export const CURRENT_VERSION = pkg.version;
+export const SANTREE_PACKAGE = "santree";
+export const CLAUDE_CODE_PACKAGE = "@anthropic-ai/claude-code";
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h
+function configDir() {
+    const xdg = process.env["XDG_CONFIG_HOME"];
+    return path.join(xdg ?? path.join(os.homedir(), ".config"), "santree");
+}
+function cachePath() {
+    return path.join(configDir(), "version-cache.json");
+}
+function isCacheEntry(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.latest === "string" &&
+        typeof v.fetchedAt === "number");
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(cachePath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        // Migrate old single-package shape `{ latest, fetchedAt }` → `{ santree: {...} }`
+        if (isCacheEntry(parsed)) {
+            return { [SANTREE_PACKAGE]: parsed };
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (isCacheEntry(v))
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function writeCacheEntry(pkgName, latest) {
+    try {
+        fs.mkdirSync(configDir(), { recursive: true });
+        const cache = readCache();
+        cache[pkgName] = { latest, fetchedAt: Date.now() };
+        fs.writeFileSync(cachePath(), JSON.stringify(cache));
+    }
+    catch {
+        // best-effort — version check is non-critical
+    }
+}
+/**
+ * Fetch the latest published version of an npm package from the registry.
+ * Returns null on network/parse failure so callers can fall back to cache.
+ * The npm registry accepts scoped names (`@scope/name`) verbatim in the path.
+ */
+export function fetchLatestVersionFor(pkgName, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+        const req = https.get(`https://registry.npmjs.org/${pkgName}/latest`, { headers: { Accept: "application/json" }, timeout: timeoutMs }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            let body = "";
+            res.setEncoding("utf-8");
+            res.on("data", (chunk) => (body += chunk));
+            res.on("end", () => {
+                try {
+                    const data = JSON.parse(body);
+                    const v = typeof data?.version === "string" ? data.version : null;
+                    if (v)
+                        writeCacheEntry(pkgName, v);
+                    resolve(v);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on("error", () => resolve(null));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(null);
+        });
+    });
+}
+/**
+ * Returns the cached latest version of a package when fresh, otherwise refetches.
+ * Falls back to a stale cache if the network call fails.
+ */
+export async function getLatestVersionFor(pkgName, opts) {
+    const cache = readCache()[pkgName];
+    if (!opts?.force && cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS) {
+        return cache.latest;
+    }
+    const fresh = await fetchLatestVersionFor(pkgName);
+    return fresh ?? cache?.latest ?? null;
+}
+/** Read a cached latest version without hitting the network. */
+export function getCachedLatestVersionFor(pkgName) {
+    return readCache()[pkgName]?.latest ?? null;
+}
+// ── Santree-specific shorthands (preserve existing call sites) ───────
+export const fetchLatestVersion = (timeoutMs) => fetchLatestVersionFor(SANTREE_PACKAGE, timeoutMs);
+export const getLatestVersion = (opts) => getLatestVersionFor(SANTREE_PACKAGE, opts);
+export const getCachedLatestVersion = () => getCachedLatestVersionFor(SANTREE_PACKAGE);
+/**
+ * Compare semver-ish versions (major.minor.patch). Pre-release tags ignored.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const stripped = v.replace(/^v/, "").split("-")[0] ?? "0";
+        return stripped.split(".").map((n) => parseInt(n, 10) || 0);
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const ai = pa[i] ?? 0;
+        const bi = pb[i] ?? 0;
+        if (ai !== bi)
+            return ai < bi ? -1 : 1;
+    }
+    return 0;
+}
+export function isUpdateAvailable(current, latest) {
+    return compareVersions(current, latest) < 0;
+}
+/**
+ * Read the locally installed Claude Code CLI version. Probes the resolved
+ * Claude binary first (which prefers cmux's bundled copy when running inside
+ * cmux — see lib/ai.ts:resolveClaudeBinary), then falls back to `claude` on
+ * PATH and the Anthropic installer location.
+ */
+export function getInstalledClaudeVersion() {
+    const resolved = resolveClaudeBinary();
+    const candidates = [
+        resolved,
+        "claude",
+        path.join(os.homedir(), ".claude", "local", "claude"),
+    ].filter((b) => b !== null);
+    const seen = new Set();
+    for (const bin of candidates) {
+        if (seen.has(bin))
+            continue;
+        seen.add(bin);
+        try {
+            const out = execSync(`${bin} --version`, {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            }).trim();
+            const v = out.split(/\s+/)[0];
+            if (v)
+                return v;
+        }
+        catch {
+            // try next
+        }
+    }
+    return null;
+}
+/**
+ * Detect which package manager owns the running santree binary by inspecting
+ * the resolved path of `process.argv[1]`. Falls back to npm when uncertain.
+ *
+ * Common install paths:
+ *   pnpm  → ~/Library/pnpm/global/..., .../node_modules/.pnpm/santree@.../
+ *   yarn  → ~/.config/yarn/global/..., ~/.yarn/...
+ *   npm   → /usr/local/lib/node_modules/santree/..., /opt/homebrew/...
+ */
+export function detectPackageManager() {
+    const candidates = [process.argv[1]].filter((p) => Boolean(p));
+    for (const candidate of candidates) {
+        let resolved = candidate;
+        try {
+            resolved = fs.realpathSync(candidate);
+        }
+        catch {
+            // keep original — still useful for path matching
+        }
+        const haystack = `${candidate}|${resolved}`;
+        if (/[\\/](?:pnpm|\.pnpm)[\\/]/i.test(haystack))
+            return "pnpm";
+        if (/[\\/]\.yarn[\\/]/i.test(haystack) || /[\\/]yarn[\\/]global[\\/]/i.test(haystack)) {
+            return "yarn";
+        }
+    }
+    return "npm";
+}
+export function getInstallCommandFor(pm, packageSpec) {
+    switch (pm) {
+        case "pnpm":
+            return {
+                cmd: "pnpm",
+                args: ["add", "-g", packageSpec],
+                display: `pnpm add -g ${packageSpec}`,
+            };
+        case "yarn":
+            return {
+                cmd: "yarn",
+                args: ["global", "add", packageSpec],
+                display: `yarn global add ${packageSpec}`,
+            };
+        case "npm":
+        default:
+            return {
+                cmd: "npm",
+                args: ["install", "-g", packageSpec],
+                display: `npm install -g ${packageSpec}`,
+            };
+    }
+}
+/** Convenience: install the latest santree via the detected manager. */
+export function getInstallCommand(pm) {
+    return getInstallCommandFor(pm, "santree@latest");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "santree",
-	"version": "0.3.0",
+	"version": "0.5.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