kankaku-tui 0.4.0 → 0.4.1

package/README.md

@@ -172,7 +172,11 @@ 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.
+  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

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

@@ -7,7 +7,7 @@
  * 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 { 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";
@@ -45,6 +45,64 @@ function copyAppFiles(packageDir, appDir) {
 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
@@ -121,16 +179,23 @@ export async function installHub(options, deps) {
         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);
-        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" });
+        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);
@@ -157,13 +222,15 @@ export async function startHub(deps) {
     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 });
+    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: healthy,
-        steps: [{ step: "start", outcome: healthy ? "done" : "error", detail: healthy ? undefined : "did not become healthy within 20s" }],
-        url,
+        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. */
@@ -246,20 +313,19 @@ export async function upgradeHub(deps) {
     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 };
+    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);
-    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();
+    const lines = readLogLines(layout);
     return lines.slice(Math.max(lines.length - n, 0));
 }

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

@@ -87,7 +87,11 @@ export async function stopProcess(pidFile, deps) {
     return killedForcibly ? "killed" : "stopped";
 }
 const HEALTH_POLL_INTERVAL_MS = 500;
-/** Polls `GET url` every 500ms until it responds ok, or `deps.timeoutMs` elapses. Returns whether it became healthy. Never throws. */
+/**
+ * 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 (;;) {
@@ -99,6 +103,8 @@ export async function waitForHealth(url, deps) {
         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);

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

@@ -3,8 +3,9 @@
  * atomic tmp+rename, and a one-time `<file>.bak` — mirrors kankaku's own
  * `adapters/project-config.ts#writeProjectTargetIds`.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+const OWNER_FILE_MODE = 0o600;
 /** Parse `filePath` as a JSON object, defaulting to `{}` on any absence, malformed JSON, or non-object document. Never throws. */
 export function readJsonObjectOrEmpty(filePath) {
     if (!existsSync(filePath))
@@ -19,18 +20,44 @@ export function readJsonObjectOrEmpty(filePath) {
         return {};
     }
 }
+/** Best-effort `chmodSync`; never throws (e.g. a read-only filesystem or an already-gone file). */
+function tightenBestEffort(path) {
+    try {
+        chmodSync(path, OWNER_FILE_MODE);
+    }
+    catch {
+        // Best-effort only.
+    }
+}
 /**
  * Copy `filePath`'s current bytes to `<filePath>.bak`, but only the first
  * time: a no-op when `filePath` does not exist yet (nothing to back up) or
- * `<filePath>.bak` already exists (never overwritten).
+ * `<filePath>.bak` already exists (its content is never overwritten).
+ *
+ * When `filePath` is owner-only (0600, e.g. `~/.kankaku/credentials.json`,
+ * which carries a live hub's service account password), the backup mirrors
+ * that mode instead of the platform's default (umask-derived, typically
+ * world-readable) mode — a previous hub's credentials must never end up
+ * more exposed in the backup than they were in the live file. An existing
+ * `.bak` from before this fix is tightened too, best-effort, whenever a
+ * 0600 source is encountered — mirroring kankaku's own "existing looser
+ * mode is tightened, best-effort, whenever encountered" rule.
  */
 export function backupOnce(filePath) {
     if (!existsSync(filePath))
         return;
     const backupPath = `${filePath}.bak`;
-    if (existsSync(backupPath))
+    const sourceIsOwnerOnly = (statSync(filePath).mode & 0o777) === OWNER_FILE_MODE;
+    if (existsSync(backupPath)) {
+        if (sourceIsOwnerOnly)
+            tightenBestEffort(backupPath);
         return;
-    writeFileSync(backupPath, readFileSync(filePath));
+    }
+    // Created owner-only from the first byte when the source is: a chmod
+    // after the write would leave a window where the secret is readable.
+    writeFileSync(backupPath, readFileSync(filePath), sourceIsOwnerOnly ? { mode: OWNER_FILE_MODE } : {});
+    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) {

package/dist/cli.js

@@ -300,6 +300,7 @@ function buildHubManagerDeps(deps) {
         locatePackage: () => locateHubPackage(),
         platform: process.platform,
         arch: process.arch,
+        isAlive: (pid) => isAlive(pid),
         ...deps.hubManager,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-tui",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Terminal app that shows today's kankaku work across every project on disk",
   "license": "MIT",
   "type": "module",