v1.90.0 ·
A docs check that failed on a busy machine
This repo checks its own CLI docs every time work leaves the coding step. A script rebuilds the command reference from the built CLI and compares it with the committed copy. If they differ, the step is blocked.
The check was slow. It took 16 to 22 seconds on my machine, and every lifecycle action is killed at 30. That margin was fine until the machine got busy. On 2026-10-10, with a load average near 100, the first run timed out and blocked the transition. The retry passed. A gate that passes or fails depending on how busy the laptop is does not tell you anything about the docs.
Where the time went
The generator read each command's help by starting the CLI again: node dist/cli.js <cmd> --help, 92 times. Each start loads the whole CLI. That start-up is exactly the part a loaded machine stretches.
Now scripts/generate-cli-reference.mjs builds the command tree once, in its own process, and asks each command for its help text directly. The output is the same JSON, byte for byte. The check finished in 0.24 seconds at load 12, and between 0.40 and 0.70 seconds with the full test suite running next to it.
Why not just make it faster
Running the 92 starts in parallel was the other option. It would have been quicker, and still at the mercy of load, only less so. Dropping the check from the lifecycle and leaving it to CI would have removed the local gate entirely. Reading help in one process takes start-up cost out of the picture, so load stops mattering.
The tests do not time anything. A stopwatch is what failed in the first place. Instead they count child processes: the generator must start none, and the check must start exactly one. A count gives the same answer on an idle machine and a busy one.
What it does not cover
I did not rerun it at a load of 100 on purpose. Generating that much load would have slowed every other session on the machine. The argument rests on the count: 92 CLI start-ups became none.
One thing changed shape. The CLI's commands are now built inside the generator's process, so a future command with side effects at registration would run them there. Tests already build the CLI this way, so that rule was there before.
The whole change cost about $2.62.