firstlight 0.0.0-stage → 0.2.0

package/dist/report.js

@@ -0,0 +1,288 @@
+// How a run looks to the agent that asked: short plain text by default, or
+// JSON Lines (one object per check, then one summary) with --json. It only
+// formats a RunSnapshot and its estimate; deciding exit codes and next
+// commands is the CLI's. A failed check's log is read through its parser,
+// when it has one, so its diagnostics come before the tail, each with the
+// evidence file and rerun command depug printed for it, when there are. `results --new`
+// gets its own text and JSON here too, from a comparison the CLI made.
+import { countFailures, isUnproven } from "./baseline.js";
+import { bucketOf, isSettled } from "./checks.js";
+import { formatDiagnostic, isParserName, parseDiagnostics } from "./diagnostics.js";
+import { formatSeconds } from "./eta.js";
+import { logPaths, readLogEnd, tailLines } from "./store.js";
+export const TAIL_LINES = 40;
+// With diagnostics, they carry the substance, and the tail only shows the
+// context the parser did not read, such as a summary.
+export const DIAGNOSTIC_TAIL_LINES = 10;
+export const DIAGNOSTIC_LIMIT = 20;
+// Every diagnostic in the log of one check of a run, through the parser
+// that run recorded for it.
+export function checkDiagnostics(run, dir, name) {
+    const parser = run.checks.find((check) => check.name === name)?.parser;
+    if (!isParserName(parser))
+        return [];
+    return parseDiagnostics(parser, readLogEnd(logPaths(dir, run.checks).get(name)), run.root);
+}
+// `shown` narrows the diagnostics printed, as `results --new` does; the
+// tail stays short whenever the log has any.
+function logReport(snapshot, view, file, shown) {
+    const all = checkDiagnostics(snapshot.run, snapshot.dir, view.name);
+    const printed = shown ?? all;
+    return {
+        diagnostics: printed.slice(0, DIAGNOSTIC_LIMIT),
+        more: Math.max(0, printed.length - DIAGNOSTIC_LIMIT),
+        tail: tailLines(file, all.length > 0 ? DIAGNOSTIC_TAIL_LINES : TAIL_LINES),
+    };
+}
+function comparedOf(comparison, view) {
+    return { baseline: comparison.baselines.get(view.name) ?? null, comparison: comparison.checks.get(view.name) };
+}
+export function summarize(snapshot, next, eta) {
+    const summary = {
+        type: "summary",
+        run: snapshot.run.id,
+        failed: [],
+        running: [],
+        passed: [],
+        cancelled: [],
+        next,
+        eta_ms: roundMs(eta.eta_ms),
+    };
+    for (const view of snapshot.checks)
+        summary[bucketOf(view.status)].push(view.name);
+    return summary;
+}
+function showsLog(view) {
+    return view.status === "failed" || view.status === "timed_out";
+}
+export function jsonLines(snapshot, next, eta) {
+    const lines = snapshot.checks.map((view) => checkJson(snapshot, view, eta));
+    lines.push(JSON.stringify(summarize(snapshot, next, eta)));
+    return `${lines.join("\n")}\n`;
+}
+// One line for the check, then, for a failed check, one line per
+// diagnostic, without a trailing newline. With `compared`, the check line
+// gains `new` and `baseline` (and `old_diagnostics` when it failed), and
+// only the new diagnostics follow it.
+export function checkJson(snapshot, view, eta, compared) {
+    const log = logPaths(snapshot.dir, snapshot.run.checks).get(view.name);
+    const checkEta = etaOf(eta, view);
+    const line = {
+        type: "check",
+        name: view.name,
+        status: view.status,
+        exit_code: view.exit_code,
+        elapsed_ms: view.elapsed_ms,
+        log,
+        eta_ms: roundMs(checkEta.eta_ms),
+        overdue: checkEta.overdue,
+        cached_from: view.cached_from,
+    };
+    if (view.orphan)
+        line.orphan = true;
+    if (compared !== undefined) {
+        line.new = compared.comparison?.isNew ?? false;
+        line.baseline = compared.baseline;
+    }
+    if (!showsLog(view))
+        return JSON.stringify(line);
+    if (compared !== undefined)
+        line.old_diagnostics = compared.comparison?.oldDiagnostics ?? 0;
+    const report = logReport(snapshot, view, log, compared?.comparison?.newDiagnostics);
+    if (report.more > 0)
+        line.more_diagnostics = report.more;
+    line.tail = report.tail;
+    const diagnostics = report.diagnostics.map((diagnostic) => JSON.stringify({
+        type: "diagnostic",
+        check: view.name,
+        file: diagnostic.file,
+        line: diagnostic.line,
+        col: diagnostic.col,
+        rule: diagnostic.rule,
+        message: diagnostic.message,
+        ...depugFields(diagnostic),
+    }));
+    return [JSON.stringify(line), ...diagnostics].join("\n");
+}
+// `focus` puts one check first with its log, as `run` does for the check
+// that failed first; the others get one status line each.
+export function text(snapshot, next, eta, focus = null) {
+    const out = [];
+    const ordered = focus === null
+        ? snapshot.checks
+        : [...snapshot.checks.filter((v) => v.name === focus), ...snapshot.checks.filter((v) => v.name !== focus)];
+    for (const view of ordered) {
+        out.push(statusLine(snapshot, view, eta));
+        if (showsLog(view) && (focus === null || view.name === focus))
+            out.push(...logBlock(snapshot, view));
+    }
+    return `${out.join("\n")}\n${summaryText(snapshot, next, eta)}`;
+}
+// The lines after the check lines: the counts, then the next command.
+export function summaryText(snapshot, next, eta) {
+    const out = [countsLine(snapshot, eta)];
+    if (next !== null) {
+        const waiting = !snapshot.checks.every(isSettled) && eta.eta_ms !== null;
+        out.push(waiting ? `next: ${next} (about ${formatSeconds(eta.eta_ms)} left)` : `next: ${next}`);
+    }
+    return `${out.join("\n")}\n`;
+}
+// One status change, as `follow` prints it. A running check gets no
+// elapsed time: when `follow` replays history, the time since it started
+// is not the time it had run when it changed.
+export function changeText(snapshot, view, eta) {
+    if (view.status === "running") {
+        const checkEta = etaOf(eta, view);
+        return checkEta.eta_ms === null
+            ? `${view.name} running\n`
+            : `${view.name} running (about ${formatSeconds(checkEta.eta_ms)} left)\n`;
+    }
+    const out = [statusLine(snapshot, view, eta)];
+    if (showsLog(view))
+        out.push(...logBlock(snapshot, view));
+    return `${out.join("\n")}\n`;
+}
+function logBlock(snapshot, view, compared) {
+    const file = logPaths(snapshot.dir, snapshot.run.checks).get(view.name);
+    const report = logReport(snapshot, view, file, compared?.comparison?.newDiagnostics);
+    const more = report.more === 0 ? [] : [`  (${report.more} more ${plural(report.more, "diagnostic")} in the log)`];
+    const old = compared?.comparison?.oldDiagnostics ?? 0;
+    const known = old === 0 ? [] : [`  (${old} ${plural(old, "diagnostic")} already in run ${compared.baseline})`];
+    return [
+        ...report.diagnostics.flatMap((diagnostic) => [`  ${formatDiagnostic(diagnostic)}`, ...depugLines(diagnostic)]),
+        ...more,
+        ...known,
+        `  log: ${file}`,
+        ...(report.tail.length === 0 ? ["    (no output)"] : report.tail.map((line) => `    ${line}`)),
+    ];
+}
+function depugFields(diagnostic) {
+    return diagnostic.evidence === undefined ? {} : { evidence: diagnostic.evidence, rerun: diagnostic.rerun };
+}
+function depugLines(diagnostic) {
+    return [
+        ...(diagnostic.evidence === undefined ? [] : [`    evidence: ${diagnostic.evidence}`]),
+        ...(diagnostic.rerun === undefined ? [] : [`    rerun: ${diagnostic.rerun}`]),
+    ];
+}
+export function summarizeNew(snapshot, comparison, next, eta) {
+    const counts = countFailures([...comparison.checks.values()]);
+    return {
+        ...summarize(snapshot, next, eta),
+        new: [...comparison.checks.values()].filter((check) => check.isNew).map((check) => check.name),
+        new_failures: counts.new,
+        old_failures: counts.old,
+        no_baseline: snapshot.checks.filter((view) => !comparison.baselines.has(view.name)).map((view) => view.name),
+    };
+}
+// Every check, as `results --json` prints it with the fields of `compared`,
+// then only the new diagnostics, then the summary.
+export function newJsonLines(snapshot, comparison, next, eta) {
+    const lines = snapshot.checks.map((view) => checkJson(snapshot, view, eta, comparedOf(comparison, view)));
+    lines.push(JSON.stringify(summarizeNew(snapshot, comparison, next, eta)));
+    return `${lines.join("\n")}\n`;
+}
+// Only the checks with a new failure, with their new diagnostics, and the
+// checks that proved nothing yet; passes and known failures are counts.
+export function newText(snapshot, comparison, next, eta) {
+    const out = [];
+    for (const view of snapshot.checks) {
+        const compared = comparedOf(comparison, view);
+        if (compared.comparison?.isNew === true) {
+            out.push(statusLine(snapshot, view, eta), ...logBlock(snapshot, view, compared));
+        }
+        else if (isUnproven(view.status)) {
+            out.push(statusLine(snapshot, view, eta));
+        }
+    }
+    const summary = summarizeNew(snapshot, comparison, next, eta);
+    if (comparison.baselines.size === 0) {
+        out.push("no earlier run to compare with, so every failure counts as new");
+    }
+    else {
+        const missing = [...comparison.checks.keys()].filter((name) => !comparison.baselines.has(name));
+        if (missing.length > 0) {
+            out.push(`no earlier result for ${missing.join(", ")}, so ${missing.length === 1 ? "its" : "their"} failures count as new`);
+        }
+    }
+    const skipped = snapshot.checks.filter((view) => view.status === "skipped").length;
+    const notNew = [
+        summary.old_failures > 0 ? `${summary.old_failures} ${plural(summary.old_failures, "failure")} already in the previous run` : "",
+        summary.passed.length > 0 ? `${summary.passed.length} passed` : "",
+        skipped > 0 ? `${skipped} skipped` : "",
+    ].filter((part) => part !== "");
+    if (notNew.length > 0)
+        out.push(`not new: ${notNew.join(", ")}`);
+    const fresh = summary.new_failures === 0 ? "no new failures" : `${summary.new_failures} new ${plural(summary.new_failures, "failure")}`;
+    const unproven = [
+        ["running", summary.running.length],
+        ["cancelled", summary.cancelled.length],
+        ["unknown", snapshot.checks.filter((view) => view.status === "unknown").length],
+    ]
+        .filter(([, count]) => count !== 0)
+        .map(([kind, count]) => `${count} ${kind}`);
+    out.push(`run ${snapshot.run.id}: ${[fresh, ...unproven].join(", ")}`);
+    if (next !== null) {
+        const waiting = !snapshot.checks.every(isSettled) && eta.eta_ms !== null;
+        out.push(waiting ? `next: ${next} (about ${formatSeconds(eta.eta_ms)} left)` : `next: ${next}`);
+    }
+    return `${out.join("\n")}\n`;
+}
+function plural(count, word) {
+    return count === 1 ? word : `${word}s`;
+}
+export function allPassedText(snapshot) {
+    const seconds = (Date.now() - Date.parse(snapshot.run.started_at)) / 1000;
+    const count = snapshot.checks.length;
+    const cached = cachedCount(snapshot);
+    const notes = cached === 0 ? `run ${snapshot.run.id}` : `${cached} cached, run ${snapshot.run.id}`;
+    return `passed ${count} check${count === 1 ? "" : "s"} in ${seconds.toFixed(1)}s (${notes})\n`;
+}
+function statusLine(snapshot, view, eta) {
+    const details = [];
+    if (view.orphan) {
+        details.push("orphan: the supervisor is gone, so the result is unknown");
+    }
+    else if (view.cached_from !== null) {
+        details.push(`cached from run ${view.cached_from}`);
+        if (view.elapsed_ms !== null)
+            details.push(`${(view.elapsed_ms / 1000).toFixed(1)}s originally`);
+    }
+    else if (view.status === "skipped") {
+        const spec = snapshot.run.checks.find((check) => check.name === view.name);
+        details.push(`needs ${spec?.after.join(", ") ?? "?"}`);
+    }
+    else {
+        if (view.exit_code !== null)
+            details.push(`exit ${view.exit_code}`);
+        const elapsed = view.elapsed_ms ?? (view.status === "running" && view.started_at !== null ? Date.now() - Date.parse(view.started_at) : null);
+        if (elapsed !== null)
+            details.push(`${(elapsed / 1000).toFixed(1)}s`);
+        const checkEta = etaOf(eta, view);
+        const usual = eta.typical.get(view.name);
+        if (checkEta.overdue && usual !== undefined) {
+            details.push(`past its usual ${(usual / 1000).toFixed(1)}s`);
+        }
+        else if (!isSettled(view) && checkEta.eta_ms !== null) {
+            details.push(`about ${formatSeconds(checkEta.eta_ms)} left`);
+        }
+    }
+    return details.length === 0 ? `${view.name} ${view.status}` : `${view.name} ${view.status} (${details.join(", ")})`;
+}
+function countsLine(snapshot, eta) {
+    const summary = summarize(snapshot, null, eta);
+    const parts = ["failed", "running", "cancelled", "passed"]
+        .filter((bucket) => summary[bucket].length > 0)
+        .map((bucket) => `${summary[bucket].length} ${bucket}`);
+    const cached = cachedCount(snapshot);
+    return `run ${snapshot.run.id}: ${parts.join(", ")}${cached === 0 ? "" : ` (${cached} cached)`}`;
+}
+function cachedCount(snapshot) {
+    return snapshot.checks.filter((view) => view.cached_from !== null).length;
+}
+function etaOf(eta, view) {
+    return eta.checks.get(view.name) ?? { eta_ms: null, overdue: false };
+}
+function roundMs(ms) {
+    return ms === null ? null : Math.round(ms);
+}

package/dist/store.js

@@ -0,0 +1,360 @@
+// The on-disk state of runs under XDG_STATE_HOME, never inside the checked
+// repository: repository identity, run ids, run.json, events.jsonl, the
+// `current` pointer, check logs, and pruning, and the earlier runs read back
+// for the time-left estimate, for reused passes, and for the baselines of
+// `results --new`. The CLI writes run.json and `current`; only the
+// supervisor appends to events.jsonl.
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, closeSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { CHECK_STATUSES, foldEvents, IllegalTransition, presentChecks, } from "./checks.js";
+import { findBaselines } from "./baseline.js";
+import { findReuse } from "./cache.js";
+import { AgentError, messageOf } from "./errors.js";
+import { typicalDurations } from "./eta.js";
+import { logFileNames } from "./names.js";
+import { isPidAlive } from "./processes.js";
+export const KEEP_RUNS = 20;
+const RUN_ID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function resolveRoot(cwd) {
+    let dir;
+    try {
+        dir = realpathSync(cwd);
+        if (!statSync(dir).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch {
+        throw new AgentError(`not a directory: ${cwd}`, "pass an existing directory to --cwd");
+    }
+    try {
+        const env = { ...process.env };
+        delete env.GIT_DIR;
+        delete env.GIT_WORK_TREE;
+        const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: dir,
+            env,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        }).trim();
+        if (top.length > 0)
+            return top;
+    }
+    catch {
+        // Not a git repository, or no git: the directory itself is the root.
+    }
+    return dir;
+}
+export function stateBase() {
+    const fromEnv = process.env.XDG_STATE_HOME?.trim();
+    const base = fromEnv && fromEnv.length > 0 ? fromEnv : path.join(homedir(), ".local", "state");
+    return path.resolve(base, "firstlight");
+}
+export function repoKey(root) {
+    return createHash("sha256").update(root).digest("hex").slice(0, 16);
+}
+export class RepoState {
+    root;
+    dir;
+    constructor(root) {
+        this.root = root;
+        this.dir = path.join(stateBase(), repoKey(root));
+    }
+    runDir(id) {
+        return path.join(this.dir, "runs", id);
+    }
+    currentId() {
+        let text;
+        try {
+            text = readFileSync(path.join(this.dir, "current"), "utf8").trim();
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return null;
+            throw new AgentError(`could not read the current run: ${messageOf(err)}`, `check permissions on ${this.dir}`);
+        }
+        return RUN_ID_RE.test(text) ? text : null;
+    }
+    setCurrent(id) {
+        atomicWrite(path.join(this.dir, "current"), `${id}\n`);
+    }
+    createRun(checks, cacheKeys, reused) {
+        const id = newRunId();
+        mkdirSync(this.runDir(id), { recursive: true });
+        const run = {
+            id,
+            root: this.root,
+            supervisor_pid: null,
+            started_at: new Date().toISOString(),
+            checks,
+            cache_keys: Object.fromEntries(cacheKeys),
+            reused: Object.fromEntries(reused),
+        };
+        this.writeRun(run);
+        return run;
+    }
+    writeRun(run) {
+        atomicWrite(path.join(this.runDir(run.id), "run.json"), `${JSON.stringify(run, null, 2)}\n`);
+    }
+    readRun(id) {
+        const file = path.join(this.runDir(id), "run.json");
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            throw new AgentError(`could not read ${file}: ${messageOf(err)}`, "start a new run with `firstlight run`");
+        }
+        if (!isRunRecord(raw)) {
+            throw new AgentError(`unreadable run record: ${file}`, "start a new run with `firstlight run`");
+        }
+        return raw;
+    }
+    snapshot(id) {
+        const run = this.readRun(id);
+        const dir = this.runDir(id);
+        const names = run.checks.map((check) => check.name);
+        let folded = this.fold(dir, names);
+        let supervisorAlive = true;
+        if (folded.outcome === null) {
+            supervisorAlive = isPidAlive(run.supervisor_pid);
+            // The supervisor writes its final event and then exits; read again so
+            // that ordering is never mistaken for an orphan.
+            if (!supervisorAlive)
+                folded = this.fold(dir, names);
+        }
+        return { run, dir, outcome: folded.outcome, supervisorAlive, checks: presentChecks(folded, supervisorAlive) };
+    }
+    fold(dir, names) {
+        try {
+            return foldEvents(names, readEvents(path.join(dir, "events.jsonl")));
+        }
+        catch (err) {
+            if (err instanceof IllegalTransition) {
+                throw new AgentError(`inconsistent events in ${path.join(dir, "events.jsonl")}: ${err.message}`, "start a new run with `firstlight run`");
+            }
+            throw err;
+        }
+    }
+    typicalDurations(run) {
+        const past = this.pastRuns()
+            .filter((files) => files.record.id < run.id)
+            .map((files) => ({ checks: files.record.checks, states: files.states }));
+        return typicalDurations(run.checks, past);
+    }
+    // The run each check of `run` is compared with, keyed by check name, with
+    // that run's record, whose parser and log the comparison reads.
+    baselines(run) {
+        const past = this.pastRuns().filter((files) => files.record.id < run.id);
+        const records = new Map(past.map((files) => [files.record.id, files.record]));
+        const found = findBaselines(run.checks, past.map((files) => ({ id: files.record.id, checks: files.record.checks, states: files.states })));
+        return new Map([...found].map(([name, baseline]) => [name, { ...baseline, record: records.get(baseline.run) }]));
+    }
+    // Called before the new run exists, so every kept run is earlier.
+    reusable(cacheKeys) {
+        const past = this.pastRuns().map((files) => ({
+            id: files.record.id,
+            keys: files.record.cache_keys ?? {},
+            states: files.states,
+        }));
+        return findReuse(cacheKeys, past);
+    }
+    // Newest first. Only the kept runs are read, so the history costs no file
+    // of its own. An earlier run that no longer reads cleanly is history with
+    // nothing to say, not a reason to fail the current command.
+    pastRuns() {
+        const past = [];
+        for (const id of this.runIds()) {
+            try {
+                const record = this.readRun(id);
+                const names = record.checks.map((check) => check.name);
+                const folded = foldEvents(names, readEvents(eventsPath(this.runDir(id))));
+                past.push({ record, states: folded.checks });
+            }
+            catch {
+                continue;
+            }
+        }
+        return past;
+    }
+    // Newest first. Run ids sort by creation time.
+    runIds() {
+        let names;
+        try {
+            names = readdirSync(path.join(this.dir, "runs"));
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return [];
+            throw err;
+        }
+        return names.filter((name) => RUN_ID_RE.test(name)).sort().reverse();
+    }
+    prune(keep = KEEP_RUNS) {
+        for (const id of this.runIds().slice(keep)) {
+            rmSync(this.runDir(id), { recursive: true, force: true });
+        }
+    }
+}
+// Derived from the run's own check list on every read, so run.json needs no
+// field for it and a run written before script and command checks existed
+// keeps `<name>.log`.
+export function logPaths(runDir, checks) {
+    const files = logFileNames(checks.map((check) => check.name));
+    return new Map([...files].map(([name, file]) => [name, path.join(runDir, file)]));
+}
+export function eventsPath(runDir) {
+    return path.join(runDir, "events.jsonl");
+}
+// One appendFileSync per event is one write(2) with O_APPEND, so a reader
+// never sees two events interleaved.
+export function appendEvent(runDir, event) {
+    appendFileSync(eventsPath(runDir), `${JSON.stringify(event)}\n`);
+}
+export function readEvents(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return [];
+        throw err;
+    }
+    const lines = text.split("\n");
+    // A line without its newline may still be in the middle of being written.
+    lines.pop();
+    const events = [];
+    for (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            throw new AgentError(`unreadable line in ${file}: ${line}`, "start a new run with `firstlight run`");
+        }
+        if (!isEvent(raw)) {
+            throw new AgentError(`unexpected event in ${file}: ${line}`, "start a new run with `firstlight run`");
+        }
+        events.push(raw);
+    }
+    return events;
+}
+const TAIL_BYTES = 256 * 1024;
+export function tailLines(file, count) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return [];
+        throw err;
+    }
+    try {
+        const size = statSync(file).size;
+        const length = Math.min(size, TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, size - length);
+        const lines = buffer.toString("utf8").split("\n");
+        if (lines.at(-1) === "")
+            lines.pop();
+        // The first line is partial when the read started mid-file.
+        if (length < size)
+            lines.shift();
+        return lines.slice(-count);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// Enough for any log a parser reads in practice. A longer log keeps its
+// end, where test runners print their failures.
+const PARSE_BYTES = 8 * 1024 * 1024;
+export function readLogEnd(file) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return "";
+        throw err;
+    }
+    try {
+        const size = statSync(file).size;
+        const length = Math.min(size, PARSE_BYTES);
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function newRunId(now = Date.now()) {
+    let time = now;
+    let timeChars = "";
+    for (let i = 0; i < 10; i += 1) {
+        timeChars = CROCKFORD[time % 32] + timeChars;
+        time = Math.floor(time / 32);
+    }
+    let randomChars = "";
+    for (const byte of randomBytes(16))
+        randomChars += CROCKFORD[byte % 32];
+    return timeChars + randomChars;
+}
+function atomicWrite(file, text) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, "utf8");
+    renameSync(tmp, file);
+}
+function isRunRecord(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.id !== "string" || typeof value.root !== "string" || typeof value.started_at !== "string")
+        return false;
+    if (!(value.supervisor_pid === null || Number.isInteger(value.supervisor_pid)))
+        return false;
+    if (!Array.isArray(value.checks))
+        return false;
+    if (value.cache_keys !== undefined && !isStringRecord(value.cache_keys))
+        return false;
+    if (value.reused !== undefined && !isReuseRecord(value.reused))
+        return false;
+    return value.checks.every((check) => isRecord(check) &&
+        typeof check.name === "string" &&
+        typeof check.run === "string" &&
+        Array.isArray(check.after) &&
+        typeof check.timeoutSec === "number" &&
+        (check.parser === undefined || check.parser === null || typeof check.parser === "string"));
+}
+function isEvent(value) {
+    if (!isRecord(value) || typeof value.at !== "string")
+        return false;
+    if (value.type === "run")
+        return value.status === "done" || value.status === "cancelled";
+    return (value.type === "check" &&
+        typeof value.check === "string" &&
+        CHECK_STATUSES.includes(value.status) &&
+        (value.cached_from === undefined || typeof value.cached_from === "string"));
+}
+function isStringRecord(value) {
+    return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isReuseRecord(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((entry) => isRecord(entry) && typeof entry.run === "string" && typeof entry.elapsed_ms === "number"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEnoent(err) {
+    return err.code === "ENOENT";
+}