kankaku-tui 0.1.1

package/dist/cli.js

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { homedir, hostname } from "node:os";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { render } from "ink";
+import { buildTasks, localDay } from "kankaku/domain";
+import { buildSyncStatusLines, formatCatalogRefreshLines, formatSyncSummaryLines, formatTasks } from "kankaku/hub";
+import { readTuiConfig } from "./adapters/tui-config.js";
+import { discoverProjects } from "./adapters/project-discovery.js";
+import { readProjectRecords } from "./adapters/worklog-reader.js";
+import { computeProjectSyncStatus, createCatalog, refreshCatalog as refreshCatalogAdapter, resolveHub, syncProject } from "./adapters/hub.js";
+import { readOwnVersion } from "./adapters/app-info.js";
+import { buildCatalogModel } from "./domain/catalog-model.js";
+import { buildTodayRows, formatTodayLines } from "./domain/today-model.js";
+import { buildDashboardModel } from "./domain/dashboard-model.js";
+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";
+/** Load today's model for `roots`: discover projects, read their worklogs, build rows. */
+export function loadToday(roots) {
+    const projects = discoverProjects(roots);
+    const withRecords = projects.map((project) => ({ name: project.name, records: readProjectRecords(project) }));
+    return buildTodayRows(withRecords);
+}
+/** Load the Tasks screen's model for `roots`: same project/record discovery as `loadToday`, restricted to today unless `options.all`. */
+export function loadTasks(roots, options) {
+    const projects = discoverProjects(roots);
+    const withRecords = projects.map((project) => ({ name: project.name, records: readProjectRecords(project) }));
+    return buildTasksModel(withRecords, options);
+}
+/**
+ * Load the Today screen's dashboard model: every project's records (kept
+ * whole — `dashboard-model.ts` derives both today's rows and the last 7
+ * days from the same set, so nothing extra is read beyond what
+ * `readProjectRecords` already loads), plus the Hub card from local
+ * no-network sync status and the cached catalog. Without hub credentials,
+ * or with no catalog cached yet, the Hub card degrades to `"unavailable"`
+ * without touching the network.
+ */
+export function loadDashboard(roots, deps) {
+    const projects = discoverProjects(roots);
+    const withRecords = projects.map((project) => ({ name: project.name, records: readProjectRecords(project) }));
+    const { now } = envDeps(deps);
+    const today = localDay(new Date(now()).toISOString());
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    if (!hub.ok) {
+        return buildDashboardModel(withRecords, undefined, undefined, { today });
+    }
+    const { fetch: fetchOverride } = envDeps(deps);
+    const hubEntries = projects.map((project) => ({
+        name: project.name,
+        status: computeProjectSyncStatus(project, hub.credentials, deps.env ?? {}),
+    }));
+    const catalog = createCatalog(hub.credentials, { homeDir: () => deps.homeDir, now, ...(fetchOverride ? { fetch: fetchOverride } : {}) });
+    const catalogModel = buildCatalogModel(catalog.read(), now());
+    const catalogSummary = catalogModel.status === "ready"
+        ? { url: catalogModel.url, clientCount: catalogModel.clients.length, projectCount: catalogModel.clients.reduce((sum, client) => sum + client.projects.length, 0) }
+        : undefined;
+    return buildDashboardModel(withRecords, hubEntries, catalogSummary, { today });
+}
+function parseRoots(argv, deps) {
+    const flagIndex = argv.indexOf("--roots");
+    if (flagIndex === -1) {
+        return { roots: readTuiConfig(deps.homeDir, deps.cwd).roots, rest: argv };
+    }
+    const value = argv[flagIndex + 1] ?? "";
+    const roots = value.split(",").filter((root) => root.length > 0);
+    const rest = [...argv.slice(0, flagIndex), ...argv.slice(flagIndex + 2)];
+    return { roots, rest };
+}
+/** Strip `--theme <name>` from `argv` (present anywhere), returning its value (if any) and the rest. */
+function parseThemeFlag(argv) {
+    const flagIndex = argv.indexOf("--theme");
+    if (flagIndex === -1)
+        return { theme: undefined, rest: argv };
+    const value = argv[flagIndex + 1];
+    const rest = [...argv.slice(0, flagIndex), ...argv.slice(flagIndex + 2)];
+    return { theme: value, rest };
+}
+function parseProjectFlag(argv, cwd) {
+    const flagIndex = argv.indexOf("--project");
+    if (flagIndex === -1)
+        return { project: undefined, rest: argv };
+    const value = argv[flagIndex + 1];
+    const rest = [...argv.slice(0, flagIndex), ...argv.slice(flagIndex + 2)];
+    return { project: value !== undefined ? resolve(cwd, value) : undefined, rest };
+}
+function envDeps(deps) {
+    return {
+        env: deps.env ?? {},
+        homeDir: () => deps.homeDir,
+        now: deps.now ?? (() => Date.now()),
+        hostname: deps.hostname ?? (() => hostname()),
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+    };
+}
+/** Filter `tasks` to `day` (local calendar day), or return every task when `day` is `undefined`. */
+function filterTasksForDay(tasks, day) {
+    return day === undefined ? tasks : tasks.filter((task) => localDay(task.startedAt) === day);
+}
+/** `kankaku tasks [--all]`: kankaku's own `formatTasks` output per project, prefixed by a `== <project> ==` header. */
+function runTasksCommand(args, roots, deps) {
+    const all = args.includes("--all");
+    const targetDay = all ? undefined : localDay(new Date().toISOString());
+    const projects = discoverProjects(roots);
+    const blocks = [];
+    for (const project of projects) {
+        const tasks = filterTasksForDay(buildTasks(readProjectRecords(project)), targetDay);
+        if (tasks.length === 0)
+            continue;
+        blocks.push(`== ${project.name} ==\n${formatTasks(tasks)}`);
+    }
+    deps.stdout(blocks.length > 0 ? blocks.join("\n\n") : "no tasks");
+}
+/** `kankaku catalog [refresh]`. Without hub credentials: a one-line note, exit 0. With credentials: `refresh` fetches over the network (exit 1 on failure); without `refresh`, only the local cache is read (no network) and reported. */
+async function runCatalogCommand(args, deps) {
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    const doRefresh = args[0] === "refresh";
+    if (!hub.ok) {
+        if (doRefresh) {
+            deps.stderr(`kankaku catalog refresh: ${hub.reason}\n`);
+            deps.exit(1);
+        }
+        else {
+            deps.stdout(hub.reason);
+        }
+        return;
+    }
+    const { now, fetch: fetchOverride } = envDeps(deps);
+    const catalog = createCatalog(hub.credentials, { homeDir: () => deps.homeDir, now, ...(fetchOverride ? { fetch: fetchOverride } : {}) });
+    if (doRefresh) {
+        const snapshot = await refreshCatalogAdapter(catalog);
+        deps.stdout(formatCatalogRefreshLines(snapshot).join("\n"));
+        if (!snapshot)
+            deps.exit(1);
+        return;
+    }
+    const model = buildCatalogModel(catalog.read(), now());
+    if (model.status === "unavailable") {
+        deps.stdout("no catalog cached yet; run 'kankaku catalog refresh'");
+        return;
+    }
+    const clientCount = model.clients.length;
+    const projectCount = model.clients.reduce((sum, client) => sum + client.projects.length, 0);
+    deps.stdout(`${model.url}: ${clientCount} client(s), ${projectCount} project(s)${model.stale ? " (stale)" : ""}`);
+}
+/** Resolve the target projects for `sync`: `--project <dir>` restricts to exactly that directory; otherwise every discovered project under `roots`. */
+function resolveTargetProjects(roots, projectFlag) {
+    if (projectFlag !== undefined) {
+        return [{ name: projectFlag.split(/[\\/]/).filter(Boolean).pop() ?? projectFlag, dir: projectFlag }];
+    }
+    return discoverProjects(roots);
+}
+/** `kankaku sync [status|all] [--project <dir>]`. Without hub credentials: a one-line note for `status` (exit 0), an error for an actual sync attempt (exit 1). */
+async function runSyncCommand(args, roots, deps) {
+    const { project: projectFlag, rest } = parseProjectFlag(args, deps.cwd);
+    const mode = rest[0] === "status" || rest[0] === "all" ? rest[0] : undefined;
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    const targets = resolveTargetProjects(roots, projectFlag);
+    if (!hub.ok) {
+        if (mode === "status") {
+            deps.stdout(hub.reason);
+        }
+        else {
+            deps.stderr(`kankaku sync: ${hub.reason}\n`);
+            deps.exit(1);
+        }
+        return;
+    }
+    if (mode === "status") {
+        const blocks = targets.map((project) => {
+            const status = computeProjectSyncStatus(project, hub.credentials, deps.env ?? {});
+            return `== ${project.name} ==\n${buildSyncStatusLines(status).join("\n")}`;
+        });
+        deps.stdout(blocks.join("\n\n"));
+        return;
+    }
+    const runnerDeps = envDeps(deps);
+    let failed = false;
+    const blocks = [];
+    for (const project of targets) {
+        const summary = await syncProject(project, hub.credentials, { full: mode === "all" }, runnerDeps);
+        if (summary.locked || summary.error !== undefined || summary.failed.length > 0)
+            failed = true;
+        blocks.push(`== ${project.name} ==\n${formatSyncSummaryLines(summary).join("\n")}`);
+    }
+    deps.stdout(blocks.join("\n\n"));
+    if (failed)
+        deps.exit(1);
+}
+/**
+ * Resolve the `--theme`/`KANKAKU_TUI_THEME` preset (flag wins), defaulting
+ * to {@link DEFAULT_THEME} when neither is given. An explicit but unknown
+ * name is a usage error, never a silent fallback.
+ */
+function resolveCliTheme(themeFlag, env) {
+    const requested = themeFlag ?? env?.KANKAKU_TUI_THEME;
+    if (requested === undefined)
+        return { ok: true, theme: DEFAULT_THEME };
+    return resolveTheme(requested);
+}
+/** Parse `argv` and run the requested mode against injected `deps`. No logic beyond argv handling belongs here. */
+export async function runCli(argv, deps) {
+    const { theme: themeFlag, rest: argvAfterTheme } = parseThemeFlag(argv);
+    const themeResult = resolveCliTheme(themeFlag, deps.env);
+    if (!themeResult.ok) {
+        deps.stderr(`kankaku: ${themeResult.reason}\n`);
+        deps.exit(1);
+        return;
+    }
+    const theme = themeResult.theme;
+    const { roots, rest } = parseRoots(argvAfterTheme, deps);
+    const [command] = rest;
+    if (command === undefined) {
+        deps.renderApp(roots, theme);
+        return;
+    }
+    if (command === "today") {
+        const model = loadToday(roots);
+        deps.stdout(formatTodayLines(model.rows, model.total).join("\n"));
+        return;
+    }
+    if (command === "tasks") {
+        runTasksCommand(rest.slice(1), roots, deps);
+        return;
+    }
+    if (command === "catalog") {
+        await runCatalogCommand(rest.slice(1), deps);
+        return;
+    }
+    if (command === "sync") {
+        await runSyncCommand(rest.slice(1), roots, deps);
+        return;
+    }
+    deps.stderr(USAGE);
+    deps.exit(1);
+}
+/** Build the Catalog screen's `load`/`refresh` deps for the interactive app; used only by `renderApp`. */
+function catalogScreenDeps(deps) {
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    const { now, fetch: fetchOverride } = envDeps(deps);
+    if (!hub.ok) {
+        return { load: () => ({ status: "unavailable", reason: hub.reason }), refresh: async () => ({ status: "unavailable", reason: hub.reason }) };
+    }
+    const catalog = createCatalog(hub.credentials, { homeDir: () => deps.homeDir, now, ...(fetchOverride ? { fetch: fetchOverride } : {}) });
+    return {
+        load: () => buildCatalogModel(catalog.read(), now()),
+        refresh: async () => buildCatalogModel(await refreshCatalogAdapter(catalog), now()),
+    };
+}
+/** Build the Sync screen's `load`/`syncOne`/`syncAll` deps for the interactive app; used only by `renderApp`. */
+function syncScreenDeps(deps, roots) {
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    const runnerDeps = envDeps(deps);
+    if (!hub.ok) {
+        const reason = hub.reason;
+        return {
+            load: () => ({ status: "unavailable", reason }),
+            syncOne: async () => ({ ok: false, message: reason }),
+            syncAll: async () => [],
+        };
+    }
+    const credentials = hub.credentials;
+    const load = () => {
+        const projects = discoverProjects(roots);
+        const entries = projects.map((project) => ({ project, status: computeProjectSyncStatus(project, credentials, deps.env ?? {}) }));
+        return { status: "ready", rows: buildSyncRows(entries) };
+    };
+    const findProject = (name) => discoverProjects(roots).find((project) => project.name === name);
+    return {
+        load,
+        syncOne: async (row, options) => {
+            const project = findProject(row.name) ?? { name: row.name, dir: row.dir };
+            const summary = await syncProject(project, credentials, options, runnerDeps);
+            return { ok: summary.error === undefined && summary.failed.length === 0 && !summary.locked, message: formatSyncSummaryLines(summary).join("; ") };
+        },
+        syncAll: async () => {
+            const projects = discoverProjects(roots);
+            const results = [];
+            for (const project of projects) {
+                const summary = await syncProject(project, credentials, {}, runnerDeps);
+                results.push({ ok: summary.error === undefined && summary.failed.length === 0 && !summary.locked, message: formatSyncSummaryLines(summary).join("; ") });
+            }
+            return results;
+        },
+    };
+}
+/**
+ * Build the Dashboard screen's Quick actions deps for the interactive app:
+ * `refreshCatalog` refreshes the cached catalog through `createCatalog`/
+ * `refreshCatalogAdapter`, `syncAll` runs `syncProject` over every
+ * discovered project — both reuse kankaku's own `formatCatalogRefreshLines`/
+ * `formatSyncSummaryLines` for the result message, never reimplementing
+ * them. Without hub credentials, `hubAvailable` is `false` and neither
+ * function is ever called by the screen. Used only by `renderApp`.
+ */
+function dashboardActionsDeps(deps, roots) {
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    if (!hub.ok) {
+        const reason = hub.reason;
+        return { hubAvailable: false, refreshCatalog: async () => reason, syncAll: async () => reason };
+    }
+    const credentials = hub.credentials;
+    const runnerDeps = envDeps(deps);
+    const { now, fetch: fetchOverride } = envDeps(deps);
+    return {
+        hubAvailable: true,
+        refreshCatalog: async () => {
+            const catalog = createCatalog(credentials, { homeDir: () => deps.homeDir, now, ...(fetchOverride ? { fetch: fetchOverride } : {}) });
+            const snapshot = await refreshCatalogAdapter(catalog);
+            return formatCatalogRefreshLines(snapshot).join(" · ");
+        },
+        syncAll: async (options) => {
+            const projects = discoverProjects(roots);
+            if (projects.length === 0)
+                return "no projects to sync";
+            const summaries = await Promise.all(projects.map((project) => syncProject(project, credentials, options, runnerDeps)));
+            return summaries.flatMap((summary) => formatSyncSummaryLines(summary)).join(" · ");
+        },
+    };
+}
+const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+    const realDeps = {
+        homeDir: homedir(),
+        cwd: process.cwd(),
+        env: process.env,
+        now: () => Date.now(),
+        hostname: () => hostname(),
+        stdout: (text) => {
+            console.log(text);
+        },
+        stderr: (text) => {
+            process.stderr.write(text);
+        },
+        exit: (code) => {
+            process.exit(code);
+        },
+        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 });
+        },
+    };
+    void runCli(process.argv.slice(2), realDeps);
+}

package/dist/domain/catalog-model.js

@@ -0,0 +1,45 @@
+/** Mirrors `CachedCatalog`'s own default TTL (`cached-catalog.ts`): six hours. */
+const DEFAULT_STALE_MS = 6 * 60 * 60 * 1000;
+/**
+ * Build a {@link CatalogModel} from a cached {@link CatalogSnapshot}:
+ * active clients, each with its active projects (sorted by name) and their
+ * open/doing hub task counts. `undefined` (no snapshot cached yet) reports
+ * `"unavailable"`. `now` is injected (never `Date.now()` here) so age and
+ * staleness stay deterministic under test.
+ */
+export function buildCatalogModel(snapshot, now, staleMs = DEFAULT_STALE_MS) {
+    if (!snapshot)
+        return { status: "unavailable" };
+    const taskCountsByProject = new Map();
+    for (const task of snapshot.tasks ?? []) {
+        const counts = taskCountsByProject.get(task.projectId) ?? { open: 0, doing: 0 };
+        if (task.status === "open")
+            counts.open += 1;
+        else if (task.status === "doing")
+            counts.doing += 1;
+        taskCountsByProject.set(task.projectId, counts);
+    }
+    const clients = snapshot.clients
+        .filter((client) => client.active)
+        .map((client) => ({
+        id: client.id,
+        name: client.name,
+        code: client.code,
+        projects: snapshot.projects
+            .filter((project) => project.active && project.clientId === client.id)
+            .map((project) => {
+            const counts = taskCountsByProject.get(project.id) ?? { open: 0, doing: 0 };
+            return {
+                id: project.id,
+                name: project.name,
+                ...(project.code !== undefined ? { code: project.code } : {}),
+                openCount: counts.open,
+                doingCount: counts.doing,
+            };
+        })
+            .sort((a, b) => a.name.localeCompare(b.name)),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const ageMs = now - snapshot.fetchedAt;
+    return { status: "ready", url: snapshot.url, fetchedAt: snapshot.fetchedAt, ageMs, stale: ageMs > staleMs, clients };
+}

package/dist/domain/dashboard-model.js

@@ -0,0 +1,82 @@
+import { summarize } from "kankaku/hub";
+import { buildTodayRows } from "./today-model.js";
+const WEEKDAY_LABELS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+/** `day` shifted by `deltaDays` (may be negative), as a `YYYY-MM-DD` string. */
+function shiftDay(day, deltaDays) {
+    const date = new Date(`${day}T00:00:00`);
+    date.setDate(date.getDate() + deltaDays);
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const dayOfMonth = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${dayOfMonth}`;
+}
+function weekdayLabel(day) {
+    const date = new Date(`${day}T00:00:00`);
+    return WEEKDAY_LABELS[date.getDay()] ?? "";
+}
+/** Sum `workMs`/`cost` across every project for each of the 7 days ending on `today`, via kankaku's own `summarize` per day — never reimplementing its aggregation. */
+function buildLast7Days(projects, today) {
+    const days = Array.from({ length: 7 }, (_, index) => shiftDay(today, index - 6));
+    return days.map((day) => {
+        let workMs = 0;
+        let cost = 0;
+        for (const project of projects) {
+            const summary = summarize(project.records, { all: false, day });
+            workMs += summary.tasks.workMs;
+            cost += summary.tasks.cost;
+        }
+        return { day, weekday: weekdayLabel(day), workMs, cost };
+    });
+}
+/** Attach `share` (`workMs / max workMs`) to each of today's rows. */
+function withShare(rows) {
+    const maxWorkMs = rows.reduce((max, row) => Math.max(max, row.workMs), 0);
+    return rows.map((row) => ({ ...row, share: maxWorkMs > 0 ? row.workMs / maxWorkMs : 0 }));
+}
+/**
+ * Build the Hub card from per-project {@link SyncStatusSnapshot}s
+ * (`computeSyncStatus`, never reimplemented here) and an optional catalog
+ * summary. `entries === undefined` means the hub is not configured at
+ * all, distinct from a configured-but-empty project list.
+ */
+function buildHubCard(entries, catalog) {
+    if (entries === undefined)
+        return { status: "unavailable" };
+    let pending = 0;
+    let staleOutsideWindow = 0;
+    let lastSyncAt;
+    let lastSyncOk = true;
+    for (const entry of entries) {
+        pending += entry.status.pending;
+        staleOutsideWindow += entry.status.staleOutsideWindow;
+        const syncedThrough = entry.status.state?.syncedThrough;
+        if (syncedThrough !== undefined && (lastSyncAt === undefined || syncedThrough > lastSyncAt)) {
+            lastSyncAt = syncedThrough;
+        }
+        if (entry.status.state?.lastError !== undefined)
+            lastSyncOk = false;
+    }
+    return {
+        status: "ready",
+        pending,
+        staleOutsideWindow,
+        lastSyncOk,
+        ...(lastSyncAt !== undefined ? { lastSyncAt } : {}),
+        ...(catalog !== undefined ? { catalog } : {}),
+    };
+}
+/**
+ * Build the Today dashboard's model: today's total and per-project rows
+ * (`today-model.ts#buildTodayRows`, not reimplemented), the last 7 days'
+ * work/cost series, and the Hub card. Pure — every "now" comes from
+ * `options.today`, and every hub fact comes from already-resolved inputs.
+ */
+export function buildDashboardModel(projects, hubEntries, catalogSummary, options) {
+    const { rows, total } = buildTodayRows(projects, { today: options.today });
+    return {
+        today: total,
+        last7Days: buildLast7Days(projects, options.today),
+        projects: withShare(rows),
+        hub: buildHubCard(hubEntries, catalogSummary),
+    };
+}

package/dist/domain/list-window.js

@@ -0,0 +1,31 @@
+/**
+ * The smallest window of at most `maxRows` rows out of `total` that still
+ * contains `selected`. When `previousStart` puts `selected` inside the
+ * window it already describes, that window is kept as-is (no scrolling on
+ * every selection move); otherwise the window scrolls the minimum amount
+ * needed to bring `selected` back into view.
+ *
+ * Pure and stateless: callers persist `previousStart` themselves (e.g. in a
+ * `useRef`) and pass it back in on the next call.
+ */
+export function windowRows(total, selected, maxRows, previousStart = 0) {
+    const size = Math.max(Math.min(maxRows, total), 0);
+    if (size === 0) {
+        return { start: 0, end: 0, hiddenAbove: 0, hiddenBelow: 0 };
+    }
+    if (size >= total) {
+        return { start: 0, end: total, hiddenAbove: 0, hiddenBelow: 0 };
+    }
+    const clampedSelected = Math.min(Math.max(selected, 0), total - 1);
+    const maxStart = total - size;
+    let start = Math.min(Math.max(previousStart, 0), maxStart);
+    if (clampedSelected < start) {
+        start = clampedSelected;
+    }
+    else if (clampedSelected >= start + size) {
+        start = clampedSelected - size + 1;
+    }
+    start = Math.min(Math.max(start, 0), maxStart);
+    const end = start + size;
+    return { start, end, hiddenAbove: start, hiddenBelow: total - end };
+}

package/dist/domain/nav-model.js

@@ -0,0 +1,69 @@
+export const SCREENS = [
+    { id: "dashboard", label: "Dashboard", key: "1" },
+    { id: "tasks", label: "Tasks", key: "2" },
+    { id: "catalog", label: "Catalog", key: "3" },
+    { id: "sync", label: "Sync", key: "4" },
+];
+/** The screen bound to `key` (one of `SCREENS`' digit keys), or `undefined` for any other key. */
+export function screenForKey(key) {
+    return SCREENS.find((screen) => screen.key === key)?.id;
+}
+/** One entry per screen for the tab bar, in `SCREENS` order, flagging which one is active. */
+export function buildTabBar(active) {
+    return SCREENS.map((screen) => ({ id: screen.id, text: `${screen.key} ${screen.label}`, active: screen.id === active }));
+}
+export const INITIAL_NAV_STATE = { screen: "dashboard", focus: "sidebar" };
+/** Switch the active screen, keeping any existing project filter and focus (e.g. `1`-`4` while Tasks is already filtered). */
+export function switchScreen(state, screen) {
+    return { ...state, screen };
+}
+/** `enter` on a Dashboard project row: jump to Tasks filtered to `project`, keeping the current focus. */
+export function openProjectInTasks(state, project) {
+    return { ...state, screen: "tasks", projectFilter: project };
+}
+/** `esc` on Tasks: drop the project filter, keeping the current screen and focus. */
+export function clearProjectFilter(state) {
+    const { projectFilter, ...rest } = state;
+    void projectFilter;
+    return rest;
+}
+/** Focus the main content zone (e.g. `enter`/`→`/`Tab` from the sidebar). */
+export function focusMain(state) {
+    return { ...state, focus: "main" };
+}
+/** Focus the sidebar zone (e.g. `←`/`Tab`/`esc` from the main content). */
+export function focusSidebar(state) {
+    return { ...state, focus: "sidebar" };
+}
+/**
+ * Move the active screen by `delta` positions in `SCREENS` order (sidebar
+ * focused `↑`/`↓`), clamping at the first/last screen rather than
+ * wrapping.
+ */
+export function moveSidebar(state, delta) {
+    const currentIndex = SCREENS.findIndex((screen) => screen.id === state.screen);
+    const nextIndex = Math.min(Math.max(currentIndex + delta, 0), SCREENS.length - 1);
+    const next = SCREENS[nextIndex];
+    return next === undefined ? state : switchScreen(state, next.id);
+}
+/** The fixed footer hints shown while the sidebar is focused. */
+const SIDEBAR_HINTS = [
+    { key: "↑↓", label: "choose" },
+    { key: "enter/→", label: "open" },
+    { key: "1-4", label: "screens" },
+    { key: "q", label: "quit" },
+];
+/** Appended to a screen's own hints when the main zone is focused, to return to the sidebar. */
+const MAIN_MENU_HINT = { key: "←", label: "menu" };
+/**
+ * The footer key hints for `screen` at the given `focus`: sidebar focus
+ * always shows the fixed navigation hints (`extras` is ignored, since the
+ * sidebar's own keys never depend on the active screen); main focus shows
+ * the screen's own `extras` (its list/action keys) followed by `← menu`.
+ */
+export function hintsFor(screen, focus, extras) {
+    void screen;
+    if (focus === "sidebar")
+        return SIDEBAR_HINTS;
+    return [...extras, MAIN_MENU_HINT];
+}

package/dist/domain/quick-actions.js

@@ -0,0 +1,49 @@
+/**
+ * The Dashboard screen's `[ Quick actions ]` panel: four fixed actions
+ * (`c` refresh the catalog, `s` sync every project, `S` full-sync every
+ * project, `r` reload the dashboard model) plus a status line describing
+ * what is running, what just finished, or why the panel is unavailable.
+ * Pure: no I/O, no Ink, no `Date.now()` — the panel component renders
+ * `QUICK_ACTIONS` itself (coloring the key) and this module's
+ * `formatQuickActionLines` for the status text underneath.
+ */
+/** The four quick actions, in the order they are listed in the panel. */
+export const QUICK_ACTIONS = [
+    { key: "c", label: "refresh catalog" },
+    { key: "s", label: "sync all projects" },
+    { key: "S", label: "full sync all" },
+    { key: "r", label: "reload" },
+];
+/** `QUICK_ACTIONS`' label for `key` (every `QuickActionKey` is present, so this is never `undefined` in practice). */
+function labelFor(key) {
+    return QUICK_ACTIONS.find((action) => action.key === key)?.label ?? key;
+}
+/** The raw (unbounded) status text for `state`, or `""` when there is nothing to show yet (`idle`). */
+function statusText(state) {
+    switch (state.status) {
+        case "idle":
+            return "";
+        case "busy":
+            return `… ${labelFor(state.key)}`;
+        case "done":
+            return state.message;
+        case "unavailable":
+            return state.reason;
+    }
+}
+/** `text` cut to at most `width` visible characters, trailing with `…` when something was cut off. `width` below 1 is treated as 1. */
+function truncate(text, width) {
+    const safeWidth = Math.max(Math.floor(width), 1);
+    if (text.length <= safeWidth)
+        return text;
+    return `${text.slice(0, Math.max(safeWidth - 1, 0))}…`;
+}
+/**
+ * The quick actions panel's status line for `state`, truncated to `width`
+ * (the panel's own inner content width) — always exactly one line, so the
+ * panel's own fixed height never changes with the message length (see the
+ * layout-stability rule other Dashboard panels follow). Empty for `idle`.
+ */
+export function formatQuickActionLines(width, state) {
+    return [truncate(statusText(state), width)];
+}

package/dist/domain/sync-model.js

@@ -0,0 +1,17 @@
+/**
+ * Build one {@link SyncRow} per project from its own
+ * {@link SyncStatusSnapshot} (`kankaku/hub`'s `computeSyncStatus`, never
+ * reimplemented here), sorted by project name.
+ */
+export function buildSyncRows(entries) {
+    return entries
+        .map(({ project, status }) => ({
+        name: project.name,
+        dir: project.dir,
+        pending: status.pending,
+        staleOutsideWindow: status.staleOutsideWindow,
+        ...(status.state?.syncedThrough !== undefined ? { syncedThrough: status.state.syncedThrough } : {}),
+        ...(status.state?.lastError !== undefined ? { lastError: status.state.lastError } : {}),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}