@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/kernel/log.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Diagnostics. Every line goes to stderr: stdout belongs to a command's
+ * result and is written only through `cli/output.ts`, so nothing logged here
+ * can corrupt a `--json` document or displace a verdict line.
+ */
+import { spinner as clackSpinner } from '@clack/prompts';
+import picocolors from 'picocolors';
+/**
+ * Colour is for a person reading a terminal. A pipe or a log file gets plain
+ * text, so output reads the same in a script, in CI and under test. `NO_COLOR`
+ * turns colour off on a terminal; `FORCE_COLOR` turns it on for a pipe.
+ */
+function colourEnabled() {
+    if (process.env['NO_COLOR'] !== undefined)
+        return false;
+    const forced = process.env['FORCE_COLOR'];
+    if (forced !== undefined)
+        return forced !== '0';
+    return process.stderr.isTTY === true;
+}
+const pc = picocolors.createColors(colourEnabled());
+let config = {};
+/**
+ * Replaces the logging configuration and returns the previous one, so an
+ * in-process CLI run can restore it.
+ *
+ * @param next - The configuration to install
+ */
+export function configureLog(next) {
+    const previous = config;
+    config = next;
+    return previous;
+}
+/** Whether `verbose` lines are shown. */
+export function isVerbose() {
+    return config.verbose === true;
+}
+function emit(prefix, message) {
+    const text = `${prefix}${message}\n`;
+    if (config.write !== undefined)
+        config.write(text);
+    else
+        process.stderr.write(text);
+}
+/**
+ * Logs progress or context the operator may want.
+ *
+ * @param message - The line
+ */
+export function info(message) {
+    if (config.quiet !== true)
+        emit('', message);
+}
+/**
+ * Logs the start of a unit of work.
+ *
+ * @param message - The line
+ */
+export function step(message) {
+    if (config.quiet !== true)
+        emit(pc.cyan('> '), message);
+}
+/**
+ * Logs a completed unit of work.
+ *
+ * @param message - The line
+ */
+export function success(message) {
+    if (config.quiet !== true)
+        emit(pc.green('ok '), message);
+}
+/**
+ * Logs something the operator should look at that did not stop the command.
+ *
+ * @param message - The line
+ */
+export function warn(message) {
+    emit(pc.yellow('warning: '), message);
+}
+/**
+ * Logs a failure. The CLI error boundary reports a thrown error itself; this
+ * is for failures a command survives.
+ *
+ * @param message - The line
+ */
+export function error(message) {
+    emit(pc.red('error: '), message);
+}
+/**
+ * Reports the failure a command ended with, the one form every failure takes
+ * for a person: `error[<code>]: <message>`, then `hint: <hint>` when the
+ * failure carries one.
+ *
+ * @param code - The failure's stable code
+ * @param message - What failed
+ * @param hint - What to do next
+ */
+export function failure(code, message, hint) {
+    emit(pc.red(`error[${code}]: `), message);
+    if (hint !== undefined)
+        emit(pc.cyan('hint: '), hint);
+}
+/**
+ * Logs detail shown only under `--verbose`.
+ *
+ * @param message - The line
+ */
+export function verbose(message) {
+    if (config.verbose === true)
+        emit(pc.dim('debug: '), message);
+}
+/**
+ * Starts a progress indicator: animated when stderr is a terminal, one line
+ * per update otherwise.
+ *
+ * @param message - The initial text
+ */
+export function spinner(message) {
+    const animated = config.write === undefined &&
+        config.quiet !== true &&
+        process.stderr.isTTY &&
+        process.stdout.isTTY;
+    if (!animated) {
+        let latest = message;
+        step(message);
+        return {
+            update(next) {
+                latest = next;
+                step(next);
+            },
+            stop(final) {
+                if (final !== undefined && final !== latest)
+                    success(final);
+            },
+            fail(final) {
+                error(final ?? latest);
+            },
+        };
+    }
+    const active = clackSpinner({ output: process.stderr });
+    active.start(message);
+    return {
+        update(next) {
+            active.message(next);
+        },
+        stop(final) {
+            active.stop(final ?? message);
+        },
+        fail(final) {
+            active.error(final ?? message);
+        },
+    };
+}

package/dist/src/kernel/process/identity.js

@@ -0,0 +1,313 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Exact process identity: the kernel's birth record for a pid.
+ *
+ * A pid alone never grants authority to signal or to call a lock holder
+ * alive, because the kernel reuses it. Identity is the pid plus an opaque
+ * `start` string:
+ *
+ *  - Linux: `<boot id>:<starttime ticks>` from `/proc/<pid>/stat`. The ticks
+ *    are boot-relative and immune to clock steps.
+ *  - macOS: the `lstart` second from `ps`, fixed at fork. One second is
+ *    enough: pids are allocated sequentially, so reusing one inside the
+ *    second it was born takes a full wrap of the pid space in that second.
+ *
+ * The periodic path is {@link snapshotProcesses}: one asynchronous listing
+ * carrying every birth, parent and group. A single-pid probe costs one `ps`
+ * on macOS, so callers that poll use {@link isIdentityAlive} between probes.
+ */
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errnoCode } from '../errors.js';
+import { sleep } from '../time.js';
+import { countListingLines, parseProcessListing, PS_BINARY, PS_ENV, psArguments, } from './listing.js';
+const SNAPSHOT_COLUMNS = ['pid', 'ppid', 'pgid', 'lstart', 'stat'];
+/** Generous on purpose: a timeout here means "unknown", which callers treat as alive. */
+const PS_TIMEOUT_MS = 5_000;
+const PS_MAX_BUFFER = 16 * 1024 * 1024;
+const PROC_ROOT = '/proc';
+/**
+ * Reads `/proc/<pid>/stat`. `comm` (field 2) is parenthesised and may contain
+ * spaces or parentheses, so only what follows the last closing paren is
+ * split: state is index 0, parent 1, group 2, and starttime (field 22) 19.
+ */
+function parseProcStat(stat) {
+    const fields = stat
+        .slice(stat.lastIndexOf(')') + 1)
+        .trim()
+        .split(/\s+/);
+    const [state, parent, group] = fields;
+    const startTick = Number(fields[19]);
+    if (state === undefined ||
+        !Number.isSafeInteger(startTick) ||
+        !Number.isSafeInteger(Number(parent)) ||
+        !Number.isSafeInteger(Number(group))) {
+        return undefined;
+    }
+    return { state, parent: Number(parent), group: Number(group), startTick };
+}
+function fromProcStat(pid, stat, bootId) {
+    const parsed = parseProcStat(stat);
+    if (parsed === undefined || parsed.state === 'Z' || parsed.state === 'X')
+        return undefined;
+    return {
+        pid,
+        start: `${bootId}:${parsed.startTick}`,
+        parent: parsed.parent,
+        group: parsed.group,
+    };
+}
+function fromPsRow(row) {
+    if (row.stat.startsWith('Z'))
+        return undefined;
+    return { pid: row.pid, start: row.lstart, parent: row.ppid, group: row.pgid };
+}
+/**
+ * The process table as procfs shows it, in one asynchronous pass.
+ *
+ * @param procRoot - procfs mount, overridable for fixtures
+ * @returns The snapshot, or undefined when procfs is not readable
+ */
+export async function snapshotFromProcfs(procRoot = PROC_ROOT) {
+    try {
+        const bootId = (await readFile(join(procRoot, 'sys/kernel/random/boot_id'), 'utf8')).trim();
+        const pids = (await readdir(procRoot)).filter((name) => /^\d+$/.test(name)).map(Number);
+        const snapshot = new Map();
+        await Promise.all(pids.map(async (pid) => {
+            let stat;
+            try {
+                stat = await readFile(join(procRoot, String(pid), 'stat'), 'utf8');
+            }
+            catch {
+                return; // Exited between the listing and this read.
+            }
+            const observation = fromProcStat(pid, stat, bootId);
+            if (observation !== undefined)
+                snapshot.set(pid, observation);
+        }));
+        return snapshot;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runPs(args) {
+    return new Promise((resolve) => {
+        execFile(PS_BINARY, [...args], {
+            cwd: '/',
+            env: { ...PS_ENV },
+            encoding: 'utf8',
+            timeout: PS_TIMEOUT_MS,
+            maxBuffer: PS_MAX_BUFFER,
+        }, (error, stdout) => {
+            resolve({ failed: error !== null, stdout });
+        });
+    });
+}
+/**
+ * Reads the whole process table without blocking the event loop.
+ *
+ * @returns The snapshot, or undefined when it could not be taken. Undefined
+ *   is "unknown", never "no processes": one unparsable line makes the whole
+ *   snapshot unknown, since a process missing from it would read as exited.
+ */
+export async function snapshotProcesses() {
+    if (process.platform === 'linux')
+        return snapshotFromProcfs();
+    if (process.platform !== 'darwin')
+        return undefined;
+    const { failed, stdout } = await runPs(psArguments(SNAPSHOT_COLUMNS));
+    if (failed)
+        return undefined;
+    const rows = parseProcessListing(stdout, SNAPSHOT_COLUMNS);
+    if (rows.length === 0 || rows.length !== countListingLines(stdout))
+        return undefined;
+    const snapshot = new Map();
+    for (const row of rows) {
+        const observation = fromPsRow(row);
+        if (observation !== undefined)
+            snapshot.set(row.pid, observation);
+    }
+    return snapshot;
+}
+/**
+ * Lists processes with the requested `ps` columns, for diagnostics and
+ * preflights. A failed listing yields no rows, which grants nothing to a
+ * caller deciding authority.
+ *
+ * @param columns - Columns in output order; a rest-of-line column must be last
+ * @param options - See {@link ListProcessesOptions}
+ */
+export async function listProcesses(columns, options = {}) {
+    if (options.pids?.length === 0)
+        return [];
+    // `ps -p` exits 1 when any listed pid is gone while still printing the rest,
+    // so the exit status says nothing here.
+    const { stdout } = await runPs(psArguments(columns, options.pids, options.environment === true));
+    return parseProcessListing(stdout, columns);
+}
+let bootId;
+function procfsIdentity(pid) {
+    bootId ??= readFileSync(join(PROC_ROOT, 'sys/kernel/random/boot_id'), 'utf8').trim();
+    return fromProcStat(pid, readFileSync(join(PROC_ROOT, String(pid), 'stat'), 'utf8'), bootId);
+}
+/**
+ * The exact identity of a live process.
+ *
+ * @param pid - Process to look up
+ * @returns The identity, or undefined when the pid is gone, is a zombie, or
+ *   the probe failed. {@link processHasExited} separates those.
+ */
+export async function processIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return undefined;
+    let observed;
+    if (process.platform === 'linux') {
+        try {
+            observed = procfsIdentity(pid);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else if (process.platform === 'darwin') {
+        const { stdout } = await runPs(psArguments(SNAPSHOT_COLUMNS, [pid]));
+        const row = parseProcessListing(stdout, SNAPSHOT_COLUMNS)[0];
+        observed = row?.pid === pid ? fromPsRow(row) : undefined;
+    }
+    return observed === undefined ? undefined : { pid: observed.pid, start: observed.start };
+}
+let own;
+/**
+ * This process's identity. A birth never changes, so one lookup serves the
+ * whole run. Undefined on a platform with no start record.
+ */
+export function ownIdentity() {
+    own ??= processIdentity(process.pid);
+    return own;
+}
+/**
+ * Whether a pid exists, by `kill(pid, 0)`. Only `ESRCH` means no. `EPERM`
+ * means a live process owned by another user, and any other answer is read as
+ * alive: every caller uses "dead" to justify taking or deleting something.
+ *
+ * @param pid - Process to probe
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errnoCode(error) !== 'ESRCH';
+    }
+}
+/**
+ * Whether a process group still has members. A group that denies the probe exists.
+ *
+ * @param pgid - Group to probe
+ */
+export function isProcessGroupAlive(pgid) {
+    return pgid > 1 && isProcessAlive(-pgid);
+}
+/**
+ * A cheap liveness answer for polling: the pid exists and, where comparing
+ * costs no spawn (Linux), still has the recorded start. May say "alive" for a
+ * reused pid elsewhere; {@link processHasExited} settles that.
+ *
+ * @param identity - The recorded identity; `start` may be unknown
+ */
+export function isIdentityAlive(identity) {
+    if (!isProcessAlive(identity.pid))
+        return false;
+    if (identity.start === undefined || process.platform !== 'linux')
+        return true;
+    try {
+        // An unreadable or zombie entry proves nothing, so it stays "alive".
+        const current = procfsIdentity(identity.pid);
+        return current === undefined || current.start === identity.start;
+    }
+    catch {
+        return isProcessAlive(identity.pid);
+    }
+}
+/**
+ * Distinguishes a dead or replaced process from a probe that could not tell.
+ *
+ * @param identity - The recorded identity; without a `start` only the pid is judged
+ * @returns True only when the process is provably gone
+ */
+export async function processHasExited(identity) {
+    if (!isProcessAlive(identity.pid))
+        return true;
+    if (identity.start === undefined)
+        return false;
+    const current = await processIdentity(identity.pid);
+    if (current !== undefined)
+        return current.start !== identity.start;
+    // The probe saw nothing: either the process just exited, or the probe failed.
+    return !isProcessAlive(identity.pid);
+}
+/**
+ * Whether a snapshot shows `identity` alive.
+ *
+ * @param snapshot - One read of the process table
+ * @param identity - The recorded identity
+ */
+export function isAliveIn(snapshot, identity) {
+    return snapshot.get(identity.pid)?.start === identity.start;
+}
+/**
+ * Signals one process only if the snapshot still shows its exact identity.
+ *
+ * @param snapshot - A snapshot taken for this decision
+ * @param identity - The positively owned process
+ * @param signal - Signal to send
+ * @returns True when the signal was delivered
+ */
+export function signalIfAlive(snapshot, identity, signal) {
+    if (!isAliveIn(snapshot, identity))
+        return false;
+    try {
+        process.kill(identity.pid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const TERMINATION_POLL_MS = 100;
+const KILL_SETTLE_DELAY_MS = 300;
+/**
+ * Terminates processes by exact identity: SIGTERM to each one a fresh
+ * snapshot still shows with its recorded birth, a grace, then SIGKILL to any
+ * that remains. A reused pid is never signalled.
+ *
+ * @param targets - The processes, as observed when they were judged owned
+ * @param graceMs - Time between SIGTERM and SIGKILL
+ */
+export async function terminateByIdentity(targets, graceMs) {
+    if (targets.length === 0)
+        return { signalled: [], survivors: [] };
+    const first = await snapshotProcesses();
+    if (first === undefined)
+        return { signalled: [], survivors: [...targets] };
+    const signalled = targets.filter((target) => signalIfAlive(first, target, 'SIGTERM'));
+    const aliveIn = (snapshot) => snapshot === undefined ? [...signalled] : signalled.filter((t) => isAliveIn(snapshot, t));
+    let current = first;
+    for (const deadline = Date.now() + graceMs; Date.now() < deadline;) {
+        await sleep(TERMINATION_POLL_MS);
+        current = await snapshotProcesses();
+        if (aliveIn(current).length === 0)
+            return { signalled, survivors: [] };
+    }
+    if (current !== undefined) {
+        for (const target of aliveIn(current))
+            signalIfAlive(current, target, 'SIGKILL');
+        await sleep(KILL_SETTLE_DELAY_MS);
+        current = await snapshotProcesses();
+    }
+    return { signalled, survivors: aliveIn(current) };
+}

package/dist/src/kernel/process/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Processes: running programs, identifying them exactly, listing them, and
+ * owning the tree a program starts.
+ */
+export { isIdentityAlive, isProcessAlive, isProcessGroupAlive, listProcesses, ownIdentity, processHasExited, processIdentity, snapshotProcesses, terminateByIdentity, } from './identity.js';
+export { commandNamesRoot } from './listing.js';
+export { findExecutable, onProcessGroup, run, runBytes } from './spawn.js';

package/dist/src/kernel/process/listing.js

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one description of a `ps` listing: which binary, which environment,
+ * which arguments, and how a row is read back. Pure, so fixtures need no
+ * process.
+ */
+/**
+ * A planted `ps` earlier on PATH must not decide who gets signalled, so the
+ * absolute path is used where it is guaranteed. Linux distributions disagree
+ * on the location; identity there reads procfs and never runs this binary.
+ */
+export const PS_BINARY = process.platform === 'darwin' ? '/bin/ps' : 'ps';
+/**
+ * `LC_ALL=C` keeps `lstart` in the one format the parser reads. `TZ=UTC`
+ * keeps a recorded start comparable across a daylight-saving change, since
+ * `lstart` renders in local time.
+ */
+export const PS_ENV = { LC_ALL: 'C', TZ: 'UTC' };
+/**
+ * Arguments for a listing of every process, or of `pids` only.
+ *
+ * With `environment`, a command column also carries each process's
+ * environment (BSD `eww`). procps refuses UNIX-style `-x` beside a BSD
+ * option, so a full listing then selects with BSD `ax`, which both accept.
+ *
+ * @param columns - Columns in output order; a rest-of-line column must be last
+ * @param pids - Limit the listing to these pids
+ * @param environment - Append each process's environment to a command column
+ */
+export function psArguments(columns, pids, environment = false) {
+    const format = columns.map((column) => `${column}=`).join(',');
+    if (environment) {
+        return pids === undefined
+            ? ['axeww', '-o', format]
+            : ['eww', '-o', format, '-p', pids.join(',')];
+    }
+    return pids === undefined ? ['-axo', format] : ['-o', format, '-p', pids.join(',')];
+}
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** Reads the five `lstart` tokens (`Sat Nov  7 01:53:10 2026`, UTC) as epoch seconds. */
+function parseLstart(tokens) {
+    const [, month, day, clock, year] = tokens;
+    const time = /^(\d{2}):(\d{2}):(\d{2})$/.exec(clock ?? '');
+    const monthIndex = MONTHS.indexOf(month ?? '');
+    if (!time || monthIndex < 0 || !/^\d+$/.test(day ?? '') || !/^\d{4}$/.test(year ?? '')) {
+        return undefined;
+    }
+    const ms = Date.UTC(Number(year), monthIndex, Number(day), Number(time[1]), Number(time[2]), Number(time[3]));
+    return Number.isNaN(ms) ? undefined : String(ms / 1000);
+}
+function parseRow(line, columns) {
+    const tokenizer = /\S+/g;
+    const row = {};
+    const next = () => tokenizer.exec(line)?.[0];
+    for (const column of columns) {
+        if (column === 'args' || column === 'command') {
+            const rest = line.slice(tokenizer.lastIndex).trim();
+            if (rest.length === 0)
+                return undefined;
+            row[column] = rest;
+            return row;
+        }
+        if (column === 'lstart') {
+            const start = parseLstart([next(), next(), next(), next(), next()]);
+            if (start === undefined)
+                return undefined;
+            row[column] = start;
+            continue;
+        }
+        const token = next();
+        if (token === undefined)
+            return undefined;
+        if (column === 'pid' || column === 'ppid' || column === 'pgid') {
+            if (!/^\d+$/.test(token))
+                return undefined;
+            row[column] = Number(token);
+        }
+        else {
+            row[column] = token;
+        }
+    }
+    return row;
+}
+/**
+ * Parses a listing. A line that does not fit the columns is skipped: `ps`
+ * prints no header for `col=` formats, so only damage produces one, and a
+ * caller that must not lose a row compares against {@link countListingLines}.
+ *
+ * @param text - Raw `ps` output (CRLF tolerated)
+ * @param columns - The columns the listing was asked for
+ */
+export function parseProcessListing(text, columns) {
+    const rows = [];
+    for (const line of text.split(/\r?\n/)) {
+        const row = parseRow(line, columns);
+        if (row !== undefined)
+            rows.push(row);
+    }
+    return rows;
+}
+/**
+ * Number of non-blank lines in a listing.
+ *
+ * @param text - Raw `ps` output
+ */
+export function countListingLines(text) {
+    return text.split(/\r?\n/).filter((line) => line.trim().length > 0).length;
+}
+/**
+ * Whether `command` names `root` as a whole absolute path token, or a path
+ * under it. `<root>2` and `/sibling<root>` do not count, and a relative or
+ * empty root never matches, so an unknown root grants nothing.
+ *
+ * @param command - A process command line
+ * @param root - Absolute directory
+ */
+export function commandNamesRoot(command, root) {
+    if (!root || !/^(?:\/|[A-Za-z]:[/\\])/.test(root))
+        return false;
+    const needle = root.replace(/[/\\]+$/, '');
+    for (let at = command.indexOf(needle); at !== -1; at = command.indexOf(needle, at + needle.length)) {
+        const before = at === 0 ? ' ' : (command[at - 1] ?? ' ');
+        const after = command[at + needle.length] ?? ' ';
+        if (/[\s"'=]/.test(before) && /[\s"'/\\]/.test(after))
+            return true;
+    }
+    return false;
+}