@hwip/cli 0.0.1 → 0.1.0

package/dist/listener-process.js

@@ -0,0 +1,470 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.awaitServiceListener = exports.LISTENER_SERVICE_START_MS = exports.startListenerDetached = exports.listenerLogSize = exports.startFailure = exports.LISTENER_START_GRACE_MS = exports.rotateListenerLogIfLarge = exports.resolveCliPath = exports.LISTENER_LAUNCH_ENV = exports.stopListener = exports.otherListenerPid = exports.isListenerPid = exports.otherListenerNote = exports.checkListenerPid = exports.isHwipListenerCommand = exports.commandOfPid = exports.clearStaleListenerRuntime = exports.clearListenerRuntime = exports.runningListenerWsUrl = exports.writeListenerRuntime = exports.runningListenerVersion = exports.runningListenerPid = exports.sleep = exports.LISTENER_LOG_FILE = exports.LISTENER_WS_URL_FILE = exports.LISTENER_VERSION_FILE = exports.LISTENER_PID_FILE = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const private_files_js_1 = require("./private-files.js");
+/**
+ * Process-level facts about the resident `hwip listener` daemon: where its
+ * PID/version stamps live, whether one is alive, how to stop it and how to
+ * respawn it detached.
+ *
+ * This lives OUTSIDE listener.ts on purpose. `wrapper.ts` (the `hwip cc` hot
+ * path) needs all of it, and importing listener.ts there would drag `ws` +
+ * the crypto stack into every agent launch. Same split as
+ * listener-device-id.ts — one small module both sides can read.
+ *
+ * Why a version stamp at all: `npm i -g @hwip/cli` replaces the package on
+ * disk but NOT the daemon already running from the old dist. That daemon
+ * keeps answering pushes (so chat looks fine) while silently ignoring every
+ * subtype added since it started — which is exactly how a pre-1.24 listener
+ * left the phone's live terminal spinning until the machine was rebooted.
+ * Stamping the version next to the PID makes that drift detectable.
+ */
+const HWIP_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.hwip');
+exports.LISTENER_PID_FILE = (0, node_path_1.join)(HWIP_DIR, 'listener.pid');
+/** CLI version the running daemon booted from. Absent ⇒ pre-stamp build. */
+exports.LISTENER_VERSION_FILE = (0, node_path_1.join)(HWIP_DIR, 'listener.version');
+/**
+ * The socket the running daemon actually connected to. A stamp rather than a
+ * line in listener.log, because the log rotates at 5MB and a long-lived daemon
+ * — exactly the one whose config edit has been outlived — loses its own startup
+ * line to that rotation, which would silently switch the staleness check off.
+ */
+exports.LISTENER_WS_URL_FILE = (0, node_path_1.join)(HWIP_DIR, 'listener.wsurl');
+exports.LISTENER_LOG_FILE = (0, node_path_1.join)(HWIP_DIR, 'listener.log');
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+exports.sleep = sleep;
+/**
+ * PID of the listener on record, or null when the file is missing or stale.
+ * Stale PID files (process gone) read as "no listener" so a crashed daemon
+ * never blocks the next autostart.
+ */
+const runningListenerPid = () => {
+    try {
+        const pid = Number((0, node_fs_1.readFileSync)(exports.LISTENER_PID_FILE, 'utf-8').trim());
+        if (!Number.isFinite(pid) || pid <= 0)
+            return null;
+        process.kill(pid, 0); // signal 0 = existence check, throws when gone
+        return pid;
+    }
+    catch {
+        return null;
+    }
+};
+exports.runningListenerPid = runningListenerPid;
+/**
+ * CLI version the running daemon started from, or null when unknown.
+ * null is meaningful: every build before the stamp existed predates the
+ * live-terminal protocol, so callers treat "unknown" as "stale".
+ */
+const runningListenerVersion = () => {
+    try {
+        return (0, node_fs_1.readFileSync)(exports.LISTENER_VERSION_FILE, 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.runningListenerVersion = runningListenerVersion;
+/** Claim the singleton slot for THIS process and stamp the version with it. */
+const writeListenerRuntime = (version, wsUrl) => {
+    (0, private_files_js_1.ensurePrivateDir)(HWIP_DIR);
+    (0, node_fs_1.writeFileSync)(exports.LISTENER_PID_FILE, String(process.pid));
+    (0, node_fs_1.writeFileSync)(exports.LISTENER_VERSION_FILE, version);
+    if (wsUrl)
+        (0, node_fs_1.writeFileSync)(exports.LISTENER_WS_URL_FILE, wsUrl);
+    for (const file of [exports.LISTENER_PID_FILE, exports.LISTENER_VERSION_FILE, ...(wsUrl ? [exports.LISTENER_WS_URL_FILE] : [])])
+        (0, private_files_js_1.handBackToSudoUser)(file);
+};
+exports.writeListenerRuntime = writeListenerRuntime;
+/** The socket the running daemon connected to, or null when it is unknown. */
+const runningListenerWsUrl = () => {
+    if ((0, exports.runningListenerPid)() === null)
+        return null;
+    try {
+        return (0, node_fs_1.readFileSync)(exports.LISTENER_WS_URL_FILE, 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.runningListenerWsUrl = runningListenerWsUrl;
+/**
+ * Drop the PID/version stamps, but only when they still name `pid` — a
+ * successor that already claimed the slot must not be trampled by a
+ * predecessor's exit handler.
+ */
+const clearListenerRuntime = (pid) => {
+    try {
+        if (!(0, node_fs_1.existsSync)(exports.LISTENER_PID_FILE))
+            return;
+        if (Number((0, node_fs_1.readFileSync)(exports.LISTENER_PID_FILE, 'utf-8').trim()) !== pid)
+            return;
+        (0, node_fs_1.unlinkSync)(exports.LISTENER_PID_FILE);
+        for (const stamp of [exports.LISTENER_VERSION_FILE, exports.LISTENER_WS_URL_FILE]) {
+            try {
+                (0, node_fs_1.unlinkSync)(stamp);
+            }
+            catch { /* best-effort — a missing stamp is already the desired state */ }
+        }
+    }
+    catch { /* best-effort */ }
+};
+exports.clearListenerRuntime = clearListenerRuntime;
+/**
+ * Drop stamps left behind by a daemon that died without running its exit
+ * handler (crash, SIGKILL, reboot-era leftovers). No-op while one is alive.
+ */
+const clearStaleListenerRuntime = () => {
+    if ((0, exports.runningListenerPid)() !== null)
+        return;
+    try {
+        (0, node_fs_1.unlinkSync)(exports.LISTENER_PID_FILE);
+    }
+    catch { /* nothing to clear */ }
+    try {
+        (0, node_fs_1.unlinkSync)(exports.LISTENER_VERSION_FILE);
+    }
+    catch { /* nothing to clear */ }
+};
+exports.clearStaleListenerRuntime = clearStaleListenerRuntime;
+const commandOfPid = (pid) => {
+    const result = (0, node_child_process_1.spawnSync)('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf-8', timeout: 2_000 });
+    if (result.error)
+        return { kind: 'unchecked', reason: result.error.message };
+    const command = result.stdout.trim();
+    if (result.status === 0 && command)
+        return { kind: 'running', command };
+    // A missing pid is a bare non-zero exit; anything on stderr is ps itself
+    // failing ("process id too large"), which says nothing about the pid.
+    const complaint = result.stderr.trim();
+    return complaint ? { kind: 'unchecked', reason: complaint } : { kind: 'gone' };
+};
+exports.commandOfPid = commandOfPid;
+/**
+ * True when a command line is hwip's listener daemon: the word before
+ * `listener` is hwip's own script — the bin shim (`…/hwip`), the published
+ * package's entry (`…/@hwip/cli/dist/cli.js`: global install, npx), or this
+ * CLI's own file (a dev checkout). Any other `…/cli.js listener` (Zeph's runs
+ * on the same machines), or a file that only sits under a `hwip*` directory,
+ * does not pass. Exported for tests, which pass `ownCliPath`.
+ */
+const isHwipListenerCommand = (command, ownCliPath = (0, exports.resolveCliPath)()) => {
+    const words = command.trim().split(/\s+/);
+    const at = words.indexOf('listener');
+    if (at < 1)
+        return false;
+    const script = words[at - 1];
+    // A shebang script shows up by its full path, so a bare `hwip` word is
+    // some other command (`grep hwip listener`), not the shim.
+    return script.endsWith('/hwip') || script.endsWith('/@hwip/cli/dist/cli.js') || script === ownCliPath;
+};
+exports.isHwipListenerCommand = isHwipListenerCommand;
+/**
+ * The pid file can outlive a crashed daemon and its pid be reused by any
+ * process, so a pid is only ours while its command line says so.
+ */
+const checkListenerPid = (pid, commandOf = exports.commandOfPid, isHwipScript = isHwipCliScript) => {
+    const found = commandOf(pid);
+    if (found.kind !== 'running')
+        return found;
+    if ((0, exports.isHwipListenerCommand)(found.command))
+        return { kind: 'ours' };
+    const script = listenerScriptOf(found.command);
+    if (script !== null && isHwipScript(script))
+        return { kind: 'other-listener', script };
+    return { kind: 'foreign', program: (0, node_path_1.basename)(found.command.split(/\s+/)[0]) };
+};
+exports.checkListenerPid = checkListenerPid;
+/**
+ * Whether a script belongs to a checkout of this CLI: the nearest
+ * package.json above it names `@hwip/cli`. That is what tells another hwip
+ * worktree's `dist/cli.js` from Zeph's, which has the same shape.
+ */
+const isHwipCliScript = (script) => {
+    for (let dir = (0, node_path_1.dirname)(script), up = 0; up < 3; dir = (0, node_path_1.dirname)(dir), up++) {
+        try {
+            return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, 'package.json'), 'utf-8')).name === '@hwip/cli';
+        }
+        catch { /* no package.json here: look one level up */ }
+    }
+    return false;
+};
+/** What every caller says about an `other-listener`. */
+const otherListenerNote = (pid, script) => `pid ${pid} is a hwip listener from another checkout (${script}) — left it running; stop it from there`;
+exports.otherListenerNote = otherListenerNote;
+/**
+ * Any `<script>.js listener` command line: hwip's own, or one from another
+ * checkout or worktree of it (`…/cli-wt-x/dist/cli.js listener`), which
+ * `isHwipListenerCommand` cannot vouch for. Zeph's listener has the same
+ * shape — deferring to it costs one start, a second hwip daemon costs every
+ * push answered twice.
+ */
+const listenerScriptOf = (command) => {
+    const words = command.trim().split(/\s+/);
+    const at = words.indexOf('listener');
+    return at >= 1 && /\.[cm]?[jt]s$/.test(words[at - 1]) ? words[at - 1] : null;
+};
+/**
+ * Whether the pid on record should be treated as a live listener: hwip's own
+ * or listener-shaped command line, or one `ps` could not check — two daemons
+ * answering the same pushes is the worse failure. `hwip verify` and the
+ * startup guard ask the same question.
+ */
+const isListenerPid = (pid, commandOf = exports.commandOfPid) => {
+    const found = commandOf(pid);
+    if (found.kind !== 'running')
+        return found.kind === 'unchecked';
+    return (0, exports.isHwipListenerCommand)(found.command) || listenerScriptOf(found.command) !== null;
+};
+exports.isListenerPid = isListenerPid;
+/**
+ * The pid of another hwip listener holding the singleton slot, or null. A pid
+ * the OS handed to an unrelated process is not a listener: deferring to it
+ * would end launchd's or `hwip cc`'s daemon with exit 0 and leave no listener
+ * at all, so its stamps are cleared and the slot is free.
+ */
+const otherListenerPid = (selfPid = process.pid, commandOf = exports.commandOfPid) => {
+    const pid = (0, exports.runningListenerPid)();
+    if (pid === null || pid === selfPid)
+        return null;
+    if ((0, exports.isListenerPid)(pid, commandOf))
+        return pid;
+    (0, exports.clearListenerRuntime)(pid);
+    return null;
+};
+exports.otherListenerPid = otherListenerPid;
+/**
+ * Stop the daemon and wait for the process to actually go away — but only a
+ * process that is still hwip's listener (`checkListenerPid`); anything else is
+ * left alone and reported, and a pid file pointing at a stranger is cleared.
+ * SIGTERM first so its exit handler clears the stamps, SIGKILL once the grace
+ * window expires.
+ *
+ * Waiting matters: the caller's next move is spawning a replacement, and two
+ * live daemons on one machine both answer the same pushes.
+ */
+const stopListener = async (pid, commandOf = exports.commandOfPid, timeoutMs = 3_000) => {
+    const check = (0, exports.checkListenerPid)(pid, commandOf);
+    // The stamps name a daemon that is gone; left in place they would keep
+    // the next daemon's singleton guard deferring to a stranger.
+    if (check.kind === 'foreign')
+        (0, exports.clearListenerRuntime)(pid);
+    if (check.kind !== 'ours')
+        return check;
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return { kind: 'gone' };
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await (0, exports.sleep)(50);
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            (0, exports.clearListenerRuntime)(pid);
+            return { kind: 'stopped' };
+        }
+    }
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { /* raced us to exit */ }
+    (0, exports.clearListenerRuntime)(pid);
+    return { kind: 'killed' };
+};
+exports.stopListener = stopListener;
+/**
+ * Set by the listener on the `hwip <agent> --detach` it runs for a schedule. That child is the listener's own: when its
+ * build is newer than the running listener's (after an upgrade) `ensureListenerRunning` would restart the listener, and
+ * the restart would end the launch's own parent. With this set it leaves the listener alone, and removes the variable from
+ * its environment so that nothing the launch starts after it (the tmux server, the agent) inherits it.
+ */
+exports.LISTENER_LAUNCH_ENV = 'HWIP_LISTENER_LAUNCH';
+/**
+ * Path to the running cli.js entry. wrapper.js/listener.js sit next to cli.js
+ * in dist/, so __dirname resolves it directly — independent of how the user
+ * invoked us.
+ *
+ * `process.argv[1]` is unreliable here: when `hwip` runs via the npm-installed
+ * bin shim (`/usr/local/bin/hwip` → cli.js via a wrapper script), argv[1] is
+ * the shim path (`.../bin/hwip`), NOT `cli.js`. That made the original
+ * `/cli\.(js|ts|mjs|cjs)$/` check silently reject the entry and the autospawn
+ * never fired — the bug only surfaced once the user switched to the global
+ * npm install.
+ *
+ * Fall back to argv[1] only when the __dirname-relative file doesn't exist
+ * (some packaging where dist layout differs).
+ */
+const resolveCliPath = () => {
+    const local = (0, node_path_1.join)(__dirname, 'cli.js');
+    if ((0, node_fs_1.existsSync)(local))
+        return local;
+    const entry = process.argv[1];
+    if (entry && /cli\.(js|ts|mjs|cjs)$/.test(entry))
+        return entry;
+    return null;
+};
+exports.resolveCliPath = resolveCliPath;
+/**
+ * Rotate the listener log once it grows past 5 MB. The daemon runs for days
+ * and writes 2-3 lines per 5-s cycle, so without rotation the file climbs
+ * into the tens of megabytes. Keep the previous window under `.old`.
+ *
+ * Copy-truncate rather than rename, because the writer is not always ours.
+ * Under the login-time LaunchAgent, launchd opens `StandardOutPath` itself
+ * and holds that fd for the life of the job: a rename moves the directory
+ * entry and leaves launchd appending to the very same inode, now called
+ * `.old`. The log the user tails would never shrink. Emptying the file in
+ * place keeps the inode — and the fd — valid.
+ */
+const LISTENER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+const rotateListenerLogIfLarge = () => {
+    try {
+        if (!(0, node_fs_1.existsSync)(exports.LISTENER_LOG_FILE))
+            return;
+        if ((0, node_fs_1.statSync)(exports.LISTENER_LOG_FILE).size <= LISTENER_LOG_MAX_BYTES)
+            return;
+        (0, node_fs_1.copyFileSync)(exports.LISTENER_LOG_FILE, exports.LISTENER_LOG_FILE + '.old');
+        (0, node_fs_1.truncateSync)(exports.LISTENER_LOG_FILE, 0);
+    }
+    catch { /* best-effort */ }
+};
+exports.rotateListenerLogIfLarge = rotateListenerLogIfLarge;
+/**
+ * Launch `hwip listener` detached, with output appended to the listener log
+ * so nothing is lost once we let go of it. Null when the cli entry couldn't
+ * be resolved or the spawn failed.
+ */
+const spawnDetachedChild = () => {
+    const cliPath = (0, exports.resolveCliPath)();
+    if (!cliPath)
+        return null;
+    try {
+        // The log can quote what the listener was handed; only its owner reads it.
+        (0, private_files_js_1.ensurePrivateDir)(HWIP_DIR);
+        (0, private_files_js_1.ensurePrivateFile)(exports.LISTENER_LOG_FILE);
+        const out = (0, node_fs_1.openSync)(exports.LISTENER_LOG_FILE, 'a');
+        const child = (0, node_child_process_1.spawn)(process.execPath, [cliPath, 'listener'], {
+            detached: true,
+            stdio: ['ignore', out, out],
+            env: { ...process.env, HWIP_LISTENER_AUTOSTART: '1' },
+        });
+        // An async spawn failure (EACCES, EAGAIN) arrives as 'error' with no
+        // 'exit'; unhandled, it would crash `hwip cc` mid-wait.
+        child.once('error', () => { });
+        child.unref();
+        return child;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * How long a daemon `hwip cc` just spawned gets to fail. The fast deaths — no
+ * key, no tmux, no socket URL — come before the daemon writes its pid file;
+ * a rejected key closes the first socket within about a second.
+ */
+exports.LISTENER_START_GRACE_MS = 1_500;
+/** Why a start failed, in one line for the user; null when a listener is up. */
+const startFailure = (started) => {
+    switch (started.kind) {
+        case 'running':
+        case 'deferred':
+            return null;
+        case 'not-spawned':
+            return 'it could not be launched';
+        case 'died':
+            return started.line ?? (started.code === null ? 'it was killed by a signal' : `it exited with code ${started.code}`);
+        case 'not-up':
+            return started.line ?? 'it is not running and logged nothing';
+    }
+};
+exports.startFailure = startFailure;
+/** Where the log ends now: what a start writes after this is that start's. */
+const listenerLogSize = () => {
+    try {
+        return (0, node_fs_1.statSync)(exports.LISTENER_LOG_FILE).size;
+    }
+    catch {
+        return 0;
+    }
+};
+exports.listenerLogSize = listenerLogSize;
+/** The last non-blank line written to the log past `offset` (from the start if it shrank). */
+const lastLogLineSince = (offset) => {
+    try {
+        const log = (0, node_fs_1.readFileSync)(exports.LISTENER_LOG_FILE);
+        const lines = log.subarray(log.length < offset ? 0 : offset).toString('utf-8').split('\n');
+        return lines.map((line) => line.trim()).filter(Boolean).pop() ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Spawn the daemon and watch it through the grace window. A daemon that dies
+ * on a missing key, a missing tmux or a rejected key only says so in the log,
+ * so `hwip cc` used to print "listener autostarted" over a dead one and the
+ * phone silently lost control.
+ */
+const startListenerDetached = async (spawnChild = spawnDetachedChild, graceMs = exports.LISTENER_START_GRACE_MS) => {
+    const offset = (0, exports.listenerLogSize)();
+    const child = spawnChild();
+    if (!child)
+        return { kind: 'not-spawned' };
+    const code = await new Promise((settle) => {
+        if (child.exitCode !== null)
+            return settle(child.exitCode);
+        const timer = setTimeout(() => settle(undefined), graceMs);
+        child.once('exit', (exitCode) => {
+            clearTimeout(timer);
+            settle(exitCode);
+        });
+        // A failed spawn (missing node, EACCES) emits 'error' and never 'exit'.
+        child.once('error', () => {
+            clearTimeout(timer);
+            settle('spawn-error');
+        });
+    });
+    if (code === 'spawn-error')
+        return { kind: 'not-spawned' };
+    if (code === undefined)
+        return { kind: 'running' };
+    if (code === 0)
+        return { kind: 'deferred' };
+    return { kind: 'died', code, line: lastLogLineSince(offset) };
+};
+exports.startListenerDetached = startListenerDetached;
+/** How long launchd gets to bring a kickstarted daemon as far as its pid file. */
+exports.LISTENER_SERVICE_START_MS = 5_000;
+const SERVICE_POLL_MS = 250;
+/**
+ * After `launchctl kickstart`: launchd starts the daemon, so there is no child
+ * to watch — only the pid file it writes once its key, tmux and socket URL
+ * check out, and the log it says why in. A daemon that dies there is restarted
+ * by launchd on a loop, and `hwip cc` used to report it "started". Waits for a
+ * pid other than `previousPid` (the daemon `kickstart -k` replaced may still
+ * be shutting down), then for the grace window a rejected key needs.
+ */
+const awaitServiceListener = async (logOffset, previousPid, deps = { sleep: exports.sleep, runningPid: exports.runningListenerPid }, graceMs = exports.LISTENER_START_GRACE_MS, startMs = exports.LISTENER_SERVICE_START_MS) => {
+    const up = () => {
+        const pid = deps.runningPid();
+        return pid !== null && pid !== previousPid;
+    };
+    const notUp = () => ({ kind: 'not-up', line: lastLogLineSince(logOffset) });
+    for (let waited = 0; !up(); waited += SERVICE_POLL_MS) {
+        if (waited >= startMs)
+            return notUp();
+        await deps.sleep(SERVICE_POLL_MS);
+    }
+    await deps.sleep(graceMs);
+    return up() ? { kind: 'running' } : notUp();
+};
+exports.awaitServiceListener = awaitServiceListener;