kankaku-tui 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soyunninja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# kankaku-tui
+
+A standalone terminal app, `kankaku`, that reads every project's
+`.kankaku/worklog.jsonl` under a configurable list of roots and shows the
+day across projects — the one view the [kankaku](https://kankaku.io) pi
+panel cannot give, since it only ever sees the one project pi is running
+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
+
+Until the next kankaku release, this package depends on the sibling
+`kankaku` checkout via `file:../kankaku`, so both repos must sit next to
+each other on disk. Run `npm install` inside `kankaku-tui/`.
+
+Later, once published: `npm install -g kankaku-tui`. For now, run it from
+this repo with `npm run dev`.
+
+## Configuration
+
+`~/.kankaku/tui.json`:
+
+```json
+{
+  "roots": ["/absolute/path/to/workspace", "~/another-workspace"]
+}
+```
+
+Each root is either a project itself (it has its own `.kankaku/worklog.jsonl`)
+or a directory containing one or more projects as direct subdirectories.
+`~` expands to the home directory. Missing or malformed config falls back
+to the current working directory as the only root.
+
+### Hub credentials (Catalog and Sync)
+
+The Catalog and Sync screens (and their subcommands) talk to the same
+PocketBase hub kankaku itself syncs to, through kankaku's own
+`resolveHubCredentials`: `~/.kankaku/credentials.json`
+
+```json
+{
+  "url": "https://your-hub.example.com",
+  "email": "you@example.com",
+  "password": "…"
+}
+```
+
+or the environment (env takes precedence per field over the file):
+
+- `KANKAKU_PB_URL`, `KANKAKU_PB_EMAIL`, `KANKAKU_PB_PASSWORD`
+- `KANKAKU_SYNC_WINDOW_HOURS` — revisit window for `sync`/`sync status` (default 24)
+- `KANKAKU_SYNC_PROMPT` — `none` (default), `truncated` or `full`
+- `KANKAKU_SYNC_RECORDS` — set to `0` to skip uploading individual `work_records`
+- `KANKAKU_MACHINE` — overrides the reported hostname
+
+Without credentials, the Catalog and Sync screens show a one-line note
+instead of a list; `kankaku catalog` and `kankaku sync status` print the
+same note and exit 0 (no network attempted); `kankaku catalog refresh` and
+`kankaku sync`/`kankaku sync all` print an error and exit 1.
+
+Every sync uploaded from here is stamped `plugin: kankaku-tui`; a task's
+`agent` comes from its own orchestrator record when it carries one (see
+kankaku's `hub-entry.ts`), else falls back to `agent: unknown` — this app
+never guesses which coding agent produced someone else's worklog.
+
+## Usage
+
+- `kankaku` — opens the interactive TUI on the Dashboard screen.
+- `kankaku today [--roots a,b]` — today's work per project, plain text.
+- `kankaku tasks [--all]` — every task's line (kankaku's own `formatTasks`),
+  grouped under a `== <project> ==` header per project; restricted to
+  today unless `--all`.
+- `kankaku catalog [refresh]` — without `refresh`, reports the locally
+  cached client/project counts (no network); `refresh` fetches a fresh
+  snapshot from the hub and caches it to `~/.kankaku/catalog.json`.
+- `kankaku sync [status|all] [--project <dir>]` — `status` reports the
+  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.
+
+`--roots` (on `today`/`tasks`) overrides the configured roots for that run.
+
+`--theme <name>` picks one of the three built-in colour presets for the
+interactive TUI; `KANKAKU_TUI_THEME=<name>` does the same through the
+environment (the flag wins when both are given). The valid names are
+`gentleman-sexy` (the default), `gentleman-cute` and `gentle` — resolved
+hex values copied from [gentle-pi](https://github.com/Gentleman-Programming/gentle-pi)'s
+own themes (MIT), so this TUI matches the owner's pi panel instead of an
+unrelated default. An unknown name prints a usage error listing the valid
+names and exits 1 without opening the TUI.
+
+## Screens
+
+One visual system drives all four screens: a left sidebar for navigation,
+titled bordered panels, aligned tables with a highlighted selection, text
+bars and sparklines, a header line and a footer of key hints — all driven
+by a single theme of colour roles (`src/ui/theme.ts`, see `--theme` above
+for the three built-in presets). The app runs fullscreen, in the
+terminal's alternate screen buffer: the frame fills the whole terminal
+height, resizing live with the terminal. The sidebar sits beside the
+screen at 100+ terminal columns, stacks full-width above it at 70-99
+columns, and collapses to a one-line tab strip below 70 columns; a
+selected row or card is always marked with a visible `›`, never colour
+alone. The sidebar itself shows which zone has focus: its border switches
+to the active border colour and the active item gets a full-row highlight
+when it has focus, dropping back to a plain `›` marker with no highlight
+once focus moves to the screen's own content.
+
+Every panel in the main area is sized to a fixed height derived from the
+terminal's own height, so it never grows with its content and shifts the
+rest of the screen — a long value (e.g. the Tasks screen's full prompt)
+is wrapped and, if it still doesn't fit the panel's fixed height, clipped
+with a trailing `… N more lines` note instead of silently overflowing or
+pushing the header out of view.
+
+Any list that can grow past the available height (the Tasks table, the
+Catalog Clients/Projects lists, the Dashboard Projects table, the Sync
+card grid) scrolls instead of overflowing the terminal: the viewport
+follows the current selection, and a `↑ N more` / `↓ N more` line marks
+rows hidden above or below it.
+
+Dashboard is the app's home screen: a Today card (work/wait/cost/tasks/
+cache hit — it shows today's numbers, hence its own title), a Last 7 days
+card (work and cost sparklines with weekday labels), a Projects table
+(work, cost and a share bar per project), a Hub card (pending/stale, last
+sync time, catalog summary) and a Quick actions panel (`c` refresh the
+catalog, `s` sync every project, `S` full-sync every project, `r` reload):
+
+```
+ >_ kankaku 0.1.0                              hub ● kankaku.soyun.ninja · synced 08:20
+┌──────────────┐ ╭─[ Today ]────────────────────╮ ╭─[ Last 7 days ]──────────────────╮
+│ › Dashboard  │ │   work   1h 42m               │ │ work  ▂▅▇▃▁▆█   cost  ▁▃▆▂▁▅█    │
+│   Tasks      │ │   wait      6m   cost  $9.83  │ │ mon tue wed thu fri sat sun       │
+│   Catalog    │ │   tasks 12       cache hit 68%│ ╰──────────────────────────────────╯
+│   Sync       │ ╰──────────────────────────────╯ ╭─[ Hub ]──────────────────────────╮
+│              │ ╭─[ Projects ]────────────────────────────╮ │ pending 1 · stale 0     │
+│              │ │ project       work    cost   share      │ │ last sync ok 08:20      │
+│              │ │ kankaku       1h 02m  $6.49  ████████░░ │ │ catalog 9 clients ·     │
+│              │ │ kankaku-tui     31m   $2.10  █████░░░░░ │ │         17 projects     │
+│              │ │ kankaku-hub      9m   $1.24  ██░░░░░░░░ │ ╰─────────────────────────╯
+│              │ ╰─────────────────────────────────────────╯
+├──────────────┤
+│ roots 1      │
+│ projects 3   │
+└──────────────┘
+ ↑↓ move   enter open   r refresh   1-4 screens   q quit
+```
+
+The Quick actions panel sits below the Hub card in wide mode (100+
+columns), or right after the Projects table in stacked mode (70-99
+columns):
+
+```
+╭─[ Quick actions ]────────────────╮
+│ c  refresh catalog               │
+│ s  sync all projects             │
+│ S  full sync all                 │
+│ r  reload                        │
+│ catalog: 9 clients · 17 projects │
+╰──────────────────────────────────╯
+```
+
+The bottom line is the status line: empty until the first action runs,
+`… <label>` while one is running, its result message once it settles
+(e.g. the catalog refresh above, or a sync summary), `error: <message>`
+if it failed, or `hub not configured (~/.kankaku/credentials.json)` when
+the hub has no credentials — in which case `c`/`s`/`S` do nothing.
+
+- **Tasks** — a table (time, project, work, cost, prompt) with a
+  highlighted row on the left, and a `[ Task ]` detail panel on the right
+  showing the selected row's full prompt, client, project, hub task,
+  wall/work/wait time, cost, cache hit and subagent count.
+- **Catalog** — `[ Clients ]` on the left; the selected client's
+  `[ Projects ]`, with open/doing hub task counts, on the right. The
+  Clients panel header shows the cache's age and a `(stale)` flag.
+- **Sync** — one card per project in a wrapping grid; the selected card is
+  highlighted, and each action's result line shows inside its card while
+  it runs and once it settles.
+
+## Keys (TUI)
+
+The app has two focus zones — the sidebar and the active screen's own main
+content — and one of them always has focus (`domain/nav-model.ts`'s
+`NavState.focus`, starting on the sidebar). `1`-`4` switch the Dashboard/
+Tasks/Catalog/Sync tab bar and `q` quits from anywhere, in either zone; every
+other key belongs to whichever zone currently has focus, so a screen's own
+list never moves by accident while you are still picking a screen.
+
+- **Sidebar focused** (the app's own starting state) — `↑`/`↓` move
+  between screens, and the screen switches as you move, so you see each
+  one before committing to it. `enter`, `→` or `Tab` focus the main zone
+  (the screen you last landed on).
+- **Main zone focused** — the active screen's own keys work as below.
+  `←` or `Tab` return focus to the sidebar. `esc` also returns to the
+  sidebar, unless the screen consumes it first: on Tasks with a project
+  filter set (from Dashboard's `enter`), the first `esc` clears the filter
+  and the next `esc` returns to the sidebar.
+
+The focused zone is visible in the frame: the sidebar's active-item marker
+is in the accent colour when the sidebar is focused and muted otherwise,
+the focused screen's primary panel gets the accent border, and the footer
+key hints change — the sidebar's own hints while it is focused, the
+screen's hints plus `← menu` while the main zone is focused.
+
+The app fills the whole terminal; every scrolling list (Tasks, Catalog's
+Clients/Projects, Dashboard's Projects, Sync's cards) additionally takes
+`PageUp`/`PageDown` to move a full window at a time and `Home`/`End` to
+jump to the first/last row.
+
+- **Dashboard** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the
+  Projects selection, `enter` opens the selected project in Tasks
+  (filtered to it), `r` refresh; the Quick actions panel additionally
+  takes `c` (refresh catalog), `s` (sync all projects) and `S` (full sync
+  all) — one at a time, ignored while another is running.
+- **Tasks** — `a` toggle today/all, `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End`
+  move the selection, `r` refresh, `esc` clears a project filter set from
+  Dashboard.
+- **Catalog** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the client
+  selection, `r` refresh from the hub.
+- **Sync** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the selection,
+  `s` sync the selected project, `f` full-sync the selected project, `S`
+  sync every project. Each action's summary shows inline in its card
+  while it runs and once it settles.
+
+The TUI never writes to disk on its own — Dashboard, Tasks and read-only
+Catalog views write nothing at all; Catalog's `refresh`, Sync's
+`s`/`f`/`S` and Dashboard's Quick actions `c`/`s`/`S` write only through
+kankaku's own adapters (`CachedCatalog`, `SyncStateStore`, the hub
+itself), exactly as kankaku's own sync paths do.

package/dist/adapters/app-info.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Reads the `version` field from `<root>/package.json`; `"0.0.0"` when it is missing. */
+export function readAppVersion(root) {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    return pkg.version ?? "0.0.0";
+}
+/** This package's own version, read from its `package.json` next to `dist/adapters/app-info.js` (or `src/adapters/app-info.ts` under `tsx`) — used by the header bar's `>_ kankaku <version>` label. */
+export function readOwnVersion() {
+    const root = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    return readAppVersion(root);
+}

package/dist/adapters/hub.js

@@ -0,0 +1,101 @@
+/**
+ * Shared hub adapter: credentials, catalog and per-project sync, used by
+ * both the Catalog/Sync screens and their `kankaku catalog`/`kankaku sync`
+ * subcommands. Mirrors kankaku-claude's `sync-cli.ts#syncConfigured` (see
+ * `odd/tasks/screens-tasks-catalog-sync.md`), but scoped to one explicit
+ * `ProjectRef` per call rather than the process's own `cwd`, since one TUI
+ * process can sync several projects.
+ */
+import { readFileSync } from "node:fs";
+import { hostname as osHostname } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CachedCatalog, JsonlWorkLog, PocketBaseClient, PocketBaseSink, SyncStateStore, computeSyncStatus, createPocketBaseCatalogFetcher, resolveHubCredentials, runSync, safeHomeDir, } from "kankaku/hub";
+const HUB_UNCONFIGURED_REASON = "hub credentials are not configured (KANKAKU_PB_URL/_EMAIL/_PASSWORD or ~/.kankaku/credentials.json)";
+/** Resolve hub credentials via kankaku's own `resolveHubCredentials`, collapsing its result into one pass/fail outcome with a display reason for the Catalog/Sync screens and subcommands. */
+export function resolveHub(deps) {
+    const { credentials, invalidReason } = resolveHubCredentials(deps);
+    if (invalidReason)
+        return { ok: false, reason: `invalid hub URL: ${invalidReason}` };
+    if (!credentials)
+        return { ok: false, reason: HUB_UNCONFIGURED_REASON };
+    return { ok: true, credentials };
+}
+/** Build the disk-backed `CachedCatalog` (`<homeDir>/.kankaku/catalog.json`) for `credentials`, mirroring kankaku-claude's `syncConfigured`. */
+export function createCatalog(credentials, deps) {
+    const client = new PocketBaseClient({ ...credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+    const home = safeHomeDir(deps.homeDir) ?? deps.homeDir();
+    return new CachedCatalog({
+        filePath: join(home, ".kankaku", "catalog.json"),
+        url: credentials.url,
+        clock: { now: deps.now },
+        fetchCatalog: createPocketBaseCatalogFetcher(client),
+    });
+}
+/** Refresh `catalog` against the hub and return the new snapshot (`undefined` on failure — see `CachedCatalog.refresh`). */
+export function refreshCatalog(catalog) {
+    return catalog.refresh();
+}
+/** `KANKAKU_SYNC_WINDOW_HOURS`, parsed the same way as kankaku's own sync paths; defaults to 24. */
+function windowHours(env) {
+    const value = Number(env.KANKAKU_SYNC_WINDOW_HOURS);
+    return env.KANKAKU_SYNC_WINDOW_HOURS && Number.isFinite(value) && value > 0 ? value : 24;
+}
+/** `KANKAKU_SYNC_PROMPT`, defaulting to `"none"`. */
+function promptMode(env) {
+    const value = env.KANKAKU_SYNC_PROMPT;
+    return value === "truncated" || value === "full" ? value : "none";
+}
+/** This package's own `version`, read from its `package.json` next to `dist/adapters/hub.js` (or `src/adapters/hub.ts` under `tsx`). */
+function packageVersion() {
+    const root = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    return pkg.version;
+}
+/** Read `<project.dir>/.kankaku` as a no-network sync status snapshot: pending count, tasks stale outside the revisit window, and the persisted `SyncState` (if any). Never touches any project other than `project`. */
+export function computeProjectSyncStatus(project, credentials, env) {
+    const dir = join(project.dir, ".kankaku");
+    const log = new JsonlWorkLog(dir);
+    const stateStore = new SyncStateStore({ dir, pid: process.pid });
+    return computeSyncStatus(log, stateStore, credentials.url, windowHours(env));
+}
+/**
+ * Sync one project against the hub: mirrors kankaku-claude's
+ * `sync-cli.ts#syncConfigured` (`JsonlWorkLog`, `SyncStateStore`,
+ * `PocketBaseSink` fed the refreshed catalog snapshot including `tasks`,
+ * `runSync`), but stamped with this TUI's own agent/plugin identity —
+ * `agent: "unknown"` (kankaku's `hub-entry.ts` prefers the record's own
+ * `agent` when it carries one, so this fallback only ever reaches a
+ * never-labelled legacy row) and `plugin: "kankaku-tui"`. Never touches
+ * any project other than `project`.
+ */
+export async function syncProject(project, credentials, options, deps) {
+    const dir = join(project.dir, ".kankaku");
+    const log = new JsonlWorkLog(dir);
+    const stateStore = new SyncStateStore({ dir, pid: process.pid, now: deps.now });
+    const catalog = createCatalog(credentials, deps);
+    // On an offline hub the cached snapshot (if any) remains usable.
+    await catalog.refresh();
+    const snapshot = catalog.read();
+    const pluginVersion = packageVersion();
+    const sink = {
+        push: async (tasks) => {
+            if (tasks.length === 0)
+                return [];
+            const client = new PocketBaseClient({ ...credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+            return new PocketBaseSink({
+                client,
+                clients: snapshot?.clients ?? [],
+                projects: snapshot?.projects ?? [],
+                tasks: snapshot?.tasks ?? [],
+                machine: deps.env.KANKAKU_MACHINE || (deps.hostname ?? osHostname)(),
+                promptMode: promptMode(deps.env),
+                syncRecords: deps.env.KANKAKU_SYNC_RECORDS !== "0",
+                agent: "unknown",
+                plugin: "kankaku-tui",
+                pluginVersion,
+            }).push(tasks);
+        },
+    };
+    return runSync({ log, sink, stateStore, clock: { now: deps.now }, target: credentials.url, windowHours: windowHours(deps.env) }, options);
+}

package/dist/adapters/project-discovery.js

@@ -0,0 +1,43 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+function hasWorklog(dir) {
+    return existsSync(join(dir, ".kankaku", "worklog.jsonl"));
+}
+function childDirs(root) {
+    try {
+        return readdirSync(root)
+            .map((entry) => join(root, entry))
+            .filter((entry) => {
+            try {
+                return statSync(entry).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Discover projects under `roots`: a root that itself has
+ * `.kankaku/worklog.jsonl` is a project; otherwise each direct child
+ * directory with one is a project. Deduped by `dir`, sorted by `name`.
+ * Never throws on an unreadable or missing root.
+ */
+export function discoverProjects(roots) {
+    const byDir = new Map();
+    for (const root of roots) {
+        if (hasWorklog(root)) {
+            byDir.set(root, { name: basename(root), dir: root });
+            continue;
+        }
+        for (const child of childDirs(root)) {
+            if (hasWorklog(child)) {
+                byDir.set(child, { name: basename(child), dir: child });
+            }
+        }
+    }
+    return Array.from(byDir.values()).sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/adapters/tui-config.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+function expandHome(path, homeDir) {
+    if (path === "~")
+        return homeDir;
+    if (path.startsWith("~/"))
+        return join(homeDir, path.slice(2));
+    return path;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+/**
+ * Read `<homeDir>/.kankaku/tui.json` (`{ "roots": [...] }`, `~` expanded
+ * against `homeDir`). A missing or malformed file falls back to `cwd` as
+ * the only root, so the app always has something to discover projects
+ * under.
+ */
+export function readTuiConfig(homeDir, cwd) {
+    const configPath = join(homeDir, ".kankaku", "tui.json");
+    if (!existsSync(configPath)) {
+        return { roots: [cwd] };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || !isStringArray(parsed["roots"])) {
+            return { roots: [cwd] };
+        }
+        const roots = parsed.roots.map((root) => expandHome(root, homeDir));
+        return { roots };
+    }
+    catch {
+        return { roots: [cwd] };
+    }
+}

package/dist/adapters/worklog-reader.js

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+import { JsonlWorkLog } from "kankaku/hub";
+/**
+ * Read every {@link WorkRecord} appended under `<project.dir>/.kankaku`,
+ * via kankaku's own `JsonlWorkLog` (which reads `<dir>/worklog.jsonl`).
+ */
+export function readProjectRecords(project) {
+    return new JsonlWorkLog(join(project.dir, ".kankaku")).readAll();
+}