@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/cli/lib/process-lifecycle.js

@@ -0,0 +1,148 @@
+// ESM port of ompweb/bin/process-lifecycle.js.
+// Semantics are preserved exactly: POSIX signals the whole process group
+// (`process.kill(-pid, signal)`) with a `child.kill(signal)` fallback, while
+// win32 shells out to `taskkill /pid <pid> /t [/f]`.
+
+const forwardedSignals = ['SIGINT', 'SIGTERM'];
+const shutdownTimeoutMs = 5_000;
+
+// Time to wait for a terminated process tree to actually exit.
+export const STOP_TIMEOUT_MS = 5_000;
+
+// Signal numbers for the 128+N shell exit-code convention (os.constants.signals
+// equivalent; only signals forwarded by this module are needed).
+const SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGKILL: 9 };
+
+function getSignalExitCode(signal) {
+  const signalNumber = signal ? SIGNAL_NUMBERS[signal] : undefined;
+  return typeof signalNumber === 'number' ? 128 + signalNumber : 1;
+}
+
+/**
+ * Whether `process.kill(-pid, …)` may be used on this PID.
+ *
+ * The negative form signals a process GROUP, and POSIX reserves `-1` for "every
+ * process this user may signal" — so a pid of 1 or 0 must never reach it. A
+ * stale instance record naming such a PID would otherwise turn `kabmo stop`
+ * into a signal to the whole session, which is a far worse outcome than a stop
+ * that fails. Kept as a named predicate so the rule is testable WITHOUT
+ * signalling anything.
+ */
+export function isGroupKillable(pid) {
+  return Number.isInteger(pid) && pid > 1;
+}
+
+/**
+ * End a process (and, on Windows, its tree).
+ *
+ * `spawn` is injectable for the same reason `platform` is: the Windows branch
+ * runs `taskkill`, and the host this project is developed on has no such binary
+ * — so the branch's failure modes (a missing binary, a non-zero exit, a success)
+ * could not be exercised at all. Bun resolves a child's executable from the PATH
+ * snapshot taken at process start, so a stub placed on PATH afterwards is NOT
+ * found (verified), and the seam is the only way to reach those paths.
+ */
+export function killChildTree(child, force, platform = process.platform, gracefulSignal = 'SIGTERM', spawn = Bun.spawn) {
+  if (platform === 'win32' && child.pid) {
+    const fallback = () => {
+      try { child.kill(force ? 'SIGKILL' : 'SIGTERM'); } catch {}
+    };
+    // `taskkill` is the only way to end a whole tree on Windows, but spawning it
+    // can fail on its own: measured, `Bun.spawn` THROWS `Executable not found in
+    // $PATH: "taskkill"` when the binary is missing, and that throw escaped as an
+    // exception from a stop that was otherwise working — the caller's escalation
+    // never ran. The fallback is the single-PID kill, which on Windows is
+    // forceful either way (POSIX signals do not exist there, so Node maps it to
+    // TerminateProcess): a host without taskkill loses the tree kill, not the
+    // stop.
+    let reaper;
+    try {
+      reaper = spawn({
+        cmd: ['taskkill', '/pid', String(child.pid), '/t', ...(force ? ['/f'] : [])],
+        stdout: 'ignore',
+        stderr: 'ignore',
+        windowsHide: true,
+      });
+    } catch {
+      fallback();
+      return;
+    }
+    void reaper.exited.then((code) => {
+      if (code !== 0) fallback();
+    }, fallback);
+    reaper.unref?.();
+    return;
+  }
+
+  const signal = force ? 'SIGKILL' : gracefulSignal;
+  if (platform !== 'win32' && isGroupKillable(child.pid)) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {}
+  }
+
+  try { child.kill(signal); } catch {}
+}
+
+function childHasExited(child) {
+  return (child.exitCode !== null && child.exitCode !== undefined)
+    || (child.signalCode !== null && child.signalCode !== undefined);
+}
+
+function waitForChildExit(child, timeoutMs) {
+  if (childHasExited(child)) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const finish = (exited) => {
+      clearTimeout(timer);
+      resolve(exited);
+    };
+    const timer = setTimeout(() => finish(childHasExited(child)), timeoutMs);
+    timer.unref?.();
+    void child.exited.then(() => finish(true));
+  });
+}
+
+export async function terminateChildProcess(child, timeoutMs = STOP_TIMEOUT_MS, platform = process.platform, spawn = Bun.spawn) {
+  if (childHasExited(child)) return true;
+  const exited = waitForChildExit(child, timeoutMs);
+  killChildTree(child, true, platform, 'SIGTERM', spawn);
+  return exited;
+}
+
+export function wireChildProcessLifecycle(child, parentProcess = process, timeoutMs = shutdownTimeoutMs, handleChildExit) {
+  const signalHandlers = new Map();
+  let shutdownTimer;
+  let settled = false;
+  const platform = parentProcess.platform ?? process.platform;
+
+  const forceKill = () => killChildTree(child, true, platform);
+
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (shutdownTimer) {
+        forceKill();
+        return;
+      }
+
+      shutdownTimer = setTimeout(forceKill, timeoutMs);
+      shutdownTimer.unref?.();
+      killChildTree(child, false, platform, signal);
+    };
+    signalHandlers.set(signal, handler);
+    parentProcess.on(signal, handler);
+  }
+
+  void child.exited.then((code) => {
+    if (settled) return;
+    settled = true;
+    if (shutdownTimer) clearTimeout(shutdownTimer);
+
+    for (const [forwardedSignal, handler] of signalHandlers) {
+      parentProcess.removeListener(forwardedSignal, handler);
+    }
+    if (handleChildExit?.({ code, signal: child.signalCode }) === true) return;
+
+    parentProcess.exit(code ?? getSignalExitCode(child.signalCode));
+  });
+}

package/src/cli/lib/process-lifecycle.test.js

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Ending a process TREE, on both platforms' mechanisms.
+ *
+ * The Windows branch shells out to `taskkill /pid <pid> /t`, and that spawn can
+ * fail on its own: measured, `Bun.spawn` THROWS `Executable not found in $PATH`
+ * when the binary is missing, which escaped `killChildTree` as an exception from
+ * a stop that was otherwise working — the caller's escalation never ran and the
+ * tree survived. The fallback is the single-PID kill, so a host without
+ * `taskkill` loses the tree kill, not the stop.
+ *
+ * The Windows branch is reached from macOS through the `spawn` seam the function
+ * exposes (Bun resolves a child's executable from the PATH snapshot taken at
+ * process start, so a stub binary cannot be injected through PATH — verified).
+ * What the seam proves is the branch's own decisions: throw → fallback, non-zero
+ * exit → fallback, success → no double kill, and the escalation the caller sees.
+ * A real child is used wherever the real mechanism is the POSIX one.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import { isGroupKillable, killChildTree, terminateChildProcess } from '@/cli/lib/process-lifecycle.js';
+import { describePosix } from '@/test-support/platform';
+
+const children = [];
+
+afterEach(async () => {
+  for (const child of children.splice(0)) {
+    try { child.kill('SIGKILL'); } catch {}
+    await child.exited;
+  }
+});
+
+function spawnSleep() {
+  const child = Bun.spawn(['/bin/sh', '-c', 'trap "" TERM; sleep 60'], { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' });
+  children.push(child);
+  return child;
+}
+
+/** A process object that records what was signalled instead of doing it. */
+function fakeChild(pid = 4242) {
+  const signals = [];
+  return { pid, signals, kill: (signal) => { signals.push(signal); } };
+}
+
+/**
+ * A stand-in for `Bun.spawn` on the win32 branch. `exitCode` is what the fake
+ * `taskkill` reports; `throws` models the missing binary.
+ */
+function fakeSpawn({ exitCode = 0, throws = false } = {}) {
+  const calls = [];
+  const fn = (options) => {
+    calls.push(options);
+    if (throws) throw new Error('Executable not found in $PATH: "taskkill"');
+    return { exited: Promise.resolve(exitCode), unref: () => {} };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+describe('isGroupKillable', () => {
+  // The guard exists because POSIX reserves `kill(-1)` for "every process this
+  // user may signal": a stale record naming PID 1 (or 0) would otherwise turn
+  // `kabmo stop` into a signal to the whole session — observed, and far
+  // worse than a stop that fails.
+  test('refuses the PIDs that make a group kill catastrophic', () => {
+    expect(isGroupKillable(0)).toBe(false);
+    expect(isGroupKillable(1)).toBe(false);
+    expect(isGroupKillable(-1)).toBe(false);
+    expect(isGroupKillable(Number.NaN)).toBe(false);
+    expect(isGroupKillable(undefined)).toBe(false);
+    expect(isGroupKillable('1')).toBe(false);
+  });
+
+  test('allows a real process group leader', () => {
+    expect(isGroupKillable(2)).toBe(true);
+    expect(isGroupKillable(process.pid)).toBe(true);
+  });
+});
+
+describe('killChildTree on win32', () => {
+  test('runs taskkill with the tree and force flags', () => {
+    const spawn = fakeSpawn({ exitCode: 0 });
+    killChildTree(fakeChild(99), true, 'win32', 'SIGTERM', spawn);
+
+    expect(spawn.calls).toHaveLength(1);
+    expect(spawn.calls[0].cmd).toEqual(['taskkill', '/pid', '99', '/t', '/f']);
+    expect(spawn.calls[0].windowsHide).toBe(true);
+  });
+
+  test('omits /f when not forced', () => {
+    const spawn = fakeSpawn({ exitCode: 0 });
+    killChildTree(fakeChild(99), false, 'win32', 'SIGTERM', spawn);
+
+    expect(spawn.calls[0].cmd).toEqual(['taskkill', '/pid', '99', '/t']);
+  });
+
+  test('falls back to the single-PID kill when taskkill cannot be spawned', () => {
+    // The regression: before the fix this THREW out of a stop that was
+    // otherwise working, so the caller's escalation never ran.
+    const child = fakeChild();
+    expect(() => killChildTree(child, true, 'win32', 'SIGTERM', fakeSpawn({ throws: true }))).not.toThrow();
+    expect(child.signals).toEqual(['SIGKILL']);
+  });
+
+  test('falls back when taskkill exits non-zero', async () => {
+    const child = fakeChild();
+    killChildTree(child, true, 'win32', 'SIGTERM', fakeSpawn({ exitCode: 1 }));
+    await Bun.sleep(20);
+    expect(child.signals).toEqual(['SIGKILL']);
+  });
+
+  test('does not double-kill when taskkill succeeded', async () => {
+    const child = fakeChild();
+    killChildTree(child, true, 'win32', 'SIGTERM', fakeSpawn({ exitCode: 0 }));
+    await Bun.sleep(20);
+    expect(child.signals).toEqual([]);
+  });
+
+  test('a reaper that rejects is treated as a failure', async () => {
+    const child = fakeChild();
+    const spawn = () => ({ exited: Promise.reject(new Error('boom')), unref: () => {} });
+    killChildTree(child, true, 'win32', 'SIGTERM', spawn);
+    await Bun.sleep(20);
+    expect(child.signals).toEqual(['SIGKILL']);
+  });
+});
+
+describePosix('terminateChildProcess', () => {
+  test('ends a real child through the win32 fallback', async () => {
+    const child = spawnSleep();
+
+    expect(await terminateChildProcess(child, 3000, 'win32', fakeSpawn({ throws: true }))).toBe(true);
+    await child.exited;
+    expect(child.signalCode).toBe('SIGKILL');
+  });
+
+  test('an already-exited child answers true without signalling', async () => {
+    const child = Bun.spawn(['/bin/sh', '-c', 'exit 0'], { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' });
+    children.push(child);
+    await child.exited;
+
+    expect(await terminateChildProcess(child, 100, 'win32', fakeSpawn({ throws: true }))).toBe(true);
+  });
+
+  test('the posix branch signals the process group', async () => {
+    const child = spawnSleep();
+    expect(await terminateChildProcess(child, 3000, 'linux')).toBe(true);
+    await child.exited;
+    expect(child.signalCode).toBe('SIGKILL');
+  });
+});

package/src/cli/lib/restart-scope.js

@@ -0,0 +1,93 @@
+// Restart scope for `kabmo update`.
+//
+// Kept separate from the command so the rule is testable without a live server,
+// exactly as `stop-scope.js` is for `stop`. The rule is ownership: an update
+// replaces this package on disk, so the only instance it may restart is one it
+// started — and, crucially, the one it picks must be that instance rather than
+// whichever answers first.
+//
+// The bug this exists to prevent: picking the LOWEST PORT instead of the owned
+// one. `bun run dev` on 3000 beside the updated daemon on 3001 (a real layout
+// on this machine) made `update` select the dev server, classify it `direct`,
+// skip it, and leave the daemon serving the build that was just replaced.
+
+import { isCliManaged } from '@/server/lib/lifecycle/launch-mode';
+
+/**
+ * The instances an update restarts. `all` is the `--all` flag: every live
+ * instance is considered, and the caller still leaves the unmanaged ones alone.
+ *
+ * Without `--all`, every CLI-owned instance is a target, because every one of
+ * them is serving the build the update just replaced — the command's own
+ * contract is "the instances still serving the previous build (the ones the
+ * CLI started)", which is plural. `--all` widens the REPORT to the instances
+ * the CLI did not start; ownership, not the flag, decides what may be replaced.
+ *
+ * Only when nothing is owned does the first live instance fall through, so the
+ * unmanaged case is still reported rather than silently ignored.
+ */
+export function selectRestartTargets(instances, all) {
+  if (all) return instances;
+  const managed = instances.filter((entry) => isCliManaged(entry.launchMode));
+  return managed.length > 0 ? managed : instances.slice(0, 1);
+}
+
+/**
+ * The `serve` options that bring a stopped instance back the way it was found.
+ *
+ * Every field here comes from the INSTANCE, never from the argv of the command
+ * that is restarting it. `kabmo restart` and `kabmo update` are their
+ * own invocations: their options describe the command, and spreading them into
+ * `serve` is what silently dropped `--tray` and `--tls` from the replacement.
+ * An instance started with `serve --startup` (whose login entry runs
+ * `serve --foreground --tray`) therefore came back after every update with no
+ * icon, and a TLS instance came back answering cleartext on the port its
+ * browser had bookmarked as https.
+ *
+ * `foreground` is always false: the replacement is the detached daemon the CLI
+ * serves, whatever the original launch mode was — a `foreground` instance was
+ * held open by its launcher (launchd), which is gone by the time a restart is
+ * spawned, so reproducing `--foreground` here would tie the replacement to a
+ * terminal nobody is watching.
+ *
+ * `--tray`/`--tls` are ADD-ONLY: an explicit flag on the restarting command
+ * turns one on, and its absence never turns one off. `restart` has no way to
+ * say "explicitly no tray" (the parser defaults both to false), so reading the
+ * absence as an instruction would strip the icon from the instance the user
+ * asked to restart — the bug this helper exists to fix. Removing one is
+ * `stop` followed by `serve` without the flag.
+ */
+export function restartServeOptions(instance, options = {}) {
+  return {
+    ...options,
+    port: instance.port,
+    host: instance.host,
+    lan: instance.host === '0.0.0.0',
+    dev: instance.mode === 'dev',
+    prod: instance.mode === 'prod',
+    tray: instance.tray === true || options.tray === true,
+    tls: instance.tls === true || options.tls === true,
+    foreground: false,
+    all: false,
+  };
+}
+
+/**
+ * The warning a restart owes the user when it cannot carry the credential over.
+ *
+ * A self-restart hands the hashed credential to its replacement, so it keeps
+ * working. A MANUAL `kabmo restart` has nothing to hand over: the original
+ * server never stored the password (only an argon2 hash lived in its memory),
+ * so the replacement genuinely cannot require it. Before this, that restart
+ * came back with authentication silently DISABLED — measured: a run started with
+ * `--ui-password` answered `required: false` afterwards, i.e. an open console on
+ * a port the user had deliberately protected.
+ *
+ * `null` when there is nothing to say: an instance that ran without auth, or one
+ * whose replacement already received the payload.
+ */
+export function restartAuthWarning(instance, handoverPayload) {
+  if (instance.auth !== true || handoverPayload) return null;
+  return `The credential of the instance on port ${instance.port} cannot be recovered — it was never stored, so the replacement starts WITHOUT a password.`
+    + ' Start it again with --ui-password to restore it.';
+}

package/src/cli/lib/restart-scope.test.js

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { restartAuthWarning, restartServeOptions, selectRestartTargets } from '@/cli/lib/restart-scope.js';
+
+const devOn3000 = { port: 3000, pid: 11, launchMode: 'direct' };
+const daemonOn3001 = { port: 3001, pid: 12, launchMode: 'daemon' };
+const foregroundOn3002 = { port: 3002, pid: 13, launchMode: 'foreground' };
+
+describe('selectRestartTargets', () => {
+  // The reported bug: the lowest port won, which was a `bun run dev` the update
+  // must not touch — so the daemon holding the replaced build was never
+  // restarted and kept serving it.
+  test('picks the CLI-owned instance over a lower-port unmanaged one', () => {
+    expect(selectRestartTargets([devOn3000, daemonOn3001], false)).toEqual([daemonOn3001]);
+  });
+
+  // With no owned instance there is still something to report, so the command
+  // says why it is skipping rather than claiming nothing is running.
+  test('falls back to the first live instance when none is owned', () => {
+    expect(selectRestartTargets([devOn3000], false)).toEqual([devOn3000]);
+    expect(selectRestartTargets([], false)).toEqual([]);
+  });
+
+  test('takes every owned instance, since each one serves the replaced build', () => {
+    expect(selectRestartTargets([daemonOn3001, foregroundOn3002], false)).toEqual([daemonOn3001, foregroundOn3002]);
+  });
+
+  test('--all considers every instance, leaving the caller to skip the unmanaged', () => {
+    const all = [devOn3000, daemonOn3001, foregroundOn3002];
+    expect(selectRestartTargets(all, true)).toEqual(all);
+  });
+
+  test('an unreadable launch mode is not owned', () => {
+    const unknown = { port: 4000, pid: 99, launchMode: undefined };
+    expect(selectRestartTargets([unknown, daemonOn3001], false)).toEqual([daemonOn3001]);
+  });
+});
+
+describe('restartServeOptions', () => {
+  // The reported bug: a server started with `serve --startup` (whose login
+  // entry runs `serve --foreground --tray`) came back after an auto-update with
+  // NO tray icon. `restart` and `update` are separate invocations, so spreading
+  // their own options into `serve` silently dropped `--tray` (and `--tls`).
+  const trayInstance = { port: 3001, host: '0.0.0.0', mode: 'prod', launchMode: 'foreground', tray: true, tls: false };
+
+  test('reproduces the tray flag of the instance it replaces', () => {
+    expect(restartServeOptions(trayInstance).tray).toBe(true);
+  });
+
+  test('reproduces TLS, and a missing flag is false rather than inherited', () => {
+    expect(restartServeOptions({ ...trayInstance, tray: false, tls: true }).tls).toBe(true);
+    // An older record has no flags at all: the replacement must not claim them.
+    const legacy = { port: 3002, host: '127.0.0.1', mode: 'prod', launchMode: 'daemon' };
+    expect(restartServeOptions(legacy)).toMatchObject({ tray: false, tls: false });
+  });
+
+  test('the command line can add a flag but never remove one', () => {
+    // `restart --tray` is a real request to show an icon, so it is honoured.
+    // Its ABSENCE is not a request to hide one — the parser defaults the flag to
+    // false, so treating that as an instruction would strip the icon from the
+    // very instance the user asked to restart.
+    const plainDaemon = { port: 3003, host: '127.0.0.1', mode: 'prod', launchMode: 'daemon' };
+    expect(restartServeOptions(plainDaemon, { tray: true }).tray).toBe(true);
+    expect(restartServeOptions(trayInstance, { tray: false }).tray).toBe(true);
+    expect(restartServeOptions(plainDaemon, { tray: false }).tray).toBe(false);
+  });
+
+  test('the instance decides the address and the mode, not the command', () => {
+    // A restart of a different port must not be retargeted by the flag that
+    // scoped it, and a recorded prod instance stays prod.
+    const options = restartServeOptions({ ...trayInstance, tray: false }, { tray: true, tls: true, port: 9999 });
+    expect(options).toMatchObject({ port: 3001, host: '0.0.0.0', lan: true, prod: true });
+  });
+
+  test('the replacement is always the detached daemon', () => {
+    // A `foreground` instance was held open by launchd, which is gone by the
+    // time a restart is spawned; reproducing `--foreground` would tie the
+    // replacement to a terminal nobody is watching.
+    expect(restartServeOptions(trayInstance, { foreground: true, all: true }))
+      .toMatchObject({ foreground: false, all: false });
+  });
+
+  test('a dev instance asks for --dev and not --prod', () => {
+    const options = restartServeOptions({ ...trayInstance, mode: 'dev' });
+    expect(options.dev).toBe(true);
+    expect(options.prod).toBe(false);
+  });
+});
+
+describe('restartAuthWarning', () => {
+  // A MANUAL restart cannot carry the credential: the original server never
+  // stored the password (only an argon2 hash lived in its memory). Before this
+  // warning, that restart came back with authentication silently DISABLED —
+  // measured: a run started with `--ui-password` answered `required: false`.
+  const authInstance = { port: 3001, host: '127.0.0.1', mode: 'prod', launchMode: 'daemon', auth: true };
+
+  test('names the port and says the replacement starts open', () => {
+    const warning = restartAuthWarning(authInstance, null);
+    expect(warning).toContain('port 3001');
+    expect(warning).toContain('WITHOUT a password');
+    expect(warning).toContain('--ui-password');
+  });
+
+  test('is silent when the replacement already received the credential', () => {
+    // The self-restart path hands the hashed credential over, so auth survives
+    // and there is nothing to warn about.
+    expect(restartAuthWarning(authInstance, '{"passwordHash":"h"}')).toBeNull();
+  });
+
+  test('is silent for an instance that ran without authentication', () => {
+    expect(restartAuthWarning({ ...authInstance, auth: false }, null)).toBeNull();
+    expect(restartAuthWarning({ port: 3002, host: '127.0.0.1' }, null)).toBeNull();
+  });
+});