santree 0.7.4 → 0.7.6

package/dist/lib/open-url.d.ts

@@ -4,7 +4,8 @@
  *   else  → `xdg-open <url>`
  *
  * Returns true on apparent success, false on failure. Callers decide how to
- * surface failures (e.g. a dashboard action message). Uses execSync with
- * `stdio: "ignore"` — fast, no output leak into the dashboard's alt screen.
+ * surface failures (e.g. a dashboard action message). Uses execFileSync (array
+ * args, no shell) so a `"` in a tracker/PR-supplied URL can't break or inject;
+ * `stdio: "ignore"` keeps output out of the dashboard's alt screen.
  */
 export declare function openUrl(url: string): boolean;

package/dist/lib/open-url.js

@@ -1,17 +1,18 @@
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 /**
  * Open a URL in the platform's default browser.
  *   macOS → `open <url>`
  *   else  → `xdg-open <url>`
  *
  * Returns true on apparent success, false on failure. Callers decide how to
- * surface failures (e.g. a dashboard action message). Uses execSync with
- * `stdio: "ignore"` — fast, no output leak into the dashboard's alt screen.
+ * surface failures (e.g. a dashboard action message). Uses execFileSync (array
+ * args, no shell) so a `"` in a tracker/PR-supplied URL can't break or inject;
+ * `stdio: "ignore"` keeps output out of the dashboard's alt screen.
  */
 export function openUrl(url) {
     try {
         const cmd = process.platform === "darwin" ? "open" : "xdg-open";
-        execSync(`${cmd} "${url}"`, { stdio: "ignore" });
+        execFileSync(cmd, [url], { stdio: "ignore" });
         return true;
     }
     catch {

package/dist/lib/prompts.d.ts

@@ -1,5 +1,5 @@
 import type { Issue } from "./trackers/types.js";
-import type { PRCheck, PRReview, PRReviewComment, FailedCheckDetail, PRConversationComment } from "./github.js";
+import type { PRCheck, PRReview, PRReviewComment, PRReviewThread, FailedCheckDetail, PRConversationComment } from "./github.js";
 /**
  * Render a nunjucks template from the prompts/ directory.
  * @param template - Template name without extension (e.g. "fill-pr")
@@ -35,3 +35,37 @@ export interface PRData {
  * Render PR feedback data into formatted markdown using the pr template.
  */
 export declare function renderPR(data: PRData): string;
+/** A failed check annotated with whether the fix loop should attempt it. */
+export interface FixContextCheck extends FailedCheckDetail {
+    fixable: boolean;
+}
+export interface FixContextData {
+    pr_number: string;
+    pr_url: string;
+    branch: string;
+    base_branch: string;
+    conflicts: boolean;
+    mergeable: string;
+    merge_state: string;
+    failed_checks: FixContextCheck[];
+    fixable_count: number;
+    manual_count: number;
+    pending_count: number;
+    reviews: PRReview[] | null;
+    /** Unresolved review threads the viewer has 👍-approved for auto-apply. */
+    approved_comments: PRReviewThread[];
+    /**
+     * The single recommended action for this iteration, computed from state so
+     * the loop doesn't have to: `merge` (conflicts) | `work` (fixable CI and/or
+     * approved comments) | `wait` (nothing to do, CI still running) |
+     * `stop-stuck` (only manual failures left) | `stop-clean` (all done).
+     */
+    directive: "merge" | "work" | "wait" | "stop-stuck" | "stop-clean";
+    /** Absolute santree invocation, for the `--signal` / resolve commands. */
+    santree_cmd: string;
+}
+/**
+ * Render the compact per-iteration brief the auto-fix loop consumes: conflict
+ * status, failing checks tagged fixable/manual, and open review asks.
+ */
+export declare function renderFixContext(data: FixContextData): string;

package/dist/lib/prompts.js

@@ -51,3 +51,10 @@ export function renderDiff(data) {
 export function renderPR(data) {
     return promptsEnv.render("pr.njk", data);
 }
+/**
+ * Render the compact per-iteration brief the auto-fix loop consumes: conflict
+ * status, failing checks tagged fixable/manual, and open review asks.
+ */
+export function renderFixContext(data) {
+    return promptsEnv.render("fix-context.njk", data);
+}

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

@@ -0,0 +1,16 @@
+/**
+ * TTY hand-off for config steps that run an interactive subprocess (brew install,
+ * gh auth login, Claude install). 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 config steps that run an interactive subprocess (brew install,
+ * gh auth login, Claude install). 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,24 @@
+/**
+ * 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[];
+/**
+ * Remove santree's ignore entries (and an orphaned `# santree` header) from both
+ * candidate files. Returns the entries actually removed. Leaves every other line
+ * — including user-authored ignores — untouched, and collapses the blank lines
+ * left behind so the file doesn't accumulate gaps across enable/disable cycles.
+ */
+export declare function removeIgnoreEntries(repoRoot: string): string[];

package/dist/lib/setup/gitignore.js

@@ -0,0 +1,95 @@
+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/fix-loops/",
+];
+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;
+}
+/**
+ * Remove santree's ignore entries (and an orphaned `# santree` header) from both
+ * candidate files. Returns the entries actually removed. Leaves every other line
+ * — including user-authored ignores — untouched, and collapses the blank lines
+ * left behind so the file doesn't accumulate gaps across enable/disable cycles.
+ */
+export function removeIgnoreEntries(repoRoot) {
+    const removed = [];
+    for (const target of ["gitignore", "exclude"]) {
+        const filePath = ignoreTargetPath(repoRoot, target);
+        if (!fs.existsSync(filePath))
+            continue;
+        const original = fs.readFileSync(filePath, "utf-8");
+        let changed = false;
+        const kept = original.split("\n").filter((line) => {
+            const t = line.trim();
+            if (SANTREE_IGNORE_ENTRIES.includes(t)) {
+                removed.push(t);
+                changed = true;
+                return false;
+            }
+            if (t === "# santree") {
+                // santree's header only ever sits above its own (now-removed) entries.
+                changed = true;
+                return false;
+            }
+            return true;
+        });
+        if (!changed)
+            continue;
+        const cleaned = kept
+            .join("\n")
+            .replace(/\n{3,}/g, "\n\n")
+            .replace(/^\n+/, "");
+        fs.writeFileSync(filePath, cleaned.length === 0 ? "" : cleaned.replace(/\n*$/, "\n"));
+    }
+    return removed;
+}

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

@@ -0,0 +1,39 @@
+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>;
+    /**
+     * Reverse `apply`, returning the step to its un-configured state. Present only
+     * on steps santree fully owns and can cleanly undo (statusline, remote control,
+     * gitignore). Steps without it have no "off" in the panel.
+     */
+    unapply?: (choice: string | undefined) => StepResult | Promise<StepResult>;
+}
+export interface SetupContext {
+    repoRoot: string | null;
+    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[];

package/dist/lib/setup/steps.js

@@ -0,0 +1,333 @@
+import * as fs from "fs";
+import { run } from "../exec.js";
+import { findMainRepoRoot, getSantreeDir, getInitScriptPath } from "../git.js";
+import { isRepoTrackerConfigured } from "../trackers/index.js";
+import { getMultiplexer } from "../multiplexer/index.js";
+import { resolveClaudeBinary } from "../ai.js";
+import { CLAUDE_CODE_PACKAGE, detectPackageManager, getInstallCommandFor } from "../version.js";
+import { isStatuslineConfigured, configureStatusline, removeStatusline, isRemoteControlEnabled, enableRemoteControl, disableRemoteControl, } from "../claude-config.js";
+import { setConfigValue, getConfiguredEditor, getConfiguredDiffTool, configStorePath, } from "../config-store.js";
+import { detectDiffPagers, detectEditors, getInstaller, which } from "./tools.js";
+import { missingIgnoreEntries, addIgnoreEntries, removeIgnoreEntries, SANTREE_IGNORE_ENTRIES, } from "./gitignore.js";
+import { spawnTTY } from "./apply.js";
+export function buildContext(dryRun) {
+    return {
+        repoRoot: findMainRepoRoot(),
+        dryRun,
+    };
+}
+/**
+ * Build the full step catalog with `detect` + `options` resolved against the
+ * current machine. The wizard filters to `actionable` steps for the checklist.
+ */
+export function buildSteps(ctx) {
+    const steps = [];
+    const { repoRoot, dryRun } = ctx;
+    const installer = getInstaller();
+    // ── Editor ──────────────────────────────────────────────────────────────────
+    {
+        const editors = detectEditors();
+        const detect = getConfiguredEditor()
+            ? "ok"
+            : editors.length > 0
+                ? "actionable"
+                : "unavailable";
+        steps.push({
+            id: "editor",
+            title: "Default editor",
+            detail: "Editor opened by the dashboard's [e] action (stored in santree's config)",
+            scope: "global",
+            kind: "file",
+            recommended: true,
+            detect,
+            options: editors.map((e) => ({ value: e.command, label: e.command })),
+            optionPrompt: "Pick your editor:",
+            apply: (choice) => {
+                const editor = choice || editors[0]?.command || "vim";
+                if (dryRun)
+                    return { ok: true, message: `Would set editor=${editor}` };
+                setConfigValue("editor", editor);
+                return { ok: true, message: `Set editor to ${editor} in ${configStorePath()}` };
+            },
+        });
+    }
+    // ── Diff tool ───────────────────────────────────────────────────────────────
+    {
+        const pagers = detectDiffPagers();
+        const hasDelta = pagers.some((p) => p.command === "delta");
+        const options = pagers.map((p) => ({ value: p.command, label: p.command }));
+        if (installer && !hasDelta) {
+            options.push({
+                value: "install:delta",
+                label: `git-delta — install via ${installer.name}`,
+            });
+        }
+        const detect = getConfiguredDiffTool()
+            ? "ok"
+            : options.length > 0
+                ? "actionable"
+                : "unavailable";
+        steps.push({
+            id: "diff-tool",
+            title: "Diff tool",
+            detail: "Pretty diffs in `worktree diff` and the dashboard [v] overlay (stored in santree's config)",
+            scope: "global",
+            kind: installer && !hasDelta ? "spawn" : "file",
+            recommended: true,
+            detect,
+            options,
+            optionPrompt: "Pick a diff pager:",
+            apply: (choice) => {
+                const pick = choice || options[0]?.value;
+                if (!pick)
+                    return { ok: false, message: "No diff pager available" };
+                let tool = pick;
+                if (pick.startsWith("install:")) {
+                    tool = pick.slice("install:".length);
+                    // `install:` options are only offered when an installer exists, but
+                    // guard explicitly so a broken invariant degrades instead of NPEs.
+                    if (!installer)
+                        return { ok: false, message: "No installer available for git-delta" };
+                    if (dryRun) {
+                        return {
+                            ok: true,
+                            message: `Would ${installer.installArgv("git-delta").join(" ")} then set diffTool=${tool}`,
+                        };
+                    }
+                    const argv = installer.installArgv("git-delta");
+                    const code = spawnTTY(argv[0], argv.slice(1));
+                    if (code !== 0)
+                        return { ok: false, message: "git-delta install failed — diff tool not set" };
+                }
+                if (dryRun)
+                    return { ok: true, message: `Would set diffTool=${tool}` };
+                setConfigValue("diffTool", tool);
+                return { ok: true, message: `Set diff tool to ${tool} in ${configStorePath()}` };
+            },
+        });
+    }
+    // ── Statusline ──────────────────────────────────────────────────────────────
+    steps.push({
+        id: "statusline",
+        title: "Statusline",
+        detail: "Worktree-aware statusline (branch, git changes, context usage)",
+        scope: "global",
+        kind: "file",
+        recommended: true,
+        detect: isStatuslineConfigured() ? "ok" : "actionable",
+        apply: () => {
+            if (dryRun)
+                return { ok: true, message: "Would configure statusLine in ~/.claude/settings.json" };
+            const p = configureStatusline();
+            return { ok: true, message: `Configured statusline in ${p}` };
+        },
+        unapply: () => {
+            if (dryRun)
+                return { ok: true, message: "Would remove statusLine from ~/.claude/settings.json" };
+            const p = removeStatusline();
+            return { ok: true, message: `Removed statusline from ${p}` };
+        },
+    });
+    // ── Remote control ──────────────────────────────────────────────────────────
+    steps.push({
+        id: "remote-control",
+        title: "Remote control",
+        detail: "Enable remote control at startup (drive sessions from the dashboard)",
+        scope: "global",
+        kind: "file",
+        recommended: false,
+        detect: isRemoteControlEnabled() ? "ok" : "actionable",
+        apply: () => {
+            if (dryRun)
+                return { ok: true, message: "Would set remoteControlAtStartup in ~/.claude.json" };
+            const p = enableRemoteControl();
+            return { ok: true, message: `Enabled remote control in ${p}` };
+        },
+        unapply: () => {
+            if (dryRun)
+                return { ok: true, message: "Would unset remoteControlAtStartup in ~/.claude.json" };
+            const p = disableRemoteControl();
+            return { ok: true, message: `Disabled remote control in ${p}` };
+        },
+    });
+    // ── GitHub CLI install + auth ───────────────────────────────────────────────
+    {
+        const ghInstalled = !!which("gh");
+        // `gh auth status` prints to stderr — redirect so it doesn't leak into the wizard.
+        const ghAuthed = ghInstalled && run("gh auth status >/dev/null 2>&1") !== null;
+        const detect = ghAuthed
+            ? "ok"
+            : ghInstalled || installer
+                ? "actionable"
+                : "unavailable";
+        steps.push({
+            id: "gh",
+            title: "GitHub CLI",
+            detail: "Required for PR create / review / checks",
+            scope: "global",
+            kind: "spawn",
+            recommended: true,
+            detect,
+            apply: () => {
+                if (dryRun) {
+                    const parts = !ghInstalled && installer ? `${installer.installArgv("gh").join(" ")} then ` : "";
+                    return { ok: true, message: `Would ${parts}gh auth login` };
+                }
+                if (!ghInstalled) {
+                    if (!installer)
+                        return { ok: false, message: "Install gh manually: see https://cli.github.com" };
+                    const argv = installer.installArgv("gh");
+                    const code = spawnTTY(argv[0], argv.slice(1));
+                    if (code !== 0)
+                        return { ok: false, message: "gh install failed" };
+                }
+                const code = spawnTTY("gh", ["auth", "login"]);
+                return code === 0
+                    ? { ok: true, message: "gh authenticated" }
+                    : { ok: false, message: "gh auth login did not complete" };
+            },
+        });
+    }
+    // ── Claude Code CLI ─────────────────────────────────────────────────────────
+    {
+        const installed = !!resolveClaudeBinary();
+        steps.push({
+            id: "claude",
+            title: "Claude Code",
+            detail: "Powers `worktree work`, `pr fix`, `pr review`",
+            scope: "global",
+            kind: "spawn",
+            recommended: true,
+            detect: installed ? "ok" : "actionable",
+            apply: () => {
+                const cmd = getInstallCommandFor(detectPackageManager(), CLAUDE_CODE_PACKAGE);
+                if (dryRun)
+                    return { ok: true, message: `Would run: ${cmd.display}` };
+                const code = spawnTTY(cmd.cmd, cmd.args);
+                return code === 0
+                    ? { ok: true, message: "Claude Code CLI installed" }
+                    : { ok: false, message: `Install failed — run manually: ${cmd.display}` };
+            },
+        });
+    }
+    // ── tmux (multiplexer) ──────────────────────────────────────────────────────
+    {
+        const active = getMultiplexer().kind !== "none";
+        const detect = active ? "ok" : installer ? "actionable" : "unavailable";
+        steps.push({
+            id: "tmux",
+            title: "tmux",
+            detail: "Enables new-window flows: work / fix / review / investigate",
+            scope: "global",
+            kind: "spawn",
+            recommended: false,
+            detect,
+            apply: () => {
+                if (!installer)
+                    return { ok: false, message: "Install tmux manually: brew install tmux" };
+                if (dryRun)
+                    return { ok: true, message: `Would ${installer.installArgv("tmux").join(" ")}` };
+                const argv = installer.installArgv("tmux");
+                const code = spawnTTY(argv[0], argv.slice(1));
+                return code === 0
+                    ? { ok: true, message: "tmux installed (start a tmux session to use new-window flows)" }
+                    : { ok: false, message: "tmux install failed" };
+            },
+        });
+    }
+    // ── Repo-scoped steps ───────────────────────────────────────────────────────
+    if (repoRoot) {
+        const santreeDir = getSantreeDir(repoRoot);
+        const initSh = getInitScriptPath(repoRoot);
+        // .santree scaffold
+        {
+            const folderOk = fs.existsSync(santreeDir);
+            const initOk = fs.existsSync(initSh);
+            let execOk = false;
+            if (initOk) {
+                try {
+                    fs.accessSync(initSh, fs.constants.X_OK);
+                    execOk = true;
+                }
+                catch { }
+            }
+            steps.push({
+                id: "scaffold",
+                title: "Repo scaffold",
+                detail: "Create .santree/ and an executable init.sh (runs on worktree create)",
+                scope: "repo",
+                kind: "file",
+                recommended: true,
+                detect: folderOk && initOk && execOk ? "ok" : "actionable",
+                apply: () => {
+                    if (dryRun)
+                        return { ok: true, message: `Would create ${santreeDir} and an executable init.sh` };
+                    fs.mkdirSync(santreeDir, { recursive: true });
+                    if (!fs.existsSync(initSh)) {
+                        fs.writeFileSync(initSh, "#!/usr/bin/env bash\n# Runs after `santree worktree create`. Add setup steps here.\n");
+                    }
+                    fs.chmodSync(initSh, 0o755);
+                    return { ok: true, message: `Scaffolded ${santreeDir}` };
+                },
+            });
+        }
+        // Ignore santree files
+        {
+            const missing = missingIgnoreEntries(repoRoot);
+            steps.push({
+                id: "gitignore",
+                title: "Gitignore entries",
+                detail: `Ignore ${SANTREE_IGNORE_ENTRIES.join(", ")} (keeps .santree/issues/ tracked)`,
+                scope: "repo",
+                kind: "file",
+                recommended: true,
+                detect: missing.length === 0 ? "ok" : "actionable",
+                options: [
+                    { value: "gitignore", label: ".gitignore — shared with your team" },
+                    { value: "exclude", label: ".git/info/exclude — local to your clone" },
+                ],
+                optionPrompt: "Where should the ignore rules go?",
+                apply: (choice) => {
+                    const target = (choice === "exclude" ? "exclude" : "gitignore");
+                    const where = target === "exclude" ? ".git/info/exclude" : ".gitignore";
+                    if (dryRun)
+                        return {
+                            ok: true,
+                            message: `Would add ${missing.length} entr${missing.length === 1 ? "y" : "ies"} to ${where}`,
+                        };
+                    const added = addIgnoreEntries(repoRoot, target);
+                    return {
+                        ok: true,
+                        message: `Added ${added.length} entr${added.length === 1 ? "y" : "ies"} to ${where}`,
+                    };
+                },
+                unapply: () => {
+                    if (dryRun)
+                        return { ok: true, message: "Would remove santree's ignore entries" };
+                    const removed = removeIgnoreEntries(repoRoot);
+                    return {
+                        ok: true,
+                        message: removed.length
+                            ? `Removed ${removed.length} entr${removed.length === 1 ? "y" : "ies"}`
+                            : "No santree ignore entries to remove",
+                    };
+                },
+            });
+        }
+        // Issue tracker
+        {
+            steps.push({
+                id: "tracker",
+                title: "Issue tracker",
+                detail: "Pick + authenticate Linear / GitHub / Local for this repo",
+                scope: "repo",
+                kind: "file",
+                recommended: true,
+                detect: isRepoTrackerConfigured(repoRoot) ? "ok" : "actionable",
+                // Driven by the config panel's inline TrackerPicker; apply is unused.
+                apply: () => ({ ok: true, message: "Pick a tracker from the config panel" }),
+            });
+        }
+    }
+    return steps;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Tool detection + installation for `santree config`.
+ *
+ * macOS (Homebrew) is the only auto-install path today. The `PlatformInstaller`
+ * seam keeps the door open for apt/dnf/etc. without touching call sites — add a
+ * resolver branch in `getInstaller()` and the steps keep working.
+ */
+export declare function isMacOS(): boolean;
+/** Resolve a command on PATH, or null if absent. */
+export declare function which(cmd: string): string | null;
+export interface DetectedTool {
+    command: string;
+    path: string;
+}
+export declare function detectDiffPagers(): DetectedTool[];
+export declare function detectEditors(): DetectedTool[];
+export interface PlatformInstaller {
+    /** Human label, e.g. "Homebrew". */
+    name: string;
+    /** argv for installing `pkg` (cmd + args), suitable for a TTY spawn. */
+    installArgv(pkg: string): string[];
+}
+export declare function getInstaller(): PlatformInstaller | null;