kankaku-tui 0.3.0 → 0.4.0

package/README.md

@@ -16,24 +16,27 @@ kankaku setup
 ```
 
 On a real terminal, `kankaku setup` opens as a full-screen wizard — one
-step at a time, in the same sidebar/panel look as the rest of the app.
-`kankaku` with no arguments does the same the very first time (no
-`~/.kankaku/tui.json` yet); after that first run it opens straight into
-the Dashboard as usual.
+step at a time, in the same header/panel/footer look as the rest of the
+app (there's no sidebar in the wizard itself: the panel's own title
+tracks progress instead, e.g. `Setup · Agents 1/5`, numbering only the
+steps this run will actually show). `kankaku` with no arguments does the
+same the very first time (no `~/.kankaku/tui.json` yet); after that first
+run it opens straight into the Dashboard as usual.
 
 The wizard's steps, `enter` to advance and `esc` to go back throughout
-(`esc` at the first step quits):
+(`esc` at the first step, Agents, quits):
 
-1. **Detect** — which agents kankaku found on this machine, and their
-   current state.
-2. **Agents** — a checklist (`space` toggles): pi, gentle-shell, Claude
-   Code. Pre-checked means already configured; unchecking a configured
+1. **Agents** — a checklist (`space` toggles) that also carries detection
+   for every agent kankaku knows about: pi, gentle-shell and Claude Code
+   each show `configured (<path, shortened with ~>)` or `not configured`;
+   pre-checked means already configured, and unchecking a configured
    agent schedules removing kankaku from it, not just skipping it. Codex
-   and OpenCode are listed but disabled — no adapter yet.
-3. **Claude Code** — the `kankaku-claude` checkout path (only shown when
+   and OpenCode are listed but disabled, showing `no adapter yet` (found,
+   but kankaku can't write its config) or `not installed` (not found).
+2. **Claude Code** — the `kankaku-claude` checkout path (only shown when
    Claude Code is checked and not already configured), guessed from any
    existing `statusLine`.
-4. **Hub** — `use an existing hub` (URL, email, masked password, a `c`
+3. **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 looks for a
    `kankaku-hub` checkout first; if found, its path is prefilled and
@@ -45,14 +48,14 @@ The wizard's steps, `enter` to advance and `esc` to go back throughout
    wizard shows the exact commands to run in another terminal and a `c`
    "check again" action, plus `m` to acknowledge you'll install it
    manually.
-5. **Roots** — the comma-separated project roots, defaulting to the
+4. **Roots** — the comma-separated project roots, defaulting to the
    current `tui.json` (or the parent of the current directory the first
-   time).
-6. **Review** — the plan: one line per change, with the exact file it
+   time). See "Configuration" below for how deep each root is searched.
+5. **Review** — the plan: one line per change, with the exact file it
    touches. `enter` applies it.
-7. **Apply** — runs each change and shows its result
+6. **Apply** — runs each change and shows its result
    (`wrote`/`unchanged`/`removed`/`started`/`error: …`) as it happens.
-8. **Done** — a summary, then `enter` opens the Dashboard in place — no
+7. **Done** — a summary, then `enter` opens the Dashboard in place — no
    restart.
 
 `kankaku setup --yes` and `kankaku setup --dry-run` stay exactly as
@@ -73,12 +76,16 @@ same read-only report: one line per agent, one for the hub, one for
 
 ## 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/`.
+```
+npm install -g kankaku-tui
+```
 
-Later, once published: `npm install -g kankaku-tui`. For now, run it from
-this repo with `npm run dev`.
+Then run `kankaku setup` (or just `kankaku` the first time) to configure
+the coding agents on this machine, the hub and your project roots. The
+package depends on the published `kankaku` library (`kankaku/domain`,
+`kankaku/hub`) and on `kankaku-hub` for the local hub installer; nothing
+else needs to be checked out. To work on this repo itself, run
+`npm install` inside it and `npm run dev`.
 
 ## Configuration
 
@@ -90,10 +97,23 @@ this repo with `npm run dev`.
 }
 ```
 
-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.
+### Projects across roots
+
+Each root is searched recursively for projects, up to 5 directory levels
+below it by default: a directory is a project once it has its own
+`.kankaku/worklog.jsonl` — including the root itself — and the search
+still continues below it, so a stray worklog in a parent directory (a pi
+session run once in `~/desarrollo`) never hides the projects beneath;
+every directory is listed at most once. Subdirectories are searched one
+level deeper, skipping `node_modules`, `.git` and any hidden
+(dot-prefixed) directory. This lets one root cover a whole workspace, e.g.
+`~/desarrollo` finding every project under `~/desarrollo/<client>/<project>`
+without listing each one. Projects are deduped by real (symlink-resolved)
+path and sorted by name — the directory's basename, or the last two path
+segments joined with `/` when two discovered projects share a basename
+(e.g. `clientA/shared` and `clientB/shared`). `~` 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)
 
@@ -127,6 +147,51 @@ Every sync uploaded from here is stamped `plugin: kankaku-tui`; a task's
 kankaku's `hub-entry.ts`), else falls back to `agent: unknown` — this app
 never guesses which coding agent produced someone else's worklog.
 
+### Local hub
+
+Instead of pointing at someone else's PocketBase, `kankaku hub install`
+sets up and runs your own hub on this machine, under `~/.kankaku/hub/`:
+
+- `bin/pocketbase` — the PocketBase binary for this OS/CPU, downloaded
+  from the `kankaku-hub` npm package's manifest and SHA256-verified.
+- `pb_data/` — the hub's own database; never touched by an upgrade.
+- `app/<version>/` — a fresh copy of that package version's migrations,
+  hooks and static files (never a symlink, so `npm update` can't change a
+  running hub out from under it); `current` names the active version.
+- `hub.json` — the installed port and versions.
+- `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.
+
+Commands (macOS and Linux only — PocketBase ships no other build):
+
+- `kankaku hub install [--port N] [--owner-email E] [--owner-password P]`
+  — 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.
+- `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`.
+- `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
+  touched.
+- `kankaku hub logs [-n N]` — the last `N` (default 50) lines of
+  `hub.log`.
+
+The Dashboard's Hub card shows `local hub · running`/`stopped` when the
+configured hub is this machine's own local install, with a matching `h`
+quick action to start or stop it. The setup wizard's Hub step's
+`install locally` option runs this same installer (asking for the owner
+email/password inline); the older checkout-based dev install
+(`kankaku-hub`'s own `scripts/dev.sh`) is still available for hub
+developers via `kankaku setup --from-checkout <dir>`.
+
 ## Usage
 
 - `kankaku` — opens the interactive TUI on the Dashboard screen.
@@ -141,9 +206,13 @@ never guesses which coding agent produced someone else's worklog.
   pending count and last sync per project, no network; with no argument,
   syncs the pending window; `all` does a full resync. Defaults to every
   discovered project, sequentially; `--project <dir>` restricts to one.
-- `kankaku setup [--yes] [--dry-run]` — see "Install everything" above.
+- `kankaku setup [--yes] [--dry-run] [--from-checkout <dir>]` — see
+  "Install everything" above; `--from-checkout` is the hub-developer-only
+  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.
 
 `--roots` (on `today`/`tasks`) overrides the configured roots for that run.
 

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

@@ -0,0 +1,52 @@
+/** Runs `pocketbase superuser upsert <email> <password> --dir <pbData>` through `runner`. Throws on a non-zero exit, including stderr/stdout in the message. */
+export async function upsertSuperuser(binary, pbData, email, password, runner) {
+    const result = await runner.run(binary, ["superuser", "upsert", email, password, "--dir", pbData], { cwd: pbData });
+    if (result.code !== 0) {
+        throw new Error(`pocketbase superuser upsert failed: ${result.stderr || result.stdout || `exit code ${result.code}`}`);
+    }
+}
+/**
+ * Authenticates as `superuser` against the `_superusers` collection, looks
+ * up `user.email` in `users`, and creates it (role `owner` or `service`,
+ * `emailVisibility: true`, `verified: true`) when absent. Idempotent: a
+ * user that already exists is left untouched and reported as `"exists"`.
+ */
+export async function createUser(baseUrl, superuser, user, doFetch) {
+    const url = baseUrl.replace(/\/+$/, "");
+    const authResponse = await doFetch(`${url}/api/collections/_superusers/auth-with-password`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ identity: superuser.email, password: superuser.password }),
+    });
+    if (!authResponse.ok) {
+        throw new Error(`superuser authentication failed: HTTP ${authResponse.status}`);
+    }
+    const auth = (await authResponse.json());
+    const filter = encodeURIComponent(`email="${user.email}"`);
+    const lookupResponse = await doFetch(`${url}/api/collections/users/records?filter=${filter}`, {
+        headers: { authorization: auth.token },
+    });
+    if (!lookupResponse.ok) {
+        throw new Error(`user lookup failed: HTTP ${lookupResponse.status}`);
+    }
+    const lookup = (await lookupResponse.json());
+    if (lookup.items && lookup.items.length > 0) {
+        return { outcome: "exists" };
+    }
+    const createResponse = await doFetch(`${url}/api/collections/users/records`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: auth.token },
+        body: JSON.stringify({
+            email: user.email,
+            password: user.password,
+            passwordConfirm: user.password,
+            role: user.role,
+            emailVisibility: true,
+            verified: true,
+        }),
+    });
+    if (!createResponse.ok) {
+        throw new Error(`user creation failed: HTTP ${createResponse.status}`);
+    }
+    return { outcome: "created" };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Downloads a PocketBase release asset (from `HubManifest.pocketbase.assets`),
+ * verifies its SHA256 against the manifest, and extracts the `pocketbase`
+ * binary from the zip into `targetBinary`.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { extractSingleEntry } from "./zip.js";
+const BINARY_MODE = 0o755;
+/**
+ * Streams `asset.url` to a temp file next to `targetBinary`, verifies its
+ * SHA256 against `asset.sha256`, extracts the single `pocketbase` entry
+ * from the zip, and writes it to `targetBinary` (mode 0755) via temp file
+ * + rename. Throws `checksum mismatch` and deletes the temp download when
+ * the hash does not match; never leaves a partial or temp file behind on
+ * any failure.
+ */
+export async function downloadPocketBase(asset, targetBinary, deps) {
+    const mkdir = deps.mkdir ?? ((dir) => mkdirSync(dir, { recursive: true }));
+    const targetDir = dirname(targetBinary);
+    mkdir(targetDir);
+    const response = await deps.fetch(asset.url);
+    if (!response.ok) {
+        throw new Error(`failed to download ${asset.url}: HTTP ${response.status}`);
+    }
+    const zipBytes = new Uint8Array(await response.arrayBuffer());
+    const zipTmpPath = `${targetBinary}.${process.pid}.download.tmp`;
+    writeFileSync(zipTmpPath, zipBytes);
+    try {
+        const hash = createHash("sha256").update(zipBytes).digest("hex");
+        if (hash.toLowerCase() !== asset.sha256.toLowerCase()) {
+            throw new Error(`checksum mismatch for ${asset.file}: expected ${asset.sha256}, got ${hash}`);
+        }
+        const binaryBytes = extractSingleEntry(zipBytes, "pocketbase");
+        const binaryTmpPath = `${targetBinary}.${process.pid}.tmp`;
+        try {
+            writeFileSync(binaryTmpPath, binaryBytes, { mode: BINARY_MODE });
+            renameSync(binaryTmpPath, targetBinary);
+        }
+        catch (error) {
+            rmSync(binaryTmpPath, { force: true });
+            throw error;
+        }
+    }
+    finally {
+        rmSync(zipTmpPath, { force: true });
+    }
+}

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

@@ -0,0 +1,265 @@
+/**
+ * Orchestrates the local hub's full lifecycle: install (idempotent),
+ * start, stop, status and upgrade — composing the pure
+ * `domain/local-hub-model.ts` with the other `hub-manager/*` adapters
+ * (`package.ts`, `download.ts`, `process.ts`, `accounts.ts`) and
+ * `adapters/setup/hub.ts#writeHubCredentials`. Every piece of I/O is
+ * injected (`HubManagerDeps`) so tests never touch the network, spawn a
+ * real PocketBase, or run a real script.
+ */
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assetKeyFor, classifyStatus, generatePassword, hubLayout, parseHubConfig, serveArgs, } 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 { createUser, upsertSuperuser } from "./accounts.js";
+import { writeHubCredentials } from "../setup/hub.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. */
+const SUPERUSER_EMAIL = "admin@kankaku.local";
+const SERVICE_EMAIL = "kankaku-sync@kankaku.local";
+export const DEFAULT_HUB_PORT = 8090;
+const HEALTH_TIMEOUT_MS = 20000;
+const STOP_TIMEOUT_MS = 5000;
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function readConfigOrUndefined(hubJsonPath) {
+    if (!existsSync(hubJsonPath))
+        return undefined;
+    try {
+        return parseHubConfig(JSON.parse(readFileSync(hubJsonPath, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fresh-copies `pocketbase/pb_migrations`, `pocketbase/pb_hooks` and `public` from the package into `appDir` — never a symlink, so `npm update` cannot change a running hub. */
+function copyAppFiles(packageDir, appDir) {
+    cpSync(join(packageDir, "pocketbase", "pb_migrations"), join(appDir, "pocketbase", "pb_migrations"), { recursive: true });
+    cpSync(join(packageDir, "pocketbase", "pb_hooks"), join(appDir, "pocketbase", "pb_hooks"), { recursive: true });
+    cpSync(join(packageDir, "public"), join(appDir, "public"), { recursive: true });
+}
+function baseUrlFor(port) {
+    return `http://127.0.0.1:${port}`;
+}
+/**
+ * Installs (or, run again, verifies) the local hub under
+ * `~/.kankaku/hub`: locates the `kankaku-hub` package, creates the layout
+ * directories (root created 0700, never chmod'd again once it exists —
+ * mirrors kankaku's own R2 rule), downloads the PocketBase binary for
+ * this platform when missing or out of date (SHA256-verified), copies the
+ * 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
+ * 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 {
+        located = deps.locatePackage();
+    }
+    catch (error) {
+        return { ok: false, steps: [{ step: "locate kankaku-hub package", outcome: "error", detail: message(error) }] };
+    }
+    const manifest = located.manifest;
+    const layout = hubLayout(deps.homeDir);
+    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 {
+            const asset = manifest.pocketbase.assets[assetKeyFor(deps.platform, deps.arch)];
+            await downloadPocketBase(asset, layout.binary, { fetch: deps.fetch });
+            steps.push({ step: "download pocketbase", outcome: "done", detail: manifest.pocketbase.version });
+        }
+        catch (error) {
+            steps.push({ step: "download pocketbase", outcome: "error", detail: message(error) });
+            return { ok: false, steps };
+        }
+    }
+    else {
+        steps.push({ step: "download pocketbase", outcome: "unchanged" });
+    }
+    const appDir = layout.appDir(manifest.version);
+    const appDirExisted = existsSync(appDir);
+    if (!appDirExisted) {
+        try {
+            copyAppFiles(located.dir, appDir);
+        }
+        catch (error) {
+            steps.push({ step: "install app files", outcome: "error", detail: message(error) });
+            return { ok: false, steps };
+        }
+    }
+    writeFileSync(layout.currentFile, manifest.version);
+    steps.push({ step: "install app files", outcome: appDirExisted ? "unchanged" : "done", detail: manifest.version });
+    const newConfig = {
+        port,
+        appVersion: manifest.version,
+        pocketbaseVersion: manifest.pocketbase.version,
+        installedAt: existingConfig?.installedAt ?? new Date(deps.now()).toISOString(),
+    };
+    const hubJsonChanged = !existingConfig || existingConfig.port !== newConfig.port || existingConfig.appVersion !== newConfig.appVersion || existingConfig.pocketbaseVersion !== newConfig.pocketbaseVersion;
+    if (hubJsonChanged)
+        writeFileSync(layout.hubJson, JSON.stringify(newConfig, null, 2));
+    steps.push({ step: "write hub.json", outcome: hubJsonChanged ? "done" : "unchanged" });
+    const accountsExist = existsSync(layout.accountsJson);
+    if (accountsExist) {
+        steps.push({ step: "provision accounts", outcome: "unchanged" });
+        return { ok: true, steps, url: baseUrlFor(port) };
+    }
+    try {
+        const superuserPassword = generatePassword(deps.randomBytes);
+        await upsertSuperuser(layout.binary, layout.pbData, SUPERUSER_EMAIL, superuserPassword, deps.runner);
+        deps.startDetached(layout.binary, serveArgs(layout, manifest.version, port), { logFile: layout.logFile, pidFile: layout.pidFile });
+        const url = baseUrlFor(port);
+        const healthy = await waitForHealth(`${url}/api/health`, { fetch: deps.fetch, sleep: deps.sleep, timeoutMs: HEALTH_TIMEOUT_MS });
+        if (!healthy) {
+            steps.push({ step: "provision accounts", outcome: "error", detail: "the local hub did not become healthy within 20s" });
+            return { ok: false, steps };
+        }
+        const superuser = { email: SUPERUSER_EMAIL, password: superuserPassword };
+        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);
+        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" });
+        return { ok: true, steps, url };
+    }
+    catch (error) {
+        steps.push({ step: "provision accounts", outcome: "error", detail: message(error) });
+        return { ok: false, steps };
+    }
+}
+/** Starts the installed hub: a no-op (`unchanged`) if already running, otherwise spawns it and waits for health. */
+export async function startHub(deps) {
+    const layout = hubLayout(deps.homeDir);
+    const config = readConfigOrUndefined(layout.hubJson);
+    if (!config)
+        return { ok: false, steps: [{ step: "start", outcome: "error", detail: "the local hub is not installed" }] };
+    const pid = readPid(layout.pidFile);
+    if (pid !== undefined && isAlive(pid)) {
+        return { ok: true, steps: [{ step: "start", outcome: "unchanged", detail: "already running" }], url: baseUrlFor(config.port) };
+    }
+    deps.startDetached(layout.binary, serveArgs(layout, config.appVersion, config.port), { logFile: layout.logFile, pidFile: layout.pidFile });
+    const url = baseUrlFor(config.port);
+    const healthy = await waitForHealth(`${url}/api/health`, { fetch: deps.fetch, sleep: deps.sleep, timeoutMs: HEALTH_TIMEOUT_MS });
+    return {
+        ok: healthy,
+        steps: [{ step: "start", outcome: healthy ? "done" : "error", detail: healthy ? undefined : "did not become healthy within 20s" }],
+        url,
+    };
+}
+/** Stops the installed hub via `SIGTERM` (bounded wait, `SIGKILL` as a last resort). A no-op (`unchanged`) when it wasn't running. */
+export async function stopHub(deps) {
+    const layout = hubLayout(deps.homeDir);
+    const result = await stopProcess(layout.pidFile, { timeoutMs: STOP_TIMEOUT_MS, sleep: deps.sleep });
+    return { ok: true, steps: [{ step: "stop", outcome: result === "not-running" ? "unchanged" : "done", detail: result }] };
+}
+/** Classifies the installed hub's current status (`hubLayout`, pid liveness and, only while a process is alive, one health check). Never throws. */
+export async function hubStatus(deps) {
+    const layout = hubLayout(deps.homeDir);
+    const config = readConfigOrUndefined(layout.hubJson);
+    const pid = readPid(layout.pidFile);
+    const pidAlive = pid !== undefined && isAlive(pid);
+    let health = "skipped";
+    if (pidAlive && config) {
+        try {
+            const response = await deps.fetch(`${baseUrlFor(config.port)}/api/health`);
+            health = response.ok ? "ok" : "failed";
+        }
+        catch {
+            health = "failed";
+        }
+    }
+    return classifyStatus({ installed: config !== undefined, config, pidAlive, health });
+}
+/**
+ * Upgrades the local hub to the currently installed `kankaku-hub`
+ * package's version: copies a fresh `app/<new version>/` (when not
+ * already present), downloads a new PocketBase binary only if its
+ * version changed, restarts the process, and leaves `pb_data` untouched.
+ * A no-op (`unchanged`) when the installed package is already the
+ * running version.
+ */
+export async function upgradeHub(deps) {
+    const layout = hubLayout(deps.homeDir);
+    const config = readConfigOrUndefined(layout.hubJson);
+    if (!config)
+        return { ok: false, steps: [{ step: "upgrade", outcome: "error", detail: "the local hub is not installed" }] };
+    let located;
+    try {
+        located = deps.locatePackage();
+    }
+    catch (error) {
+        return { ok: false, steps: [{ step: "locate kankaku-hub package", outcome: "error", detail: message(error) }] };
+    }
+    const manifest = located.manifest;
+    if (manifest.version === config.appVersion && manifest.pocketbase.version === config.pocketbaseVersion) {
+        return { ok: true, steps: [{ step: "upgrade", outcome: "unchanged", detail: "already up to date" }], url: baseUrlFor(config.port) };
+    }
+    const steps = [];
+    const appDir = layout.appDir(manifest.version);
+    const appDirExisted = existsSync(appDir);
+    if (!appDirExisted) {
+        try {
+            copyAppFiles(located.dir, appDir);
+        }
+        catch (error) {
+            steps.push({ step: "install app files", outcome: "error", detail: message(error) });
+            return { ok: false, steps };
+        }
+    }
+    writeFileSync(layout.currentFile, manifest.version);
+    steps.push({ step: "install app files", outcome: appDirExisted ? "unchanged" : "done", detail: manifest.version });
+    if (manifest.pocketbase.version !== config.pocketbaseVersion) {
+        try {
+            const asset = manifest.pocketbase.assets[assetKeyFor(deps.platform, deps.arch)];
+            await downloadPocketBase(asset, layout.binary, { fetch: deps.fetch });
+            steps.push({ step: "download pocketbase", outcome: "done", detail: manifest.pocketbase.version });
+        }
+        catch (error) {
+            steps.push({ step: "download pocketbase", outcome: "error", detail: message(error) });
+            return { ok: false, steps };
+        }
+    }
+    else {
+        steps.push({ step: "download pocketbase", outcome: "unchanged" });
+    }
+    const newConfig = { ...config, appVersion: manifest.version, pocketbaseVersion: manifest.pocketbase.version };
+    writeFileSync(layout.hubJson, JSON.stringify(newConfig, null, 2));
+    steps.push({ step: "write hub.json", outcome: "done" });
+    await stopProcess(layout.pidFile, { timeoutMs: STOP_TIMEOUT_MS, sleep: deps.sleep });
+    deps.startDetached(layout.binary, serveArgs(layout, newConfig.appVersion, newConfig.port), { logFile: layout.logFile, pidFile: layout.pidFile });
+    const url = baseUrlFor(newConfig.port);
+    const healthy = await waitForHealth(`${url}/api/health`, { fetch: deps.fetch, sleep: deps.sleep, timeoutMs: HEALTH_TIMEOUT_MS });
+    steps.push({ step: "restart", outcome: healthy ? "done" : "error", detail: healthy ? undefined : "did not become healthy within 20s" });
+    return { ok: healthy, steps, url };
+}
+/** The last `n` lines of `hub.log`, oldest first; `[]` when the hub has never logged anything. */
+export function hubLogs(n, deps) {
+    const layout = hubLayout(deps.homeDir);
+    if (!existsSync(layout.logFile))
+        return [];
+    const content = readFileSync(layout.logFile, "utf8");
+    const lines = content.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines.slice(Math.max(lines.length - n, 0));
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Locates the installed `kankaku-hub` npm package (a real dependency —
+ * `file:../kankaku-hub-worktrees/npm-package` until the package is
+ * published) and reads/validates its `hub-manifest.json`.
+ */
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseHubManifest } from "../../domain/local-hub-model.js";
+const defaultRequire = createRequire(import.meta.url);
+/**
+ * Resolves `kankaku-hub/package.json` through `resolve` (defaulting to
+ * `require.resolve`), then reads and validates the `hub-manifest.json`
+ * next to it. Throws a clear error when the package cannot be resolved,
+ * its manifest file is missing, or the manifest fails validation.
+ */
+export function locateHubPackage(resolve = (specifier) => defaultRequire.resolve(specifier)) {
+    let packageJsonPath;
+    try {
+        packageJsonPath = resolve("kankaku-hub/package.json");
+    }
+    catch (error) {
+        throw new Error(`kankaku-hub package is not installed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const dir = dirname(packageJsonPath);
+    const manifestPath = join(dir, "hub-manifest.json");
+    let raw;
+    try {
+        raw = readFileSync(manifestPath, "utf8");
+    }
+    catch (error) {
+        throw new Error(`could not read ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const manifest = parseHubManifest(JSON.parse(raw));
+    return { dir, manifest };
+}