santree 0.4.0 → 0.5.1

package/dist/lib/dashboard/data.js

@@ -1,4 +1,4 @@
-import { listWorktrees, extractTicketId, getBaseBranch, readAllMetadata, readSessionState, isSessionAlive, clearSessionState, getGitStatusAsync, getCommitsAheadAsync, } from "../git.js";
+import { listWorktrees, extractTicketId, getBaseBranch, readAllMetadata, readSessionState, isSessionAlive, clearSessionState, getGitStatusAsync, getCommitsAheadAsync, getDiffShortstatAsync, } from "../git.js";
 import { getPRInfoAsync, getPRChecksAsync, getPRReviewsAsync, getPRConversationCommentsAsync, getPRViewAsync, getReviewRequestedPRsAsync, getRepoNameAsync, } from "../github.js";
 import { fetchAssignedIssues } from "../linear.js";
 export async function loadDashboardData(repoRoot) {
@@ -33,10 +33,11 @@ export async function loadDashboardData(repoRoot) {
         let reviewsInfo = null;
         if (wt) {
             const base = getBaseBranch(wt.branch);
-            const [gitStatusOutput, ahead, pr] = await Promise.all([
+            const [gitStatusOutput, ahead, pr, shortstat] = await Promise.all([
                 getGitStatusAsync(wt.path),
                 getCommitsAheadAsync(wt.path, base),
                 getPRInfoAsync(wt.branch),
+                getDiffShortstatAsync(wt.path, base),
             ]);
             let sessState = readSessionState(repoRoot, issue.identifier);
             // Validate against the active multiplexer — if the session has gone, clear stale state
@@ -54,6 +55,7 @@ export async function loadDashboardData(repoRoot) {
                 gitStatus: gitStatusOutput,
                 sessionState: ss === "exited" ? null : ss,
                 sessionMessage: sessState?.message ?? null,
+                diffStats: shortstat,
             };
             prInfo = pr;
             if (pr) {
@@ -76,10 +78,11 @@ export async function loadDashboardData(repoRoot) {
         .filter(([tid]) => !consumedTicketIds.has(tid))
         .map(async ([tid, wt]) => {
         const base = getBaseBranch(wt.branch);
-        const [gitStatusOutput, ahead, pr] = await Promise.all([
+        const [gitStatusOutput, ahead, pr, shortstat] = await Promise.all([
             getGitStatusAsync(wt.path),
             getCommitsAheadAsync(wt.path, base),
             getPRInfoAsync(wt.branch),
+            getDiffShortstatAsync(wt.path, base),
         ]);
         let checksInfo = null;
         let reviewsInfo = null;
@@ -123,6 +126,7 @@ export async function loadDashboardData(repoRoot) {
                 gitStatus: gitStatusOutput,
                 sessionState: ss === "exited" ? null : ss,
                 sessionMessage: sessState?.message ?? null,
+                diffStats: shortstat,
             },
             pr,
             checks: checksInfo,
@@ -255,9 +259,10 @@ export async function loadReviewsData(repoRoot) {
             if (wt) {
                 const ticketId = extractTicketId(branch);
                 const base = getBaseBranch(branch);
-                const [gitStatusOutput, ahead] = await Promise.all([
+                const [gitStatusOutput, ahead, shortstat] = await Promise.all([
                     getGitStatusAsync(wt.path),
                     getCommitsAheadAsync(wt.path, base),
+                    getDiffShortstatAsync(wt.path, base),
                 ]);
                 let sessState = ticketId ? readSessionState(repoRoot, ticketId) : null;
                 if (sessState && ticketId && !isSessionAlive(ticketId)) {
@@ -274,6 +279,7 @@ export async function loadReviewsData(repoRoot) {
                     gitStatus: gitStatusOutput,
                     sessionState: ss === "exited" ? null : ss,
                     sessionMessage: sessState?.message ?? null,
+                    diffStats: shortstat,
                 };
             }
         }

package/dist/lib/dashboard/theme.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Dashboard theme detection — picks light vs dark based on the terminal's
+ * actual background color (queried via OSC 11) or an explicit override from
+ * SANTREE_THEME (`light` / `dark` / `auto`, default `auto`).
+ *
+ * Most foreground colors used in the dashboard are terminal-native names
+ * (`green`, `red`, `yellow`, `cyan`, etc.) that the terminal renders in a
+ * scheme-appropriate way, so the only piece of styling that needs to flip
+ * is the selection background. That's the surface this module exposes.
+ */
+export type ThemeMode = "light" | "dark";
+export interface DashboardTheme {
+    mode: ThemeMode;
+    selectionBg: string;
+}
+export declare function getThemeForMode(mode: ThemeMode): DashboardTheme;
+/**
+ * Query the terminal for its background color via OSC 11 and resolve the
+ * detected ThemeMode within `timeoutMs`. Falls back to `dark` on timeout or
+ * non-TTY stdin/stdout.
+ *
+ * The returned promise never rejects — failures resolve to `dark`.
+ */
+export declare function detectTerminalTheme(timeoutMs?: number): Promise<ThemeMode>;

package/dist/lib/dashboard/theme.js

@@ -0,0 +1,113 @@
+/**
+ * Dashboard theme detection — picks light vs dark based on the terminal's
+ * actual background color (queried via OSC 11) or an explicit override from
+ * SANTREE_THEME (`light` / `dark` / `auto`, default `auto`).
+ *
+ * Most foreground colors used in the dashboard are terminal-native names
+ * (`green`, `red`, `yellow`, `cyan`, etc.) that the terminal renders in a
+ * scheme-appropriate way, so the only piece of styling that needs to flip
+ * is the selection background. That's the surface this module exposes.
+ */
+const DARK = { mode: "dark", selectionBg: "#1e3a5f" };
+const LIGHT = { mode: "light", selectionBg: "#bfdbfe" };
+export function getThemeForMode(mode) {
+    return mode === "light" ? LIGHT : DARK;
+}
+/**
+ * Honor SANTREE_THEME env override. Returns null when set to `auto` or
+ * unset/invalid — caller should fall back to terminal detection.
+ */
+function envOverride() {
+    const raw = process.env["SANTREE_THEME"]?.toLowerCase().trim();
+    if (raw === "light")
+        return "light";
+    if (raw === "dark")
+        return "dark";
+    return null;
+}
+/**
+ * Compute relative luminance from sRGB components in the 0..1 range. Uses
+ * Rec. 709 coefficients — good enough to decide light vs dark.
+ */
+function luminance(r, g, b) {
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/**
+ * Parse an OSC 11 color response. Terminals reply with one of:
+ *   \x1b]11;rgb:RRRR/GGGG/BBBB\x07
+ *   \x1b]11;rgb:RR/GG/BB\x1b\\
+ * Component widths can be 2 or 4 hex digits. Returns luminance in 0..1, or
+ * null if the buffer doesn't contain a recognisable response.
+ */
+function parseOsc11(buf) {
+    const m = buf.match(/\x1b\]11;rgb:([0-9a-fA-F]+)\/([0-9a-fA-F]+)\/([0-9a-fA-F]+)/);
+    if (!m)
+        return null;
+    const conv = (hex) => parseInt(hex, 16) / (hex.length >= 4 ? 65535 : 255);
+    const r = conv(m[1]);
+    const g = conv(m[2]);
+    const b = conv(m[3]);
+    return luminance(r, g, b);
+}
+/**
+ * Query the terminal for its background color via OSC 11 and resolve the
+ * detected ThemeMode within `timeoutMs`. Falls back to `dark` on timeout or
+ * non-TTY stdin/stdout.
+ *
+ * The returned promise never rejects — failures resolve to `dark`.
+ */
+export function detectTerminalTheme(timeoutMs = 150) {
+    const override = envOverride();
+    if (override)
+        return Promise.resolve(override);
+    return new Promise((resolve) => {
+        if (!process.stdout.isTTY || !process.stdin.isTTY) {
+            resolve("dark");
+            return;
+        }
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        let buf = "";
+        let settled = false;
+        const finish = (mode) => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.removeListener("data", onData);
+            clearTimeout(timer);
+            if (!wasRaw) {
+                try {
+                    stdin.setRawMode(false);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            resolve(mode);
+        };
+        const onData = (chunk) => {
+            buf += chunk.toString("utf-8");
+            const lum = parseOsc11(buf);
+            if (lum !== null)
+                finish(lum > 0.5 ? "light" : "dark");
+        };
+        try {
+            if (!wasRaw)
+                stdin.setRawMode(true);
+        }
+        catch {
+            finish("dark");
+            return;
+        }
+        stdin.on("data", onData);
+        const timer = setTimeout(() => finish("dark"), timeoutMs);
+        // Send the OSC 11 query. The terminal's response is consumed by onData
+        // above and never reaches Ink's input handlers.
+        try {
+            process.stdout.write("\x1b]11;?\x07");
+        }
+        catch {
+            finish("dark");
+        }
+    });
+}

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

@@ -23,6 +23,11 @@ export interface WorktreeInfo {
     gitStatus: string;
     sessionState: "waiting" | "idle" | "active" | null;
     sessionMessage: string | null;
+    diffStats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    } | null;
 }
 export interface DashboardIssue {
     issue: LinearAssignedIssue;
@@ -58,7 +63,13 @@ export interface EnrichedReviewPR {
     worktree: WorktreeInfo | null;
 }
 export type DashboardTab = "issues" | "reviews";
-export type ActionOverlay = "mode-select" | "context-input" | "base-select" | "confirm-delete" | "confirm-setup" | "commit" | "pr-create" | null;
+export type ActionOverlay = "mode-select" | "context-input" | "base-select" | "confirm-delete" | "confirm-setup" | "commit" | "pr-create" | "diff" | null;
+export type DiffFileStatus = "M" | "A" | "D" | "R" | "C" | "U" | "?";
+export interface DiffFile {
+    path: string;
+    status: DiffFileStatus;
+    oldPath?: string;
+}
 export type CommitPhase = "idle" | "confirm-stage" | "awaiting-message" | "committing" | "pushing" | "done" | "error";
 export type PrCreatePhase = "idle" | "choose-mode" | "pushing" | "filling" | "review" | "confirm" | "creating" | "done" | "error";
 export interface DashboardState {
@@ -103,6 +114,18 @@ export interface DashboardState {
     contextInputValue: string;
     contextInputMode: "plan" | "implement" | null;
     contextInputPhase: "editing" | "review";
+    diffTicketId: string | null;
+    diffWorktreePath: string | null;
+    diffBaseBranch: string | null;
+    diffMergeBase: string | null;
+    diffFiles: DiffFile[];
+    diffFileIndex: number;
+    diffFileScrollOffset: number;
+    diffContent: string | null;
+    diffContentScrollOffset: number;
+    diffLoadingFiles: boolean;
+    diffLoadingContent: boolean;
+    diffError: string | null;
 }
 export type DashboardAction = {
     type: "SET_DATA";
@@ -237,6 +260,34 @@ export type DashboardAction = {
     type: "CONTEXT_INPUT_EDIT";
 } | {
     type: "CONTEXT_INPUT_DONE";
+} | {
+    type: "DIFF_OPEN";
+    ticketId: string;
+    worktreePath: string;
+    baseBranch: string;
+} | {
+    type: "DIFF_FILES_LOADED";
+    files: DiffFile[];
+    mergeBase: string;
+} | {
+    type: "DIFF_FILES_ERROR";
+    error: string;
+} | {
+    type: "DIFF_FILE_SELECT";
+    index: number;
+} | {
+    type: "DIFF_FILE_SCROLL";
+    offset: number;
+} | {
+    type: "DIFF_CONTENT_LOADING";
+} | {
+    type: "DIFF_CONTENT_LOADED";
+    content: string;
+} | {
+    type: "DIFF_CONTENT_SCROLL";
+    offset: number;
+} | {
+    type: "DIFF_CLOSE";
 };
 export declare const initialState: DashboardState;
 export declare function reducer(state: DashboardState, action: DashboardAction): DashboardState;

package/dist/lib/dashboard/types.js

@@ -41,6 +41,18 @@ export const initialState = {
     contextInputValue: "",
     contextInputMode: null,
     contextInputPhase: "editing",
+    diffTicketId: null,
+    diffWorktreePath: null,
+    diffBaseBranch: null,
+    diffMergeBase: null,
+    diffFiles: [],
+    diffFileIndex: 0,
+    diffFileScrollOffset: 0,
+    diffContent: null,
+    diffContentScrollOffset: 0,
+    diffLoadingFiles: false,
+    diffLoadingContent: false,
+    diffError: null,
 };
 export function reducer(state, action) {
     switch (action.type) {
@@ -273,6 +285,75 @@ export function reducer(state, action) {
                 contextInputValue: "",
                 contextInputPhase: "editing",
             };
+        case "DIFF_OPEN":
+            return {
+                ...state,
+                overlay: "diff",
+                diffTicketId: action.ticketId,
+                diffWorktreePath: action.worktreePath,
+                diffBaseBranch: action.baseBranch,
+                diffMergeBase: null,
+                diffFiles: [],
+                diffFileIndex: 0,
+                diffFileScrollOffset: 0,
+                diffContent: null,
+                diffContentScrollOffset: 0,
+                diffLoadingFiles: true,
+                diffLoadingContent: false,
+                diffError: null,
+            };
+        case "DIFF_FILES_LOADED":
+            return {
+                ...state,
+                diffFiles: action.files,
+                diffMergeBase: action.mergeBase,
+                diffFileIndex: 0,
+                diffFileScrollOffset: 0,
+                diffLoadingFiles: false,
+                diffError: null,
+            };
+        case "DIFF_FILES_ERROR":
+            return {
+                ...state,
+                diffLoadingFiles: false,
+                diffError: action.error,
+            };
+        case "DIFF_FILE_SELECT":
+            return {
+                ...state,
+                diffFileIndex: action.index,
+                diffContentScrollOffset: 0,
+            };
+        case "DIFF_FILE_SCROLL":
+            return { ...state, diffFileScrollOffset: action.offset };
+        case "DIFF_CONTENT_LOADING":
+            return { ...state, diffLoadingContent: true, diffContent: null };
+        case "DIFF_CONTENT_LOADED":
+            return {
+                ...state,
+                diffContent: action.content,
+                diffLoadingContent: false,
+                diffContentScrollOffset: 0,
+            };
+        case "DIFF_CONTENT_SCROLL":
+            return { ...state, diffContentScrollOffset: action.offset };
+        case "DIFF_CLOSE":
+            return {
+                ...state,
+                overlay: null,
+                diffTicketId: null,
+                diffWorktreePath: null,
+                diffBaseBranch: null,
+                diffMergeBase: null,
+                diffFiles: [],
+                diffFileIndex: 0,
+                diffFileScrollOffset: 0,
+                diffContent: null,
+                diffContentScrollOffset: 0,
+                diffLoadingFiles: false,
+                diffLoadingContent: false,
+                diffError: null,
+            };
         default:
             return state;
     }

package/dist/lib/git.d.ts

@@ -190,6 +190,26 @@ export declare function getCommitsAhead(baseBranch: string): number;
  * Returns 0 on failure.
  */
 export declare function getCommitsAheadAsync(cwd: string, baseBranch: string): Promise<number>;
+/**
+ * Read the SANTREE_DIFF_TOOL env var, returning the configured pager command
+ * (e.g. "delta", "diff-so-fancy") or null if unset/invalid.
+ *
+ * The value is restricted to a safe shell-token character set since it ends
+ * up in arguments passed to spawn() — even though we never use shell:true,
+ * keeping the surface tight defends against accidental misconfigurations.
+ */
+export declare function getDiffTool(): string | null;
+export interface DiffShortstat {
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+}
+/**
+ * Compute branch-only diff stats vs base (uses merge-base, like a GitHub PR
+ * diff). Includes both committed and uncommitted changes. Returns zeros on
+ * failure or when there are no changes.
+ */
+export declare function getDiffShortstatAsync(cwd: string, baseBranch: string): Promise<DiffShortstat>;
 /**
  * Check if a branch exists on the remote (origin).
  * Runs: `git ls-remote --heads origin <branchName>`

package/dist/lib/git.js

@@ -468,6 +468,43 @@ export async function getCommitsAheadAsync(cwd, baseBranch) {
     const output = await runAsync(`git -C "${cwd}" rev-list --count ${baseBranch}..HEAD`);
     return output ? parseInt(output, 10) || 0 : 0;
 }
+/**
+ * Read the SANTREE_DIFF_TOOL env var, returning the configured pager command
+ * (e.g. "delta", "diff-so-fancy") or null if unset/invalid.
+ *
+ * The value is restricted to a safe shell-token character set since it ends
+ * up in arguments passed to spawn() — even though we never use shell:true,
+ * keeping the surface tight defends against accidental misconfigurations.
+ */
+export function getDiffTool() {
+    const raw = process.env["SANTREE_DIFF_TOOL"];
+    if (!raw || !raw.trim())
+        return null;
+    const tool = raw.trim();
+    if (!/^[a-zA-Z0-9_\-/.+]+$/.test(tool))
+        return null;
+    return tool;
+}
+/**
+ * Compute branch-only diff stats vs base (uses merge-base, like a GitHub PR
+ * diff). Includes both committed and uncommitted changes. Returns zeros on
+ * failure or when there are no changes.
+ */
+export async function getDiffShortstatAsync(cwd, baseBranch) {
+    const mergeBase = await runAsync(`git -C "${cwd}" merge-base "${baseBranch}" HEAD`);
+    const ref = mergeBase ?? baseBranch;
+    const out = await runAsync(`git -C "${cwd}" diff --shortstat "${ref}"`);
+    if (!out)
+        return { filesChanged: 0, insertions: 0, deletions: 0 };
+    const fm = out.match(/(\d+) files? changed/);
+    const im = out.match(/(\d+) insertions?\(\+\)/);
+    const dm = out.match(/(\d+) deletions?\(-\)/);
+    return {
+        filesChanged: fm ? parseInt(fm[1], 10) : 0,
+        insertions: im ? parseInt(im[1], 10) : 0,
+        deletions: dm ? parseInt(dm[1], 10) : 0,
+    };
+}
 /**
  * Check if a branch exists on the remote (origin).
  * Runs: `git ls-remote --heads origin <branchName>`

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;