firstlight 0.0.0-stage → 0.3.0

package/dist/store.js

@@ -0,0 +1,369 @@
+// 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 newest pass of each check in any kept run, for checks that no run
+    // holds yet, as `firstlight init` proposes them.
+    passDurations(specs) {
+        const past = this.pastRuns().map((files) => ({ checks: files.record.checks, states: files.states }));
+        return typicalDurations(specs, 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" ||
+            (Array.isArray(check.parser) && check.parser.every((name) => typeof name === "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";
+}

package/dist/supervisor.js

@@ -0,0 +1,188 @@
+// The per-run supervisor: a detached process that starts each check when
+// its `after` checks have passed, waits on it, enforces its timeout, and
+// appends every status change to events.jsonl. It is the only writer of
+// that file, so it also records the passes the CLI chose to reuse, before
+// it starts anything, and their dependents start at once. It exits when every check is terminal, or after SIGTERM once
+// it has cancelled what was left. It prints nothing; the CLI reads the file.
+import { spawn } from "node:child_process";
+import { appendFileSync, closeSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { constants } from "node:os";
+import path from "node:path";
+import { advance, initialState, isTerminal, } from "./checks.js";
+import { signalGroup } from "./processes.js";
+import { appendEvent, logPaths } from "./store.js";
+export const SUPERVISE_COMMAND = "__supervise";
+export const GRACE_MS = 3_000;
+const KILL_WAIT_MS = 2_000;
+export function supervise(runDir) {
+    const run = JSON.parse(readFileSync(path.join(runDir, "run.json"), "utf8"));
+    new Supervisor(run, runDir).start();
+}
+class Supervisor {
+    run;
+    runDir;
+    logs;
+    states = new Map();
+    running = new Map();
+    stopping = false;
+    finished = false;
+    constructor(run, runDir) {
+        this.run = run;
+        this.runDir = runDir;
+        this.logs = logPaths(runDir, run.checks);
+        for (const check of run.checks)
+            this.states.set(check.name, initialState(check.name));
+    }
+    start() {
+        for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+            process.on(signal, () => {
+                void this.stop();
+            });
+        }
+        for (const check of this.run.checks) {
+            const reuse = this.run.reused?.[check.name];
+            if (reuse === undefined)
+                continue;
+            // The log is written so its path in the output points at something
+            // that says why this run has no output of its own.
+            writeFileSync(this.logs.get(check.name), `firstlight: not run; passed in run ${reuse.run} on the same working tree with the same command\n`);
+            this.record(check.name, "passed", { exit_code: 0, elapsed_ms: reuse.elapsed_ms, cached_from: reuse.run });
+        }
+        this.schedule();
+    }
+    record(name, status, extra = {}) {
+        const event = { type: "check", check: name, status, ...extra, at: new Date().toISOString() };
+        this.states.set(name, advance(this.states.get(name), event));
+        appendEvent(this.runDir, event);
+    }
+    status(name) {
+        return this.states.get(name).status;
+    }
+    schedule() {
+        if (this.stopping || this.finished)
+            return;
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const check of this.run.checks) {
+                if (this.status(check.name) !== "pending")
+                    continue;
+                const deps = check.after.map((dep) => this.status(dep));
+                if (deps.some((status) => isTerminal(status) && status !== "passed")) {
+                    this.record(check.name, "skipped");
+                    changed = true;
+                }
+                else if (deps.every((status) => status === "passed")) {
+                    this.launch(check);
+                    changed = true;
+                }
+            }
+        }
+        if (this.run.checks.every((check) => isTerminal(this.status(check.name)))) {
+            this.finish("done");
+        }
+    }
+    launch(check) {
+        const log = this.logs.get(check.name);
+        const fd = openSync(log, "a");
+        let child;
+        try {
+            // detached gives the check its own process group, so one signal to
+            // -pid reaches everything the shell started.
+            child = spawn("/bin/sh", ["-c", check.run], {
+                cwd: this.run.root,
+                detached: true,
+                stdio: ["ignore", fd, fd],
+                env: process.env,
+            });
+        }
+        finally {
+            closeSync(fd);
+        }
+        const startedMs = Date.now();
+        const pid = child.pid;
+        if (pid === undefined) {
+            child.once("error", (err) => {
+                appendFileSync(log, `firstlight: could not start /bin/sh: ${err.message}\n`);
+            });
+            this.record(check.name, "running");
+            this.record(check.name, "failed", { exit_code: null, elapsed_ms: 0 });
+            return;
+        }
+        let markExited = () => { };
+        const exited = new Promise((resolve) => {
+            markExited = resolve;
+        });
+        const entry = {
+            pid,
+            startedMs,
+            timedOut: false,
+            exited,
+            timer: setTimeout(() => {
+                entry.timedOut = true;
+                void this.terminate(entry);
+            }, check.timeoutSec * 1000),
+        };
+        this.running.set(check.name, entry);
+        this.record(check.name, "running", { pid });
+        child.on("exit", (code, signal) => {
+            clearTimeout(entry.timer);
+            this.running.delete(check.name);
+            const exitCode = exitCodeOf(code, signal);
+            const status = entry.timedOut
+                ? "timed_out"
+                : this.stopping
+                    ? "cancelled"
+                    : exitCode === 0
+                        ? "passed"
+                        : "failed";
+            this.record(check.name, status, { pid, exit_code: exitCode, elapsed_ms: Date.now() - startedMs });
+            markExited();
+            this.schedule();
+        });
+    }
+    // SIGKILL only while the shell is still unreaped: once it has exited its
+    // pid, and with it the group id, may belong to a process we did not start.
+    async terminate(entry) {
+        signalGroup(entry.pid, "SIGTERM");
+        const gone = await Promise.race([entry.exited.then(() => true), delay(GRACE_MS).then(() => false)]);
+        if (!gone)
+            signalGroup(entry.pid, "SIGKILL");
+    }
+    async stop() {
+        if (this.stopping || this.finished)
+            return;
+        this.stopping = true;
+        const entries = [...this.running.values()];
+        await Promise.all(entries.map((entry) => this.terminate(entry)));
+        await Promise.race([Promise.all(entries.map((entry) => entry.exited)), delay(KILL_WAIT_MS)]);
+        for (const check of this.run.checks) {
+            if (!isTerminal(this.status(check.name))) {
+                this.record(check.name, "cancelled", this.status(check.name) === "running" ? { exit_code: null } : {});
+            }
+        }
+        this.finish("cancelled");
+    }
+    finish(outcome) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        appendEvent(this.runDir, { type: "run", status: outcome, at: new Date().toISOString() });
+        process.exit(0);
+    }
+}
+// A signal death is recorded with the shell convention, 128 plus the
+// signal number, because the signal was observed rather than guessed.
+function exitCodeOf(code, signal) {
+    if (code !== null)
+        return code;
+    if (signal !== null) {
+        const number = constants.signals[signal];
+        if (number !== undefined)
+            return 128 + number;
+    }
+    return null;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/tree.js

@@ -0,0 +1,60 @@
+// The tree key: the git tree hash of the working tree as it is on disk,
+// untracked files included and ignored files left out. It is the part of a
+// cache key that stands for the files a check reads. It runs git against a
+// temporary index of its own; the user's index and refs stay as they were.
+// Blobs for changed files land in the object store as loose objects, which
+// git's own gc prunes like any other unreferenced object.
+import { execFileSync } from "node:child_process";
+import { copyFileSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+const GIT_TIMEOUT_MS = 60_000;
+// Not a git repository, no git, or any git failure gives null: without a
+// key nothing is reused, which is never wrong, only slower.
+export function treeKey(root) {
+    const base = { ...process.env };
+    delete base.GIT_DIR;
+    delete base.GIT_WORK_TREE;
+    delete base.GIT_INDEX_FILE;
+    const git = (args, env = base) => execFileSync("git", args, {
+        cwd: root,
+        env,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: GIT_TIMEOUT_MS,
+    }).trim();
+    let realIndex;
+    try {
+        // A directory inside some other repository is not that repository's root.
+        if (realpathSync(git(["rev-parse", "--show-toplevel"])) !== realpathSync(root))
+            return null;
+        realIndex = path.resolve(root, git(["rev-parse", "--git-path", "index"]));
+    }
+    catch {
+        return null;
+    }
+    const dir = mkdtempSync(path.join(tmpdir(), "firstlight-index-"));
+    const index = path.join(dir, "index");
+    const env = { ...base, GIT_INDEX_FILE: index };
+    try {
+        // A copy of the real index carries its stat data, so `git add` hashes
+        // only the files that changed. A copy git cannot use (a split index,
+        // say) falls back to an empty index, which only costs time.
+        for (const seed of [true, false]) {
+            rmSync(index, { force: true });
+            try {
+                if (seed)
+                    copyFileSync(realIndex, index);
+                git(["add", "-A"], env);
+                return git(["write-tree"], env);
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "firstlight",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Run lint, typecheck, and tests in parallel for a coding agent, and return at the first failure.",
+  "keywords": [
+    "parallel",
+    "checks",
+    "lint",
+    "typecheck",
+    "test-runner",
+    "npm-run-all",
+    "coding-agents"
+  ],
+  "license": "MIT",
+  "author": "meganemura",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meganemura/firstlight.git"
+  },
+  "homepage": "https://github.com/meganemura/firstlight#readme",
+  "bugs": {
+    "url": "https://github.com/meganemura/firstlight/issues"
+  },
+  "type": "module",
+  "bin": {
+    "firstlight": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:scenarios": "nuka check && nuka run features",
+    "typecheck": "tsc --noEmit",
+    "archstrict": "archstrict check",
+    "mutation": "stryker run",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@hegeldev/hegel": "0.4.5",
+    "@meganemura/depug": "0.1.3",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
+    "@types/node": "26.5.1",
+    "archstrict": "0.1.0",
+    "nukadoko": "0.14.0",
+    "stryker-agent-reporter": "0.1.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "overrides": {
+    "zod": "4.6.5",
+    "ip-address": "10.7.3"
+  }
+}