@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/kernel/signals.js

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What happens between SIGINT, SIGTERM or SIGHUP and the process exiting.
+ *
+ * `finally` blocks do not run across `process.exit`, so anything that must
+ * happen on an interrupt (stop children, undo a half-made change, release a
+ * lock) registers here, and the process entry drives the pipeline without
+ * knowing who registered. The phases run in this order:
+ *
+ *  1. `announce`  synchronously, in the signal's own tick, before anything
+ *                 that can stall: a final line saying the run was killed.
+ *  2. `stop`      in parallel: forward the signal to children and wait for
+ *                 them.
+ *  3. `rollback`  undo journaled changes. After `stop`, so no child is still
+ *                 writing the files being restored.
+ *  4. `restore`   put back temporary alterations while the locks are still
+ *                 held, so the next holder never sees them.
+ *  5. `release`   release locks.
+ *  6. `finish`    close logs, remove scratch directories.
+ *
+ * Every handler is bounded and its failure is logged, never thrown: nothing
+ * registered here can keep the process from exiting. A phase starts only once
+ * every handler of the phase before it has finished. When one has not
+ * finished within its bound, everything up to `finish` is skipped: a child
+ * may still be writing, or an undo may still be restoring, so no undo starts
+ * and no lock is released. The journal stays for the next run, and the locks
+ * are taken over once this process is gone. A second signal while the
+ * pipeline runs exits at once.
+ */
+import { ExitCode, toError } from './errors.js';
+import { warn } from './log.js';
+import { settlesWithin } from './time.js';
+/** The phases that run in order after `announce`, each only if the one before finished. */
+const PHASES = ['stop', 'rollback', 'restore', 'release'];
+/** Default bound on one handler. */
+const HANDLER_TIMEOUT_MS = 15_000;
+const handlers = new Map();
+const forceHandlers = new Set();
+let running;
+/**
+ * Registers work for one phase of an interrupt.
+ *
+ * @param phase - When to run; `announce` handlers must be synchronous
+ * @param handler - The work. May reject; the rejection is logged
+ * @param options - `timeoutMs` bounds the handler (default 15 s)
+ * @returns A function that removes the registration
+ */
+export function onShutdown(phase, handler, options = {}) {
+    const registration = { handler, timeoutMs: options.timeoutMs ?? HANDLER_TIMEOUT_MS };
+    let set = handlers.get(phase);
+    if (set === undefined) {
+        set = new Set();
+        handlers.set(phase, set);
+    }
+    set.add(registration);
+    return () => {
+        handlers.get(phase)?.delete(registration);
+    };
+}
+/**
+ * Registers synchronous work for the moment a second signal forces the exit:
+ * the last chance to kill a child outright.
+ *
+ * @param handler - Must not throw and cannot wait
+ * @returns A function that removes the registration
+ */
+export function onForceExit(handler) {
+    forceHandlers.add(handler);
+    return () => {
+        forceHandlers.delete(handler);
+    };
+}
+/** Whether an interrupt is being handled. */
+export function isShuttingDown() {
+    return running !== undefined;
+}
+/** Runs one handler within its bound. Returns false when it did not finish in time. */
+async function runBounded(phase, registration, signal) {
+    let failure;
+    const work = Promise.resolve()
+        .then(() => registration.handler(signal))
+        .catch((error) => {
+        failure = error;
+    });
+    if (!(await settlesWithin(work, registration.timeoutMs))) {
+        warn(`A ${phase} step did not finish within ${registration.timeoutMs} ms of ${signal}.`);
+        return false;
+    }
+    if (failure !== undefined) {
+        warn(`A ${phase} step failed after ${signal}: ${toError(failure).message}`);
+    }
+    return true;
+}
+async function runPhase(phase, signal) {
+    const work = [...(handlers.get(phase) ?? [])].map((registration) => runBounded(phase, registration, signal));
+    return (await Promise.all(work)).every(Boolean);
+}
+async function pipeline(signal) {
+    for (const registration of handlers.get('announce') ?? []) {
+        try {
+            void registration.handler(signal);
+        }
+        catch {
+            // A diagnostic never keeps the process from exiting.
+        }
+    }
+    for (const phase of PHASES) {
+        if (!(await runPhase(phase, signal))) {
+            warn('Leaving the remaining undo and lock release to the next run.');
+            break;
+        }
+    }
+    await runPhase('finish', signal);
+}
+/**
+ * Runs the interrupt pipeline. Never rejects. A second call joins the first.
+ *
+ * @param signal - The signal that arrived
+ */
+export function runShutdown(signal) {
+    running ??= pipeline(signal);
+    return running;
+}
+/**
+ * Forgets a finished pipeline, so one process can exercise it more than once.
+ * Registrations are kept.
+ */
+export function resetShutdown() {
+    running = undefined;
+}
+const EXIT_CODES = {
+    SIGINT: ExitCode.USER_CANCELLED,
+    SIGTERM: ExitCode.TERMINATED,
+    // A closed terminal ends the command the way a request to stop does.
+    SIGHUP: ExitCode.TERMINATED,
+};
+/**
+ * Installs the SIGINT, SIGTERM and SIGHUP listeners. The first signal runs
+ * the pipeline and then exits with 130 (SIGINT) or 143. A signal that arrives while the
+ * pipeline is running runs the force handlers and exits at once.
+ *
+ * @param hooks - See {@link ExitHooks}
+ * @returns A function that removes the listeners
+ */
+export function installSignalHandlers(hooks) {
+    const listeners = Object.keys(EXIT_CODES).map((signal) => {
+        const listener = () => {
+            if (isShuttingDown()) {
+                for (const handler of forceHandlers) {
+                    try {
+                        handler();
+                    }
+                    catch {
+                        // The exit below is what the user asked for.
+                    }
+                }
+                hooks.forceExit(EXIT_CODES[signal]);
+                return;
+            }
+            void runShutdown(signal).finally(() => {
+                hooks.exit(EXIT_CODES[signal]);
+            });
+        };
+        process.on(signal, listener);
+        return { signal, listener };
+    });
+    return () => {
+        for (const { signal, listener } of listeners)
+            process.off(signal, listener);
+    };
+}

package/dist/src/kernel/text.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Escapes every regular-expression metacharacter in `text`.
+ *
+ * @param text - Literal text to match
+ */
+export function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Splits text into lines on `\n` or `\r\n`, without a trailing empty line.
+ *
+ * @param text - The text
+ */
+export function splitLines(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * The last `count` non-empty lines of `text`.
+ *
+ * @param text - The text
+ * @param count - How many lines to keep
+ */
+export function tailLines(text, count) {
+    return splitLines(text)
+        .filter((line) => line.trim().length > 0)
+        .slice(-count);
+}
+const C_ESCAPES = {
+    a: 0x07,
+    b: 0x08,
+    t: 0x09,
+    n: 0x0a,
+    v: 0x0b,
+    f: 0x0c,
+    r: 0x0d,
+};
+/**
+ * Decodes a C-style quoted string, the form git writes a path in when it
+ * holds a quote, a backslash, a control character or (under
+ * `core.quotePath`) any byte outside printable ASCII: `"dir/f\303\274r.js"`.
+ * Octal escapes are raw bytes, so the result is bytes; a git path decodes
+ * from them as UTF-8.
+ *
+ * @param quoted - The text, with or without its surrounding double quotes
+ * @param encoding - How the unescaped characters map to bytes
+ */
+export function unquoteC(quoted, encoding = 'utf8') {
+    const body = quoted.length >= 2 && quoted.startsWith('"') && quoted.endsWith('"')
+        ? quoted.slice(1, -1)
+        : quoted;
+    const parts = [];
+    let literal = '';
+    const flush = () => {
+        if (literal.length > 0)
+            parts.push(Buffer.from(literal, encoding));
+        literal = '';
+    };
+    for (let index = 0; index < body.length; index++) {
+        const char = body.charAt(index);
+        const next = body.charAt(index + 1);
+        if (char !== '\\' || next === '') {
+            literal += char;
+            continue;
+        }
+        flush();
+        const octal = /^[0-3][0-7]{2}/.exec(body.slice(index + 1, index + 4))?.[0];
+        if (octal !== undefined) {
+            parts.push(Buffer.from([parseInt(octal, 8)]));
+            index += 3;
+        }
+        else {
+            parts.push(Buffer.from([C_ESCAPES[next] ?? next.charCodeAt(0)]));
+            index += 1;
+        }
+    }
+    flush();
+    return Buffer.concat(parts);
+}
+/** A partial line longer than this is dispatched as it stands, so the buffer stays bounded. */
+const MAX_PARTIAL_LINE = 1024 * 1024;
+/**
+ * Turns a chunked stream into lines. `\n`, `\r\n` and a lone `\r` (progress
+ * bars that repaint a line) all end a line. A trailing `\r` is held back,
+ * since it may be the first half of a `\r\n` split across chunks.
+ *
+ * @param onLine - Receives each complete line
+ * @returns `push` for each chunk and `flush` for the final partial line
+ */
+export function lineSplitter(onLine) {
+    let buffer = '';
+    return {
+        push(chunk) {
+            buffer += chunk;
+            for (;;) {
+                const index = buffer.search(/[\r\n]/);
+                if (index === -1)
+                    break;
+                if (buffer[index] === '\r' && index === buffer.length - 1)
+                    break;
+                const width = buffer[index] === '\r' && buffer[index + 1] === '\n' ? 2 : 1;
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + width);
+                onLine(line);
+            }
+            if (buffer.length > MAX_PARTIAL_LINE) {
+                onLine(buffer);
+                buffer = '';
+            }
+        },
+        flush() {
+            const rest = buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer;
+            buffer = '';
+            if (rest.length > 0)
+                onLine(rest);
+        },
+    };
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution);
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+/**
+ * The candidate most likely meant by a mistyped `input`, or undefined when
+ * none is close enough to suggest.
+ *
+ * @param input - What was typed
+ * @param candidates - The valid names
+ */
+export function nearest(input, candidates) {
+    const limit = Math.max(2, Math.floor(input.length / 3));
+    let best;
+    for (const name of candidates) {
+        const distance = editDistance(input.toLowerCase(), name.toLowerCase());
+        if (distance <= limit && (best === undefined || distance < best.distance)) {
+            best = { name, distance };
+        }
+    }
+    return best?.name;
+}

package/dist/src/kernel/time.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one awaitable delay. Built on the global `setTimeout` so fake timers
+ * reach it. The timer holds the event loop open unless `unref` is set: an
+ * unref'd delay between a SIGTERM and its escalation would let Node exit
+ * mid-grace.
+ *
+ * @param ms - Milliseconds to wait
+ * @param options - `unref` for a delay that must not keep the process alive
+ */
+export function sleep(ms, options = {}) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (options.unref === true)
+            timer.unref();
+    });
+}
+/**
+ * Formats a duration as `12s`, `3m 12s` or `2h 05m`.
+ *
+ * @param ms - Milliseconds; negative input reads as zero
+ */
+export function formatDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    if (hours > 0)
+        return `${hours}h ${String(minutes).padStart(2, '0')}m`;
+    return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+/**
+ * Whether `promise` settles (either way) within `ms`.
+ *
+ * @param promise - The work being waited on
+ * @param ms - The bound
+ */
+export async function settlesWithin(promise, ms) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(false);
+        }, ms);
+    });
+    const settled = promise.then(() => true, () => true);
+    try {
+        return await Promise.race([settled, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Maps `items` with at most `limit` calls in flight, preserving order. On a
+ * failure it stops scheduling, waits for what already started, then rejects,
+ * so the caller can clean up safely.
+ *
+ * @param items - Inputs
+ * @param limit - Maximum concurrent calls
+ * @param fn - The mapper
+ */
+export async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const state = {};
+    const worker = async () => {
+        while (state.failure === undefined) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            try {
+                results[index] = await fn(items[index], index);
+            }
+            catch (error) {
+                state.failure ??= { error };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+    if (state.failure !== undefined)
+        throw state.failure.error;
+    return results;
+}

package/dist/src/kernel/tty.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { confirm as clackConfirm, isCancel, select as clackSelect, text as clackText, } from '@clack/prompts';
+import { CancelledError, ExitCode, FireForgeError } from './errors.js';
+/**
+ * Whether a prompt can be answered: stdin and stdout are both terminals.
+ * At runtime `isTTY` is `true` or absent, never `false`, hence the comparison.
+ */
+export function isInteractive() {
+    const stdin = process.stdin.isTTY;
+    const stdout = process.stdout.isTTY;
+    return stdin === true && stdout === true;
+}
+/**
+ * Asks a yes/no question on the terminal.
+ *
+ * @param message - The question
+ * @param options - `initial` is the answer Enter gives (default no)
+ * @returns The answer. "No" is an answer, not a cancellation
+ * @throws {CancelledError} When the user interrupts the prompt
+ * @throws An `invalid-argument` error when no terminal is attached, so a
+ *   scripted run fails with the flag to pass instead of hanging
+ */
+export async function confirm(message, options = {}) {
+    if (!isInteractive()) {
+        throw new FireForgeError('invalid-argument', `"${message}" needs an answer, but no terminal is attached.`, { exitCode: ExitCode.INVALID_ARGUMENT, hint: 'Pass --yes to confirm without a prompt.' });
+    }
+    const answer = await clackConfirm({
+        message,
+        initialValue: options.initial ?? false,
+        output: process.stderr,
+    });
+    if (isCancel(answer))
+        throw new CancelledError();
+    return answer;
+}
+function requireTerminal(message) {
+    if (isInteractive())
+        return;
+    throw new FireForgeError('invalid-argument', `"${message}" needs an answer, but no terminal is attached.`, { exitCode: ExitCode.INVALID_ARGUMENT, hint: 'Pass the value as an option.' });
+}
+/**
+ * Asks for one line of text on the terminal.
+ *
+ * @param message - The question
+ * @param options - `initial` is the answer Enter gives; `validate` returns
+ *   why an answer is refused, or undefined to accept it
+ * @returns The answer, trimmed
+ * @throws {CancelledError} When the user interrupts the prompt
+ * @throws An `invalid-argument` error when no terminal is attached
+ */
+export async function ask(message, options = {}) {
+    requireTerminal(message);
+    const { initial, validate } = options;
+    const answer = await clackText({
+        message,
+        output: process.stderr,
+        ...(initial === undefined ? {} : { placeholder: initial, defaultValue: initial }),
+        validate: (value) => validate?.((value ?? '').trim() || (initial ?? '')),
+    });
+    if (isCancel(answer))
+        throw new CancelledError();
+    return answer.trim();
+}
+/**
+ * Asks the user to pick one of several values on the terminal.
+ *
+ * @param message - The question
+ * @param choices - The values, each with the label shown for it
+ * @param initial - The value the cursor starts on
+ * @throws {CancelledError} When the user interrupts the prompt
+ * @throws An `invalid-argument` error when no terminal is attached
+ */
+export async function choose(message, choices, initial) {
+    requireTerminal(message);
+    const answer = await clackSelect({
+        message,
+        output: process.stderr,
+        options: choices.map((choice) => ({ value: choice.value, label: choice.label })),
+        ...(initial === undefined ? {} : { initialValue: initial }),
+    });
+    if (isCancel(answer))
+        throw new CancelledError();
+    return answer;
+}

package/dist/src/lint/cache.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The TypeScript result cache. An entry is keyed by everything that shapes
+ * a program except file content (compiler version and options, roots, shim,
+ * the set of resolvable modules), and records the digest of every file the
+ * program read. It answers only while each of those files still has that
+ * digest, so a hit is exactly the result a rebuild would give. Entries are
+ * disposable: an unreadable one is a miss and is overwritten.
+ */
+import { join } from 'node:path';
+import { listDir, readTextIfExists, remove, writeFile } from '../kernel/fs.js';
+import { parseJson, stringifyJson } from '../kernel/json.js';
+import { s } from '../kernel/schema.js';
+const entrySchema = s.object({
+    inputs: s.record(s.string()),
+    findings: s.array(s.object({
+        path: s.string(),
+        line: s.int({ min: 1 }),
+        severity: s.enum(['error', 'warning']),
+        message: s.string(),
+    })),
+});
+const fileOf = (cacheDir, key) => join(cacheDir, `${key}.json`);
+/**
+ * The cached findings of a program, when every file it read is unchanged.
+ *
+ * @param cacheDir - The cache directory, or undefined for no cache
+ * @param key - The program's key
+ * @param digests - Current content digest per path
+ */
+export async function readCached(cacheDir, key, digests) {
+    if (cacheDir === undefined)
+        return undefined;
+    const text = await readTextIfExists(fileOf(cacheDir, key));
+    if (text === undefined)
+        return undefined;
+    let value;
+    try {
+        value = parseJson(text);
+    }
+    catch {
+        return undefined;
+    }
+    const result = entrySchema.validate(value);
+    if (!result.ok)
+        return undefined;
+    const fresh = Object.entries(result.value.inputs).every(([path, digest]) => digests.get(path) === digest);
+    return fresh ? result.value.findings : undefined;
+}
+/**
+ * Records a program's findings with the digests of the files it read.
+ *
+ * @param cacheDir - The cache directory, or undefined for no cache
+ * @param key - The program's key
+ * @param read - The paths the program read
+ * @param digests - Current content digest per path
+ * @param findings - The program's findings
+ */
+export async function writeCached(cacheDir, key, read, digests, findings) {
+    if (cacheDir === undefined)
+        return;
+    const inputs = Object.fromEntries(read.map((path) => [path, digests.get(path) ?? '']));
+    await writeFile(fileOf(cacheDir, key), stringifyJson({ inputs, findings }), { durable: false });
+}
+/**
+ * Removes every entry but the given keys: after a run over every owned
+ * file, what it did not use describes programs that no longer exist.
+ *
+ * @param cacheDir - The cache directory
+ * @param keep - Keys the run used
+ */
+export async function pruneCache(cacheDir, keep) {
+    const entries = await listDir(cacheDir);
+    await Promise.all(entries
+        .filter((entry) => entry.name.endsWith('.json') && !keep.has(entry.name.slice(0, -'.json'.length)))
+        .map((entry) => remove(join(cacheDir, entry.name))));
+}