firstlight 0.0.0-stage → 0.2.0

package/dist/diagnostics.js

@@ -0,0 +1,459 @@
+// Uniform diagnostics from the log of a failed check: which parser reads a
+// check's output (named in firstlight.json, or inferred from its command),
+// and the parsers themselves, for tsc, vitest, node:test, and archstrict.
+// Each parser reads the text the tool prints by default, because the user's
+// command decides the output format and text is what the log holds. This
+// module does no I/O: the caller reads the log and package.json.
+//
+// A parser never throws and never guesses: a line it does not recognize is
+// skipped, and a log with nothing it recognizes gives no diagnostics, so the
+// caller falls back to the plain log tail. A vitest diagnostic also gets the
+// evidence file and rerun command depug printed for its test, when exactly
+// one of each side names that test.
+export const PARSERS = ["tsc", "vitest", "node-test", "archstrict"];
+// "none" in firstlight.json turns inference off for one check.
+export const PARSER_CHOICES = [...PARSERS, "none"];
+const MESSAGE_MAX = 300;
+export function isParserName(value) {
+    return typeof value === "string" && PARSERS.includes(value);
+}
+export function parseDiagnostics(parser, log, root) {
+    const lines = toLines(log);
+    switch (parser) {
+        case "tsc":
+            return parseTsc(lines);
+        case "vitest":
+            return attachDepug(parseVitest(lines, root), depugFailures(lines));
+        case "node-test":
+            return lines.some((line) => /^TAP version \d+$/.test(line)) ? parseNodeTestTap(lines, root) : parseNodeTestSpec(lines, root);
+        case "archstrict":
+            return parseArchstrict(lines, root);
+    }
+}
+export function formatDiagnostic(diagnostic) {
+    let where = diagnostic.file;
+    if (diagnostic.line !== null) {
+        where += `:${diagnostic.line}`;
+        if (diagnostic.col !== null)
+            where += `:${diagnostic.col}`;
+    }
+    return [where, diagnostic.rule, diagnostic.message].filter((part) => part !== null && part !== "").join(" ");
+}
+// The command is read only when it is one simple command: a pipe, a list,
+// or a substitution could run any tool, and a wrong parser is worse than
+// none. `npm run <script>` and `npm test` look up the script's own command
+// one level deep; that command is not followed further.
+export function inferParser(command, scriptOf) {
+    const words = simpleWords(command);
+    if (words === null)
+        return null;
+    let i = 0;
+    while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
+        i += 1;
+    if (words[i] === "npx") {
+        i += 1;
+        while (i < words.length && words[i].startsWith("-"))
+            i += 1;
+    }
+    else if (words[i] === "pnpm" && words[i + 1] === "exec") {
+        i += 2;
+    }
+    const program = words[i]?.split("/").at(-1);
+    const args = words.slice(i + 1);
+    switch (program) {
+        case "tsc":
+        case "vitest":
+        case "archstrict":
+            return program;
+        case "node":
+            return nodeRunsTests(args) ? "node-test" : null;
+        case "npm": {
+            const script = npmScript(args);
+            if (script === null)
+                return null;
+            const scriptCommand = scriptOf(script);
+            if (scriptCommand === null)
+                return null;
+            return inferParser(scriptCommand, () => null);
+        }
+        default:
+            return null;
+    }
+}
+function simpleWords(command) {
+    if (/[;&|`<>\n]|\$\(/.test(command))
+        return null;
+    const words = [];
+    for (const raw of command.trim().split(/\s+/)) {
+        if (raw.length === 0)
+            continue;
+        const quoted = /^'([^']*)'$/.exec(raw) ?? /^"([^"]*)"$/.exec(raw);
+        words.push(quoted === null ? raw : quoted[1]);
+    }
+    return words;
+}
+const NODE_VALUE_FLAGS = new Set(["--import", "--require", "-r", "--loader", "--experimental-loader", "--env-file"]);
+// `--test` counts only before the script: after it, it is the script's own.
+function nodeRunsTests(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--test")
+            return true;
+        if (!arg.startsWith("-") && !NODE_VALUE_FLAGS.has(args[i - 1] ?? ""))
+            return false;
+    }
+    return false;
+}
+function npmScript(args) {
+    const rest = args.filter((arg) => !arg.startsWith("-") || arg === "--");
+    const [verb, name] = rest;
+    if (verb === "test" || verb === "t" || verb === "tst")
+        return "test";
+    if ((verb === "run" || verb === "run-script" || verb === "rum" || verb === "urn") && name !== undefined && name !== "--")
+        return name;
+    return null;
+}
+function toLines(log) {
+    return log.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, "").split(/\r\n|\n|\r/);
+}
+function positive(text) {
+    if (text === undefined)
+        return null;
+    const value = Number(text);
+    return Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+function clip(message) {
+    const flat = message.replace(/\s+/g, " ").trim();
+    return flat.length <= MESSAGE_MAX ? flat : `${flat.slice(0, MESSAGE_MAX - 3)}...`;
+}
+// The first line of an error, joined with the next ones while it ends in
+// ":", because assert's "Expected values to be strictly equal:" says
+// nothing until the "7 !== 6" that follows it.
+function headline(lines) {
+    const kept = lines.map((line) => line.trim()).filter((line) => line.length > 0);
+    let message = kept[0] ?? "";
+    for (let i = 1; i < kept.length && message.endsWith(":") && message.length < MESSAGE_MAX; i += 1) {
+        message += ` ${kept[i]}`;
+    }
+    return clip(message);
+}
+// A stack path relative to the root, or null when it is outside the
+// project: a dependency, a Node internal, or another directory.
+function projectPath(raw, root) {
+    let file = raw;
+    if (file.startsWith("file://")) {
+        try {
+            file = decodeURIComponent(file.slice("file://".length));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (file.startsWith("node:") || file.includes("node_modules/") || file.length === 0)
+        return null;
+    if (!file.startsWith("/"))
+        return file;
+    const prefix = root.endsWith("/") ? root : `${root}/`;
+    return file.startsWith(prefix) && file.length > prefix.length ? file.slice(prefix.length) : null;
+}
+function displayPath(raw, root) {
+    return projectPath(raw, root) ?? raw;
+}
+// tsc --pretty false: `src/a.ts(3,7): error TS2322: message`. --pretty:
+// `src/a.ts:3:7 - error TS2322: message` once the colors are gone. The
+// indented lines after either are elaboration and are left to the log.
+function parseTsc(lines) {
+    const out = [];
+    for (const line of lines) {
+        const plain = /^(\S.*?)\((\d+),(\d+)\): (?:error|warning) (TS\d+): (.*)$/.exec(line);
+        const pretty = plain === null ? /^(\S.*?):(\d+):(\d+) - (?:error|warning) (TS\d+): (.*)$/.exec(line) : null;
+        const match = plain ?? pretty;
+        if (match === null)
+            continue;
+        out.push({ file: match[1], line: positive(match[2]), col: positive(match[3]), rule: match[4], message: clip(match[5]) });
+    }
+    return out;
+}
+const VITEST_FRAME = /^\s*❯ (?:(.+) )?(\S+?):(\d+):(\d+)$/;
+// vitest's default reporter: a ` FAIL  file > suite > test` header (or
+// ` FAIL  file [ file ]` for a file that failed to load), the error, then
+// `❯ [fn] file:line:col` frames, each followed by a code frame.
+function parseVitest(lines, root) {
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const header = /^ FAIL {2}(\S+?)(?: > (.+)| \[ .+ \])$/.exec(lines[i]);
+        if (header === null)
+            continue;
+        const testFile = header[1];
+        const message = [];
+        let frame = null;
+        let j = i + 1;
+        let inError = true;
+        for (; j < lines.length; j += 1) {
+            const line = lines[j];
+            if (/^ FAIL {2}/.test(line) || /^⎯{3,}/.test(line))
+                break;
+            const found = VITEST_FRAME.exec(line);
+            if (found !== null) {
+                inError = false;
+                const file = frame === null ? projectPath(found[2], root) : null;
+                if (file !== null)
+                    frame = { file, line: positive(found[3]), col: positive(found[4]) };
+                continue;
+            }
+            if (inError)
+                message.push(line);
+        }
+        const diagnostic = {
+            file: frame?.file ?? testFile,
+            line: frame?.line ?? null,
+            col: frame?.col ?? null,
+            rule: header[2] ?? null,
+            message: headline(message),
+        };
+        out.push({ diagnostic, testFile, name: header[2] ?? null });
+        i = j - 1;
+    }
+    return out;
+}
+const JSON_STRING = '"(?:[^"\\\\]|\\\\.)*"';
+const DEPUG_TARGET = new RegExp(`(?:^|\\s)vitest run (${JSON_STRING}) -t (${JSON_STRING})(?:\\s|$)`);
+const REGEX_METACHARACTER = /[.*+?^${}()|[\]\\]/g;
+// depug's vitest reporter prints `depug evidence: <absolute path> (<note>)`
+// and, on the next line, `depug rerun: <command>`. The command is the only
+// place that names the test: `vitest run "<file>" -t "<pattern>"`, both
+// JSON strings, where the pattern is the names joined by a space, with
+// regex metacharacters escaped, between `^` and `$`. A pattern that does
+// not escape back to itself is not depug's, so it names nothing.
+function depugFailures(lines) {
+    const out = [];
+    for (let i = 0; i + 1 < lines.length; i += 1) {
+        const evidence = /^depug evidence: ((?:\/|[A-Za-z]:[\\/]).*?)(?: \([^()]*\))?$/.exec(lines[i]);
+        if (evidence === null)
+            continue;
+        const rerun = /^depug rerun: (\S.*)$/.exec(lines[i + 1]);
+        if (rerun === null)
+            continue;
+        i += 1;
+        const target = DEPUG_TARGET.exec(rerun[1]);
+        if (target === null)
+            continue;
+        let testFile;
+        let pattern;
+        try {
+            testFile = JSON.parse(target[1]);
+            pattern = JSON.parse(target[2]);
+        }
+        catch {
+            continue;
+        }
+        if (typeof testFile !== "string" || typeof pattern !== "string")
+            continue;
+        const anchored = /^\^(.*)\$$/s.exec(pattern);
+        if (anchored === null)
+            continue;
+        const name = anchored[1].replace(/\\([.*+?^${}()|[\]\\])/g, "$1");
+        if (name.replace(REGEX_METACHARACTER, "\\$&") !== anchored[1])
+            continue;
+        out.push({ testFile, name, evidence: evidence[1], rerun: rerun[1] });
+    }
+    return out;
+}
+// vitest's header joins the names with " > " and depug's pattern with a
+// space, so two tests can share a key ("a > b c" and "a b > c"), and a name
+// that itself holds " > " reads back as two names. The key names one test
+// only when exactly one diagnostic and one depug failure carry it.
+function attachDepug(failures, depug) {
+    const keyOf = (testFile, name) => JSON.stringify([testFile, name]);
+    const counts = new Map();
+    for (const failure of failures) {
+        if (failure.name === null)
+            continue;
+        const key = keyOf(failure.testFile, failure.name.split(" > ").join(" "));
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const byKey = new Map();
+    for (const entry of depug) {
+        const key = keyOf(entry.testFile, entry.name);
+        byKey.set(key, [...(byKey.get(key) ?? []), entry]);
+    }
+    return failures.map((failure) => {
+        if (failure.name === null)
+            return failure.diagnostic;
+        const key = keyOf(failure.testFile, failure.name.split(" > ").join(" "));
+        const matches = byKey.get(key) ?? [];
+        if (counts.get(key) !== 1 || matches.length !== 1)
+            return failure.diagnostic;
+        return { ...failure.diagnostic, evidence: matches[0].evidence, rerun: matches[0].rerun };
+    });
+}
+const STACK_FRAME = /^\s*at (?:.*? \()?(\S+?):(\d+):(\d+)\)?$/;
+function firstProjectFrame(lines, root) {
+    for (const line of lines) {
+        const found = STACK_FRAME.exec(line);
+        if (found === null)
+            continue;
+        const file = projectPath(found[1], root);
+        if (file !== null)
+            return { file, line: positive(found[2]), col: positive(found[3]) };
+    }
+    return null;
+}
+function locationOf(text, root) {
+    if (text === undefined)
+        return null;
+    const found = /^(.+?):(\d+):(\d+)$/.exec(text.trim());
+    if (found === null)
+        return text.trim().length === 0 ? null : { file: displayPath(text.trim(), root), line: null, col: null };
+    return { file: displayPath(found[1], root), line: positive(found[2]), col: positive(found[3]) };
+}
+// node --test with the spec reporter: after `✖ failing tests:`, each
+// failure is an optional `test at file:line:col`, `✖ name (time)`, and the
+// indented error with its `at` stack.
+function parseNodeTestSpec(lines, root) {
+    const start = lines.findIndex((line) => /^✖ failing tests:$/.test(line));
+    if (start === -1)
+        return [];
+    const fullNames = specFailures(lines.slice(0, start));
+    const out = [];
+    let location;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        const at = /^test at (.+)$/.exec(line);
+        if (at !== null) {
+            location = at[1];
+            continue;
+        }
+        const failed = /^✖ (.+?)(?: \([\d.]+m?s\))?$/.exec(line);
+        if (failed === null)
+            continue;
+        const body = [];
+        let j = i + 1;
+        for (; j < lines.length && (lines[j].startsWith(" ") || lines[j].length === 0); j += 1)
+            body.push(lines[j]);
+        const frameStart = body.findIndex((entry) => STACK_FRAME.test(entry));
+        const message = headline(frameStart === -1 ? body : body.slice(0, frameStart));
+        const where = firstProjectFrame(body, root) ?? locationOf(location, root);
+        out.push({
+            file: where?.file ?? "",
+            line: where?.line ?? null,
+            col: where?.col ?? null,
+            rule: takeFullName(fullNames, failed[1]),
+            message: message.replace(/^'(.*)'$/, "$1"),
+        });
+        location = undefined;
+        i = j - 1;
+    }
+    return out.filter((diagnostic) => diagnostic.file.length > 0);
+}
+// The failing section names a test by its own name only, so the tree above
+// it, two spaces per suite, gives the full name. A suite opens with `▶ name`
+// and closes with a `✖ name` line at the same depth.
+function specFailures(lines) {
+    const suites = [];
+    const failures = [];
+    for (const line of lines) {
+        const entry = /^((?: {2})*)([▶✖]) (.+?)(?: \([\d.]+m?s\))?$/.exec(line);
+        if (entry === null)
+            continue;
+        const depth = entry[1].length / 2;
+        if (entry[2] === "▶") {
+            suites.length = depth;
+            suites[depth] = entry[3];
+        }
+        else if (suites.length === depth + 1 && suites[depth] === entry[3]) {
+            suites.length = depth;
+        }
+        else {
+            failures.push([...suites.slice(0, depth), entry[3]].join(" > "));
+        }
+    }
+    return failures;
+}
+function takeFullName(fullNames, name) {
+    const index = fullNames.findIndex((full) => full === name || full.endsWith(` > ${name}`));
+    if (index === -1)
+        return name;
+    return fullNames.splice(index, 1)[0];
+}
+// node --test --test-reporter=tap: `# Subtest: name` lines nest by four
+// spaces, and each `not ok` carries a YAML block. A suite that failed only
+// because a subtest did (`subtestsFailed`) adds nothing of its own.
+function parseNodeTestTap(lines, root) {
+    const out = [];
+    const names = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const subtest = /^((?: {4})*)# Subtest: (.*)$/.exec(line);
+        if (subtest !== null) {
+            const depth = subtest[1].length / 4;
+            names.length = depth;
+            names[depth] = subtest[2];
+            continue;
+        }
+        const failed = /^((?: {4})*)not ok \d+ - (.*?)(?: # .*)?$/.exec(line);
+        if (failed === null)
+            continue;
+        const indent = failed[1];
+        const depth = indent.length / 4;
+        const fields = new Map();
+        let j = i + 1;
+        if (lines[j] === `${indent}  ---`) {
+            let key = null;
+            for (j += 1; j < lines.length && lines[j] !== `${indent}  ...`; j += 1) {
+                const entry = lines[j];
+                const field = entry.startsWith(`${indent}  `) ? /^([A-Za-z_]+):(?: (.*))?$/.exec(entry.slice(indent.length + 2)) : null;
+                if (field !== null) {
+                    key = field[1];
+                    const value = field[2] ?? "";
+                    fields.set(key, value === "|-" || value === "|" || value === ">-" ? [] : [unquote(value)]);
+                }
+                else if (key !== null) {
+                    fields.get(key).push(entry.slice(indent.length + 4));
+                }
+            }
+        }
+        i = j;
+        if (fields.get("failureType")?.[0] === "subtestsFailed")
+            continue;
+        const name = [...names.slice(0, depth), failed[2]].join(" > ");
+        const kind = fields.get("name")?.[0];
+        const error = headline(fields.get("error") ?? []);
+        const where = firstProjectFrame((fields.get("stack") ?? []).map((frame) => `at ${frame}`), root) ?? locationOf(fields.get("location")?.[0], root);
+        if (where === null)
+            continue;
+        out.push({
+            file: where.file,
+            line: where.line,
+            col: where.col,
+            rule: name,
+            message: clip(kind === undefined || kind.length === 0 ? error : `${kind}: ${error}`),
+        });
+    }
+    return out;
+}
+function unquote(value) {
+    const quoted = /^'(.*)'$/.exec(value);
+    return quoted === null ? value : quoted[1].replace(/''/g, "'");
+}
+// archstrict check: `[rule] /abs/path:line:col`, then the indented
+// evidence (after an optional `frozen: true`), `because:`, and `do:`. The
+// grouped form past 20 violations prints the same block for each example.
+function parseArchstrict(lines, root) {
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const head = /^\[([a-z][a-z0-9-]*)\] (.+?):(\d+):(\d+)$/.exec(lines[i]);
+        if (head === null)
+            continue;
+        let evidence = "";
+        for (let j = i + 1; j < lines.length && lines[j].startsWith("  "); j += 1) {
+            const entry = lines[j].trim();
+            if (entry === "frozen: true")
+                continue;
+            evidence = entry.replace(/^evidence: /, "");
+            break;
+        }
+        out.push({ file: displayPath(head[2], root), line: positive(head[3]), col: positive(head[4]), rule: head[1], message: clip(evidence) });
+    }
+    return out;
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+// Failures of firstlight itself: the error type every module throws, and the
+// one place that turns it into the {"error","do"} envelope on stderr.
+// A failing check is not this; checks are reported by report.ts.
+import { writeSync } from "node:fs";
+export class AgentError extends Error {
+    next;
+    constructor(message, next) {
+        super(message);
+        this.name = "AgentError";
+        this.next = next;
+    }
+}
+export function exitWithEnvelope(err) {
+    const body = err instanceof AgentError
+        ? { error: err.message, do: err.next }
+        : {
+            error: `internal error: ${err instanceof Error ? err.message : String(err)}`,
+            do: "rerun the same command; if it repeats, report it with this message",
+        };
+    writeSync(2, `${JSON.stringify(body)}\n`);
+    process.exit(1);
+}
+export function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/eta.js

@@ -0,0 +1,76 @@
+// The estimated time left for checks that have not finished, from how long
+// the same check took when it last passed. It only computes; reading earlier
+// runs is the store's, and printing the estimate is the report's. No I/O.
+import { isSettled } from "./checks.js";
+// Only a pass counts: a failed, timed-out, or cancelled check stopped early,
+// so its elapsed time says nothing about a full run. A changed `run` command
+// is a different check that happens to share the name.
+export function typicalDurations(specs, newestFirst) {
+    const typical = new Map();
+    for (const spec of specs) {
+        for (const past of newestFirst) {
+            const pastSpec = past.checks.find((check) => check.name === spec.name);
+            if (pastSpec === undefined || pastSpec.run !== spec.run)
+                continue;
+            const state = past.states.find((check) => check.name === spec.name);
+            if (state?.status === "passed" && state.elapsed_ms !== null) {
+                typical.set(spec.name, state.elapsed_ms);
+                break;
+            }
+        }
+    }
+    return typical;
+}
+export function estimate(views, specs, typical, now) {
+    const byName = new Map(views.map((view) => [view.name, view]));
+    const after = new Map(specs.map((spec) => [spec.name, spec.after]));
+    const memo = new Map();
+    // The after graph is acyclic once config.ts accepted it, so the recursion
+    // ends.
+    const remaining = (name) => {
+        const known = memo.get(name);
+        if (known !== undefined)
+            return known;
+        const result = remainingOf(name);
+        memo.set(name, result);
+        return result;
+    };
+    const remainingOf = (name) => {
+        const view = byName.get(name);
+        if (view === undefined)
+            return { eta_ms: null, overdue: false };
+        if (isSettled(view))
+            return { eta_ms: 0, overdue: false };
+        const usual = typical.get(name);
+        if (usual === undefined)
+            return { eta_ms: null, overdue: false };
+        if (view.status === "running") {
+            if (view.started_at === null)
+                return { eta_ms: null, overdue: false };
+            const elapsed = now - Date.parse(view.started_at);
+            return elapsed > usual ? { eta_ms: 0, overdue: true } : { eta_ms: usual - elapsed, overdue: false };
+        }
+        let wait = 0;
+        for (const dep of after.get(name) ?? []) {
+            const depEta = remaining(dep).eta_ms;
+            if (depEta === null)
+                return { eta_ms: null, overdue: false };
+            wait = Math.max(wait, depEta);
+        }
+        return { eta_ms: usual + wait, overdue: false };
+    };
+    const checks = new Map(views.map((view) => [view.name, remaining(view.name)]));
+    let overall = 0;
+    for (const view of views) {
+        if (isSettled(view))
+            continue;
+        const eta = checks.get(view.name).eta_ms;
+        overall = eta === null || overall === null ? null : Math.max(overall, eta);
+    }
+    return { checks, eta_ms: overall, typical };
+}
+// Whole seconds above 10 s, where a tenth is noise; one decimal below.
+export function formatSeconds(ms) {
+    const seconds = ms / 1000;
+    return seconds >= 10 ? `${Math.round(seconds)}s` : `${seconds.toFixed(1)}s`;
+}

package/dist/names.js

@@ -0,0 +1,67 @@
+// Check names as a person types them and as files on disk: the npm-run-all
+// glob over package.json script names, the log file name each check gets,
+// and the shell quoting of a word. It only computes; reading package.json is
+// config.ts's, and creating the files is the store's. No I/O.
+// npm-run-all reads "lint:*" as a path glob with ":" for "/", so "*" stays
+// inside one segment and "**" crosses them. Only "*" is special here; any
+// other character is literal.
+export function isPattern(word) {
+    return word.includes("*");
+}
+export function patternRegExp(pattern) {
+    let source = "";
+    for (const part of pattern.split(/(\*+)/)) {
+        if (part.length === 0)
+            continue;
+        if (part.startsWith("*"))
+            source += part.length === 1 ? "[^:]*" : ".*";
+        else
+            source += part.replace(/[\\^$.|?+()[\]{}]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`, "su");
+}
+export function matchesPattern(pattern, name) {
+    return patternRegExp(pattern).test(name);
+}
+// Keeps the order of `names`, which is package.json order, as npm-run-all
+// does.
+export function expandPattern(pattern, names) {
+    const re = patternRegExp(pattern);
+    return names.filter((name) => re.test(name));
+}
+// The supervisor writes its own stderr to supervisor.log beside the check
+// logs.
+const RESERVED_LOG_BASES = ["supervisor"];
+// Leaves room for "-<n>.log" under the usual 255-byte file name limit.
+const MAX_LOG_BASE = 100;
+export function logBase(name) {
+    const base = name.replace(/[^A-Za-z0-9._-]/gu, "_").slice(0, MAX_LOG_BASE);
+    return base.length === 0 ? "_" : base;
+}
+// Two names can map to one file ("a:b" and "a_b"), and on a case-insensitive
+// file system "Test" and "test" already do; a later claimant gets "-2",
+// "-3", and so on. A name that is already a safe base claims first, so a
+// check from firstlight.json keeps `<name>.log` whatever runs beside it.
+export function logFileNames(names) {
+    const files = new Map();
+    const taken = new Set(RESERVED_LOG_BASES);
+    const claim = (name) => {
+        if (files.has(name))
+            return;
+        const base = logBase(name);
+        let file = base;
+        for (let n = 2; taken.has(file.toLowerCase()); n += 1)
+            file = `${base}-${n}`;
+        taken.add(file.toLowerCase());
+        files.set(name, `${file}.log`);
+    };
+    for (const name of names)
+        if (logBase(name) === name)
+            claim(name);
+    for (const name of names)
+        claim(name);
+    return new Map(names.map((name) => [name, files.get(name)]));
+}
+export function shellQuote(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/processes.js

@@ -0,0 +1,56 @@
+// Process liveness and process-group signalling for pids firstlight started.
+// Nothing here looks processes up by name or pattern: every call takes a pid
+// that a run record or an event recorded.
+import { readFileSync } from "node:fs";
+export function isPidAlive(pid) {
+    if (pid === null || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+    return !isZombie(pid);
+}
+// A detached supervisor is reparented when the CLI exits. If the new parent
+// never reaps (a container whose pid 1 is not an init), a dead supervisor
+// stays a zombie and kill(pid, 0) keeps succeeding, which would hide an
+// orphan forever. Linux exposes the state in /proc; elsewhere we fall back
+// to kill(pid, 0) alone.
+function isZombie(pid) {
+    let stat;
+    try {
+        stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const state = stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3);
+    return state === "Z" || state === "X";
+}
+export function signalGroup(pgid, signal) {
+    if (!Number.isInteger(pgid) || pgid <= 0)
+        return false;
+    try {
+        process.kill(-pgid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function signalPid(pid, signal) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}