firstlight 0.0.0-stage → 0.2.0

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,60 @@
 {
   "name": "firstlight",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+    "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",
+    "stryker-agent-reporter": "0.1.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "overrides": {
+    "zod": "4.6.5",
+    "ip-address": "10.7.3"
+  }
+}