kankaku-tui 0.1.2 → 0.2.1

package/README.md

@@ -8,6 +8,36 @@ in. Built with [Ink](https://github.com/vadimdemedes/ink) on Node 24. Four
 screens — Dashboard, Tasks, Catalog and Sync — share one tab bar, and each
 has a plain-text subcommand for scripts and cron.
 
+## Install everything
+
+```
+npm i -g kankaku-tui
+kankaku setup
+```
+
+`kankaku setup` detects every coding agent kankaku knows how to configure
+on this machine (pi, gentle-shell, Claude Code — each by its own settings
+file) and, for each one that already exists but isn't wired up, offers to
+add it: `npm:kankaku` to a pi-family `packages` array, or Claude Code's
+`statusLine` pointing at a `kankaku-claude` checkout. It also offers to
+configure hub credentials (reusing `~/.kankaku/credentials.json` or the
+`KANKAKU_PB_*` environment when either is already set) and writes this
+app's own `~/.kankaku/tui.json`. Codex and OpenCode are detected and
+reported, but kankaku has no adapter for either yet.
+
+Every question has a sensible default; `kankaku setup --yes` accepts every
+default without asking, and `kankaku setup --dry-run` prints the plan —
+each step's state (`done`/`todo`/`unavailable`) and the exact file it
+would change — without writing anything. Nothing is ever written without
+either an explicit prompt answer or `--yes`. Before the first change to
+any file, kankaku setup creates a `<file>.bak` next to it; re-running
+`kankaku setup` is always safe, since it only ever writes what is still
+missing or what you explicitly change.
+
+`kankaku setup` ends with, and `kankaku doctor` prints on its own, the
+same read-only report: one line per agent, one for the hub, one for
+`tui.json`, and a `next: …` hint for anything still `todo`.
+
 ## Install
 
 Until the next kankaku release, this package depends on the sibling
@@ -78,6 +108,9 @@ never guesses which coding agent produced someone else's worklog.
   pending count and last sync per project, no network; with no argument,
   syncs the pending window; `all` does a full resync. Defaults to every
   discovered project, sequentially; `--project <dir>` restricts to one.
+- `kankaku setup [--yes] [--dry-run]` — see "Install everything" above.
+- `kankaku doctor` — the same read-only report `kankaku setup` ends with,
+  without prompting or writing anything.
 
 `--roots` (on `today`/`tasks`) overrides the configured roots for that run.
 

package/dist/adapters/setup/agents.js

@@ -0,0 +1,55 @@
+/**
+ * Reads the real per-agent settings/config files under `homeDir` into the
+ * plain facts `domain/setup-plan.ts#detectAgents` expects. Never throws: a
+ * missing or malformed file reads as absent, exactly like
+ * `adapters/tui-config.ts#readTuiConfig` and kankaku's own
+ * `hub-credentials.ts#readCredentialsFile`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+function readJsonObject(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function readSettingsPackages(settingsPath) {
+    const parsed = readJsonObject(settingsPath);
+    if (!parsed)
+        return undefined;
+    const packages = isStringArray(parsed["packages"]) ? parsed["packages"] : [];
+    return { settingsPath, packages };
+}
+function readClaudeSettings(settingsPath) {
+    const parsed = readJsonObject(settingsPath);
+    if (!parsed)
+        return undefined;
+    const statusLine = parsed["statusLine"];
+    const command = statusLine && typeof statusLine === "object" && !Array.isArray(statusLine) && typeof statusLine["command"] === "string"
+        ? statusLine["command"]
+        : undefined;
+    return { settingsPath, statusLineCommand: command };
+}
+function readConfigFilePresence(configPath) {
+    return existsSync(configPath) ? { configPath } : undefined;
+}
+/** Read every agent's settings/config file under `homeDir`, tolerating any absence or malformed content. */
+export function readAgentFacts(homeDir) {
+    return {
+        pi: readSettingsPackages(join(homeDir, ".pi", "agent", "settings.json")),
+        gentleShell: readSettingsPackages(join(homeDir, ".gentle-shell", "agent", "settings.json")),
+        claudeCode: readClaudeSettings(join(homeDir, ".claude", "settings.json")),
+        codex: readConfigFilePresence(join(homeDir, ".codex", "config.toml")),
+        opencode: readConfigFilePresence(join(homeDir, ".config", "opencode", "opencode.json")),
+    };
+}

package/dist/adapters/setup/claude.js

@@ -0,0 +1,25 @@
+/**
+ * Writer for Claude Code's `~/.claude/settings.json`: sets `statusLine` to
+ * run kankaku's `src/statusline.ts` from the given `kankaku-claude`
+ * checkout, leaving every other key untouched. A no-op when the
+ * `statusLine.command` already runs that exact statusline.ts for this
+ * checkout.
+ */
+import { backupOnce, readJsonObjectOrEmpty, writeJsonAtomic } from "./json-writer.js";
+/** The exact `statusLine.command` kankaku-tui writes for a given `kankaku-claude` checkout path. */
+export function statusLineCommand(checkoutPath) {
+    return `node "${checkoutPath}/src/statusline.ts"`;
+}
+export function writeStatusLine(settingsPath, checkoutPath) {
+    const existing = readJsonObjectOrEmpty(settingsPath);
+    const command = statusLineCommand(checkoutPath);
+    const currentStatusLine = existing["statusLine"];
+    const currentCommand = currentStatusLine && typeof currentStatusLine === "object" && !Array.isArray(currentStatusLine)
+        ? currentStatusLine["command"]
+        : undefined;
+    if (currentCommand === command)
+        return { changed: false };
+    backupOnce(settingsPath);
+    writeJsonAtomic(settingsPath, { ...existing, statusLine: { type: "command", command } });
+    return { changed: true };
+}

package/dist/adapters/setup/hub.js

@@ -0,0 +1,52 @@
+/**
+ * Setup-only hub adapter: writes `~/.kankaku/credentials.json` and checks
+ * the hub's health endpoint. Reading hub credentials for normal (non-setup)
+ * use is `adapters/hub.ts#resolveHub`, wrapping kankaku's own
+ * `resolveHubCredentials` — this file only ever writes.
+ */
+import { existsSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { backupOnce, readJsonObjectOrEmpty, writeJsonAtomic } from "./json-writer.js";
+const OWNER_DIR_MODE = 0o700;
+const OWNER_FILE_MODE = 0o600;
+export function credentialsPath(homeDir) {
+    return join(homeDir, ".kankaku", "credentials.json");
+}
+/**
+ * Write `credentials` to `<homeDir>/.kankaku/credentials.json`, 0600.
+ * `~/.kankaku` is created 0700 only when it does not exist yet — an
+ * already-existing `~/.kankaku` (shared with kankaku's own worklog
+ * storage) is never chmod'd, mirroring kankaku's own R2 rule. A no-op,
+ * with no backup and no write, when the file already holds these exact
+ * values.
+ */
+export function writeHubCredentials(homeDir, credentials) {
+    const dir = join(homeDir, ".kankaku");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: OWNER_DIR_MODE });
+    const filePath = credentialsPath(homeDir);
+    const existing = readJsonObjectOrEmpty(filePath);
+    const unchanged = existsSync(filePath) && existing["url"] === credentials.url && existing["email"] === credentials.email && existing["password"] === credentials.password;
+    if (unchanged)
+        return { changed: false };
+    backupOnce(filePath);
+    writeJsonAtomic(filePath, { ...existing, url: credentials.url, email: credentials.email, password: credentials.password });
+    chmodSync(filePath, OWNER_FILE_MODE);
+    return { changed: true };
+}
+/** `GET <url>/api/health` under a timeout (default 5s); `true` only on an ok response, `false` on any error, non-ok status, or timeout. Never throws. */
+export async function checkHubHealth(url, deps = {}) {
+    const doFetch = deps.fetch ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? 5000);
+    try {
+        const response = await doFetch(`${url.replace(/\/+$/, "")}/api/health`, { signal: controller.signal });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/adapters/setup/json-writer.js

@@ -0,0 +1,41 @@
+/**
+ * Shared write primitives for every `setup` writer: read-existing-or-{},
+ * atomic tmp+rename, and a one-time `<file>.bak` — mirrors kankaku's own
+ * `adapters/project-config.ts#writeProjectTargetIds`.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** Parse `filePath` as a JSON object, defaulting to `{}` on any absence, malformed JSON, or non-object document. Never throws. */
+export function readJsonObjectOrEmpty(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Copy `filePath`'s current bytes to `<filePath>.bak`, but only the first
+ * time: a no-op when `filePath` does not exist yet (nothing to back up) or
+ * `<filePath>.bak` already exists (never overwritten).
+ */
+export function backupOnce(filePath) {
+    if (!existsSync(filePath))
+        return;
+    const backupPath = `${filePath}.bak`;
+    if (existsSync(backupPath))
+        return;
+    writeFileSync(backupPath, readFileSync(filePath));
+}
+/** Write `value` as 2-space-indented JSON to `filePath` via tmp file + rename, creating the parent directory when missing. */
+export function writeJsonAtomic(filePath, value, dirMode) {
+    mkdirSync(dirname(filePath), dirMode !== undefined ? { recursive: true, mode: dirMode } : { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value, null, 2));
+    renameSync(tmp, filePath);
+}

package/dist/adapters/setup/pi.js

@@ -0,0 +1,21 @@
+/**
+ * Writer for a pi-family settings file (`~/.pi/agent/settings.json`,
+ * `~/.gentle-shell/agent/settings.json` — same shape, shared here): adds
+ * `"npm:kankaku"` to `packages`, leaving every other key and its order
+ * untouched. A no-op when kankaku is already present (`npm:kankaku`, a
+ * versioned spec, or a local path — see `domain/setup-plan.ts#isKankakuPackage`).
+ */
+import { isKankakuPackage } from "../../domain/setup-plan.js";
+import { backupOnce, readJsonObjectOrEmpty, writeJsonAtomic } from "./json-writer.js";
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+export function addKankakuPackage(settingsPath) {
+    const existing = readJsonObjectOrEmpty(settingsPath);
+    const packages = isStringArray(existing["packages"]) ? existing["packages"] : [];
+    if (packages.some(isKankakuPackage))
+        return { changed: false };
+    backupOnce(settingsPath);
+    writeJsonAtomic(settingsPath, { ...existing, packages: [...packages, "npm:kankaku"] });
+    return { changed: true };
+}

package/dist/adapters/setup/readline-prompter.js

@@ -0,0 +1,68 @@
+/**
+ * `node:readline/promises`-backed `Prompter`. `secret()` hides typed input
+ * by routing readline's own echo through a `Writable` that swallows bytes
+ * while muted — readline only echoes per keystroke when it treats the
+ * output as a terminal (`terminal: true`, the default when `output.isTTY`
+ * is set), which is exactly the case that needs hiding; a piped/non-tty
+ * output (as in tests) never echoes per keystroke in the first place, so
+ * muting there is a no-op rather than a behaviour change.
+ */
+import * as readline from "node:readline/promises";
+import { Writable } from "node:stream";
+function createMutableOutput(realOutput) {
+    let muted = false;
+    const stream = new Writable({
+        write(chunk, encoding, callback) {
+            if (!muted)
+                realOutput.write(chunk, encoding);
+            callback();
+        },
+    });
+    // Mirror `isTTY` so readline's terminal-mode autodetection (based on
+    // `output.isTTY`) behaves the same as it would against `realOutput`.
+    stream.isTTY = realOutput.isTTY;
+    return { stream, setMuted: (value) => (muted = value) };
+}
+export function createReadlinePrompter(input, output) {
+    return {
+        async confirm(question, defaultValue) {
+            const rl = readline.createInterface({ input, output });
+            try {
+                const suffix = defaultValue ? "[Y/n]" : "[y/N]";
+                const raw = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+                if (raw === "")
+                    return defaultValue;
+                return raw === "y" || raw === "yes";
+            }
+            finally {
+                rl.close();
+            }
+        },
+        async text(question, defaultValue) {
+            const rl = readline.createInterface({ input, output });
+            try {
+                const raw = (await rl.question(`${question} (${defaultValue}) `)).trim();
+                return raw === "" ? defaultValue : raw;
+            }
+            finally {
+                rl.close();
+            }
+        },
+        async secret(question) {
+            const mutable = createMutableOutput(output);
+            const rl = readline.createInterface({ input, output: mutable.stream });
+            try {
+                mutable.setMuted(false);
+                output.write(`${question} `);
+                mutable.setMuted(true);
+                const answer = await rl.question("");
+                return answer;
+            }
+            finally {
+                mutable.setMuted(false);
+                output.write("\n");
+                rl.close();
+            }
+        },
+    };
+}

package/dist/adapters/setup/tui-config.js

@@ -0,0 +1,34 @@
+/**
+ * Setup-only writer for `~/.kankaku/tui.json`. Reading it for normal
+ * (non-setup) use is `adapters/tui-config.ts#readTuiConfig` — this file
+ * only ever writes.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { backupOnce, readJsonObjectOrEmpty, writeJsonAtomic } from "./json-writer.js";
+const OWNER_DIR_MODE = 0o700;
+export function tuiConfigPath(homeDir) {
+    return join(homeDir, ".kankaku", "tui.json");
+}
+function sameRoots(a, b) {
+    return Array.isArray(a) && a.length === b.length && a.every((entry, index) => entry === b[index]);
+}
+/**
+ * Write `{ roots }` to `<homeDir>/.kankaku/tui.json`, preserving any other
+ * existing key. `~/.kankaku` is created 0700 only when it does not exist
+ * yet (never chmod'd otherwise — see `setup/hub.ts#writeHubCredentials`).
+ * A no-op, with no backup and no write, when `roots` already matches
+ * exactly.
+ */
+export function writeTuiConfig(homeDir, roots) {
+    const dir = join(homeDir, ".kankaku");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: OWNER_DIR_MODE });
+    const filePath = tuiConfigPath(homeDir);
+    const existing = readJsonObjectOrEmpty(filePath);
+    if (existsSync(filePath) && sameRoots(existing["roots"], roots))
+        return { changed: false };
+    backupOnce(filePath);
+    writeJsonAtomic(filePath, { ...existing, roots });
+    return { changed: true };
+}

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { jsx as _jsx } from "react/jsx-runtime";
 import { homedir, hostname } from "node:os";
-import { resolve } from "node:path";
-import { realpathSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { render } from "ink";
 import { buildTasks, localDay } from "kankaku/domain";
@@ -19,7 +19,14 @@ import { App } from "./ui/app.js";
 import { buildTasksModel } from "./domain/tasks-model.js";
 import { buildSyncRows } from "./domain/sync-model.js";
 import { DEFAULT_THEME, ThemeProvider, resolveTheme } from "./ui/theme.js";
-const USAGE = "usage: kankaku [today|tasks [--all]|catalog [refresh]|sync [status|all] [--project <dir>]] [--roots a,b] [--theme name]\n";
+import { detectAgents, formatDoctorLines, formatSetupPlanLines, planSetup } from "./domain/setup-plan.js";
+import { readAgentFacts } from "./adapters/setup/agents.js";
+import { addKankakuPackage } from "./adapters/setup/pi.js";
+import { writeStatusLine } from "./adapters/setup/claude.js";
+import { checkHubHealth, credentialsPath, writeHubCredentials } from "./adapters/setup/hub.js";
+import { tuiConfigPath, writeTuiConfig } from "./adapters/setup/tui-config.js";
+import { createReadlinePrompter } from "./adapters/setup/readline-prompter.js";
+const USAGE = "usage: kankaku [today|tasks [--all]|catalog [refresh]|sync [status|all] [--project <dir>]|setup [--yes] [--dry-run]|doctor] [--roots a,b] [--theme name]\n";
 /** Load today's model for `roots`: discover projects, read their worklogs, build rows. */
 export function loadToday(roots) {
     const projects = discoverProjects(roots);
@@ -192,6 +199,135 @@ async function runSyncCommand(args, roots, deps) {
     if (failed)
         deps.exit(1);
 }
+/**
+ * Gather the plain facts `domain/setup-plan.ts` needs: every detected
+ * agent, hub credentials/health, and whether `tui.json` exists. Read-only;
+ * the hub health check (bounded to 5s) is the only network call.
+ */
+async function gatherSetupFacts(deps) {
+    const agents = detectAgents(readAgentFacts(deps.homeDir));
+    const hubResolution = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    const credPath = credentialsPath(deps.homeDir);
+    const hub = hubResolution.ok
+        ? {
+            credentialsPresent: true,
+            url: hubResolution.credentials.url,
+            healthOk: await checkHubHealth(hubResolution.credentials.url, { fetch: deps.fetch }),
+            credentialsPath: credPath,
+        }
+        : { credentialsPresent: false, url: undefined, healthOk: undefined, credentialsPath: credPath };
+    const tuiPath = tuiConfigPath(deps.homeDir);
+    const tui = { present: existsSync(tuiPath), path: tuiPath };
+    return { agents, hub, tui };
+}
+/** `kankaku doctor`: read-only report, `domain/setup-plan.ts#formatDoctorLines` verbatim. Also run as the last step of `kankaku setup`. */
+async function runDoctorCommand(deps) {
+    const { agents, hub, tui } = await gatherSetupFacts(deps);
+    deps.stdout(formatDoctorLines(agents, hub, tui).join("\n"));
+}
+/**
+ * Extract a plausible kankaku-claude checkout path from an existing
+ * `statusLine.command` of the shape `node "<checkout>/src/statusline.ts"`,
+ * whatever package it currently points at — used as the `text()` prompt's
+ * default. `undefined` when the command doesn't match that shape at all.
+ */
+function guessClaudeCheckout(existingCommand) {
+    if (!existingCommand)
+        return undefined;
+    const match = /^node\s+"(.+)\/src\/statusline\.ts"$/.exec(existingCommand.trim());
+    return match ? match[1] : undefined;
+}
+/** Answers one question at a time: `--yes` always takes `defaultValue` without touching `prompter`; otherwise a `Prompter` must have been injected. */
+function makeAsker(yes, prompter) {
+    function requirePrompter() {
+        if (!prompter)
+            throw new Error("kankaku setup: no prompter available (pass --yes or --dry-run, or inject one)");
+        return prompter;
+    }
+    return {
+        confirm: (question, defaultValue) => (yes ? Promise.resolve(defaultValue) : requirePrompter().confirm(question, defaultValue)),
+        text: (question, defaultValue) => (yes ? Promise.resolve(defaultValue) : requirePrompter().text(question, defaultValue)),
+        secret: (question) => (yes ? Promise.resolve("") : requirePrompter().secret(question)),
+    };
+}
+/**
+ * `kankaku setup [--yes] [--dry-run]`: detects every agent, prompts (or
+ * takes each question's own default with `--yes`) for what to install or
+ * configure, writes only what was confirmed, and ends with the same
+ * report as `kankaku doctor`. `--dry-run` prints the plan and writes
+ * nothing — no prompt is asked and no default is applied.
+ */
+/** Tell the user what setup just did to a file: nothing is written silently. */
+function announceWrite(deps, file, result) {
+    deps.stdout(result.changed ? `wrote ${file}` : `unchanged ${file}`);
+}
+async function runSetupCommand(args, deps) {
+    const dryRun = args.includes("--dry-run");
+    const yes = args.includes("--yes");
+    const initial = await gatherSetupFacts(deps);
+    const steps = planSetup(initial.agents, initial.hub, initial.tui);
+    if (dryRun) {
+        deps.stdout(formatSetupPlanLines(steps).join("\n"));
+        return;
+    }
+    const ask = makeAsker(yes, deps.prompter);
+    const byId = Object.fromEntries(steps.map((step) => [step.id, step]));
+    for (const agent of initial.agents) {
+        if (agent.id === "codex" || agent.id === "opencode")
+            continue;
+        const step = byId[agent.id];
+        if (step.state !== "todo")
+            continue;
+        if (agent.id === "claude-code") {
+            const doIt = await ask.confirm(`Configure Claude Code's statusLine for kankaku (${step.file})?`, true);
+            if (!doIt)
+                continue;
+            const guessed = guessClaudeCheckout(readAgentFacts(deps.homeDir).claudeCode?.statusLineCommand) ?? "";
+            const checkoutPath = await ask.text("Path to your kankaku-claude checkout", guessed);
+            if (checkoutPath !== "")
+                announceWrite(deps, step.file, writeStatusLine(step.file, checkoutPath));
+            continue;
+        }
+        const doIt = await ask.confirm(`Install kankaku in ${step.title} (${step.file})?`, true);
+        if (doIt)
+            announceWrite(deps, step.file, addKankakuPackage(step.file));
+    }
+    if (byId["hub"].state === "todo" && !initial.hub.credentialsPresent) {
+        const doIt = await ask.confirm("Configure hub credentials now?", false);
+        if (doIt) {
+            const url = await ask.text("Hub URL", "");
+            if (url !== "") {
+                const email = await ask.text("Email", "");
+                const password = await ask.secret("Password");
+                announceWrite(deps, credentialsPath(deps.homeDir), writeHubCredentials(deps.homeDir, { url, email, password }));
+            }
+        }
+    }
+    if (byId["tui-config"].state === "todo") {
+        const defaultRoots = dirname(deps.cwd);
+        const doIt = await ask.confirm(`Write TUI roots to ${byId["tui-config"].file}?`, true);
+        if (doIt) {
+            const rootsInput = await ask.text("Roots for the TUI (comma-separated)", defaultRoots);
+            const roots = rootsInput
+                .split(",")
+                .map((root) => root.trim())
+                .filter((root) => root.length > 0);
+            if (roots.length > 0)
+                announceWrite(deps, tuiConfigPath(deps.homeDir), writeTuiConfig(deps.homeDir, roots));
+        }
+    }
+    const finalHub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    if (finalHub.ok) {
+        const doRefresh = await ask.confirm("Refresh the hub catalog now?", false);
+        if (doRefresh) {
+            const { now, fetch: fetchOverride } = envDeps(deps);
+            const catalog = createCatalog(finalHub.credentials, { homeDir: () => deps.homeDir, now, ...(fetchOverride ? { fetch: fetchOverride } : {}) });
+            const snapshot = await refreshCatalogAdapter(catalog);
+            deps.stdout(formatCatalogRefreshLines(snapshot).join("\n"));
+        }
+    }
+    await runDoctorCommand(deps);
+}
 /**
  * Resolve the `--theme`/`KANKAKU_TUI_THEME` preset (flag wins), defaulting
  * to {@link DEFAULT_THEME} when neither is given. An explicit but unknown
@@ -236,6 +372,14 @@ export async function runCli(argv, deps) {
         await runSyncCommand(rest.slice(1), roots, deps);
         return;
     }
+    if (command === "setup") {
+        await runSetupCommand(rest.slice(1), deps);
+        return;
+    }
+    if (command === "doctor") {
+        await runDoctorCommand(deps);
+        return;
+    }
     deps.stderr(USAGE);
     deps.exit(1);
 }
@@ -360,6 +504,7 @@ if (isMain) {
         exit: (code) => {
             process.exit(code);
         },
+        prompter: createReadlinePrompter(process.stdin, process.stdout),
         renderApp: (roots, theme) => {
             render(_jsx(ThemeProvider, { theme: theme, children: _jsx(App, { roots: roots, version: readOwnVersion(), loadToday: () => loadDashboard(roots, realDeps), loadTasks: (options) => loadTasks(roots, options), catalog: catalogScreenDeps(realDeps), sync: syncScreenDeps(realDeps, roots), dashboardActions: dashboardActionsDeps(realDeps, roots) }) }), { alternateScreen: true, exitOnCtrlC: true });
         },

package/dist/domain/setup-plan.js

@@ -0,0 +1,109 @@
+/**
+ * Pure setup domain: which coding agents kankaku can find on this machine,
+ * whether each is already configured, and the ordered plan `kankaku setup`
+ * and `kankaku doctor` both report from. No I/O, no `Date.now()` — callers
+ * read the real files (`src/adapters/setup/*.ts`) and pass plain facts in.
+ */
+/**
+ * A `packages` entry counts as kankaku when it is the bare npm spec
+ * (`npm:kankaku`), a versioned npm spec (`npm:kankaku@x.y.z`), or a path
+ * (relative or absolute, npm's `file:`-less local-package shorthand) whose
+ * last segment is exactly `kankaku` — e.g. `../../workspace/kankaku`.
+ */
+export function isKankakuPackage(entry) {
+    if (entry === "npm:kankaku" || entry.startsWith("npm:kankaku@"))
+        return true;
+    const segments = entry.split("/").filter((segment) => segment.length > 0);
+    return segments[segments.length - 1] === "kankaku";
+}
+function settingsPackagesStatus(id, facts) {
+    if (!facts)
+        return { id, present: false, configured: false, adapterAvailable: true, detail: "not found" };
+    return { id, present: true, configured: facts.packages.some(isKankakuPackage), adapterAvailable: true, detail: facts.settingsPath };
+}
+function claudeCodeStatus(facts) {
+    if (!facts)
+        return { id: "claude-code", present: false, configured: false, adapterAvailable: true, detail: "not found" };
+    const configured = facts.statusLineCommand !== undefined && facts.statusLineCommand.includes("kankaku");
+    return { id: "claude-code", present: true, configured, adapterAvailable: true, detail: facts.settingsPath };
+}
+function noAdapterStatus(id, facts) {
+    if (!facts)
+        return { id, present: false, configured: false, adapterAvailable: false, detail: "not found" };
+    return { id, present: true, configured: false, adapterAvailable: false, detail: facts.configPath };
+}
+/** Detect every agent kankaku-tui knows about from plain, already-read facts. Order: pi, gentle-shell, claude-code, codex, opencode. */
+export function detectAgents(facts) {
+    return [
+        settingsPackagesStatus("pi", facts.pi),
+        settingsPackagesStatus("gentle-shell", facts.gentleShell),
+        claudeCodeStatus(facts.claudeCode),
+        noAdapterStatus("codex", facts.codex),
+        noAdapterStatus("opencode", facts.opencode),
+    ];
+}
+const AGENT_TITLES = {
+    pi: "pi",
+    "gentle-shell": "gentle-shell",
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    opencode: "OpenCode",
+};
+function todoAction(agent) {
+    if (agent.id === "claude-code")
+        return `set statusLine in ${agent.detail} to the kankaku status line`;
+    return `add "npm:kankaku" to packages in ${agent.detail}`;
+}
+function agentStep(agent) {
+    const title = AGENT_TITLES[agent.id];
+    if (!agent.adapterAvailable) {
+        return { id: agent.id, title, state: "unavailable", action: "no adapter yet", file: "" };
+    }
+    if (!agent.present) {
+        return { id: agent.id, title, state: "unavailable", action: `no settings file found (expected ${agent.detail})`, file: "" };
+    }
+    if (agent.configured) {
+        return { id: agent.id, title, state: "done", action: `already configured (${agent.detail})`, file: agent.detail };
+    }
+    return { id: agent.id, title, state: "todo", action: todoAction(agent), file: agent.detail };
+}
+function hubStep(hub) {
+    if (!hub.credentialsPresent) {
+        return { id: "hub", title: "Hub", state: "todo", action: `write hub credentials to ${hub.credentialsPath}`, file: hub.credentialsPath };
+    }
+    if (hub.healthOk === true) {
+        return { id: "hub", title: "Hub", state: "done", action: `credentials present (${hub.url}); health check ok`, file: hub.credentialsPath };
+    }
+    return {
+        id: "hub",
+        title: "Hub",
+        state: "todo",
+        action: `credentials present (${hub.url}) but the health check did not succeed; verify the hub is reachable`,
+        file: "",
+    };
+}
+function tuiStep(tui) {
+    if (tui.present) {
+        return { id: "tui-config", title: "TUI config", state: "done", action: `roots already configured (${tui.path})`, file: tui.path };
+    }
+    return { id: "tui-config", title: "TUI config", state: "todo", action: `write roots to ${tui.path}`, file: tui.path };
+}
+/** Build the ordered setup plan: one step per detected agent, then the hub, then the TUI's own `tui.json`. */
+export function planSetup(agents, hub, tui) {
+    return [...agents.map(agentStep), hubStep(hub), tuiStep(tui)];
+}
+/**
+ * `kankaku doctor`'s plain-text report: one line per agent, one for the
+ * hub, one for `tui.json` (`<title>: <state> — <action>`), followed by a
+ * `next: <action>` hint for every step still `todo`.
+ */
+export function formatDoctorLines(agents, hub, tui) {
+    const steps = planSetup(agents, hub, tui);
+    const statusLines = steps.map((step) => `${step.title}: ${step.state} — ${step.action}`);
+    const hints = steps.filter((step) => step.state === "todo").map((step) => `next: ${step.action}`);
+    return [...statusLines, ...hints];
+}
+/** `kankaku setup [--dry-run]`'s plan report: one line per step, appending the exact file it would change (`[<file>]`) when there is one. */
+export function formatSetupPlanLines(steps) {
+    return steps.map((step) => `${step.title}: ${step.state} — ${step.action}${step.file ? ` [${step.file}]` : ""}`);
+}

package/dist/ports/prompter.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-tui",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Terminal app that shows today's kankaku work across every project on disk",
   "license": "MIT",
   "type": "module",