kankaku-tui 0.3.1 → 0.4.1

package/README.md

@@ -76,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
 
@@ -143,6 +147,55 @@ 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. 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.
+- `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.
@@ -157,9 +210,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,331 @@
+/**
+ * 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, unlinkSync, 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}`;
+}
+/** `hub.log`'s lines, oldest first, `[]` when unreadable or empty. Shared by `hubLogs` (public, by line count) and `healthFailureDetail` (the last line only). */
+function readLogLines(layout) {
+    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;
+}
+function portInUseMessage(port) {
+    return `port ${port} is already in use by another process — pass --port <N> or stop it`;
+}
+/**
+ * Before spawning: if `GET /api/health` on `port` answers at all (ok or
+ * not — any response means something is already listening), the port is
+ * 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.
+ */
+async function ensurePortFree(port, deps) {
+    try {
+        await deps.fetch(`${baseUrlFor(port)}/api/health`);
+        return portInUseMessage(port);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Spawns the hub detached and waits for it to become healthy, stopping
+ * immediately (rather than waiting out the full timeout) if the process
+ * dies first. On an early exit, removes the pid file it just wrote so a
+ * dead process is never left claiming to be running.
+ */
+async function spawnAndAwaitHealth(layout, appVersion, port, deps) {
+    const pid = deps.startDetached(layout.binary, serveArgs(layout, appVersion, port), { logFile: layout.logFile, pidFile: layout.pidFile });
+    const healthy = await waitForHealth(`${baseUrlFor(port)}/api/health`, {
+        fetch: deps.fetch,
+        sleep: deps.sleep,
+        timeoutMs: HEALTH_TIMEOUT_MS,
+        isAlive: () => deps.isAlive(pid),
+    });
+    if (healthy)
+        return { pid, healthy: true, exitedEarly: false };
+    const exitedEarly = !deps.isAlive(pid);
+    if (exitedEarly && existsSync(layout.pidFile))
+        unlinkSync(layout.pidFile);
+    return { pid, healthy: false, exitedEarly };
+}
+/** The error detail for a failed `spawnAndAwaitHealth`: the last `hub.log` line when the process exited early and one is readable, otherwise a plain timeout message. */
+function healthFailureDetail(layout, exitedEarly) {
+    if (!exitedEarly)
+        return "the local hub did not become healthy within 20s";
+    const lastLine = readLogLines(layout).at(-1);
+    return lastLine ? `the hub exited during startup: ${lastLine}` : "the hub exited during startup";
+}
+/**
+ * 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) };
+    }
+    // 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);
+    if (portConflict) {
+        steps.push({ step: "start hub", outcome: "error", detail: portConflict });
+        return { ok: false, steps };
+    }
+    try {
+        const superuserPassword = generatePassword(deps.randomBytes);
+        await upsertSuperuser(layout.binary, layout.pbData, SUPERUSER_EMAIL, superuserPassword, deps.runner);
+        const spawnResult = await spawnAndAwaitHealth(layout, manifest.version, port, deps);
+        if (!spawnResult.healthy) {
+            steps.push({ step: "start hub", outcome: "error", detail: healthFailureDetail(layout, spawnResult.exitedEarly) });
+            return { ok: false, steps };
+        }
+        steps.push({ step: "start hub", outcome: "done" });
+        const url = baseUrlFor(port);
+        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) };
+    }
+    const portConflict = await ensurePortFree(config.port, deps);
+    if (portConflict) {
+        return { ok: false, steps: [{ step: "start", outcome: "error", detail: portConflict }] };
+    }
+    const spawnResult = await spawnAndAwaitHealth(layout, config.appVersion, config.port, deps);
+    return {
+        ok: spawnResult.healthy,
+        steps: [{ step: "start", outcome: spawnResult.healthy ? "done" : "error", detail: spawnResult.healthy ? undefined : healthFailureDetail(layout, spawnResult.exitedEarly) }],
+        url: baseUrlFor(config.port),
+    };
+}
+/** 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 });
+    const url = baseUrlFor(newConfig.port);
+    const portConflict = await ensurePortFree(newConfig.port, deps);
+    if (portConflict) {
+        steps.push({ step: "restart", outcome: "error", detail: portConflict });
+        return { ok: false, steps };
+    }
+    const spawnResult = await spawnAndAwaitHealth(layout, newConfig.appVersion, newConfig.port, deps);
+    steps.push({ step: "restart", outcome: spawnResult.healthy ? "done" : "error", detail: spawnResult.healthy ? undefined : healthFailureDetail(layout, spawnResult.exitedEarly) });
+    return { ok: spawnResult.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);
+    const lines = readLogLines(layout);
+    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 };
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Detached process control for the local hub's PocketBase server: start,
+ * pid tracking, liveness, stop (SIGTERM with a bounded wait, SIGKILL as a
+ * last resort) and health polling.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+/**
+ * Spawns `binary args` detached (survives the caller exiting), appending
+ * its combined stdout/stderr to `logFile`, and writes its pid to
+ * `pidFile`. Returns the pid.
+ */
+export function startDetached(binary, args, deps) {
+    const fd = openSync(deps.logFile, "a");
+    const child = spawn(binary, args, { detached: true, stdio: ["ignore", fd, fd] });
+    child.unref();
+    const pid = child.pid ?? -1;
+    writeFileSync(deps.pidFile, String(pid));
+    return pid;
+}
+/** Reads the pid written by `startDetached`, or `undefined` when `pidFile` is missing or holds no valid positive integer. */
+export function readPid(pidFile) {
+    if (!existsSync(pidFile))
+        return undefined;
+    const raw = readFileSync(pidFile, "utf8").trim();
+    const pid = Number(raw);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+/** `true` when a process with `pid` is reachable. An `EPERM` (a different owner, still on this machine) counts as alive; `ESRCH` (no such process) does not. */
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+const POLL_INTERVAL_MS = 100;
+const POST_KILL_POLL_ATTEMPTS = 10;
+/**
+ * Reads the pid from `pidFile`. If no live process is found, removes a
+ * stale pid file (if any) and returns `"not-running"`. Otherwise sends
+ * SIGTERM and polls `isAlive` every 100ms up to `deps.timeoutMs`; if the
+ * process is still alive at the deadline, sends SIGKILL. Always removes
+ * `pidFile` before returning.
+ */
+export async function stopProcess(pidFile, deps) {
+    const pid = readPid(pidFile);
+    if (pid === undefined || !isAlive(pid)) {
+        if (existsSync(pidFile))
+            unlinkSync(pidFile);
+        return "not-running";
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // The process exited between the isAlive check and here.
+        if (existsSync(pidFile))
+            unlinkSync(pidFile);
+        return "not-running";
+    }
+    let elapsedMs = 0;
+    let killedForcibly = false;
+    while (isAlive(pid)) {
+        if (elapsedMs >= deps.timeoutMs) {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // Already gone.
+            }
+            killedForcibly = true;
+            break;
+        }
+        await deps.sleep(POLL_INTERVAL_MS);
+        elapsedMs += POLL_INTERVAL_MS;
+    }
+    if (killedForcibly) {
+        for (let attempt = 0; isAlive(pid) && attempt < POST_KILL_POLL_ATTEMPTS; attempt++) {
+            await deps.sleep(POLL_INTERVAL_MS);
+        }
+    }
+    if (existsSync(pidFile))
+        unlinkSync(pidFile);
+    return killedForcibly ? "killed" : "stopped";
+}
+const HEALTH_POLL_INTERVAL_MS = 500;
+/**
+ * Polls `GET url` every 500ms until it responds ok, `deps.timeoutMs`
+ * elapses, or (when `deps.isAlive` is given) the process dies. Returns
+ * whether it became healthy. Never throws.
+ */
+export async function waitForHealth(url, deps) {
+    let elapsedMs = 0;
+    for (;;) {
+        try {
+            const response = await deps.fetch(url);
+            if (response.ok)
+                return true;
+        }
+        catch {
+            // Not up yet; keep polling until the deadline.
+        }
+        if (deps.isAlive && !deps.isAlive())
+            return false;
+        if (elapsedMs >= deps.timeoutMs)
+            return false;
+        await deps.sleep(HEALTH_POLL_INTERVAL_MS);
+        elapsedMs += HEALTH_POLL_INTERVAL_MS;
+    }
+}