santree 0.7.4 → 0.7.5

package/dist/commands/worktree/switch.js

@@ -1,23 +1,15 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from "react";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Text, Box } from "ink";
 import { z } from "zod";
 import { getWorktreePath } from "../../lib/git.js";
+import { formatCdCommand } from "../../lib/cd-hint.js";
 export const description = "Switch to another worktree";
 export const args = z.tuple([z.string().describe("Branch name to switch to")]);
 export default function Switch({ args }) {
     const [branchName] = args;
-    const hasOutputRef = useRef(false);
     // Find worktree path synchronously
     const worktreePath = getWorktreePath(branchName);
-    // Output SANTREE_CD once (before Ink fully renders)
-    useEffect(() => {
-        if (worktreePath && !hasOutputRef.current) {
-            hasOutputRef.current = true;
-            process.stdout.write(`SANTREE_CD:${worktreePath}\n`);
-        }
-    }, [worktreePath]);
     const status = worktreePath ? "done" : "error";
     const error = worktreePath ? null : `Worktree not found for branch: ${branchName}`;
-    return (_jsxs(Box, { flexDirection: "column", padding: 1, width: "100%", children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: "cyan", children: "\uD83D\uDD00 Switch" }) }), _jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: status === "error" ? "red" : "green", paddingX: 1, width: "100%", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "branch:" }), _jsx(Text, { color: "cyan", bold: true, children: branchName })] }), worktreePath && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "path:" }), _jsx(Text, { dimColor: true, children: worktreePath })] }))] }), _jsxs(Box, { marginTop: 1, children: [status === "done" && (_jsx(Text, { color: "green", bold: true, children: "\u2713 Switching to worktree" })), status === "error" && (_jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", error] }))] })] }));
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, width: "100%", children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: "cyan", children: "\uD83D\uDD00 Switch" }) }), _jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: status === "error" ? "red" : "green", paddingX: 1, width: "100%", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "branch:" }), _jsx(Text, { color: "cyan", bold: true, children: branchName })] }), worktreePath && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "path:" }), _jsx(Text, { dimColor: true, children: worktreePath })] }))] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [status === "done" && worktreePath && (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "\u2192 Run this to enter the worktree:" }), _jsxs(Text, { color: "cyan", children: [" ", formatCdCommand({ path: worktreePath })] })] })), status === "error" && (_jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", error] }))] })] }));
 }

package/dist/lib/cd-hint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * santree is a plain binary — a child process can't change its parent shell's
+ * working directory. So when a command wants you to land in a worktree, it
+ * prints the command for you to run. (Dashboard flows with tmux/cmux open a new
+ * window in the right directory instead and never need this.)
+ */
+export interface CdHint {
+    path: string;
+    /** Append a `worktree work` launch after the cd. */
+    work?: {
+        mode: "plan" | "implement" | string;
+        contextFile?: string;
+    };
+}
+/** The shell command to enter a worktree (and optionally start work). */
+export declare function formatCdCommand(hint: CdHint): string;
+/** Print the cd hint to stdout (for non-Ink contexts, e.g. after the dashboard exits). */
+export declare function printCdHint(hint: CdHint): void;

package/dist/lib/cd-hint.js

@@ -0,0 +1,27 @@
+/**
+ * santree is a plain binary — a child process can't change its parent shell's
+ * working directory. So when a command wants you to land in a worktree, it
+ * prints the command for you to run. (Dashboard flows with tmux/cmux open a new
+ * window in the right directory instead and never need this.)
+ */
+/** Single-quote a value for safe copy-paste into a POSIX shell. */
+function sq(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** The shell command to enter a worktree (and optionally start work). */
+export function formatCdCommand(hint) {
+    let cmd = `cd ${sq(hint.path)}`;
+    if (hint.work) {
+        let work = "santree worktree work";
+        if (hint.work.mode === "plan")
+            work += " --plan";
+        if (hint.work.contextFile)
+            work += ` --context-file ${sq(hint.work.contextFile)}`;
+        cmd += ` && ${work}`;
+    }
+    return cmd;
+}
+/** Print the cd hint to stdout (for non-Ink contexts, e.g. after the dashboard exits). */
+export function printCdHint(hint) {
+    console.log(`\n→ Run this to enter the worktree:\n  ${formatCdCommand(hint)}`);
+}

package/dist/lib/claude-config.d.ts

@@ -0,0 +1,12 @@
+export declare function claudeSettingsPath(): string;
+export declare function claudeConfigPath(): string;
+export declare function readJsonSafe(filePath: string): Record<string, any>;
+export declare function getStatuslineCommand(): string | undefined;
+export declare function isStatuslineConfigured(): boolean;
+export declare function configureStatusline(): string;
+export declare function isRemoteControlEnabled(): boolean;
+export declare function enableRemoteControl(): string;
+export declare const SESSION_SIGNAL_EVENTS: string[];
+/** Returns the session-signal events that are NOT yet wired in settings.json. */
+export declare function missingSessionSignalHooks(): string[];
+export declare function isSessionSignalConfigured(): boolean;

package/dist/lib/claude-config.js

@@ -0,0 +1,86 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Shared read/detect/configure helpers for the two Claude Code config files
+ * santree touches:
+ *   - ~/.claude/settings.json   (statusline + hooks)
+ *   - ~/.claude.json            (remote control)
+ *
+ * Both `santree doctor` (detect) and `santree setup` (configure) go through
+ * here so the two commands can never disagree about what "configured" means.
+ */
+const STATUSLINE_COMMAND = "santree helpers statusline";
+export function claudeSettingsPath() {
+    return path.join(process.env.HOME || "", ".claude", "settings.json");
+}
+export function claudeConfigPath() {
+    return path.join(process.env.HOME || "", ".claude.json");
+}
+export function readJsonSafe(filePath) {
+    try {
+        if (fs.existsSync(filePath)) {
+            return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        }
+    }
+    catch {
+        // Invalid/unreadable — caller decides whether to start fresh.
+    }
+    return {};
+}
+function writeJson(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+// ── Statusline ───────────────────────────────────────────────────────────────
+export function getStatuslineCommand() {
+    const settings = readJsonSafe(claudeSettingsPath());
+    const cmd = settings.statusLine?.command;
+    return cmd ? String(cmd) : undefined;
+}
+export function isStatuslineConfigured() {
+    const cmd = getStatuslineCommand();
+    return (!!cmd && (cmd.includes("santree statusline") || cmd.includes("santree helpers statusline")));
+}
+export function configureStatusline() {
+    const settingsPath = claudeSettingsPath();
+    const settings = readJsonSafe(settingsPath);
+    settings.statusLine = { type: "command", command: STATUSLINE_COMMAND };
+    writeJson(settingsPath, settings);
+    return settingsPath;
+}
+// ── Remote control ────────────────────────────────────────────────────────────
+export function isRemoteControlEnabled() {
+    return readJsonSafe(claudeConfigPath()).remoteControlAtStartup === true;
+}
+export function enableRemoteControl() {
+    const configPath = claudeConfigPath();
+    const config = readJsonSafe(configPath);
+    config.remoteControlAtStartup = true;
+    writeJson(configPath, config);
+    return configPath;
+}
+// ── Session-signal hooks ──────────────────────────────────────────────────────
+export const SESSION_SIGNAL_EVENTS = ["Notification", "Stop", "UserPromptSubmit", "SessionEnd"];
+/** Returns the session-signal events that are NOT yet wired in settings.json. */
+export function missingSessionSignalHooks() {
+    const settings = readJsonSafe(claudeSettingsPath());
+    const hooks = settings.hooks || {};
+    const missing = [];
+    for (const event of SESSION_SIGNAL_EVENTS) {
+        const eventHooks = hooks[event];
+        if (!Array.isArray(eventHooks)) {
+            missing.push(event);
+            continue;
+        }
+        const found = eventHooks.some((entry) => {
+            const inner = entry.hooks || [];
+            return inner.some((h) => typeof h.command === "string" && h.command.includes("session-signal"));
+        });
+        if (!found)
+            missing.push(event);
+    }
+    return missing;
+}
+export function isSessionSignalConfigured() {
+    return missingSessionSignalHooks().length === 0;
+}

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

@@ -8,6 +8,9 @@ interface Props {
     creationLogs: string;
     /** Deletion progress for the selected worktree, when one is being removed. */
     deleteStatus?: DeleteStatus;
+    /** True while a just-created PR is shown optimistically, before a refresh
+     * confirms it (renders a "syncing…" hint next to the PR). */
+    prSyncing?: boolean;
     /** Triage mode: hide worktree/PR/checks sections (they never apply to an
      * inbox issue) and show the discussion instead. */
     triage?: boolean;
@@ -39,5 +42,5 @@ export declare function buildIssueActions(di: DashboardIssue, trackerName: strin
     canMutate?: boolean;
     triageInvestigateConfigured?: boolean;
 }): IssueActionItem[];
-export default function DetailPanel({ issue, scrollOffset, height, width, creatingForTicket, creationLogs, deleteStatus, triage, comments, onCall, }: Props): import("react/jsx-runtime").JSX.Element;
+export default function DetailPanel({ issue, scrollOffset, height, width, creatingForTicket, creationLogs, deleteStatus, prSyncing, triage, comments, onCall, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/lib/dashboard/DetailPanel.js

@@ -158,7 +158,7 @@ function sectionHeader(icon, label, iconColor = "cyan") {
         ],
     };
 }
-export default function DetailPanel({ issue, scrollOffset, height, width, creatingForTicket, creationLogs, deleteStatus, triage = false, comments, onCall, }) {
+export default function DetailPanel({ issue, scrollOffset, height, width, creatingForTicket, creationLogs, deleteStatus, prSyncing = false, triage = false, comments, onCall, }) {
     // Show deletion progress when the selected worktree is being removed.
     if (issue && deleteStatus) {
         const logLines = deleteStatus.logs.split("\n");
@@ -557,11 +557,21 @@ export default function DetailPanel({ issue, scrollOffset, height, width, creati
                 { text: "  " },
                 { text: pr.state, color: prColor },
                 { text: draft, dim: true },
+                ...(prSyncing ? [{ text: "  · syncing…", color: "yellow" }] : []),
             ],
         });
         if (pr.url) {
             lines.push({ text: `  ${pr.url}`, dim: true });
         }
+        if (prSyncing) {
+            // Just created from the dashboard — number/url are known, but checks
+            // and reviews aren't fetched yet. Show a clear loading line for this
+            // one PR (other PRs keep their already-loaded data).
+            lines.push({
+                text: "",
+                segments: [{ text: "  ⟳ loading checks & reviews…", color: "yellow" }],
+            });
+        }
     }
     else if (!isMain) {
         lines.push(sectionHeader("◉", "Pull Request"));

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

@@ -163,6 +163,12 @@ export interface DashboardState {
     creationError: string | null;
     /** In-flight (and just-finished) worktree deletions, keyed by ticket id. */
     deletingTickets: Record<string, DeleteStatus>;
+    /**
+     * Optimistic PRs just created from the dashboard, keyed by ticket id. They
+     * make the "Open PR" action appear immediately (before the next refresh
+     * surfaces the real PR), and are reconciled away by SET_DATA.
+     */
+    pendingPrs: Record<string, PRInfo>;
     commitPhase: CommitPhase;
     commitMessage: string;
     commitError: string | null;

package/dist/lib/dashboard/types.js

@@ -48,6 +48,7 @@ export const initialState = {
     creationLogs: "",
     creationError: null,
     deletingTickets: {},
+    pendingPrs: {},
     commitPhase: "idle",
     commitMessage: "",
     commitError: null,
@@ -117,12 +118,27 @@ export function reducer(state, action) {
             // keep their row, so their entries survive and stay visible.
             const presentTreeIds = new Set(action.flatTrees.map((d) => d.issue.identifier));
             const deletingTickets = Object.fromEntries(Object.entries(state.deletingTickets).filter(([id]) => presentTreeIds.has(id)));
+            // Reconcile optimistic PRs: keep the placeholder until the refresh
+            // actually surfaces the PR (GitHub may not have indexed it yet), then
+            // drop it once real PR data — or the worktree itself — is gone.
+            let reconciledTrees = action.flatTrees;
+            const pendingPrs = {};
+            for (const [id, optimistic] of Object.entries(state.pendingPrs)) {
+                const idx = reconciledTrees.findIndex((d) => d.issue.identifier === id);
+                if (idx < 0)
+                    continue; // worktree gone → drop
+                if (reconciledTrees[idx].pr)
+                    continue; // real PR arrived → reconciled
+                reconciledTrees = reconciledTrees.map((d, i) => (i === idx ? { ...d, pr: optimistic } : d));
+                pendingPrs[id] = optimistic; // still pending → keep showing it
+            }
             return {
                 ...state,
                 groups: action.groups,
                 flatIssues: action.flatIssues,
                 treeGroups: action.treeGroups,
-                flatTrees: action.flatTrees,
+                flatTrees: reconciledTrees,
+                pendingPrs,
                 triageGroups: action.triageGroups,
                 flatTriage: action.flatTriage,
                 deletingTickets,
@@ -408,14 +424,33 @@ export function reducer(state, action) {
             return { ...state, prCreateDraft: !state.prCreateDraft };
         case "PR_CREATE_EDIT":
             return { ...state, prCreatePhase: "review" };
-        case "PR_CREATE_DONE":
+        case "PR_CREATE_DONE": {
+            // Optimistically attach the new PR to its tree row so the "Open PR"
+            // action appears immediately, instead of waiting for the next refresh
+            // to surface it via `gh pr view`.
+            const ticketId = state.prCreateTicketId;
+            let flatTrees = state.flatTrees;
+            let pendingPrs = state.pendingPrs;
+            if (ticketId) {
+                const optimistic = {
+                    number: action.url.match(/\/pull\/(\d+)/)?.[1] ?? "?",
+                    state: "OPEN",
+                    isDraft: state.prCreateDraft,
+                    url: action.url,
+                };
+                flatTrees = state.flatTrees.map((d) => d.issue.identifier === ticketId && !d.pr ? { ...d, pr: optimistic } : d);
+                pendingPrs = { ...state.pendingPrs, [ticketId]: optimistic };
+            }
             return {
                 ...state,
                 prCreatePhase: "done",
                 prCreateUrl: action.url,
                 prCreateBody: null,
                 prCreateTitle: null,
+                flatTrees,
+                pendingPrs,
             };
+        }
         case "PR_CREATE_CANCEL":
             return {
                 ...state,

package/dist/lib/setup/apply.d.ts

@@ -0,0 +1,16 @@
+/**
+ * TTY hand-off for setup steps that run an interactive subprocess (brew install,
+ * gh auth login, `santree issue setup`). Mirrors lib/dashboard/external-editor.ts:
+ * drop raw mode so the child owns the terminal, run it synchronously (Ink can't
+ * repaint while the event loop is blocked), then restore raw mode.
+ *
+ * Returns the child's exit code (1 on spawn failure).
+ */
+export declare function spawnTTY(cmd: string, args: string[], opts?: {
+    cwd?: string;
+}): number;
+/** argv to re-invoke this same santree binary (robust to global vs local installs). */
+export declare function santreeSelfArgv(args: string[]): {
+    cmd: string;
+    args: string[];
+};

package/dist/lib/setup/apply.js

@@ -0,0 +1,35 @@
+import { spawnSync } from "child_process";
+/**
+ * TTY hand-off for setup steps that run an interactive subprocess (brew install,
+ * gh auth login, `santree issue setup`). Mirrors lib/dashboard/external-editor.ts:
+ * drop raw mode so the child owns the terminal, run it synchronously (Ink can't
+ * repaint while the event loop is blocked), then restore raw mode.
+ *
+ * Returns the child's exit code (1 on spawn failure).
+ */
+export function spawnTTY(cmd, args, opts) {
+    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", cwd: opts?.cwd });
+    if (process.stdin.isTTY && process.stdin.setRawMode) {
+        try {
+            process.stdin.setRawMode(wasRaw);
+        }
+        catch { }
+    }
+    if (result.error)
+        return 1;
+    return result.status ?? 1;
+}
+/** argv to re-invoke this same santree binary (robust to global vs local installs). */
+export function santreeSelfArgv(args) {
+    const entry = process.argv[1];
+    if (entry)
+        return { cmd: process.execPath, args: [entry, ...args] };
+    return { cmd: "santree", args };
+}

package/dist/lib/setup/gitignore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ignore-rule management for santree's per-repo files.
+ *
+ * We add SPECIFIC entries (not a blanket `.santree/`) so `.santree/issues/`
+ * stays version-controlled for the Local tracker. Trailing slashes mark
+ * directories (see santree's own .gitignore convention).
+ */
+export declare const SANTREE_IGNORE_ENTRIES: string[];
+export type IgnoreTarget = "gitignore" | "exclude";
+export declare function ignoreTargetPath(repoRoot: string, target: IgnoreTarget): string;
+/** Entries that are not yet ignored by git (so we don't write duplicates). */
+export declare function missingIgnoreEntries(repoRoot: string): string[];
+/**
+ * Append the still-missing santree entries to the chosen target file. Returns
+ * the entries actually written (skips any already present as literal lines).
+ */
+export declare function addIgnoreEntries(repoRoot: string, target: IgnoreTarget): string[];

package/dist/lib/setup/gitignore.js

@@ -0,0 +1,57 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { run } from "../exec.js";
+/**
+ * Ignore-rule management for santree's per-repo files.
+ *
+ * We add SPECIFIC entries (not a blanket `.santree/`) so `.santree/issues/`
+ * stays version-controlled for the Local tracker. Trailing slashes mark
+ * directories (see santree's own .gitignore convention).
+ */
+export const SANTREE_IGNORE_ENTRIES = [
+    ".santree/worktrees/",
+    ".santree/metadata.json",
+    ".santree/session-states/",
+];
+export function ignoreTargetPath(repoRoot, target) {
+    if (target === "exclude") {
+        // Resolve the real excludes file (handles non-standard git dirs).
+        const rel = run("git rev-parse --git-path info/exclude", { cwd: repoRoot });
+        return rel ? path.resolve(repoRoot, rel) : path.join(repoRoot, ".git", "info", "exclude");
+    }
+    return path.join(repoRoot, ".gitignore");
+}
+function isGitIgnored(relPath, repoRoot) {
+    try {
+        execSync(`git check-ignore -q "${relPath}"`, { cwd: repoRoot, stdio: "ignore" });
+        return true; // exit 0 = ignored
+    }
+    catch {
+        return false;
+    }
+}
+/** Entries that are not yet ignored by git (so we don't write duplicates). */
+export function missingIgnoreEntries(repoRoot) {
+    return SANTREE_IGNORE_ENTRIES.filter((e) => !isGitIgnored(e, repoRoot));
+}
+/**
+ * Append the still-missing santree entries to the chosen target file. Returns
+ * the entries actually written (skips any already present as literal lines).
+ */
+export function addIgnoreEntries(repoRoot, target) {
+    const filePath = ignoreTargetPath(repoRoot, target);
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : "";
+    const existingLines = new Set(existing
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean));
+    const toAdd = missingIgnoreEntries(repoRoot).filter((e) => !existingLines.has(e));
+    if (toAdd.length === 0)
+        return [];
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    const header = existing.includes("# santree") ? "" : "\n# santree\n";
+    fs.appendFileSync(filePath, prefix + header + toAdd.join("\n") + "\n");
+    return toAdd;
+}

package/dist/lib/setup/shell-config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shell-config detection + idempotent editing for `santree setup`.
+ *
+ * Everything santree writes to a user's shell rc lives inside a single managed
+ * block (nvm/conda style) so re-running setup replaces the block rather than
+ * appending duplicates. Individual lines inside the block are tagged with a
+ * trailing `# santree:<key>` comment so each setup step can upsert just its own
+ * line without disturbing the others.
+ */
+export type ShellName = "zsh" | "bash" | "unknown";
+export interface ShellConfig {
+    shell: ShellName;
+    /** rc file the managed block is written to (interactive shell init). */
+    rcPath: string;
+    /** Files scanned to detect pre-existing `export FOO=...` lines (rc + env files). */
+    scanPaths: string[];
+}
+/**
+ * Resolve the rc file the managed block should live in, honoring ZDOTDIR (zsh)
+ * so users with an XDG-based setup (~/.config/zsh, no ~/.zshrc) get the block in
+ * the right place.
+ */
+export declare function resolveShellConfig(shellEnv?: string): ShellConfig;
+/**
+ * Upsert a single tagged line into the managed block, creating the block (and
+ * the rc file) if needed. The line for `key` is replaced if present, else
+ * appended. `line` is the raw shell statement WITHOUT the trailing tag comment.
+ */
+export declare function upsertManagedLine(rcPath: string, key: string, line: string): void;
+/**
+ * Detect whether `name` is already exported by the user's shell config (any of
+ * `scanPaths`) or the current environment. Used so setup doesn't clobber an
+ * export the user already maintains by hand (e.g. SANTREE_EDITOR in .zshenv).
+ * Ignores santree's own managed block so a prior setup run isn't mistaken for a
+ * hand-maintained export.
+ */
+export declare function isEnvVarSet(name: string, cfg: ShellConfig): boolean;
+export declare function envKey(name: string): string;

package/dist/lib/setup/shell-config.js

@@ -0,0 +1,131 @@
+import * as fs from "fs";
+import * as path from "path";
+const BLOCK_START = "# >>> santree >>>";
+const BLOCK_END = "# <<< santree <<<";
+const BLOCK_HEADER = "# Managed by `santree setup` — safe to re-run; edits here may be overwritten.";
+/**
+ * Resolve the rc file the managed block should live in, honoring ZDOTDIR (zsh)
+ * so users with an XDG-based setup (~/.config/zsh, no ~/.zshrc) get the block in
+ * the right place.
+ */
+export function resolveShellConfig(shellEnv = process.env.SHELL || "") {
+    const home = process.env.HOME || "";
+    const base = path.basename(shellEnv);
+    if (base.includes("zsh")) {
+        const dir = process.env.ZDOTDIR || home;
+        return {
+            shell: "zsh",
+            rcPath: path.join(dir, ".zshrc"),
+            scanPaths: [
+                path.join(dir, ".zshrc"),
+                path.join(dir, ".zshenv"),
+                path.join(home, ".zshenv"),
+                path.join(home, ".zprofile"),
+            ],
+        };
+    }
+    if (base.includes("bash")) {
+        return {
+            shell: "bash",
+            rcPath: path.join(home, ".bashrc"),
+            scanPaths: [
+                path.join(home, ".bashrc"),
+                path.join(home, ".bash_profile"),
+                path.join(home, ".profile"),
+            ],
+        };
+    }
+    // Fall back to zsh conventions (the default macOS shell).
+    const dir = process.env.ZDOTDIR || home;
+    return {
+        shell: "unknown",
+        rcPath: path.join(dir, ".zshrc"),
+        scanPaths: [path.join(dir, ".zshrc"), path.join(dir, ".zshenv"), path.join(home, ".zshenv")],
+    };
+}
+function tagFor(key) {
+    return `# santree:${key}`;
+}
+function readFileSafe(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+function splitBlock(content) {
+    const startIdx = content.indexOf(BLOCK_START);
+    if (startIdx === -1) {
+        return { before: content, body: [], after: "", exists: false };
+    }
+    const endMarkerIdx = content.indexOf(BLOCK_END, startIdx);
+    if (endMarkerIdx === -1) {
+        // Malformed (start without end) — treat everything from start as the block.
+        const before = content.slice(0, startIdx);
+        return { before, body: [], after: "", exists: true };
+    }
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endMarkerIdx + BLOCK_END.length);
+    const inner = content.slice(startIdx + BLOCK_START.length, endMarkerIdx);
+    const body = inner
+        .split("\n")
+        .map((l) => l.trimEnd())
+        .filter((l) => l.length > 0 && l !== BLOCK_HEADER);
+    return { before, body, after, exists: true };
+}
+function renderBlock(body) {
+    return [BLOCK_START, BLOCK_HEADER, ...body, BLOCK_END].join("\n");
+}
+/**
+ * Upsert a single tagged line into the managed block, creating the block (and
+ * the rc file) if needed. The line for `key` is replaced if present, else
+ * appended. `line` is the raw shell statement WITHOUT the trailing tag comment.
+ */
+export function upsertManagedLine(rcPath, key, line) {
+    const content = readFileSafe(rcPath);
+    const { before, body, after, exists } = splitBlock(content);
+    const tag = tagFor(key);
+    const tagged = `${line} ${tag}`;
+    const idx = body.findIndex((l) => l.trimEnd().endsWith(tag));
+    const nextBody = idx === -1 ? [...body, tagged] : body.map((l, i) => (i === idx ? tagged : l));
+    let output;
+    if (exists) {
+        output = before + renderBlock(nextBody) + after;
+    }
+    else {
+        // Append a fresh block, keeping a single trailing newline.
+        const trimmed = content.replace(/\n+$/, "");
+        const prefix = trimmed.length > 0 ? trimmed + "\n\n" : "";
+        output = prefix + renderBlock(nextBody) + "\n";
+    }
+    const dir = path.dirname(rcPath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(rcPath, output.endsWith("\n") ? output : output + "\n");
+}
+/**
+ * Detect whether `name` is already exported by the user's shell config (any of
+ * `scanPaths`) or the current environment. Used so setup doesn't clobber an
+ * export the user already maintains by hand (e.g. SANTREE_EDITOR in .zshenv).
+ * Ignores santree's own managed block so a prior setup run isn't mistaken for a
+ * hand-maintained export.
+ */
+export function isEnvVarSet(name, cfg) {
+    if (process.env[name])
+        return true;
+    const re = new RegExp(`^\\s*export\\s+${name}=`, "m");
+    for (const p of cfg.scanPaths) {
+        const content = readFileSafe(p);
+        if (!content)
+            continue;
+        // Strip our own managed block before scanning hand-maintained exports.
+        const { before, after } = splitBlock(content);
+        const userContent = p === cfg.rcPath ? before + after : content;
+        if (re.test(userContent))
+            return true;
+    }
+    return false;
+}
+export function envKey(name) {
+    return `env:${name}`;
+}

package/dist/lib/setup/steps.d.ts

@@ -0,0 +1,35 @@
+import { type ShellConfig } from "./shell-config.js";
+export type DetectState = "ok" | "actionable" | "unavailable";
+export interface StepOption {
+    value: string;
+    label: string;
+}
+export interface StepResult {
+    ok: boolean;
+    message: string;
+}
+export interface SetupStep {
+    id: string;
+    title: string;
+    detail: string;
+    scope: "global" | "repo";
+    /** "spawn" steps take over the terminal (installs/logins); UI flags them. */
+    kind: "file" | "spawn";
+    recommended: boolean;
+    detect: DetectState;
+    /** Pick-one sub-prompt collected before apply; absent = no choice needed. */
+    options?: StepOption[];
+    optionPrompt?: string;
+    apply: (choice: string | undefined) => StepResult | Promise<StepResult>;
+}
+export interface SetupContext {
+    repoRoot: string | null;
+    shell: ShellConfig;
+    dryRun: boolean;
+}
+export declare function buildContext(dryRun: boolean): SetupContext;
+/**
+ * Build the full step catalog with `detect` + `options` resolved against the
+ * current machine. The wizard filters to `actionable` steps for the checklist.
+ */
+export declare function buildSteps(ctx: SetupContext): SetupStep[];