firstlight 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## Unreleased
+## 0.3.0 (2026-10-16)
+
+- A version bump that lands on `main` now publishes the package: `publish.yml` runs on a push to `main` that changes `package.json`, releases nothing when the `v<version>` tag already exists, and after `npm publish` creates that tag and the GitHub release on the published commit. Nobody pushes a release tag by hand.
+
+- A check whose command, or whose `npm run` script, joins simple commands with `&&` gets the parser of each command that has one, in order, so `tsc --noEmit && vitest run` shows tsc's or vitest's diagnostics instead of a 40-line log tail. `parser` in `firstlight.json` and the parser recorded in `run.json` can be a list, like `["tsc", "vitest"]`, and `firstlight init` writes one for such a script. A list joined by `||` or `;`, or a pipe, still gets none.
+
+- The README has a CPU contention section: measurements of checks run alone and together in three repositories, why firstlight has no concurrency limit, and how `after` trades a longer run for an earlier result of one heavy check.
+
+- `firstlight init [script|pattern...]` proposes a `firstlight.json` from the `package.json` scripts and prints it; `--write` writes it, and refuses to replace an existing one without `--force`. With no names, it holds the scripts `lint`, `typecheck`, `test`, and `archstrict` that exist; names and patterns pick other scripts. Each check runs `npm run <script>`, gets the parser inferred from the script, and gets a `timeoutSec` of three times its newest pass, in whole minutes, when that is more than the 600-second default. It names the check-like scripts it left out, with the command that adds them. `--json` prints one `{"type":"init",...}` object. A shell command, an unknown script, a missing `package.json`, or a package with none of the four scripts and no names gives the error envelope.
+- A check name in `firstlight.json` may contain `:`, so a check can keep its script's name, like `check:architecture`.
+
+- Without `firstlight.json`, `firstlight run` names the `package.json` scripts it did not run whose name starts with `lint`, `typecheck`, `test`, `check`, or `archstrict` (for example `check:architecture`, `test:mutation`, or `check`), on a `not run:` line after its result, with a hint to name one or write `firstlight.json` with `firstlight init`. With `--json`, the summary gains `not_run`, only when that list is not empty. It still runs only `lint`, `typecheck`, `test`, and `archstrict`, because such a script can chain the others or take hours. When none of those four exists, the error envelope names the check-like scripts and its `do` runs them.
+
+- Once every check of a run is done and one did not pass, the next command that `run`, `results`, `results --new`, and `follow` print is `firstlight run --failed` instead of `firstlight run`, in the text `next:` line and the `next` field of `--json`. While a check is still running, it stays `firstlight results --wait`. The `do` of an error envelope does not change, and neither does the next command after `stop`.
+
+- On a Node older than 24, every command stops before it reads its arguments or starts a run, and prints the error envelope `{"error":"firstlight needs Node 24 or newer (found v20.19.0)","do":"install Node 24 or newer, then rerun the same command"}` with exit code 1. Before, an older Node could run firstlight on a version it was never tested on.
 
 ## 0.2.0 (2026-10-13)
 

package/README.md

@@ -40,6 +40,8 @@ and run `firstlight run`, or `firstlight run rspec` for one of them.
 
    It returns at the first failed or timed-out check, with the last 40 lines of that check's log, the status of every other check, and the next command. When firstlight can read that tool's output, the check's [diagnostics](#diagnostics) come first and the log tail is 10 lines. If every check passes, it prints one line and exits 0.
 
+   While other checks are still running, the next command is `firstlight results --wait`.
+
 2. Fix the failure. Meanwhile, the other checks continue.
 
 3. Read the rest:
@@ -50,16 +52,16 @@ and run `firstlight run`, or `firstlight run rspec` for one of them.
 
    Or watch each check finish as it happens, with `firstlight follow`.
 
-4. Run again. This cancels anything left from step 1:
+4. Run only what did not pass. Once every check is done and one failed, this is the next command that `results` and `follow` print. It cancels anything left from step 1:
 
    ```sh
-   firstlight run lint typecheck test
+   firstlight run --failed
    ```
 
-   Or run only what did not pass the last time:
+   Or run every check again:
 
    ```sh
-   firstlight run --failed
+   firstlight run lint typecheck test
    ```
 
 ## Arguments of `run`
@@ -81,7 +83,7 @@ firstlight has no sequential `run-s` mode and none of npm-run-all's other flags.
 
 ## Install
 
-Requires Node.js 24 or newer. Add it to a project as a development dependency:
+Requires Node.js 24 or newer. On an older Node, every command stops before it does anything and prints `{"error":"firstlight needs Node 24 or newer (found v20.19.0)","do":"install Node 24 or newer, then rerun the same command"}` with exit code 1. Add it to a project as a development dependency:
 
 ```sh
 npm i -D firstlight
@@ -94,6 +96,15 @@ Or run it once without adding it:
 npx firstlight run
 ```
 
+Without `firstlight.json`, `firstlight run` runs the `package.json` scripts `lint`, `typecheck`, `test`, and `archstrict`. To choose the checks, let `firstlight init` propose a `firstlight.json`, read it, then write it:
+
+```sh
+npx firstlight init typecheck test check:architecture
+npx firstlight init typecheck test check:architecture --write
+```
+
+See [Starting a config](#starting-a-config).
+
 The package holds JavaScript compiled from `src/` and has no runtime dependencies. From a checkout, Node strips the TypeScript types and runs the source directly, with no build:
 
 ```sh
@@ -119,12 +130,54 @@ node src/cli.ts --help
 | `run` | A command string. firstlight runs it with `/bin/sh -c` in the repository root. stdout and stderr go to one log file. |
 | `after` | Checks that must pass before this one starts. If one of them does not pass, this check is `skipped`. |
 | `timeoutSec` | Seconds before firstlight stops the check and records `timed_out`. The default is 600. |
-| `parser` | How to read the check's log when it fails: `tsc`, `vitest`, `node-test`, or `archstrict`. Without it, firstlight infers the parser from `run`. `none` turns diagnostics off for this check. See [Diagnostics](#diagnostics). |
+| `parser` | How to read the check's log when it fails: `tsc`, `vitest`, `node-test`, or `archstrict`, or a list of them, like `["tsc", "vitest"]`, read in order. Without it, firstlight infers the parser from `run`. `none` turns diagnostics off for this check. See [Diagnostics](#diagnostics). |
 
-A check name in `firstlight.json` must match `[A-Za-z0-9][A-Za-z0-9._-]*`, so that an argument that names it cannot also read as a pattern or a command. firstlight rejects unknown keys, unknown `after` names, cycles, and an unknown `parser` before it starts anything.
+A check name in `firstlight.json` must match `[A-Za-z0-9][A-Za-z0-9._:-]*`, so that an argument that names it cannot also read as a pattern or a command. firstlight rejects unknown keys, unknown `after` names, cycles, and an unknown `parser` before it starts anything.
 
 Without `firstlight.json`, each of the `package.json` scripts `lint`, `typecheck`, `test`, and `archstrict` that exists becomes a check that runs `npm run <name>`, with no `after`.
 
+Other scripts whose name starts with one of those words or with `check` (`check:architecture`, `test:mutation`, `check`) are not run, because such a script can chain the others or take hours. `firstlight run` names them instead, after its result:
+
+```text
+passed 2 checks in 79.5s (run 01K...)
+not run: check:architecture, test:mutation (without firstlight.json, only lint, typecheck, test, archstrict run; name a script, like firstlight run check:architecture, or write firstlight.json with firstlight init)
+```
+
+With `--json`, the summary gains `"not_run": ["check:architecture", "test:mutation"]`. When none of the four scripts exists, the error envelope names those scripts and suggests running them.
+
+### Starting a config
+
+`firstlight init` proposes a `firstlight.json` from the `package.json` scripts and prints it. It writes nothing until `--write` is given, and `--write` does not replace an existing `firstlight.json` without `--force`.
+
+```text
+$ firstlight init typecheck test check:architecture
+would write /repo/firstlight.json:
+{
+  "checks": {
+    "typecheck": {
+      "run": "npm run typecheck",
+      "parser": "tsc"
+    },
+    "test": {
+      "run": "npm run test",
+      "parser": "vitest"
+    },
+    "check:architecture": {
+      "run": "npm run check:architecture"
+    }
+  }
+}
+left out: test:mutation (to add them: firstlight init typecheck test check:architecture test:mutation)
+next: firstlight init typecheck test check:architecture --write
+```
+
+- With no names, the proposal holds the scripts `lint`, `typecheck`, `test`, and `archstrict` that exist. Names and patterns (`"check:*"`, as in `run`) pick any scripts instead. A shell command is not a script, so add it to `firstlight.json` by hand.
+- Each check is named after its script and runs `npm run <script>`, the same command `firstlight run <script>` runs, so the runs before `init` still count for reused passes and time estimates.
+- `parser` is written when firstlight can infer it from the script (see [Diagnostics](#diagnostics)). A script that chains commands with `&&`, like `tsc --noEmit && vitest run`, gets the list of its commands' parsers.
+- `timeoutSec` is written when a kept run passed the same check in more than a third of the default 600 seconds: three times that duration, rounded up to whole minutes.
+- `left out:` names the scripts that look like checks (they start with `lint`, `typecheck`, `test`, `check`, or `archstrict`) and that the proposal does not hold, with the command that adds them.
+- `--json` prints one object: `{"type":"init","file","written","existed","config","left_out","next"}`.
+
 The repository root is `git rev-parse --show-toplevel` from the current directory, or the current directory when that fails. `--cwd DIR` starts from `DIR` instead.
 
 ## Commands
@@ -135,6 +188,7 @@ firstlight run --failed [--no-cache] [--cwd DIR] [--json]
 firstlight results [--wait] [--new] [--cwd DIR] [--json]
 firstlight follow [--cwd DIR] [--json]
 firstlight stop [--cwd DIR] [--json]
+firstlight init [script|pattern...] [--write [--force]] [--cwd DIR] [--json]
 firstlight --help
 ```
 
@@ -143,6 +197,7 @@ firstlight --help
 - `results` reports the latest run: status, exit code, elapsed time, and for `failed` and `timed_out` checks the diagnostics, the log path, and the last 40 log lines (10 when there are diagnostics). `--wait` blocks until every check is done. `--new` reports only the failures the previous run did not have; see [Only new failures](#only-new-failures).
 - `follow` prints the status changes of the latest run as they happen; see [Following a run](#following-a-run).
 - `stop` cancels the checks that are still running. With nothing running, it does nothing and exits 0.
+- `init` proposes a `firstlight.json` from the `package.json` scripts, and writes it with `--write`; see [Starting a config](#starting-a-config).
 
 A `running` or `pending` check shows about how long it has left, and the `next: firstlight results --wait` line shows the time left for the whole run, so the agent knows when to pull the rest:
 
@@ -178,7 +233,7 @@ lint failed (exit 1, 0.4s)
     src/a.ts:3:1 unused variable x
 test passed (exit 0, 10.4s)
 run 01K...: 1 failed, 1 passed
-next: firstlight run
+next: firstlight run --failed
 ```
 
 A `running` line shows the time left that firstlight estimated when the check started, when there is one. A failed or timed-out check has the same [diagnostics](#diagnostics) and log tail that `run` prints. A reused pass says `cached from run 01K...`, and a check whose supervisor died appears as `unknown` at the end. With `--json`, each change is one check object, in the same shape as `results --json`, followed by the diagnostic lines of a failed check, and the last line is the summary object.
@@ -197,7 +252,7 @@ typecheck failed (exit 2, 1.4s)
     ...
 not new: 1 failure already in the previous run, 2 passed
 run 01K...: 1 new failure
-next: firstlight run
+next: firstlight run --failed
 ```
 
 The previous run is chosen per check: it is the newest kept run before the latest one in which a check with the same name and the same `run` command `passed`, `failed`, or `timed_out`. A run in which that check was `cancelled`, `skipped`, or never finished is passed over, because it proved nothing either way. This is per check, not one run for all, because `run --failed` and `run <name>` leave runs that hold only some of the checks.
@@ -217,7 +272,7 @@ With `--json`, every check object of `results --json` comes, with two more field
 ```json
 {"type":"check","name":"typecheck","status":"failed","exit_code":2,"elapsed_ms":1412,"log":"/.../typecheck.log","eta_ms":0,"overdue":false,"cached_from":null,"new":true,"baseline":"01K...","old_diagnostics":1,"tail":["..."]}
 {"type":"diagnostic","check":"typecheck","file":"src/a.ts","line":4,"col":26,"rule":"TS2304","message":"Cannot find name 'missing'."}
-{"type":"summary","run":"01K...","failed":["typecheck"],"running":[],"passed":[],"cancelled":[],"next":"firstlight run","eta_ms":0,"new":["typecheck"],"new_failures":1,"old_failures":1,"no_baseline":[]}
+{"type":"summary","run":"01K...","failed":["typecheck"],"running":[],"passed":[],"cancelled":[],"next":"firstlight run --failed","eta_ms":0,"new":["typecheck"],"new_failures":1,"old_failures":1,"no_baseline":[]}
 ```
 
 ## Diagnostics
@@ -245,7 +300,7 @@ Each line is `file:line:col rule message`. A part the tool does not report is le
 
 The message is the first line of the error. A line that ends in `:` takes the next line too, so `Expected values to be strictly equal: 7 !== 6` stays whole. Paths inside the repository are relative to its root. Colors and CRLF line endings make no difference.
 
-A check's `parser` in `firstlight.json` chooses the parser. Without one, firstlight infers it from the `run` command when the command is one simple command: `tsc`, `vitest`, `node --test`, or `archstrict`, also through `npx`, `pnpm exec`, a `node_modules/.bin/` path, or a leading `NAME=value`. For `npm run <script>` and `npm test`, it reads the script's own command in `package.json`, one level deep. A command with `&&`, `||`, `;`, or a pipe gets no parser, because it can run more than one tool. firstlight decides the parser when the run starts, so `results` reads the log the same way later. A parser reads text, so a command that prints JSON, such as `archstrict check --json`, gives no diagnostics.
+A check's `parser` in `firstlight.json` chooses the parser. Without one, firstlight infers it from the `run` command when the command is simple commands joined by `&&`: `tsc`, `vitest`, `node --test`, or `archstrict`, also through `npx`, `pnpm exec`, a `node_modules/.bin/` path, or a leading `NAME=value`. For `npm run <script>` and `npm test`, it reads the script's own command in `package.json`, one level deep. An `&&` list, like `tsc --noEmit && vitest run`, gets the parser of each command that has one, in order, and its diagnostics are what each parser finds; a parser skips the lines of other tools. A command with `||`, `;`, or a pipe gets no parser, because which tool's output the log ends with is not fixed. firstlight decides the parser when the run starts, so `results` reads the log the same way later. A parser reads text, so a command that prints JSON, such as `archstrict check --json`, gives no diagnostics.
 
 In `--json`, the diagnostics follow their check's object, one line each:
 
@@ -302,6 +357,20 @@ The limits:
 
 In these cases, run `firstlight run --no-cache`. It runs every selected check, and still records the keys, so a later run can reuse its passes.
 
+## CPU contention
+
+firstlight starts every check at once and has no concurrency limit. Test runners such as vitest and `node --test` already spread one check over every core, so checks that run together share the CPU: each one takes longer than it does alone, and the whole run takes at least the checks' total CPU time divided by the number of cores. Measured on a 4-CPU machine, with Node 24.21.0, three runs each, times in seconds:
+
+| Repository | Checks | Each alone (sum) | Together | Slowest check alone, together |
+| --- | --- | --- | --- | --- |
+| firstlight | typecheck, test, archstrict | 35.1 | 34.7 | test 30.9, 34.2 |
+| finderscope | typecheck, test, archstrict | 62.8 | 59.4 | test 58.4, 58.9 |
+| polylinedb | typecheck, test, check:architecture | 197.8 | 178.9 | test 132.0, 178.4 |
+
+In polylinedb, test used about 2.9 cores and check:architecture about 3.8 while each ran alone, so together they need about 160 seconds of the 4 cores at best; 179 is close to that, and 20 seconds less than one after the other. A limit on how many checks run at once would not make the run shorter, because the total CPU time is the same; it would only move time from one check to another. The failure that arrives first still arrives first: typecheck finished in 3 to 6 seconds in every run, against about 2 alone. (finderscope's test had the same two failures on that machine in every run, alone and together.)
+
+To see one heavy check's result sooner at the cost of a longer run, start another heavy check after it with `after`. In polylinedb, putting check:architecture after test would let test report at about 132 seconds instead of 178, and the run would end at about 196 instead of 179.
+
 ## Statuses and output
 
 A check is `pending`, `running`, `passed`, `failed`, `timed_out`, `cancelled`, or `skipped`. A check is `unknown`, with `orphan: true`, when its supervisor process is gone before the check finished. firstlight does not invent an exit code for it. A check killed by a signal has the exit code 128 plus the signal number.
@@ -315,7 +384,7 @@ The default output is short plain text with no colors. `--json` prints JSON Line
 {"type":"summary","run":"01K...","failed":["lint"],"running":["test"],"passed":["build"],"cancelled":[],"next":"firstlight results --wait","eta_ms":8012}
 ```
 
-`failed` in the summary holds the checks that are `failed`, `timed_out`, `skipped`, or `unknown`. `running` holds `pending` and `running` checks. `next` is the command to run next, or `null`. `eta_ms` on a check is the estimated milliseconds it has left: `0` for a finished check, and `null` when there is no estimate. `overdue` is `true` when a running check has run longer than its usual duration; its `eta_ms` is then `0`. `cached_from` is the id of the run that ran a reused check, or `null`. That run may be pruned since. For a reused check, `exit_code` and `elapsed_ms` come from that run, and its log holds one line that names it. `eta_ms` in the summary is the estimate for the whole run, `0` when nothing is left to run, or `null`.
+`failed` in the summary holds the checks that are `failed`, `timed_out`, `skipped`, or `unknown`. `running` holds `pending` and `running` checks. `next` is the command to run next, or `null`: `firstlight results --wait` while a check is still running, and `firstlight run --failed` once every check is done and one did not pass. `eta_ms` on a check is the estimated milliseconds it has left: `0` for a finished check, and `null` when there is no estimate. `overdue` is `true` when a running check has run longer than its usual duration; its `eta_ms` is then `0`. `cached_from` is the id of the run that ran a reused check, or `null`. That run may be pruned since. For a reused check, `exit_code` and `elapsed_ms` come from that run, and its log holds one line that names it. `eta_ms` in the summary is the estimate for the whole run, `0` when nothing is left to run, or `null`.
 
 ## Exit codes
 

package/dist/cli.js

@@ -5,15 +5,15 @@
 // subcommand).
 // It never appends to events.jsonl; it only reads what the supervisor wrote.
 import { spawn } from "node:child_process";
-import { closeSync, openSync, writeSync } from "node:fs";
+import { closeSync, existsSync, openSync, writeFileSync, writeSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { compareFailures, isFailure, isUnproven } from "./baseline.js";
 import { cacheKeys } from "./cache.js";
 import { bucketOf, IllegalTransition, isSettled, presentChecks, replay } from "./checks.js";
-import { configuredChecks, loadConfig, resolveRun, selectFailed, withParsers } from "./config.js";
-import { AgentError, exitWithEnvelope } from "./errors.js";
+import { CONFIG_FILE, configText, configuredChecks, loadConfig, proposeChecks, resolveRun, selectFailed, suggestTimeoutSec, withParsers, } from "./config.js";
+import { AgentError, exitWithEnvelope, nodeVersionError } from "./errors.js";
 import { estimate } from "./eta.js";
 import { shellQuote } from "./names.js";
 import { signalGroup, signalPid, sleep } from "./processes.js";
@@ -31,6 +31,7 @@ Usage:
   firstlight results [--wait] [--new] [--cwd DIR] [--json]
   firstlight follow [--cwd DIR] [--json]
   firstlight stop [--cwd DIR] [--json]
+  firstlight init [script|pattern...] [--write [--force]] [--cwd DIR] [--json]
   firstlight --help
 
 run      Stop the previous run if it is still going, start the checks in
@@ -59,6 +60,15 @@ follow   Print one line for each status change of the latest run, from its
          exit as results --wait would. Each line is flushed on its own, so
          a log watcher sees it at once.
 stop     Cancel the checks still running. Does nothing when none are.
+init     Propose a firstlight.json from the package.json scripts and print
+         it. --write writes it; --force lets --write replace an existing
+         one. With no names, it holds the scripts lint, typecheck, test,
+         and archstrict; names and patterns pick other scripts:
+           firstlight init typecheck test check:architecture
+         Each check runs "npm run <script>", gets the parser inferred from
+         the script, and gets a timeoutSec when an earlier run passed it in
+         more than a third of the 600s default. It names the scripts that
+         look like checks and were left out.
 
 Arguments of run:
   word       a check in firstlight.json (with its "after" checks), else a
@@ -88,7 +98,8 @@ diagnostics, at most 20, as "file:line:col rule message" lines before a
 {"type":"diagnostic",...} lines after the check. The parsers are tsc,
 vitest, node-test (node --test), and archstrict. Each check's parser comes from its "parser" in firstlight.json,
 or from its command: tsc, vitest, node --test, archstrict, or "npm run
-<script>" (and "npm test") whose script runs one of them. "parser":
+<script>" (and "npm test") whose script runs one of them; an && list
+gets each of its commands' parsers, like ["tsc", "vitest"]. "parser":
 "none" turns this off for one check. A vitest diagnostic whose test
 depug's reporter named also gets "evidence: <path>" and "rerun:
 <command>" lines under it, and "evidence" and "rerun" fields in --json.
@@ -100,7 +111,9 @@ shell command:
               "types": {"run": "make types", "parser": "tsc"}}}
 To run checks in order, give a check "after" in firstlight.json. Without
 firstlight.json, "firstlight run" runs the package.json scripts lint,
-typecheck, test, and archstrict.
+typecheck, test, and archstrict, and names the other scripts that start
+with one of those words or with "check" (check:architecture, test:e2e)
+on a "not run:" line, without running them.
 
 Exit codes:
   0  every check passed (run), or no check failed or was cancelled
@@ -135,6 +148,8 @@ async function main(argv) {
                 failed: { type: "boolean", default: false },
                 new: { type: "boolean", default: false },
                 "no-cache": { type: "boolean", default: false },
+                write: { type: "boolean", default: false },
+                force: { type: "boolean", default: false },
                 help: { type: "boolean", short: "h", default: false },
             },
         });
@@ -159,10 +174,13 @@ async function main(argv) {
     if (command === undefined) {
         throw new AgentError("missing command", "run `firstlight run`, or `firstlight --help` for the usage");
     }
-    if (!["run", "results", "follow", "stop"].includes(command)) {
+    if (!["run", "results", "follow", "stop", "init"].includes(command)) {
         throw new AgentError(`unknown command: ${command}`, "run `firstlight --help` for the usage");
     }
-    if (command !== "run" && (names.length > 0 || commands.length > 0)) {
+    if (command === "init" && commands.length > 0) {
+        throw new AgentError("init picks package.json scripts and takes no commands after --", `add the commands to ${CONFIG_FILE} by hand`);
+    }
+    if (command !== "run" && command !== "init" && (names.length > 0 || commands.length > 0)) {
         throw new AgentError(`${command} takes no check names`, `run \`firstlight ${command}\` without arguments`);
     }
     if (values.wait && command !== "results") {
@@ -174,6 +192,12 @@ async function main(argv) {
     if (values["no-cache"] && command !== "run") {
         throw new AgentError("--no-cache belongs to run", "run `firstlight run --no-cache`");
     }
+    if (values.write && command !== "init") {
+        throw new AgentError("--write belongs to init", "run `firstlight init --write`");
+    }
+    if (values.force && !values.write) {
+        throw new AgentError("--force only lets init --write replace a firstlight.json", "run `firstlight init --write --force`");
+    }
     if (values.failed && command !== "run") {
         throw new AgentError("--failed belongs to run", "run `firstlight run --failed`");
     }
@@ -193,6 +217,8 @@ async function main(argv) {
             return resultsCommand(ctx, values.wait, values.new);
         case "follow":
             return followCommand(ctx);
+        case "init":
+            return initCommand(ctx, names, values.write, values.force);
         default:
             return stopCommand(ctx);
     }
@@ -200,6 +226,7 @@ async function main(argv) {
 async function runCommand(ctx, selection, useCache) {
     const previous = ctx.state.currentId();
     let checks;
+    let notRun = [];
     if (selection === "failed") {
         if (previous === null) {
             throw new AgentError(`no run yet for ${ctx.state.root}, so no check has failed`, cmd(ctx, "run"));
@@ -213,10 +240,14 @@ async function runCommand(ctx, selection, useCache) {
     }
     else {
         const { names, commands } = selection;
-        checks =
-            names.length === 0 && commands.length === 0
-                ? loadConfig(ctx.state.root).checks
-                : resolveRun(ctx.state.root, names, commands);
+        if (names.length === 0 && commands.length === 0) {
+            const config = loadConfig(ctx.state.root);
+            checks = config.checks;
+            notRun = config.notRun;
+        }
+        else {
+            checks = resolveRun(ctx.state.root, names, commands);
+        }
         if (previous !== null)
             await stopRun(ctx.state, previous);
     }
@@ -258,18 +289,18 @@ async function runCommand(ctx, selection, useCache) {
         const eta = etaOf(snapshot, typical);
         const first = firstFailure(snapshot.checks);
         if (first !== null) {
-            const next = snapshot.checks.every(isSettled) ? cmd(ctx, "run") : cmd(ctx, "results --wait");
-            out(ctx.json ? jsonLines(snapshot, next, eta) : text(snapshot, next, eta, first.name));
+            const next = snapshot.checks.every(isSettled) ? cmd(ctx, "run --failed") : cmd(ctx, "results --wait");
+            out(ctx.json ? jsonLines(snapshot, next, eta, notRun) : text(snapshot, next, eta, first.name, notRun));
             return 1;
         }
         if (snapshot.checks.every(isSettled)) {
             if (snapshot.checks.every((view) => view.status === "passed")) {
-                out(ctx.json ? jsonLines(snapshot, null, eta) : allPassedText(snapshot));
+                out(ctx.json ? jsonLines(snapshot, null, eta, notRun) : allPassedText(snapshot, notRun));
                 return 0;
             }
             const superseded = ctx.state.currentId() !== run.id;
-            const next = superseded ? cmd(ctx, "results --wait") : cmd(ctx, "run");
-            out(ctx.json ? jsonLines(snapshot, next, eta) : text(snapshot, next, eta));
+            const next = superseded ? cmd(ctx, "results --wait") : cmd(ctx, "run --failed");
+            out(ctx.json ? jsonLines(snapshot, next, eta, notRun) : text(snapshot, next, eta, null, notRun));
             return 1;
         }
         await sleep(POLL_MS);
@@ -302,7 +333,7 @@ async function resultsCommand(ctx, wait, onlyNew) {
         const failing = [...comparison.checks.values()].some((check) => check.isNew);
         const running = snapshot.checks.some((view) => bucketOf(view.status) === "running");
         const unproven = snapshot.checks.some((view) => isUnproven(view.status));
-        const next = running ? cmd(ctx, "results --new --wait") : failing || unproven ? cmd(ctx, "run") : null;
+        const next = running ? cmd(ctx, "results --new --wait") : failing || unproven ? cmd(ctx, "run --failed") : null;
         out(ctx.json ? newJsonLines(snapshot, comparison, next, eta) : newText(snapshot, comparison, next, eta));
         return failing || unproven ? 1 : 0;
     }
@@ -383,6 +414,39 @@ async function followCommand(ctx) {
         await sleep(POLL_MS);
     }
 }
+function initCommand(ctx, names, write, force) {
+    const { checks, leftOut } = proposeChecks(ctx.state.root, names);
+    const durations = ctx.state.passDurations(checks);
+    const proposed = checks.map((check) => {
+        const ms = durations.get(check.name);
+        const timeoutSec = ms === undefined ? null : suggestTimeoutSec(ms);
+        return timeoutSec === null ? check : { ...check, timeoutSec };
+    });
+    const file = path.join(ctx.state.root, CONFIG_FILE);
+    const exists = existsSync(file);
+    const content = configText(proposed);
+    if (write) {
+        if (exists && !force) {
+            throw new AgentError(`${file} already exists, and init does not replace it`, cmd(ctx, `init${argsOf(names)} --write --force`));
+        }
+        writeFileSync(file, content);
+    }
+    const next = write ? cmd(ctx, "run") : cmd(ctx, `init${argsOf(names)} --write${exists ? " --force" : ""}`);
+    const widen = leftOut.length === 0 ? null : cmd(ctx, `init${argsOf([...checks.map((check) => check.name), ...leftOut])}`);
+    if (ctx.json) {
+        out(`${JSON.stringify({ type: "init", file, written: write, existed: exists, config: JSON.parse(content), left_out: leftOut, next })}\n`);
+        return 0;
+    }
+    const lines = [write ? `wrote ${file}:` : `would write ${file}${exists ? " (it exists; --force replaces it)" : ""}:`, content.trimEnd()];
+    if (widen !== null)
+        lines.push(`left out: ${leftOut.join(", ")} (to add them: ${widen})`);
+    lines.push(`next: ${next}`);
+    out(`${lines.join("\n")}\n`);
+    return 0;
+}
+function argsOf(names) {
+    return names.map((name) => ` ${shellQuote(name)}`).join("");
+}
 async function stopCommand(ctx) {
     const id = ctx.state.currentId();
     const stopped = id === null ? false : await stopRun(ctx.state, id);
@@ -438,7 +502,7 @@ function nextFor(ctx, snapshot) {
     if (buckets.includes("running"))
         return cmd(ctx, "results --wait");
     if (buckets.includes("failed") || buckets.includes("cancelled"))
-        return cmd(ctx, "run");
+        return cmd(ctx, "run --failed");
     return null;
 }
 function cmd(ctx, rest) {
@@ -447,6 +511,9 @@ function cmd(ctx, rest) {
 function out(textValue) {
     writeSync(1, textValue);
 }
+const tooOld = nodeVersionError(process.version);
+if (tooOld !== null)
+    exitWithEnvelope(tooOld);
 main(process.argv.slice(2)).then((code) => {
     process.exitCode = code;
 }, (err) => exitWithEnvelope(err));

package/dist/config.js

@@ -7,28 +7,42 @@
 // process.
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { inferParser, PARSER_CHOICES } from "./diagnostics.js";
+import { inferParser, isParserChoice, PARSER_CHOICES, PARSERS } from "./diagnostics.js";
 import { AgentError, messageOf } from "./errors.js";
 import { expandPattern, isPattern, shellQuote } from "./names.js";
 export const CONFIG_FILE = "firstlight.json";
 export const DEFAULT_TIMEOUT_SEC = 600;
 export const FALLBACK_SCRIPTS = ["lint", "typecheck", "test", "archstrict"];
+// Script names that look like a check by their first ":" segment. The
+// fallback does not run them: a name like test:mutation or check can take
+// hours or chain the others, so a guess would duplicate or stall work. They
+// are only named, so the reader can pick.
+const CHECK_LIKE = new Set(["lint", "typecheck", "test", "check", "archstrict"]);
 // A configured name is one plain word, never whitespace or "*", so an
 // argument of `firstlight run` that names it cannot also read as a shell
-// command or a script glob.
-const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// command or a script glob. ":" is allowed so a check can keep the name of
+// the script it runs, like check:architecture.
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
 const CHECK_KEYS = new Set(["run", "after", "timeoutSec", "parser"]);
 export function loadConfig(root) {
     const configPath = path.join(root, CONFIG_FILE);
     const text = readOptional(configPath);
     if (text !== null) {
-        return { source: "firstlight.json", checks: parseConfig(text, configPath) };
+        return { source: "firstlight.json", checks: parseConfig(text, configPath), notRun: [] };
     }
     const scripts = readScripts(path.join(root, "package.json")) ?? [];
     const checks = FALLBACK_SCRIPTS.filter((name) => scripts.includes(name)).map(scriptCheck);
+    const notRun = checkLikeScripts(scripts);
     if (checks.length > 0)
-        return { source: "package.json", checks };
-    throw new AgentError(`no checks found in ${root}: there is no ${CONFIG_FILE} and package.json has no ${FALLBACK_SCRIPTS.join(", ")} script`, `create ${configPath} like {"checks": {"test": {"run": "npm test"}}}, then run \`firstlight run\``);
+        return { source: "package.json", checks, notRun };
+    const named = notRun.length === 0 ? "" : ` (scripts that look like checks: ${notRun.join(", ")})`;
+    throw new AgentError(`no checks found in ${root}: there is no ${CONFIG_FILE} and package.json has no ${FALLBACK_SCRIPTS.join(", ")} script${named}`, notRun.length === 0
+        ? `create ${configPath} like {"checks": {"test": {"run": "npm test"}}}, then run \`firstlight run\``
+        : `run \`firstlight run ${notRun.map(shellQuote).join(" ")}\`, or write ${configPath} with \`firstlight init ${notRun.map(shellQuote).join(" ")} --write\``);
+}
+export function checkLikeScripts(scripts) {
+    const fallback = FALLBACK_SCRIPTS;
+    return scripts.filter((name) => !fallback.includes(name) && CHECK_LIKE.has(name.split(":")[0]));
 }
 export function parseConfig(text, file) {
     let raw;
@@ -84,8 +98,8 @@ function parseCheck(name, value, file) {
     }
     if (value.parser === undefined)
         return { name, run: value.run, after, timeoutSec };
-    if (typeof value.parser !== "string" || !PARSER_CHOICES.includes(value.parser)) {
-        throw invalid(file, `check "${name}" has "parser" ${JSON.stringify(value.parser)}; allowed values are ${PARSER_CHOICES.join(", ")}`);
+    if (!(value.parser === "none" || isParserChoice(value.parser))) {
+        throw invalid(file, `check "${name}" has "parser" ${JSON.stringify(value.parser)}; allowed values are ${PARSER_CHOICES.join(", ")}, or a list of ${PARSERS.join(", ")}`);
     }
     return { name, run: value.run, after, timeoutSec, parser: value.parser };
 }
@@ -252,8 +266,72 @@ export function selectFailed(configured, previous) {
     }
     return { checks: picked, dropped };
 }
-// The checks of firstlight.json alone, without the package.json fallback:
-// what a word given to `run` can name as a configured check.
+// What `firstlight init` would write: each picked script as the check
+// `run` would make of it, so a later run shares its cache keys and
+// durations with the runs before init, plus the parser inferred from the
+// script. With no names, the picked scripts are the package.json fallback.
+export function proposeChecks(root, args) {
+    const file = path.join(root, "package.json");
+    const commands = readScriptCommands(file);
+    if (commands === null) {
+        throw new AgentError(`there is no package.json in ${root}, and firstlight init proposes checks from its scripts`, `write ${path.join(root, CONFIG_FILE)} by hand, like {"checks": {"test": {"run": "make test"}}}`);
+    }
+    const scripts = Object.keys(commands);
+    const checkLike = checkLikeScripts(scripts);
+    let picked;
+    if (args.length === 0) {
+        picked = FALLBACK_SCRIPTS.filter((name) => scripts.includes(name));
+        if (picked.length === 0) {
+            throw new AgentError(`package.json has no ${FALLBACK_SCRIPTS.join(", ")} script, so firstlight init has nothing to propose`, checkLike.length === 0
+                ? `name the scripts to check, like \`firstlight init ${scripts[0] ?? "test"}\``
+                : `name the scripts to check, like \`firstlight init ${checkLike.map(shellQuote).join(" ")}\``);
+        }
+    }
+    else {
+        picked = [];
+        for (const arg of args) {
+            if (/\s/u.test(arg)) {
+                throw new AgentError(`firstlight init picks package.json scripts, and "${arg}" is a shell command`, `add it to ${CONFIG_FILE} by hand, like {"checks": {"name": {"run": ${JSON.stringify(arg)}}}}`);
+            }
+            const matched = isPattern(arg) ? expandPattern(arg, scripts) : scripts.includes(arg) ? [arg] : [];
+            if (matched.length === 0) {
+                throw new AgentError(`no package.json script ${isPattern(arg) ? "matches" : "is named"} "${arg}"; the scripts are: ${scripts.join(", ") || "(none)"}`, `pick from: ${scripts.join(", ") || "(none)"}`);
+            }
+            for (const name of matched)
+                if (!picked.includes(name))
+                    picked.push(name);
+        }
+    }
+    const scriptOf = (name) => commands[name] ?? null;
+    const checks = picked.map((name) => {
+        const check = scriptCheck(name);
+        const parser = inferParser(check.run, scriptOf);
+        return parser === null ? check : { ...check, parser };
+    });
+    return { checks, leftOut: checkLike.filter((name) => !picked.includes(name)) };
+}
+// A timeout that leaves room for a check that once passed in `ms`: three
+// times that, in whole minutes, or null when the default already does.
+export function suggestTimeoutSec(ms) {
+    const seconds = Math.ceil((ms * 3) / 60_000) * 60;
+    return seconds > DEFAULT_TIMEOUT_SEC ? seconds : null;
+}
+// The firstlight.json text for `checks`, with only the keys that differ
+// from the defaults, so the file reads like one written by hand.
+export function configText(checks) {
+    const body = {};
+    for (const check of checks) {
+        const entry = { run: check.run };
+        if (check.after.length > 0)
+            entry.after = check.after;
+        if (check.timeoutSec !== DEFAULT_TIMEOUT_SEC)
+            entry.timeoutSec = check.timeoutSec;
+        if (check.parser !== undefined && check.parser !== null)
+            entry.parser = check.parser;
+        body[check.name] = entry;
+    }
+    return `${JSON.stringify({ checks: body }, null, 2)}\n`;
+}
 export function configuredChecks(root) {
     const configPath = path.join(root, CONFIG_FILE);
     const configText = readOptional(configPath);

package/dist/diagnostics.js

@@ -39,14 +39,37 @@ export function formatDiagnostic(diagnostic) {
     }
     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 isParserChoice(value) {
+    return isParserName(value) || (Array.isArray(value) && value.length > 0 && value.every(isParserName));
+}
+export function parserList(choice) {
+    return typeof choice === "string" ? [choice] : choice;
+}
+// The command is read only when it is simple commands joined by `&&`: a
+// pipe, `;`, `||`, or a substitution could run any tool, and a wrong parser
+// is worse than none. An `&&` list runs its commands in order and each
+// parser skips the lines it does not recognize, so every command's parser
+// reads the one log. `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)
+    const segments = command.split("&&");
+    const found = [];
+    for (const segment of segments) {
+        if (segment.trim().length === 0)
+            return null;
+        const words = simpleWords(segment);
+        if (words === null)
+            return null;
+        for (const parser of parserList(inferSimple(words, scriptOf) ?? [])) {
+            if (!found.includes(parser))
+                found.push(parser);
+        }
+    }
+    if (found.length === 0)
         return null;
+    return found.length === 1 ? found[0] : found;
+}
+function inferSimple(words, scriptOf) {
     let i = 0;
     while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
         i += 1;

package/dist/errors.js

@@ -20,6 +20,16 @@ export function exitWithEnvelope(err) {
     writeSync(2, `${JSON.stringify(body)}\n`);
     process.exit(1);
 }
+// The oldest Node major firstlight is tested on; package.json "engines"
+// says the same. Older Nodes are refused up front, so a missing API never
+// surfaces later as an unrelated stack trace or a hang.
+export const NODE_FLOOR = 24;
+export function nodeVersionError(version) {
+    const major = Number(/^v?(\d+)\./.exec(version)?.[1]);
+    if (!Number.isInteger(major) || major >= NODE_FLOOR)
+        return null;
+    return new AgentError(`firstlight needs Node ${NODE_FLOOR} or newer (found ${version})`, `install Node ${NODE_FLOOR} or newer, then rerun the same command`);
+}
 export function messageOf(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/report.js

@@ -7,7 +7,8 @@
 // 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 { FALLBACK_SCRIPTS } from "./config.js";
+import { formatDiagnostic, isParserChoice, parseDiagnostics, parserList } from "./diagnostics.js";
 import { formatSeconds } from "./eta.js";
 import { logPaths, readLogEnd, tailLines } from "./store.js";
 export const TAIL_LINES = 40;
@@ -19,9 +20,10 @@ export const DIAGNOSTIC_LIMIT = 20;
 // that run recorded for it.
 export function checkDiagnostics(run, dir, name) {
     const parser = run.checks.find((check) => check.name === name)?.parser;
-    if (!isParserName(parser))
+    if (!isParserChoice(parser))
         return [];
-    return parseDiagnostics(parser, readLogEnd(logPaths(dir, run.checks).get(name)), run.root);
+    const log = readLogEnd(logPaths(dir, run.checks).get(name));
+    return parserList(parser).flatMap((one) => parseDiagnostics(one, log, run.root));
 }
 // `shown` narrows the diagnostics printed, as `results --new` does; the
 // tail stays short whenever the log has any.
@@ -37,7 +39,7 @@ function logReport(snapshot, view, file, shown) {
 function comparedOf(comparison, view) {
     return { baseline: comparison.baselines.get(view.name) ?? null, comparison: comparison.checks.get(view.name) };
 }
-export function summarize(snapshot, next, eta) {
+export function summarize(snapshot, next, eta, notRun = []) {
     const summary = {
         type: "summary",
         run: snapshot.run.id,
@@ -50,14 +52,16 @@ export function summarize(snapshot, next, eta) {
     };
     for (const view of snapshot.checks)
         summary[bucketOf(view.status)].push(view.name);
+    if (notRun.length > 0)
+        summary.not_run = notRun;
     return summary;
 }
 function showsLog(view) {
     return view.status === "failed" || view.status === "timed_out";
 }
-export function jsonLines(snapshot, next, eta) {
+export function jsonLines(snapshot, next, eta, notRun = []) {
     const lines = snapshot.checks.map((view) => checkJson(snapshot, view, eta));
-    lines.push(JSON.stringify(summarize(snapshot, next, eta)));
+    lines.push(JSON.stringify(summarize(snapshot, next, eta, notRun)));
     return `${lines.join("\n")}\n`;
 }
 // One line for the check, then, for a failed check, one line per
@@ -106,7 +110,7 @@ export function checkJson(snapshot, view, eta, compared) {
 }
 // `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) {
+export function text(snapshot, next, eta, focus = null, notRun = []) {
     const out = [];
     const ordered = focus === null
         ? snapshot.checks
@@ -116,7 +120,7 @@ export function text(snapshot, next, eta, focus = null) {
         if (showsLog(view) && (focus === null || view.name === focus))
             out.push(...logBlock(snapshot, view));
     }
-    return `${out.join("\n")}\n${summaryText(snapshot, next, eta)}`;
+    return `${out.join("\n")}\n${notRunText(notRun)}${summaryText(snapshot, next, eta)}`;
 }
 // The lines after the check lines: the counts, then the next command.
 export function summaryText(snapshot, next, eta) {
@@ -231,12 +235,19 @@ export function newText(snapshot, comparison, next, eta) {
 function plural(count, word) {
     return count === 1 ? word : `${word}s`;
 }
-export function allPassedText(snapshot) {
+// Only a run without firstlight.json has these: the check-like scripts the
+// package.json fallback did not run.
+export function notRunText(notRun) {
+    if (notRun.length === 0)
+        return "";
+    return `not run: ${notRun.join(", ")} (without firstlight.json, only ${FALLBACK_SCRIPTS.join(", ")} run; name a script, like firstlight run ${notRun[0]}, or write firstlight.json with firstlight init)\n`;
+}
+export function allPassedText(snapshot, notRun = []) {
     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`;
+    return `passed ${count} check${count === 1 ? "" : "s"} in ${seconds.toFixed(1)}s (${notes})\n${notRunText(notRun)}`;
 }
 function statusLine(snapshot, view, eta) {
     const details = [];

package/dist/store.js

@@ -145,6 +145,12 @@ export class RepoState {
             .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) {
@@ -333,7 +339,10 @@ function isRunRecord(value) {
         typeof check.run === "string" &&
         Array.isArray(check.after) &&
         typeof check.timeoutSec === "number" &&
-        (check.parser === undefined || check.parser === null || typeof check.parser === "string"));
+        (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")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstlight",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Run lint, typecheck, and tests in parallel for a coding agent, and return at the first failure.",
   "keywords": [
     "parallel",
@@ -37,6 +37,7 @@
   "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",
@@ -49,6 +50,7 @@
     "@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"