kankaku 1.0.2 → 1.1.0

package/README.md

@@ -81,14 +81,16 @@ The wizard's steps, `enter` to advance and `esc` to go back throughout
    below.
 2. **Hub** — `use an existing hub` (URL, email, masked password, a `c`
    inline health check, reusing the current credentials as the default),
-   `install locally`, or `skip`. Installing locally asks only for the
-   owner's email and password and then runs the same installer as
-   `kankaku hub install` (see "Local hub" below): no `kankaku-hub`
-   checkout is needed, and the wizard writes the local hub's service
-   account as this machine's hub credentials. The wizard always uses the
-   default port; if another process already holds it the step fails with
-   the port-in-use message, and `kankaku hub install --port <N>` is the
-   way to pick another one.
+   `install locally`, or `skip`. Installing locally asks for the owner's
+   email and password and a `port` (digits only, 1024-65535), then runs
+   the same installer as `kankaku hub install` (see "Local hub" below): no
+   `kankaku-hub` checkout is needed. The port field starts at the first
+   free port from 8090 upwards (or at the port of an existing install)
+   and rejects a port that is in use inline (`port <N> is in use`). The
+   Review step says what happens to the sync credentials: either
+   `sync credentials → the local hub`, or `sync credentials stay on <url>
+   (switch later with kankaku hub use)` when this machine already syncs to
+   another hub.
 3. **Roots** — the comma-separated project roots, defaulting to the
    current `tui.json` (or the parent of the current directory the first
    time). See "Configuration" below for how deep each root is searched.
@@ -265,9 +267,18 @@ sets up and runs your own hub on this machine, under `~/.kankaku/hub/`:
 - `accounts.json` (owner-only, `0600`) — the PocketBase superuser email
   and generated password, and the owner account's email. The owner logs
   into the hub's own web admin UI with that owner account.
-- `~/.kankaku/credentials.json` — the generated `service` account
-  (`kankaku-sync@kankaku.local`) this app and kankaku's own sync already
-  read, exactly like a remote hub's credentials.
+- `service.json` (owner-only, `0600`) — the generated `service` account
+  (`kankaku-sync@kankaku.local`) as `{ url, email, password }`. Install
+  always writes it.
+
+Install never repoints where this machine syncs on its own.
+`~/.kankaku/credentials.json` (the file this app and kankaku's own sync
+read) is written by install only when it does not exist yet, or when its
+`url` already is this local hub's (same host and port). When it points at
+another hub it is left untouched, and the install report says so with a
+`sync credentials` step: `this machine syncs to <url>; run 'kankaku hub
+use' to switch to the local hub`. `kankaku hub use` is the explicit
+switch.
 
 Commands (macOS and Linux only — PocketBase ships no other build):
 
@@ -275,15 +286,33 @@ Commands (macOS and Linux only — PocketBase ships no other build):
   — installs (or, run again, verifies) the hub and leaves it running. On
   a real terminal, a missing owner email/password is prompted for
   (masked); without a TTY, both flags are required. Idempotent: re-running
-  with everything already in place changes nothing. If another process
-  already answers on the target port, `install`/`start`/`upgrade` refuse
-  with `port <N> is already in use by another process — pass --port <N>
-  or stop it` instead of provisioning accounts against it; pass a
-  different `--port` or free the port and retry.
+  with everything already in place changes nothing, and an existing
+  install keeps its recorded port. Without `--port`, a fresh install uses
+  8090 when it is free; when it is not, install fails (exit 1) with `port
+  8090 is already in use — try: kankaku hub install --port <first free>`
+  and never picks a port silently. A `--port` that is taken fails the same
+  way, with the existing message plus the suggestion; a `--port` that is
+  not a whole number between 1 and 65535 is a usage error. The check binds
+  `127.0.0.1:<port>` before anything is downloaded or created, and the
+  pre-spawn health check still runs after it. `start` and `upgrade` refuse
+  with `port <N> is already in use by another process — pass --port <N> or
+  stop it` when a foreign process holds the recorded port. Re-running
+  install on a hub made by an older version, which has no `service.json`,
+  writes it when the service password is still known (it is in
+  `credentials.json`); otherwise it says the password is not recoverable
+  and does not invent one.
+- `kankaku hub use` — points `~/.kankaku/credentials.json` at the local
+  hub, from `service.json` (the previous file is kept once as
+  `credentials.json.bak`, mode `0600`) and prints `sync now points at
+  <local url> (was <previous url>)`. Running it again reports `unchanged`.
+  It fails (exit 1) when no local hub is installed or `service.json` is
+  missing.
 - `kankaku hub start` / `kankaku hub stop` — start or stop the server
   process; `stop` is a no-op when it isn't running.
 - `kankaku hub status` — `local hub: running 0.2.0 (PocketBase 0.40.4) at
-  http://127.0.0.1:8090 · pb_data 1.2 MB`, `stopped`, or `not installed`.
+  http://127.0.0.1:8090 · pb_data 1.2 MB`, `stopped`, or `not installed`,
+  followed by where this machine's sync points: `sync: local hub`,
+  `sync: <other url>` or `sync: not configured`.
 - `kankaku hub upgrade` — copies a fresh `app/<version>/` from the
   currently installed `kankaku-hub` package, downloads a new PocketBase
   binary only if that version changed, and restarts — `pb_data` is never
@@ -318,8 +347,12 @@ developers via `kankaku setup --from-checkout <dir>`.
   checkout-based local hub install, see "Local hub" above.
 - `kankaku doctor` — the same read-only report `kankaku setup` ends with,
   without prompting or writing anything.
-- `kankaku hub install|start|stop|status|upgrade|logs` — the local hub's
-  lifecycle; see "Local hub" above.
+- `kankaku hub install|use|start|stop|status|upgrade|logs` — the local
+  hub's lifecycle; see "Local hub" above.
+- `kankaku --version`, `kankaku -v` or `kankaku version` — prints `kankaku
+  <version>` and, indented, the version of each package it carries
+  (`kankaku-pi`, `kankaku-claude`, `kankaku-hub`), or `not found` for one
+  that cannot be resolved; exit 0.
 
 `--roots` (on `today`/`tasks`) overrides the configured roots for that run.
 

package/dist/adapters/hub-manager/credentials.js

@@ -0,0 +1,58 @@
+/**
+ * The local hub's service account and where this machine's sync points.
+ * Install always stores the service account in `~/.kankaku/hub/service.json`
+ * (0600); `~/.kankaku/credentials.json` is a separate decision, made by
+ * `installHub` (only when none exists or it already points here) and by
+ * `useLocalHub` (`kankaku hub use`, explicit).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { hubLayout, parseServiceAccount } from "../../domain/local-hub-model.js";
+import { credentialsPath, writeHubCredentials } from "../setup/hub.js";
+import { readJsonObjectOrEmpty, writeJsonAtomic } from "../setup/json-writer.js";
+const OWNER_FILE_MODE = 0o600;
+/** `~/.kankaku/hub/service.json`, or `undefined` when it is missing or malformed. Never throws. */
+export function readServiceAccount(homeDir) {
+    const file = hubLayout(homeDir).serviceJson;
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return parseServiceAccount(JSON.parse(readFileSync(file, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Writes `account` to `~/.kankaku/hub/service.json` (0600, tmp + rename); a no-op when it already holds exactly these values. */
+export function writeServiceAccount(homeDir, account) {
+    const current = readServiceAccount(homeDir);
+    if (current && current.url === account.url && current.email === account.email && current.password === account.password)
+        return { changed: false };
+    writeJsonAtomic(hubLayout(homeDir).serviceJson, { url: account.url, email: account.email, password: account.password }, undefined, OWNER_FILE_MODE);
+    return { changed: true };
+}
+/** The `url` currently in `~/.kankaku/credentials.json`, or `undefined` when there is none. */
+export function readCredentialsUrl(homeDir) {
+    const url = readJsonObjectOrEmpty(credentialsPath(homeDir))["url"];
+    return typeof url === "string" && url !== "" ? url : undefined;
+}
+/**
+ * `kankaku hub use`: points `credentials.json` at the local hub's service
+ * account (`service.json`), keeping the one-time `.bak` of the previous
+ * file. Needs an installed local hub and its `service.json`; idempotent.
+ */
+export function useLocalHub(homeDir) {
+    const layout = hubLayout(homeDir);
+    if (!existsSync(layout.hubJson)) {
+        return { ok: false, error: "no local hub is installed; run: kankaku hub install" };
+    }
+    const service = readServiceAccount(homeDir);
+    if (!service) {
+        return {
+            ok: false,
+            error: "the local hub has no service.json (an install made by an older version does not write one); run 'kankaku hub install' again - it is idempotent and writes it when the service password is still known",
+        };
+    }
+    const previousUrl = readCredentialsUrl(homeDir);
+    const written = writeHubCredentials(homeDir, service);
+    return { ok: true, changed: written.changed, url: service.url, ...(previousUrl !== undefined ? { previousUrl } : {}) };
+}

package/dist/adapters/hub-manager/install.js

@@ -9,12 +9,15 @@
  */
 import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { assetKeyFor, classifyStatus, generatePassword, hubLayout, parseHubConfig, serveArgs, } from "../../domain/local-hub-model.js";
+import { assetKeyFor, classifyStatus, generatePassword, hubLayout, credentialsKeptDetail, parseHubConfig, sameHubUrl, serveArgs, shouldWriteCredentials, } from "../../domain/local-hub-model.js";
 import { locateHubPackage } from "./package.js";
 import { downloadPocketBase } from "./download.js";
 import { isAlive, readPid, stopProcess, waitForHealth } from "./process.js";
+import { firstFreePort, isPortFree } from "./port-probe.js";
 import { createUser, upsertSuperuser } from "./accounts.js";
-import { writeHubCredentials } from "../setup/hub.js";
+import { credentialsPath, writeHubCredentials } from "../setup/hub.js";
+import { readJsonObjectOrEmpty } from "../setup/json-writer.js";
+import { readCredentialsUrl, readServiceAccount, writeServiceAccount } from "./credentials.js";
 const OWNER_DIR_MODE = 0o700;
 const OWNER_FILE_MODE = 0o600;
 /** The PocketBase superuser account this package provisions on first install; distinct from the owner/service application users. */
@@ -55,8 +58,14 @@ function readLogLines(layout) {
         lines.pop();
     return lines;
 }
-function portInUseMessage(port) {
-    return `port ${port} is already in use by another process — pass --port <N> or stop it`;
+/** The message when a foreign process holds `port`; `suggestion` (the first free port above it) adds the command that would work. */
+function portInUseMessage(port, suggestion) {
+    const base = `port ${port} is already in use by another process — pass --port <N> or stop it`;
+    return suggestion === undefined ? base : `${base}; try: kankaku hub install --port ${suggestion}`;
+}
+/** The first free port above `port`, for a "try: kankaku hub install --port N" suggestion; `undefined` when none of the next 20 is free. */
+function suggestPortAbove(port, deps) {
+    return firstFreePort(port + 1, 20, deps.portBinder);
 }
 /**
  * Before spawning: if `GET /api/health` on `port` answers at all (ok or
@@ -64,17 +73,32 @@ function portInUseMessage(port) {
  * held by a process that is not ours. Callers only reach this once they
  * have already established that no pid of ours is alive, so any response
  * here means a foreign process. Returns the detail message to report, or
- * `undefined` when the port is free.
+ * `undefined` when the port is free. `suggest` (install only) appends the
+ * first free port to try instead.
  */
-async function ensurePortFree(port, deps) {
+async function ensurePortFree(port, deps, suggest = false) {
     try {
         await deps.fetch(`${baseUrlFor(port)}/api/health`);
-        return portInUseMessage(port);
+        return portInUseMessage(port, suggest ? await suggestPortAbove(port, deps) : undefined);
     }
     catch {
         return undefined;
     }
 }
+/**
+ * The earlier, cheaper check of a fresh install: binds `127.0.0.1:<port>`.
+ * `explicit` (a `--port` was given) keeps the existing message and adds the
+ * first free port; without `--port` the default is never swapped silently -
+ * the message names the first free port to pass instead.
+ */
+async function checkPortBindable(port, explicit, deps) {
+    if (await isPortFree(port, deps.portBinder))
+        return undefined;
+    const suggestion = await suggestPortAbove(port, deps);
+    if (explicit)
+        return portInUseMessage(port, suggestion);
+    return suggestion === undefined ? `port ${port} is already in use` : `port ${port} is already in use — try: kankaku hub install --port ${suggestion}`;
+}
 /**
  * Spawns the hub detached and waits for it to become healthy, stopping
  * immediately (rather than waiting out the full timeout) if the process
@@ -103,6 +127,51 @@ function healthFailureDetail(layout, exitedEarly) {
     const lastLine = readLogLines(layout).at(-1);
     return lastLine ? `the hub exited during startup: ${lastLine}` : "the hub exited during startup";
 }
+/**
+ * Stores the local hub's service account in `service.json` (always) and
+ * decides what happens to `~/.kankaku/credentials.json`: written only when
+ * none exists or it already points at this local hub, otherwise left
+ * byte-for-byte untouched with a step saying how to switch (`kankaku hub
+ * use`). Returns the two report steps.
+ */
+function storeServiceAccount(homeDir, account, recoveredFrom) {
+    const serviceResult = writeServiceAccount(homeDir, account);
+    const steps = [
+        { step: "write service.json", outcome: serviceResult.changed ? "done" : "unchanged", ...(recoveredFrom ? { detail: recoveredFrom } : {}) },
+    ];
+    const existingUrl = readCredentialsUrl(homeDir);
+    if (!shouldWriteCredentials(existingUrl, account.url)) {
+        steps.push({ step: "sync credentials", outcome: "unchanged", detail: credentialsKeptDetail(existingUrl) });
+        return steps;
+    }
+    const written = writeHubCredentials(homeDir, account);
+    steps.push({ step: "sync credentials", outcome: written.changed ? "done" : "unchanged", detail: `points at ${account.url}` });
+    return steps;
+}
+/**
+ * Re-run on an install that already has accounts: `service.json` is kept up
+ * to date when it exists (its url follows the recorded port); an install
+ * made before `service.json` existed gets it back only when the service
+ * password is still known - it is in `credentials.json` (email and url are
+ * the local hub's). When it is not recoverable, says so and invents nothing.
+ */
+function ensureServiceAccount(homeDir, url) {
+    const stored = readServiceAccount(homeDir);
+    if (stored)
+        return storeServiceAccount(homeDir, { ...stored, url });
+    const credentials = readJsonObjectOrEmpty(credentialsPath(homeDir));
+    const { url: credentialsUrl, email, password } = credentials;
+    if (email === SERVICE_EMAIL && typeof password === "string" && password !== "" && typeof credentialsUrl === "string" && sameHubUrl(credentialsUrl, url)) {
+        return storeServiceAccount(homeDir, { url, email: SERVICE_EMAIL, password }, "recovered from credentials.json");
+    }
+    return [
+        {
+            step: "write service.json",
+            outcome: "unchanged",
+            detail: "the service account's password is not recoverable: it was not stored by the version that installed this hub and credentials.json does not hold it; none was invented",
+        },
+    ];
+}
 /**
  * Installs (or, run again, verifies) the local hub under
  * `~/.kankaku/hub`: locates the `kankaku-hub` package, creates the layout
@@ -112,13 +181,14 @@ function healthFailureDetail(layout, exitedEarly) {
  * package's migrations/hooks/public into `app/<version>/`, writes
  * `hub.json`, and — only the first time, when `accounts.json` doesn't
  * exist yet — provisions the superuser and the owner/service application
- * users, then leaves the server running. Idempotent: re-running with
- * everything already present reports every step `unchanged` and touches
+ * users, then leaves the server running. The service account always goes
+ * to `service.json`; `credentials.json` is written only when none exists
+ * or it already points at this hub (see `storeServiceAccount`). Idempotent:
+ * re-running with everything already present reports every step `unchanged` and touches
  * neither the process nor the accounts. Never throws; a failing step
  * stops the sequence and is reported as `error`.
  */
 export async function installHub(options, deps) {
-    const port = options.port ?? DEFAULT_HUB_PORT;
     const steps = [];
     let located;
     try {
@@ -129,13 +199,20 @@ export async function installHub(options, deps) {
     }
     const manifest = located.manifest;
     const layout = hubLayout(deps.homeDir);
+    // An existing install keeps its recorded port; a fresh one takes the default, and never a different one silently.
+    const existingConfig = readConfigOrUndefined(layout.hubJson);
+    const port = options.port ?? existingConfig?.port ?? DEFAULT_HUB_PORT;
+    if (!existsSync(layout.accountsJson)) {
+        const conflict = await checkPortBindable(port, options.port !== undefined, deps);
+        if (conflict)
+            return { ok: false, steps: [{ step: "check port", outcome: "error", detail: conflict }] };
+    }
     const rootExisted = existsSync(layout.root);
     if (!rootExisted)
         mkdirSync(layout.root, { recursive: true, mode: OWNER_DIR_MODE });
     mkdirSync(layout.bin, { recursive: true });
     mkdirSync(layout.pbData, { recursive: true });
     steps.push({ step: "create ~/.kankaku/hub", outcome: rootExisted ? "unchanged" : "done" });
-    const existingConfig = readConfigOrUndefined(layout.hubJson);
     const needsBinary = !existsSync(layout.binary) || existingConfig?.pocketbaseVersion !== manifest.pocketbase.version;
     if (needsBinary) {
         try {
@@ -177,11 +254,12 @@ export async function installHub(options, deps) {
     const accountsExist = existsSync(layout.accountsJson);
     if (accountsExist) {
         steps.push({ step: "provision accounts", outcome: "unchanged" });
+        steps.push(...ensureServiceAccount(deps.homeDir, baseUrlFor(port)));
         return { ok: true, steps, url: baseUrlFor(port) };
     }
     // Reported as its own step: a hub that cannot start is not an accounts
     // problem, and the accounts step must never claim to have run.
-    const portConflict = await ensurePortFree(port, deps);
+    const portConflict = await ensurePortFree(port, deps, true);
     if (portConflict) {
         steps.push({ step: "start hub", outcome: "error", detail: portConflict });
         return { ok: false, steps };
@@ -200,11 +278,12 @@ export async function installHub(options, deps) {
         await createUser(url, superuser, { email: options.ownerEmail, password: options.ownerPassword, role: "owner" }, deps.fetch);
         const servicePassword = generatePassword(deps.randomBytes);
         await createUser(url, superuser, { email: SERVICE_EMAIL, password: servicePassword, role: "service" }, deps.fetch);
+        // The service password is stored before accounts.json marks the accounts as provisioned: a crash in between must never leave a password nobody has.
+        const serviceSteps = storeServiceAccount(deps.homeDir, { url, email: SERVICE_EMAIL, password: servicePassword });
         const accounts = { superuserEmail: SUPERUSER_EMAIL, superuserPassword, ownerEmail: options.ownerEmail };
         writeFileSync(layout.accountsJson, JSON.stringify(accounts, null, 2));
         chmodSync(layout.accountsJson, OWNER_FILE_MODE);
-        writeHubCredentials(deps.homeDir, { url, email: SERVICE_EMAIL, password: servicePassword });
-        steps.push({ step: "provision accounts", outcome: "done" });
+        steps.push({ step: "provision accounts", outcome: "done" }, ...serviceSteps);
         return { ok: true, steps, url };
     }
     catch (error) {

package/dist/adapters/hub-manager/port-probe.js

@@ -0,0 +1,38 @@
+/**
+ * Free-port probe for the local hub: bind `127.0.0.1:<port>` with
+ * `node:net` and release it again. The binder is injectable so every test
+ * but the one proving the real binder works uses a fake.
+ */
+import { createServer } from "node:net";
+const LOOPBACK = "127.0.0.1";
+const MAX_PORT = 65535;
+/** The real binder: a `node:net` server listening on `host:port`. */
+export const realPortBinder = (port, host) => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(port, host, () => {
+        resolve(() => new Promise((done) => server.close(() => done())));
+    });
+});
+/** `true` when `127.0.0.1:<port>` can be bound (it is released again before returning); `false` on any bind error. */
+export async function isPortFree(port, bind = realPortBinder) {
+    try {
+        const release = await bind(port, LOOPBACK);
+        await release();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The first free port among `from`, `from + 1`, … (at most `tries` candidates, never above 65535), or `undefined` when none is free. */
+export async function firstFreePort(from, tries = 20, bind = realPortBinder) {
+    for (let offset = 0; offset < tries; offset += 1) {
+        const port = from + offset;
+        if (port > MAX_PORT)
+            return undefined;
+        if (await isPortFree(port, bind))
+            return port;
+    }
+    return undefined;
+}

package/dist/adapters/package-versions.js

@@ -0,0 +1,24 @@
+/**
+ * The versions of the packages `kankaku` carries (`kankaku-pi`,
+ * `kankaku-claude`, `kankaku-hub`), resolved the same way the rest of the
+ * code finds them (`require.resolve("<name>/package.json")`, see
+ * `hub-manager/package.ts` and `setup/claude-plugin.ts`). Never throws: a
+ * package that cannot be resolved or read has an `undefined` version.
+ */
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+const defaultRequire = createRequire(import.meta.url);
+export const CARRIED_PACKAGES = ["kankaku-pi", "kankaku-claude", "kankaku-hub"];
+function versionOf(name, resolve) {
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(`${name}/package.json`), "utf8"));
+        return typeof parsed.version === "string" && parsed.version !== "" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Each carried package's version, in {@link CARRIED_PACKAGES} order. `resolve` defaults to `require.resolve`; tests inject one. */
+export function readCarriedVersions(resolve = (specifier) => defaultRequire.resolve(specifier)) {
+    return CARRIED_PACKAGES.map((name) => ({ name, version: versionOf(name, resolve) }));
+}

package/dist/adapters/setup/hub.js

@@ -30,7 +30,7 @@ export function writeHubCredentials(homeDir, credentials) {
     if (unchanged)
         return { changed: false };
     backupOnce(filePath);
-    writeJsonAtomic(filePath, { ...existing, url: credentials.url, email: credentials.email, password: credentials.password });
+    writeJsonAtomic(filePath, { ...existing, url: credentials.url, email: credentials.email, password: credentials.password }, undefined, OWNER_FILE_MODE);
     chmodSync(filePath, OWNER_FILE_MODE);
     return { changed: true };
 }

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

@@ -59,10 +59,15 @@ export function backupOnce(filePath) {
     if (sourceIsOwnerOnly)
         tightenBestEffort(backupPath);
 }
-/** 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) {
+/**
+ * Write `value` as 2-space-indented JSON to `filePath` via tmp file + rename,
+ * creating the parent directory when missing. With `fileMode` the temp file
+ * is created with that mode from the first byte, so a secret is never
+ * readable through a wider mode, not even for the instant before a chmod.
+ */
+export function writeJsonAtomic(filePath, value, dirMode, fileMode) {
     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));
+    writeFileSync(tmp, JSON.stringify(value, null, 2), fileMode !== undefined ? { mode: fileMode } : {});
     renameSync(tmp, filePath);
 }

package/dist/cli.js

@@ -13,6 +13,8 @@ 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 { readCarriedVersions } from "./adapters/package-versions.js";
+import { formatVersionLines } from "./domain/version-info.js";
 import { buildCatalogModel } from "./domain/catalog-model.js";
 import { buildTodayRows, formatTodayLines } from "./domain/today-model.js";
 import { buildDashboardModel } from "./domain/dashboard-model.js";
@@ -21,6 +23,7 @@ import { buildTasksModel } from "./domain/tasks-model.js";
 import { buildSyncRows } from "./domain/sync-model.js";
 import { DEFAULT_THEME, ThemeProvider, resolveTheme } from "./ui/theme.js";
 import { detectAgents, formatDoctorLines, formatSetupPlanLines, planSetup } from "./domain/setup-plan.js";
+import { parseHubPort } from "./domain/setup-wizard.js";
 import { readAgentFacts } from "./adapters/setup/agents.js";
 import { addKankakuPackage, removeKankakuPackage } from "./adapters/setup/pi.js";
 import { removeClaudeIntegration, writeClaudeIntegration } from "./adapters/setup/claude.js";
@@ -31,11 +34,13 @@ import { tuiConfigPath, writeTuiConfig } from "./adapters/setup/tui-config.js";
 import { installLocalHub } from "./adapters/setup/local-hub.js";
 import { createChildProcessRunner } from "./adapters/setup/child-process-runner.js";
 import { createReadlinePrompter } from "./adapters/setup/readline-prompter.js";
-import { hubLayout, parseHubConfig } from "./domain/local-hub-model.js";
+import { describeSyncTarget, hubLayout, parseHubConfig } from "./domain/local-hub-model.js";
 import { hubLogs, hubStatus, installHub, startHub, stopHub, upgradeHub } from "./adapters/hub-manager/install.js";
 import { isAlive, readPid, startDetached } from "./adapters/hub-manager/process.js";
 import { locateHubPackage } from "./adapters/hub-manager/package.js";
-const USAGE = "usage: kankaku [today|tasks [--all]|catalog [refresh]|sync [status|all] [--project <dir>]|setup [--yes] [--dry-run] [--from-checkout <dir>] [--claude-plugin-dir <dir>]|doctor|hub install [--port N] [--owner-email E] [--owner-password P]|hub start|hub stop|hub status|hub upgrade|hub logs [-n N]] [--roots a,b] [--theme name]\n";
+import { useLocalHub } from "./adapters/hub-manager/credentials.js";
+import { firstFreePort, isPortFree, realPortBinder } from "./adapters/hub-manager/port-probe.js";
+const USAGE = "usage: kankaku [--version|-v|version|today|tasks [--all]|catalog [refresh]|sync [status|all] [--project <dir>]|setup [--yes] [--dry-run] [--from-checkout <dir>] [--claude-plugin-dir <dir>]|doctor|hub install [--port N] [--owner-email E] [--owner-password P]|hub use|hub start|hub stop|hub status|hub upgrade|hub logs [-n N]] [--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);
@@ -267,19 +272,23 @@ async function runDoctorCommand(deps, claudePluginOverride) {
  * with no network call — the hub's health is checked interactively, from
  * the wizard's own Hub step, never upfront.
  */
-function gatherWizardFacts(deps, claudePluginOverride) {
+export function gatherWizardFacts(deps, claudePluginOverride) {
     const agentFacts = readAgentFacts(deps.homeDir, claudePluginOverride);
     const hubResolution = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
     const credPath = credentialsPath(deps.homeDir);
-    const hub = hubResolution.ok
-        ? {
-            credentialsPresent: true,
-            url: hubResolution.credentials.url,
-            email: hubResolution.credentials.email,
-            password: hubResolution.credentials.password,
-            credentialsPath: credPath,
-        }
-        : { credentialsPresent: false, url: undefined, email: undefined, password: undefined, credentialsPath: credPath };
+    const localPort = localHubPort(deps);
+    const hub = {
+        ...(hubResolution.ok
+            ? {
+                credentialsPresent: true,
+                url: hubResolution.credentials.url,
+                email: hubResolution.credentials.email,
+                password: hubResolution.credentials.password,
+                credentialsPath: credPath,
+            }
+            : { credentialsPresent: false, url: undefined, email: undefined, password: undefined, credentialsPath: credPath }),
+        ...(localPort !== undefined ? { localPort } : {}),
+    };
     const tuiPath = tuiConfigPath(deps.homeDir);
     const roots = {
         current: existsSync(tuiPath) ? readTuiConfig(deps.homeDir, deps.cwd).roots : undefined,
@@ -303,6 +312,7 @@ function buildHubManagerDeps(deps) {
         platform: process.platform,
         arch: process.arch,
         isAlive: (pid) => isAlive(pid),
+        portBinder: realPortBinder,
         ...deps.hubManager,
     };
 }
@@ -330,8 +340,10 @@ async function performLocalHubInstallFromCheckout(checkout, deps) {
  * `--claude-plugin-dir`/`KANKAKU_CLAUDE_PLUGIN_DIR` — see
  * `runCli`/`resolveClaudePluginOverride`), never from wizard state.
  * `install-local-hub` runs the real `hub-manager/install.ts#installHub`
- * (which writes `accounts.json` and `~/.kankaku/credentials.json`
- * itself), reporting every install step in the result detail. Never
+ * (which writes `accounts.json` and `service.json`, and
+ * `~/.kankaku/credentials.json` only when none exists or it already
+ * points at the local hub), reporting every install step in the result
+ * detail - the `sync credentials` step with its own explanation. Never
  * throws: any adapter failure becomes an `"error"` outcome instead.
  */
 async function applyWizardAction(action, state, deps, claudePluginOverride) {
@@ -363,8 +375,8 @@ async function applyWizardAction(action, state, deps, claudePluginOverride) {
                 return { action, outcome: result.changed ? "wrote" : "unchanged" };
             }
             case "install-local-hub": {
-                const report = await installHub({ ownerEmail: state.hub.ownerEmail, ownerPassword: state.hub.ownerPassword }, buildHubManagerDeps(deps));
-                const detail = report.steps.map((step) => `${step.step}: ${step.outcome}`).join("; ");
+                const report = await installHub({ port: parseHubPort(state.hub.port), ownerEmail: state.hub.ownerEmail, ownerPassword: state.hub.ownerPassword }, buildHubManagerDeps(deps));
+                const detail = report.steps.map((step) => `${step.step}: ${step.outcome}${step.step === "sync credentials" && step.detail ? ` (${step.detail})` : ""}`).join("; ");
                 if (!report.ok)
                     return { action, outcome: "error", detail };
                 return { action, outcome: "started", detail: `${detail} — running at ${report.url}` };
@@ -401,11 +413,17 @@ function announceCommands(deps, result) {
     for (const file of result.foreign)
         deps.stdout(`skipped ${file} (not a kankaku command)`);
 }
+/** The binder for the wizard's port probe: the real one, unless a test injected another through `CliDeps.hubManager`. */
+function portBinderFor(deps) {
+    return deps.hubManager?.portBinder ?? realPortBinder;
+}
 /** Build the setup wizard's `WizardActions` for the interactive app: every write goes through the same real `adapters/setup/*` writers `kankaku setup --yes` uses. Used only by `renderApp`. */
 export function buildWizardActions(deps, claudePluginOverride) {
     return {
         apply: (action, state) => applyWizardAction(action, state, deps, claudePluginOverride),
         checkHealth: (url) => checkHubHealth(url, { fetch: deps.fetch }),
+        isPortFree: (port) => isPortFree(port, portBinderFor(deps)),
+        suggestPort: (from) => firstFreePort(from, 20, portBinderFor(deps)),
     };
 }
 /** `--claude-plugin-dir <dir>`'s value when given, else `KANKAKU_CLAUDE_PLUGIN_DIR`; `undefined` resolves to the bundled `kankaku-claude` package (see `adapters/setup/claude-plugin.ts#locateClaudePlugin`). */
@@ -444,6 +462,28 @@ function formatHubStatusLine(status, pocketbaseVersion, pbDataBytes) {
     const pbPart = pocketbaseVersion ? ` (PocketBase ${pocketbaseVersion})` : "";
     return `local hub: ${label}${status.version ? ` ${status.version}` : ""}${pbPart} at ${status.url} · pb_data ${formatBytes(pbDataBytes)}`;
 }
+/** The URL this machine's sync resolves to (`resolveHub`: environment first, then `~/.kankaku/credentials.json`), or `undefined` when none is configured. */
+function syncCredentialsUrl(deps) {
+    const hub = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    return hub.ok ? hub.credentials.url : undefined;
+}
+/** The installed local hub's port from `hub.json`, or `undefined` when it is not installed (or `hub.json` is unreadable). */
+function localHubPort(deps) {
+    const layout = hubLayout(deps.homeDir);
+    if (!existsSync(layout.hubJson))
+        return undefined;
+    try {
+        return parseHubConfig(JSON.parse(readFileSync(layout.hubJson, "utf8"))).port;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The installed local hub's URL, or `undefined` when it is not installed. */
+function localHubUrl(deps) {
+    const port = localHubPort(deps);
+    return port === undefined ? undefined : `http://127.0.0.1:${port}`;
+}
 /** `-n <count>`'s value, defaulting to 50 when absent or not a positive integer. */
 function logCountFlag(args) {
     const index = args.indexOf("-n");
@@ -454,12 +494,13 @@ function flagValue(args, flag) {
     const index = args.indexOf(flag);
     return index === -1 ? undefined : args[index + 1];
 }
+/** `--port`'s value: `undefined` when the flag is absent, `NaN` when it is present but not a whole number between 1 and 65535. */
 function portFlag(args) {
     const raw = flagValue(args, "--port");
     if (raw === undefined)
-        return undefined;
+        return args.includes("--port") ? Number.NaN : undefined;
     const value = Number(raw);
-    return Number.isInteger(value) && value > 0 ? value : undefined;
+    return Number.isInteger(value) && value >= 1 && value <= 65535 ? value : Number.NaN;
 }
 /** Print every `HubActionReport` step, one per line (`<step>: <outcome> (<detail>)`), and the resulting URL when present. */
 function printHubReport(deps, report) {
@@ -482,6 +523,12 @@ async function runHubCommand(args, deps) {
     const [sub, ...rest] = args;
     const hubDeps = buildHubManagerDeps(deps);
     if (sub === "install") {
+        const port = portFlag(rest);
+        if (Number.isNaN(port)) {
+            deps.stderr("kankaku hub install: --port must be a whole number between 1 and 65535\n");
+            deps.exit(1);
+            return;
+        }
         let ownerEmail = flagValue(rest, "--owner-email");
         let ownerPassword = flagValue(rest, "--owner-password");
         if ((ownerEmail === undefined || ownerPassword === undefined) && (deps.isTTY?.() ?? false) && deps.prompter) {
@@ -493,7 +540,7 @@ async function runHubCommand(args, deps) {
             deps.exit(1);
             return;
         }
-        const report = await installHub({ port: portFlag(rest), ownerEmail, ownerPassword }, hubDeps);
+        const report = await installHub({ port, ownerEmail, ownerPassword }, hubDeps);
         printHubReport(deps, report);
         if (!report.ok)
             deps.exit(1);
@@ -524,6 +571,19 @@ async function runHubCommand(args, deps) {
             }
         }
         deps.stdout(formatHubStatusLine(status, pocketbaseVersion, dirSizeBytes(layout.pbData)));
+        deps.stdout(`sync: ${describeSyncTarget(syncCredentialsUrl(deps), localHubUrl(deps))}`);
+        return;
+    }
+    if (sub === "use") {
+        const result = useLocalHub(deps.homeDir);
+        if (!result.ok) {
+            deps.stderr(`kankaku hub use: ${result.error}\n`);
+            deps.exit(1);
+            return;
+        }
+        deps.stdout(result.changed
+            ? `sync now points at ${result.url} (was ${result.previousUrl ?? "not configured"})`
+            : `sync credentials: unchanged (already points at ${result.url})`);
         return;
     }
     if (sub === "upgrade") {
@@ -708,6 +768,10 @@ export async function runCli(argv, deps) {
         deps.renderApp(roots, theme, { startInWizard });
         return;
     }
+    if (command === "--version" || command === "-v" || command === "version") {
+        deps.stdout(formatVersionLines(readOwnVersion(), readCarriedVersions(deps.resolvePackage)).join("\n"));
+        return;
+    }
     if (command === "today") {
         const model = loadToday(roots);
         deps.stdout(formatTodayLines(model.rows, model.total).join("\n"));

package/dist/domain/local-hub-model.js

@@ -101,6 +101,7 @@ export function hubLayout(homeDir) {
         currentFile: joinPath(root, "current"),
         hubJson: joinPath(root, "hub.json"),
         accountsJson: joinPath(root, "accounts.json"),
+        serviceJson: joinPath(root, "service.json"),
         pidFile: joinPath(root, "pid"),
         logFile: joinPath(root, "hub.log"),
     };
@@ -177,3 +178,42 @@ export function generatePassword(randomBytes, length = 24) {
     }
     return password;
 }
+/** Narrows `json` to a `ServiceAccount` (three non-empty strings), or `undefined` when it is anything else. */
+export function parseServiceAccount(json) {
+    if (!json || typeof json !== "object" || Array.isArray(json))
+        return undefined;
+    const record = json;
+    const { url, email, password } = record;
+    if (typeof url !== "string" || url === "" || typeof email !== "string" || email === "" || typeof password !== "string" || password === "")
+        return undefined;
+    return { url, email, password };
+}
+function hostAndPort(url) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname === "localhost" ? "127.0.0.1" : parsed.hostname;
+        return `${parsed.protocol}//${host}:${parsed.port}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether two hub URLs name the same scheme, host and port (`localhost` and `127.0.0.1` are the same host; a trailing slash or path is ignored). An unparsable URL never matches. */
+export function sameHubUrl(a, b) {
+    const left = hostAndPort(a);
+    return left !== undefined && left === hostAndPort(b);
+}
+/** Install may write `~/.kankaku/credentials.json` only when none exists, or when it already points at this local hub. */
+export function shouldWriteCredentials(existingUrl, localUrl) {
+    return existingUrl === undefined || sameHubUrl(existingUrl, localUrl);
+}
+/** The `sync credentials` step's detail when install leaves `credentials.json` alone. */
+export function credentialsKeptDetail(existingUrl) {
+    return `this machine syncs to ${existingUrl}; run 'kankaku hub use' to switch to the local hub`;
+}
+/** Where this machine's sync points, for `kankaku hub status`: `local hub`, the other hub's URL, or `not configured`. */
+export function describeSyncTarget(credentialsUrl, localUrl) {
+    if (credentialsUrl === undefined)
+        return "not configured";
+    return localUrl !== undefined && sameHubUrl(credentialsUrl, localUrl) ? "local hub" : credentialsUrl;
+}

package/dist/domain/setup-wizard.js

@@ -5,8 +5,9 @@
  * callers (`src/ui/setup/*`, `src/cli.tsx`) read the real files and pass
  * plain facts in via `WizardFacts`, exactly like `domain/setup-plan.ts`.
  */
+import { shouldWriteCredentials } from "./local-hub-model.js";
 import { detectAgents } from "./setup-plan.js";
-/** The local hub's fixed port for the wizard's `install locally` review line and `install-local-hub` action — mirrors `hub-manager/install.ts#DEFAULT_HUB_PORT`. */
+/** The local hub's default port, where the wizard's port field starts looking for a free one - mirrors `hub-manager/install.ts#DEFAULT_HUB_PORT`. */
 export const DEFAULT_HUB_PORT = 8090;
 /**
  * Shorten `path` for display by replacing a leading `homeDir` with `~`.
@@ -31,7 +32,7 @@ function clearError(errors, key) {
     delete rest[key];
     return rest;
 }
-const HUB_ERROR_KEYS = ["url", "email", "password", "ownerEmail", "ownerPassword"];
+const HUB_ERROR_KEYS = ["url", "email", "password", "ownerEmail", "ownerPassword", "port"];
 function clearHubErrors(errors) {
     return HUB_ERROR_KEYS.reduce((acc, key) => clearError(acc, key), errors);
 }
@@ -50,6 +51,7 @@ export function createWizardState(facts) {
             password: facts.hub.password ?? "",
             ownerEmail: "",
             ownerPassword: "",
+            port: String(facts.hub.localPort ?? DEFAULT_HUB_PORT),
         },
         roots: facts.roots.current ?? facts.roots.defaultRoots,
         errors: {},
@@ -68,6 +70,17 @@ export function setHubMode(state, mode) {
 export function setHubField(state, field, value) {
     return { ...state, hub: { ...state.hub, [field]: value }, errors: clearError(state.errors, field) };
 }
+/** The local hub port as a number when `text` is digits only within 1024-65535, otherwise `undefined`. */
+export function parseHubPort(text) {
+    if (!/^\d+$/.test(text))
+        return undefined;
+    const port = Number(text);
+    return port >= 1024 && port <= 65535 ? port : undefined;
+}
+/** Flags `port` as occupied (`port N is in use`), found by the probe the Hub step runs before advancing; editing the port field clears it. */
+export function setHubPortInUse(state, port) {
+    return { ...state, errors: { ...state.errors, port: `port ${port} is in use` } };
+}
 export function setHubHealth(state, ok) {
     return { ...state, hub: { ...state.hub, healthOk: ok } };
 }
@@ -96,6 +109,8 @@ function validateHub(hub) {
             errors.ownerEmail = "enter a valid email";
         if (hub.ownerPassword.trim() === "")
             errors.ownerPassword = "enter a password";
+        if (parseHubPort(hub.port) === undefined)
+            errors.port = "enter a port between 1024 and 65535";
         return errors;
     }
     return {};
@@ -140,8 +155,12 @@ export function planFromWizard(state, facts) {
         }
     }
     else if (state.hub.mode === "local") {
-        const url = `http://127.0.0.1:${DEFAULT_HUB_PORT}`;
-        actions.push({ kind: "install-local-hub", file: url, label: `install a local hub at ${url}` });
+        const url = `http://127.0.0.1:${parseHubPort(state.hub.port) ?? DEFAULT_HUB_PORT}`;
+        const existingUrl = facts.hub.credentialsPresent ? facts.hub.url : undefined;
+        const note = shouldWriteCredentials(existingUrl, url)
+            ? "sync credentials → the local hub"
+            : `sync credentials stay on ${existingUrl} (switch later with kankaku hub use)`;
+        actions.push({ kind: "install-local-hub", file: url, label: `install a local hub at ${url}`, note });
     }
     const sameRoots = facts.roots.current !== undefined && arraysEqual(facts.roots.current, state.roots);
     if (!sameRoots) {

package/dist/domain/version-info.js

@@ -0,0 +1,5 @@
+/** Pure text for `kankaku --version`. No I/O: `adapters/package-versions.ts` reads the versions. */
+/** `kankaku <version>`, then one indented line per carried package: its version, or `not found`. */
+export function formatVersionLines(ownVersion, carried) {
+    return [`kankaku ${ownVersion}`, ...carried.map(({ name, version }) => `  ${name} ${version ?? "not found"}`)];
+}

package/dist/ui/setup/wizard-screen.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { Box, Text, useInput, useStdout } from "ink";
-import { DEFAULT_HUB_PORT, applyResult, back, createWizardState, hintsForStep, next, planFromWizard, setHubField, setHubHealth, setHubMode, setRoots, shortenHome, toggleAgent, } from "../../domain/setup-wizard.js";
+import { DEFAULT_HUB_PORT, applyResult, back, createWizardState, hintsForStep, next, parseHubPort, planFromWizard, setHubField, setHubHealth, setHubMode, setHubPortInUse, setRoots, shortenHome, toggleAgent, } from "../../domain/setup-wizard.js";
 import { HeaderBar } from "../components/header-bar.js";
 import { KeyHints } from "../components/key-hints.js";
 import { Panel } from "../components/panel.js";
@@ -111,11 +111,27 @@ export function SetupWizard({ facts, actions, onDone, onQuit, version, columns,
     const [healthChecking, setHealthChecking] = useState(false);
     const [rootsText, setRootsText] = useState(() => state.roots.join(", "));
     const applyStartedRef = useRef(false);
+    const portTouchedRef = useRef(false);
     useEffect(() => {
         if (state.step === "hub")
             setHubFocus(0);
     }, [state.step]);
-    const hubFieldCount = state.hub.mode === "existing" ? 4 : state.hub.mode === "local" ? 3 : 1;
+    // Prefill the local hub's port with the first free one from the default upwards, unless an install already recorded its own or the user got there first.
+    useEffect(() => {
+        if (facts.hub.localPort !== undefined)
+            return;
+        let cancelled = false;
+        void actions.suggestPort(DEFAULT_HUB_PORT).then((port) => {
+            if (cancelled || port === undefined || portTouchedRef.current)
+                return;
+            setState((s) => setHubField(s, "port", String(port)));
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const hubFieldCount = state.hub.mode === "existing" ? 4 : state.hub.mode === "local" ? 4 : 1;
     const textInputFocused = state.step === "roots" || (state.step === "hub" && hubFocus >= 1 && hubFocus < hubFieldCount);
     useEffect(() => {
         if (state.step !== "apply" || applyStartedRef.current)
@@ -140,6 +156,14 @@ export function SetupWizard({ facts, actions, onDone, onQuit, version, columns,
                 onDone();
                 return;
             }
+            if (state.step === "hub" && state.hub.mode === "local") {
+                // A valid port is probed before advancing; an existing install's own port is ours and is never probed.
+                const port = parseHubPort(state.hub.port);
+                if (port !== undefined && port !== facts.hub.localPort) {
+                    void actions.isPortFree(port).then((free) => setState((s) => (free ? next(s, facts) : setHubPortInUse(s, port))));
+                    return;
+                }
+            }
             setState((s) => next(s, facts));
             return;
         }
@@ -172,8 +196,11 @@ export function SetupWizard({ facts, actions, onDone, onQuit, version, columns,
     const height = rows ?? stdout?.rows ?? DEFAULT_ROWS;
     const mainWidth = width;
     const mainHeight = Math.max(height - HEADER_ROWS - FOOTER_ROWS, 0);
-    return (_jsxs(Box, { flexDirection: "column", width: width, height: height, children: [_jsx(HeaderBar, { left: `>_ kankaku setup${version ? ` ${version}` : ""}`, width: width }), _jsx(Box, { flexDirection: "column", flexGrow: 1, minHeight: 0, children: _jsxs(Panel, { title: panelTitle(state), width: mainWidth, height: mainHeight, active: true, children: [state.step === "agents" && (_jsx(Checklist, { items: agentChecklistItems(state.agents, state.selected, facts.homeDir), cursor: agentCursor, onToggle: (id) => setState((s) => toggleAgent(s, id)), onMove: (delta) => setAgentCursor((c) => Math.min(Math.max(c + delta, 0), state.agents.length - 1)), focused: true })), state.step === "hub" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Radio, { options: HUB_MODE_OPTIONS, value: state.hub.mode, onChange: (mode) => setState((s) => setHubMode(s, mode)), focused: hubFocus === 0 }), state.hub.mode === "existing" && (_jsxs(Box, { flexDirection: "column", children: [["url", "email", "password"].map((field, index) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: `${field}: ` }), _jsx(TextInput, { value: state.hub[field], onChange: (value) => setState((s) => setHubField(s, field, value)), masked: field === "password", focused: hubFocus === index + 1 })] }, field))), state.errors.url && _jsx(Text, { color: theme.error, children: state.errors.url }), state.errors.email && _jsx(Text, { color: theme.error, children: state.errors.email }), state.errors.password && _jsx(Text, { color: theme.error, children: state.errors.password }), _jsx(Text, { children: `[ check ] c   ${healthLine(state.hub.healthOk, healthChecking)}` })] })), state.hub.mode === "local" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: `will install and run at http://127.0.0.1:${DEFAULT_HUB_PORT}` }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: "owner email: " }), _jsx(TextInput, { value: state.hub.ownerEmail, onChange: (value) => setState((s) => setHubField(s, "ownerEmail", value)), focused: hubFocus === 1 })] }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: "owner password: " }), _jsx(TextInput, { value: state.hub.ownerPassword, onChange: (value) => setState((s) => setHubField(s, "ownerPassword", value)), masked: true, focused: hubFocus === 2 })] }), state.errors.ownerEmail && _jsx(Text, { color: theme.error, children: state.errors.ownerEmail }), state.errors.ownerPassword && _jsx(Text, { color: theme.error, children: state.errors.ownerPassword })] }))] })), state.step === "roots" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "project roots (comma-separated):" }), _jsx(TextInput, { value: rootsText, onChange: (value) => {
+    return (_jsxs(Box, { flexDirection: "column", width: width, height: height, children: [_jsx(HeaderBar, { left: `>_ kankaku setup${version ? ` ${version}` : ""}`, width: width }), _jsx(Box, { flexDirection: "column", flexGrow: 1, minHeight: 0, children: _jsxs(Panel, { title: panelTitle(state), width: mainWidth, height: mainHeight, active: true, children: [state.step === "agents" && (_jsx(Checklist, { items: agentChecklistItems(state.agents, state.selected, facts.homeDir), cursor: agentCursor, onToggle: (id) => setState((s) => toggleAgent(s, id)), onMove: (delta) => setAgentCursor((c) => Math.min(Math.max(c + delta, 0), state.agents.length - 1)), focused: true })), state.step === "hub" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Radio, { options: HUB_MODE_OPTIONS, value: state.hub.mode, onChange: (mode) => setState((s) => setHubMode(s, mode)), focused: hubFocus === 0 }), state.hub.mode === "existing" && (_jsxs(Box, { flexDirection: "column", children: [["url", "email", "password"].map((field, index) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: `${field}: ` }), _jsx(TextInput, { value: state.hub[field], onChange: (value) => setState((s) => setHubField(s, field, value)), masked: field === "password", focused: hubFocus === index + 1 })] }, field))), state.errors.url && _jsx(Text, { color: theme.error, children: state.errors.url }), state.errors.email && _jsx(Text, { color: theme.error, children: state.errors.email }), state.errors.password && _jsx(Text, { color: theme.error, children: state.errors.password }), _jsx(Text, { children: `[ check ] c   ${healthLine(state.hub.healthOk, healthChecking)}` })] })), state.hub.mode === "local" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: `will install and run at http://127.0.0.1:${parseHubPort(state.hub.port) ?? DEFAULT_HUB_PORT}` }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: "owner email: " }), _jsx(TextInput, { value: state.hub.ownerEmail, onChange: (value) => setState((s) => setHubField(s, "ownerEmail", value)), focused: hubFocus === 1 })] }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: "owner password: " }), _jsx(TextInput, { value: state.hub.ownerPassword, onChange: (value) => setState((s) => setHubField(s, "ownerPassword", value)), masked: true, focused: hubFocus === 2 })] }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: "port: " }), _jsx(TextInput, { value: state.hub.port, onChange: (value) => {
+                                                        portTouchedRef.current = true;
+                                                        setState((s) => setHubField(s, "port", value.replace(/\D/g, "")));
+                                                    }, focused: hubFocus === 3 })] }), state.errors.ownerEmail && _jsx(Text, { color: theme.error, children: state.errors.ownerEmail }), state.errors.ownerPassword && _jsx(Text, { color: theme.error, children: state.errors.ownerPassword }), state.errors.port && _jsx(Text, { color: theme.error, children: state.errors.port })] }))] })), state.step === "roots" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "project roots (comma-separated):" }), _jsx(TextInput, { value: rootsText, onChange: (value) => {
                                         setRootsText(value);
                                         setState((s) => setRoots(s, value));
-                                    }, focused: true }), state.errors.roots && _jsx(Text, { color: theme.error, children: state.errors.roots })] })), state.step === "review" && (_jsx(Table, { columns: reviewColumns(mainWidth), rows: state.plan, rowKey: (row) => `${row.kind}-${row.file}`, cell: reviewCell, emptyText: "nothing to change" })), state.step === "apply" && (_jsxs(Box, { flexDirection: "column", children: [state.results.map((result, index) => (_jsx(Text, { children: applyResultLine(result) }, `${result.action.kind}-${index}`))), state.results.length < state.plan.length && _jsx(Text, { dimColor: true, children: "applying\u2026" })] })), state.step === "done" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: `setup complete: ${state.results.length} change(s) applied` }), _jsx(Text, { dimColor: true, children: "enter open dashboard" })] }))] }) }), _jsx(KeyHints, { hints: hints })] }));
+                                    }, focused: true }), state.errors.roots && _jsx(Text, { color: theme.error, children: state.errors.roots })] })), state.step === "review" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Table, { columns: reviewColumns(mainWidth), rows: state.plan, rowKey: (row) => `${row.kind}-${row.file}`, cell: reviewCell, emptyText: "nothing to change" }), state.plan.map((action) => action.note !== undefined && _jsx(Text, { children: action.note }, `note-${action.kind}-${action.file}`))] })), state.step === "apply" && (_jsxs(Box, { flexDirection: "column", children: [state.results.map((result, index) => (_jsx(Text, { children: applyResultLine(result) }, `${result.action.kind}-${index}`))), state.results.length < state.plan.length && _jsx(Text, { dimColor: true, children: "applying\u2026" })] })), state.step === "done" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: `setup complete: ${state.results.length} change(s) applied` }), _jsx(Text, { dimColor: true, children: "enter open dashboard" })] }))] }) }), _jsx(KeyHints, { hints: hints })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Terminal app that shows today's kankaku work across every project on disk",
   "keywords": [
     "pi-package",
@@ -38,8 +38,8 @@
   },
   "dependencies": {
     "ink": "^7.1.1",
-    "kankaku-pi": "^1.0.2",
-    "kankaku-claude": "^1.0.2",
+    "kankaku-pi": "^1.1.0",
+    "kankaku-claude": "^1.1.0",
     "kankaku-hub": "^0.2.0",
     "react": "^19.3.0"
   },

package/vendor/kankaku-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-pi",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
   "license": "MIT",
   "author": "soyunninja",
@@ -58,8 +58,8 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1",
     "@types/node": "^24.13.4",
     "typescript": "^5.7.0"
   }