@jobshimo/browser-link 0.40.0 → 0.41.0

package/dist/lifecycle/election.js

@@ -0,0 +1,187 @@
+import { request } from 'node:http';
+import { platform } from 'node:os';
+import { compareSemver } from '../utils/semver.js';
+import { defaultExecFile } from './processes.js';
+/** The pure decision table (a)/(b)/(c) above. */
+export function decideElection(input) {
+    const { probe } = input;
+    if (probe.kind === 'version') {
+        const remote = probe.info.version;
+        if (compareSemver(remote, input.local) < 0) {
+            return {
+                decision: 'take-over',
+                pid: probe.info.pid,
+                reason: `running primary ${remote} is older than ${input.local}`,
+            };
+        }
+        return {
+            decision: 'defer',
+            pid: probe.info.pid,
+            reason: `running primary ${remote} is not older than ${input.local}`,
+        };
+    }
+    if (probe.kind === 'unreachable') {
+        return { decision: 'defer', pid: input.ownerPid, reason: 'port holder does not answer HTTP' };
+    }
+    const { ownerPid, ownerStartedAt, installedCodeMtime } = input;
+    if (ownerPid === null || ownerStartedAt === null || installedCodeMtime === null) {
+        return {
+            decision: 'defer',
+            pid: ownerPid,
+            reason: 'primary has no /version and its start time cannot be compared',
+        };
+    }
+    if (ownerStartedAt < installedCodeMtime) {
+        return {
+            decision: 'take-over',
+            pid: ownerPid,
+            reason: 'primary has no /version and started before the installed code was written',
+        };
+    }
+    return {
+        decision: 'defer',
+        pid: ownerPid,
+        reason: 'primary has no /version but started after the installed code was written',
+    };
+}
+/** Probe, decide and, on take-over, step the owner down. The caller binds
+ * afterwards (see `retryBind`). A step-down that fails turns into `defer`. */
+export async function runElection(deps) {
+    const probe = await deps.probe();
+    let ownerPid = null;
+    let ownerStartedAt = null;
+    let installedCodeMtime = null;
+    if (probe.kind === 'no-endpoint') {
+        ownerPid = deps.findOwnerPid();
+        ownerStartedAt = ownerPid === null ? null : deps.processStartTime(ownerPid);
+        installedCodeMtime = deps.installedCodeMtime();
+    }
+    const outcome = decideElection({
+        local: deps.localVersion,
+        probe,
+        ownerPid,
+        ownerStartedAt,
+        installedCodeMtime,
+    });
+    if (outcome.decision !== 'take-over' || outcome.pid === null)
+        return outcome;
+    try {
+        await deps.stepDown(outcome.pid);
+        return outcome;
+    }
+    catch (err) {
+        return {
+            decision: 'defer',
+            pid: outcome.pid,
+            reason: `step-down of PID ${outcome.pid} failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+function isVersionInfo(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return (typeof o.name === 'string' &&
+        typeof o.version === 'string' &&
+        typeof o.pid === 'number' &&
+        Number.isInteger(o.pid) &&
+        o.pid > 0 &&
+        typeof o.startedAt === 'string' &&
+        (o.installedVersion === null || typeof o.installedVersion === 'string'));
+}
+/** `GET http://<host>:<port>/version`. Never rejects. */
+export function probeVersion(port, timeoutMs = 1000, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (probe) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(probe);
+        };
+        const req = request({ host, port, path: '/version', method: 'GET', timeout: timeoutMs }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    done({ kind: 'no-endpoint' });
+                    return;
+                }
+                try {
+                    const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    done(isVersionInfo(body) ? { kind: 'version', info: body } : { kind: 'no-endpoint' });
+                }
+                catch {
+                    done({ kind: 'no-endpoint' });
+                }
+            });
+            res.on('error', () => {
+                done({ kind: 'no-endpoint' });
+            });
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            done({ kind: 'unreachable' });
+        });
+        req.on('error', () => {
+            done({ kind: 'unreachable' });
+        });
+        req.end();
+    });
+}
+const sleepReal = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Run `bind` until it succeeds, retrying only errors `isRetryable` accepts
+ * (a busy port), at most `attempts` times with `delayMs` between tries. */
+export async function retryBind(bind, opts) {
+    const sleep = opts.sleep ?? sleepReal;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await bind();
+        }
+        catch (err) {
+            if (!opts.isRetryable(err) || attempt >= opts.attempts)
+                throw err;
+            await sleep(opts.delayMs);
+        }
+    }
+}
+/** Unix grace period between SIGTERM and SIGKILL. */
+export const STEP_DOWN_GRACE_MS = 3000;
+const STEP_DOWN_POLL_MS = 100;
+function isAliveReal(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists but belongs to someone else.
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Stop a process: Windows `taskkill /PID n /F`; Unix `SIGTERM`, wait up to
+ * 3 s for it to exit, then `SIGKILL`. Throws when the kill itself fails.
+ */
+export async function stepDownProcess(pid, deps = {}) {
+    const os = deps.os ?? platform();
+    if (os === 'win32') {
+        (deps.execFile ?? defaultExecFile)('taskkill', ['/PID', String(pid), '/F'], {
+            timeout: 5000,
+        });
+        return;
+    }
+    const kill = deps.kill ?? ((p, s) => void process.kill(p, s));
+    const isAlive = deps.isAlive ?? isAliveReal;
+    const sleep = deps.sleep ?? sleepReal;
+    const now = deps.now ?? Date.now;
+    kill(pid, 'SIGTERM');
+    const deadline = now() + STEP_DOWN_GRACE_MS;
+    while (isAlive(pid)) {
+        if (now() >= deadline) {
+            kill(pid, 'SIGKILL');
+            return;
+        }
+        await sleep(STEP_DOWN_POLL_MS);
+    }
+}
+//# sourceMappingURL=election.js.map

package/dist/lifecycle/election.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"election.js","sourceRoot":"","sources":["../../src/lifecycle/election.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/processes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Process enumeration for the lifecycle features: `browser-link stop`
+ * (kill every live bridge, not only the port owner), `doctor` (list them)
+ * and the primary election (when did the port owner start?).
+ *
+ * Every OS call goes through an injectable `ExecFileLike`, the same
+ * dependency-injection pattern `auth/silent-debugger.ts` uses, but
+ * synchronous: `runFreePort` is synchronous and consumed as such by the CLI,
+ * the TUI and `self-update`. Nothing in this module throws: a failed or
+ * unparseable listing degrades to "no processes" / `null`.
+ *
+ * Windows uses `Get-CimInstance Win32_Process` (never `wmic`: deprecated and
+ * absent on newer Windows 11 installs). Unix uses BSD-style `ps -axo`,
+ * accepted by both macOS and procps.
+ */
+/** `execFileSync`-shaped primitive: argv array, no shell, stdout as text. */
+export type ExecFileLike = (file: string, args: readonly string[], options: {
+    timeout: number;
+}) => string;
+/** One row of the OS process table. `startedAt` is epoch milliseconds, or
+ * `null` when the OS did not report a usable start time. */
+export interface ProcessEntry {
+    pid: number;
+    ppid: number;
+    startedAt: number | null;
+    command: string;
+}
+export declare const defaultExecFile: ExecFileLike;
+/**
+ * Parse a process start time in any of the forms the OS tools print:
+ * PowerShell 5.1's JSON `/Date(ms)/`, ISO 8601 (PowerShell 7 JSON,
+ * `ToString('o')`), a WMI datetime `yyyyMMddHHmmss.ffffff±UUU` (offset in
+ * minutes) and `ps`'s `lstart` (`Mon Nov  9 02:17:44 2026`, local time).
+ */
+export declare function parseProcessTime(raw: string): number | null;
+/** Parse `Get-CimInstance … | ConvertTo-Json -Compress`. One process comes
+ * out as a bare object, several as an array; both are accepted. */
+export declare function parseWindowsProcessList(stdout: string): ProcessEntry[];
+/** Parse `ps -axo pid=,ppid=,lstart=,command=` (C locale). */
+export declare function parseUnixProcessList(stdout: string): ProcessEntry[];
+/** The whole process table, or `[]` when it cannot be read. */
+export declare function listProcesses(os?: NodeJS.Platform, exec?: ExecFileLike): ProcessEntry[];
+/** Start time of one process (epoch ms), or `null` when unknown. */
+export declare function readProcessStartTime(pid: number, opts?: {
+    os?: NodeJS.Platform;
+    exec?: ExecFileLike;
+}): number | null;
+/**
+ * Whether a command line runs this package, and with which subcommand
+ * (`null` = none, i.e. the MCP server or the TUI). Only the script argument
+ * counts (the first non-flag argument after the runtime, or the package
+ * spec after npm's `npx-cli.js`), so a process that merely mentions a
+ * browser-link path as an option value is never matched.
+ */
+export declare function matchBrowserLinkCommand(command: string): {
+    subcommand: string | null;
+} | null;
+/** Live browser-link bridges in `list`, excluding `selfPid`, its ancestor
+ * chain (the shell or client that launched it) and non-bridge commands. */
+export declare function findBridgeProcesses(list: readonly ProcessEntry[], selfPid: number): ProcessEntry[];
+export declare function listBridgeProcesses(opts?: {
+    os?: NodeJS.Platform;
+    exec?: ExecFileLike;
+    selfPid?: number;
+}): ProcessEntry[];
+/** Short, display-only form: runtime name, `browser-link`, then arguments. */
+export declare function shortCommand(command: string, max?: number): string;

package/dist/lifecycle/processes.js

@@ -0,0 +1,239 @@
+import { execFileSync } from 'node:child_process';
+import { platform } from 'node:os';
+/** WMI cold starts are slow: same budget `silent-debugger.ts` documents. */
+const LIST_TIMEOUT_MS = 5000;
+export const defaultExecFile = (file, args, options) => execFileSync(file, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    windowsHide: true,
+    timeout: options.timeout,
+    // `ps` prints lstart in the C locale only when told so.
+    env: { ...process.env, LC_ALL: 'C' },
+});
+/**
+ * Parse a process start time in any of the forms the OS tools print:
+ * PowerShell 5.1's JSON `/Date(ms)/`, ISO 8601 (PowerShell 7 JSON,
+ * `ToString('o')`), a WMI datetime `yyyyMMddHHmmss.ffffff±UUU` (offset in
+ * minutes) and `ps`'s `lstart` (`Mon Nov  9 02:17:44 2026`, local time).
+ */
+export function parseProcessTime(raw) {
+    const text = raw.trim();
+    if (text.length === 0)
+        return null;
+    const msDate = /^\/Date\((-?\d+)\)\/$/.exec(text);
+    if (msDate)
+        return Number(msDate[1]);
+    const wmi = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{3})\d*([+-])(\d{3})$/.exec(text);
+    if (wmi) {
+        const [, y, mo, d, h, mi, s, ms, sign, off] = wmi;
+        const utc = Date.UTC(+y, +mo - 1, +d, +h, +mi, +s, +ms);
+        const offsetMs = Number(off) * 60_000 * (sign === '-' ? -1 : 1);
+        return utc - offsetMs;
+    }
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/** Parse `Get-CimInstance … | ConvertTo-Json -Compress`. One process comes
+ * out as a bare object, several as an array; both are accepted. */
+export function parseWindowsProcessList(stdout) {
+    let data;
+    try {
+        data = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    const rows = (Array.isArray(data) ? data : [data]);
+    const out = [];
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const { ProcessId, ParentProcessId, CreationDate, CommandLine } = row;
+        const pid = Number(ProcessId);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        const ppid = Number(ParentProcessId);
+        out.push({
+            pid,
+            ppid: Number.isInteger(ppid) ? ppid : 0,
+            startedAt: typeof CreationDate === 'string' ? parseProcessTime(CreationDate) : null,
+            command: typeof CommandLine === 'string' ? CommandLine.trim() : '',
+        });
+    }
+    return out;
+}
+const UNIX_ROW = /^\s*(\d+)\s+(\d+)\s+(\w{3}\s+\w{3}\s+\d{1,2}\s+\d{1,2}:\d{2}:\d{2}\s+\d{4})\s+(.*)$/;
+/** Parse `ps -axo pid=,ppid=,lstart=,command=` (C locale). */
+export function parseUnixProcessList(stdout) {
+    const out = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const m = UNIX_ROW.exec(line);
+        if (!m)
+            continue;
+        out.push({
+            pid: Number(m[1]),
+            ppid: Number(m[2]),
+            startedAt: parseProcessTime(m[3]),
+            command: m[4].trim(),
+        });
+    }
+    return out;
+}
+const WINDOWS_LIST_SCRIPT = 'Get-CimInstance Win32_Process | ' +
+    'Select-Object ProcessId, ParentProcessId, CreationDate, CommandLine | ' +
+    'ConvertTo-Json -Compress';
+function powershell(script) {
+    return ['powershell', ['-NoProfile', '-NonInteractive', '-Command', script]];
+}
+/** The whole process table, or `[]` when it cannot be read. */
+export function listProcesses(os = platform(), exec = defaultExecFile) {
+    try {
+        if (os === 'win32') {
+            const [file, args] = powershell(WINDOWS_LIST_SCRIPT);
+            return parseWindowsProcessList(exec(file, args, { timeout: LIST_TIMEOUT_MS }));
+        }
+        return parseUnixProcessList(exec('ps', ['-axo', 'pid=,ppid=,lstart=,command='], { timeout: LIST_TIMEOUT_MS }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Start time of one process (epoch ms), or `null` when unknown. */
+export function readProcessStartTime(pid, opts = {}) {
+    const os = opts.os ?? platform();
+    const exec = opts.exec ?? defaultExecFile;
+    try {
+        if (os === 'win32') {
+            const [file, args] = powershell(`Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}' | ` +
+                `Select-Object -ExpandProperty CreationDate | ` +
+                `ForEach-Object { $_.ToUniversalTime().ToString('o') }`);
+            return parseProcessTime(exec(file, args, { timeout: LIST_TIMEOUT_MS }));
+        }
+        return parseProcessTime(exec('ps', ['-o', 'lstart=', '-p', String(pid)], { timeout: LIST_TIMEOUT_MS }));
+    }
+    catch {
+        return null;
+    }
+}
+/** Split a command line into arguments. Double quotes group (Windows
+ * command lines quote paths with spaces); backslashes stay literal. */
+function tokenize(command) {
+    const tokens = [];
+    let current = '';
+    let inQuotes = false;
+    let hasToken = false;
+    for (const ch of command) {
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            hasToken = true;
+            continue;
+        }
+        if (!inQuotes && /\s/.test(ch)) {
+            if (hasToken)
+                tokens.push(current);
+            current = '';
+            hasToken = false;
+            continue;
+        }
+        current += ch;
+        hasToken = true;
+    }
+    if (hasToken)
+        tokens.push(current);
+    return tokens;
+}
+function normalise(token) {
+    return token.replace(/\\+/g, '/').toLowerCase();
+}
+function basename(token) {
+    const n = normalise(token);
+    return n.slice(n.lastIndexOf('/') + 1);
+}
+/** Runtimes a browser-link process runs under. */
+const RUNTIMES = new Set(['node', 'node.exe', 'nodejs', 'bun', 'bun.exe']);
+/** npm's own entry scripts: the package spec is a later argument. */
+const NPM_ENTRIES = new Set(['npx-cli.js', 'npm-cli.js']);
+function isBrowserLinkEntry(token) {
+    const n = normalise(token);
+    if (n.includes('@jobshimo/browser-link'))
+        return true;
+    if (n.endsWith('browser-link/dist/cli.js'))
+        return true;
+    // The global bin shim (a symlink on Unix): `node /usr/local/bin/browser-link`.
+    const base = basename(token);
+    return n.includes('/') && (base === 'browser-link' || base === 'browser-link.js');
+}
+/**
+ * Whether a command line runs this package, and with which subcommand
+ * (`null` = none, i.e. the MCP server or the TUI). Only the script argument
+ * counts (the first non-flag argument after the runtime, or the package
+ * spec after npm's `npx-cli.js`), so a process that merely mentions a
+ * browser-link path as an option value is never matched.
+ */
+export function matchBrowserLinkCommand(command) {
+    const tokens = tokenize(command);
+    if (tokens.length < 2 || !RUNTIMES.has(basename(tokens[0])))
+        return null;
+    let i = 1;
+    while (i < tokens.length && tokens[i].startsWith('-'))
+        i += 1;
+    if (i >= tokens.length)
+        return null;
+    if (NPM_ENTRIES.has(basename(tokens[i]))) {
+        i += 1;
+        while (i < tokens.length && (tokens[i].startsWith('-') || tokens[i] === 'exec'))
+            i += 1;
+        if (i >= tokens.length)
+            return null;
+    }
+    if (!isBrowserLinkEntry(tokens[i]))
+        return null;
+    return { subcommand: tokens[i + 1] ?? null };
+}
+/** Subcommands that run the bridge (see `cli.ts`'s dispatch switch: only a
+ * bare invocation and `start` call `runServer`). Every other subcommand
+ * (`stop`, `doctor`, `version`, `help`, `about`, `config`, `map`,
+ * `instructions`, `activity`, `self-update`, …) is a short-lived command
+ * that `stop` must never kill. */
+function isBridgeSubcommand(subcommand) {
+    return subcommand === null || subcommand === 'start';
+}
+/** `selfPid` and every ancestor reachable through `ppid` in `list`. */
+function selfAndAncestors(list, selfPid) {
+    const byPid = new Map(list.map((p) => [p.pid, p]));
+    const out = new Set();
+    let pid = selfPid;
+    while (pid !== undefined && pid > 0 && !out.has(pid)) {
+        out.add(pid);
+        pid = byPid.get(pid)?.ppid;
+    }
+    return out;
+}
+/** Live browser-link bridges in `list`, excluding `selfPid`, its ancestor
+ * chain (the shell or client that launched it) and non-bridge commands. */
+export function findBridgeProcesses(list, selfPid) {
+    const excluded = selfAndAncestors(list, selfPid);
+    return list.filter((p) => {
+        if (excluded.has(p.pid))
+            return false;
+        const match = matchBrowserLinkCommand(p.command);
+        return match !== null && isBridgeSubcommand(match.subcommand);
+    });
+}
+export function listBridgeProcesses(opts = {}) {
+    return findBridgeProcesses(listProcesses(opts.os, opts.exec), opts.selfPid ?? process.pid);
+}
+/** Short, display-only form: runtime name, `browser-link`, then arguments. */
+export function shortCommand(command, max = 80) {
+    const tokens = tokenize(command);
+    if (tokens.length === 0)
+        return '';
+    const parts = tokens.map((t, i) => {
+        if (i === 0)
+            return basename(t).replace(/\.exe$/, '');
+        return isBrowserLinkEntry(t) ? 'browser-link' : t;
+    });
+    const text = parts.join(' ');
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+//# sourceMappingURL=processes.js.map

package/dist/lifecycle/processes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processes.js","sourceRoot":"","sources":["../../src/lifecycle/processes.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/repair.d.ts

@@ -0,0 +1,48 @@
+import type { BridgeRepairMessage, ServerToExtension } from '../messages.js';
+/**
+ * Popup "Repair connection", server side (S4).
+ *
+ * On `bridge.repair` the bridge answers first, then this process restarts
+ * itself on the installed code: spawn the installed CLI detached, terminate
+ * every extension socket uncleanly (`ws.terminate()`, which the extension's
+ * auto-reconnect treats as involuntary), stop IPC (proxies get
+ * `primary-closing`) and exit 0. The child wins the port through the
+ * election's bind retries, and the extension reconnects to it by itself.
+ *
+ * The policy is pure; `server.ts` injects the real spawn/terminate/exit.
+ */
+export interface RepairDeps {
+    /** `process.execPath`. */
+    execPath: string;
+    /** The installed `dist/cli.js` (same file the process started from). */
+    cliPath: string;
+    spawn: (command: string, args: string[], options: {
+        detached: true;
+        stdio: 'ignore';
+        windowsHide: true;
+    }) => {
+        unref(): void;
+    };
+    terminateSockets: () => void;
+    stopIpc: () => Promise<void>;
+    exit: (code: number) => void;
+    /** Waits long enough for the ack frame to be flushed to the socket. */
+    delay: (ms: number) => Promise<void>;
+    log?: (msg: string) => void;
+}
+/** Time given to the `bridge.repair.result` frame before sockets die. */
+export declare const REPAIR_FLUSH_DELAY_MS = 150;
+export interface RepairController {
+    /** Start the restart (once). Returns whether it is (now) in progress. */
+    start(): boolean;
+    /** Settles when the current restart attempt finished (tests). */
+    readonly done: Promise<void>;
+}
+export declare function createRepairController(deps: RepairDeps): RepairController;
+/**
+ * Answer one `bridge.repair` frame: the ack goes out BEFORE the repair
+ * starts, so the popup learns the outcome even though its socket is about to
+ * be terminated. `startRepair` is undefined in a process that cannot repair
+ * itself (tests, a bridge started without the wiring).
+ */
+export declare function answerRepairRequest(msg: BridgeRepairMessage, send: (reply: ServerToExtension) => void, startRepair: (() => boolean) | undefined): void;

package/dist/lifecycle/repair.js

@@ -0,0 +1,67 @@
+/** Time given to the `bridge.repair.result` frame before sockets die. */
+export const REPAIR_FLUSH_DELAY_MS = 150;
+export function createRepairController(deps) {
+    let inProgress = false;
+    let done = Promise.resolve();
+    const run = async () => {
+        await deps.delay(REPAIR_FLUSH_DELAY_MS);
+        try {
+            deps
+                .spawn(deps.execPath, [deps.cliPath], {
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: true,
+            })
+                .unref();
+        }
+        catch (err) {
+            // Without a successor, exiting would leave no server at all: keep
+            // serving and let the user fall back to `browser-link stop`.
+            inProgress = false;
+            deps.log?.(`Repair: could not start the installed server (${err instanceof Error ? err.message : String(err)}); still serving.`);
+            return;
+        }
+        deps.log?.('Repair: installed server started; handing over the port.');
+        deps.terminateSockets();
+        try {
+            await deps.stopIpc();
+        }
+        catch {
+            /* already closed; exiting anyway */
+        }
+        deps.exit(0);
+    };
+    return {
+        start() {
+            if (inProgress)
+                return true;
+            inProgress = true;
+            done = run();
+            return true;
+        },
+        get done() {
+            return done;
+        },
+    };
+}
+/**
+ * Answer one `bridge.repair` frame: the ack goes out BEFORE the repair
+ * starts, so the popup learns the outcome even though its socket is about to
+ * be terminated. `startRepair` is undefined in a process that cannot repair
+ * itself (tests, a bridge started without the wiring).
+ */
+export function answerRepairRequest(msg, send, startRepair) {
+    const requestId = typeof msg.request_id === 'string' ? msg.request_id : '';
+    if (!startRepair) {
+        send({
+            kind: 'bridge.repair.result',
+            request_id: requestId,
+            ok: false,
+            error: 'repair is not available in this server process',
+        });
+        return;
+    }
+    send({ kind: 'bridge.repair.result', request_id: requestId, ok: true, action: 'restarting' });
+    startRepair();
+}
+//# sourceMappingURL=repair.js.map

package/dist/lifecycle/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../../src/lifecycle/repair.ts"],"names":[],"mappings":"AAiCA,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AASzC,MAAM,UAAU,sBAAsB,CAAC,IAAgB;IACrD,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE5C,MAAM,GAAG,GAAG,KAAK,IAAmB,EAAE;QACpC,MAAM,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,IAAI;iBACD,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;gBACpC,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,QAAQ;gBACf,WAAW,EAAE,IAAI;aAClB,CAAC;iBACD,KAAK,EAAE,CAAC;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,kEAAkE;YAClE,6DAA6D;YAC7D,UAAU,GAAG,KAAK,CAAC;YACnB,IAAI,CAAC,GAAG,EAAE,CACR,iDAAiD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,mBAAmB,CACrH,CAAC;YACF,OAAO;QACT,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAC,0DAA0D,CAAC,CAAC;QACvE,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,KAAK;YACH,IAAI,UAAU;gBAAE,OAAO,IAAI,CAAC;YAC5B,UAAU,GAAG,IAAI,CAAC;YAClB,IAAI,GAAG,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,IAAI;YACN,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAwB,EACxB,IAAwC,EACxC,WAAwC;IAExC,MAAM,SAAS,GAAG,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,EAAE,sBAAsB;YAC5B,UAAU,EAAE,SAAS;YACrB,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,gDAAgD;SACxD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,IAAI,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAC9F,WAAW,EAAE,CAAC;AAChB,CAAC"}

package/dist/lifecycle/version-endpoint.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { VersionInfo } from './election.js';
+/**
+ * The installed CLI entry point: `<package>/dist/cli.js`. This module lives
+ * in `dist/lifecycle/` (installed) or `src/lifecycle/` (dev), two levels
+ * below the package root either way. After `npm install -g` this is the
+ * same path the running process started from, now holding the new code.
+ */
+export declare const INSTALLED_CLI_PATH: string;
+/** Last-modified time of the installed CLI (epoch ms), or `null`. */
+export declare function readInstalledCodeMtime(path?: string): number | null;
+/** Approximate wall-clock start of this process, epoch ms. */
+export declare const PROCESS_STARTED_AT: number;
+export declare function buildVersionInfo(version: string, pid?: number, startedAt?: number, installed?: () => string | null): VersionInfo;
+/** The bridge's plain-HTTP handler: `/version` or 404. */
+export declare function handleBridgeHttpRequest(req: IncomingMessage, res: ServerResponse, version: string): void;