@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.11

package/dist/commands/resources/check-progress.js

@@ -0,0 +1,250 @@
+/**
+ * The progress log a supervised `vat resources check` writes, and the reader
+ * that turns whatever survived into a report.
+ *
+ * ## 🚨 Why progress goes to a FILE, and never to stdout or IPC
+ *
+ * The run this log exists for is one that gets `SIGKILL`ed. That is not a design
+ * preference: a statement blocked inside synchronous `node:sqlite` never returns
+ * to the event loop, so nothing in-process can interrupt it — measured on Node
+ * 24.13.1, `worker.terminate()` never resolves against such a thread and the
+ * parent's own `process.exit()` does not exit either. An external `SIGKILL` is
+ * the only lever, and `SIGKILL` cannot be handled, deferred or flushed.
+ *
+ * So the child's report of what it has finished has to be DURABLE at every
+ * instant, not merely sent. stdout is buffered by the pipe and lost with the
+ * process; an IPC message needs a live event loop to be delivered, which is the
+ * exact resource the hung child does not have. An `appendFileSync` per unit is
+ * on disk before the next unit starts, which is the only property that matters.
+ *
+ * Keeping it off stdout has a second benefit worth stating: stdout stays the one
+ * parseable document this verb has always published, so `vat resources check |
+ * jq` is unaffected by a mechanism it should never have to know about.
+ *
+ * ## 🪤 The reader must expect DAMAGE, not merely tolerate it
+ *
+ * The signal lands wherever it lands, including part-way through a write, so the
+ * last line of a killed run's log is routinely half a JSON object. A reader that
+ * threw there would replace the bounded failure report with a stack trace at
+ * exactly the moment the report is the only thing the operator gets. A reader
+ * that GUESSED at a damaged line would be worse still: it would publish a cost
+ * record for a measurement nobody took, beside ones somebody did.
+ *
+ * Every line is therefore validated against a `.strict()` schema and silently
+ * dropped when it does not parse. That schema is also the whole of the format
+ * contract — there is no version integer here and there must never be one. This
+ * file is written and read by ONE process pair within ONE run of ONE build; the
+ * question a version integer pretends to answer ("can I read this?") is answered
+ * exactly and automatically by the schema the reader compiles with.
+ */
+import { appendFileSync } from 'node:fs';
+import { z } from 'zod';
+/**
+ * The child has booted — Node is up, the CLI is loaded, and no work has begun.
+ *
+ * 🚨 **The defect this closes: the population was charged the child's boot.**
+ * The watchdog's clock starts at the spawn, and the population line used to be
+ * the child's FIRST line — so Node's startup and the CLI's module graph were
+ * silently billed to the one unit the budget is already a total bound for. On a
+ * loaded runner the boot alone grows by seconds, and a run whose tree was fine
+ * was killed "during population" for its neighbours' load. This line closes the
+ * boot's window and opens the population's own, so the budget measures work.
+ *
+ * It carries no fields: the fact that it was written is the whole message. Its
+ * ABSENCE is what {@link unitInFlight} reads as `startup` — a run killed before
+ * it could say anything at all.
+ */
+const StartedEntrySchema = z.object({
+    kind: z.literal('started'),
+}).strict();
+/**
+ * The population finished — how it was obtained, what it cost, and how much of
+ * the tree it covered.
+ *
+ * Written the instant the projection is ready, because a kill BEFORE this line
+ * means there is no projection at all: the document the parent publishes then
+ * carries its population fields as `null`, not as a value nobody measured. The
+ * parent distinguishes those two endings by this line's presence and nothing
+ * else, so it must never be written early or optimistically.
+ */
+const PopulationEntrySchema = z.object({
+    kind: z.literal('population'),
+    population: z.union([z.literal('derived'), z.literal('store')]),
+    populationMs: z.number(),
+    // Carried across the process boundary rather than recomputed, for the same
+    // reason every other field here is: a killed run's document is rebuilt from
+    // these lines alone, and a cost the parent cannot see is a cost it would have
+    // to invent or omit. Omitting it would make an interrupted run's report claim
+    // the lens was free.
+    lensMs: z.number(),
+    // What that cost COVERS: `lensMs: 0` is ambiguous on its own — nothing asked,
+    // or a lens that stopped running. Carried rather than recomputed because an
+    // interrupted run's document is rebuilt from these lines alone.
+    lensesEvaluated: z.array(z.string()),
+    membersEnumerated: z.number(),
+}).strict();
+/**
+ * A check's statement is ABOUT to run.
+ *
+ * The only record that can name the rule that hung: a check which never returns
+ * never files a cost, so without this line a killed run could say a check was in
+ * flight but not which one — and "one of your forty rules hangs" is not an
+ * actionable report.
+ */
+const StartEntrySchema = z.object({
+    kind: z.literal('start'),
+    name: z.string(),
+}).strict();
+/**
+ * A check completed — the same fields `CheckCost` publishes.
+ *
+ * 🪤 `rows` is optional and `broken` is `true`-or-absent, mirroring `CheckCost`
+ * exactly: a statement that threw has no row count, and `rows: 0` on it would
+ * read as "selected nothing and passed". Keeping the two shapes identical is
+ * what lets the parent hand recovered records to the same `buildCheckOutputData`
+ * a completed run uses, rather than growing a second payload builder that could
+ * drift from it.
+ */
+const CheckEntrySchema = z.object({
+    kind: z.literal('check'),
+    name: z.string(),
+    durationMs: z.number(),
+    rows: z.number().optional(),
+    broken: z.literal(true).optional(),
+    // Which SET the name came from. Carried, not recomputed: a parent that looked
+    // the name up in `BUILTIN_CHECK_NAMES` would be a second authority that
+    // disagrees the day a project declares a check of the same name.
+    builtin: z.literal(true).optional(),
+}).strict();
+/**
+ * Every check has filed its cost; the document is about to be built.
+ *
+ * 🚨 **The defect this closes is a run killed AFTER it had its answer.** When
+ * the last check files its cost the child is not finished: it still resolves
+ * severities and serialises the document, and a document with 5,000 issues is
+ * 639 KB of YAML. That phase emitted nothing, so the watchdog's clock kept
+ * running from the final cost line and a budget that expired there SIGKILLed a
+ * run whose work was complete — a false failure that discards a correct result.
+ *
+ * One `appendFileSync` buys severity resolution and serialisation a fresh budget
+ * window. It carries no fields: the fact that it was written is the whole
+ * message.
+ *
+ * 🪤 **Emitted by `runProjectChecks`, before it resolves severities.** It first
+ * shipped a level up, from `runOutcome` after that function had already
+ * returned, which left `resolveIssueSeverity` charged to the last check's window
+ * while this comment claimed otherwise. What it still does NOT cover is the last
+ * check's row-to-issue conversion — `runUnits` files that check's cost before
+ * converting its rows — which is why the report's `idle` sentence hedges.
+ */
+const ChecksCompleteEntrySchema = z.object({
+    kind: z.literal('checks-complete'),
+}).strict();
+const ProgressEntrySchema = z.discriminatedUnion('kind', [
+    StartedEntrySchema,
+    PopulationEntrySchema,
+    StartEntrySchema,
+    CheckEntrySchema,
+    ChecksCompleteEntrySchema,
+]);
+/**
+ * Read whatever of the log survived.
+ *
+ * @param text - The log's raw contents, tail damage and all
+ * @returns The lines that validate, in the order they were written
+ */
+export function parseProgressLog(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const entry = readLine(line);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * One line, or nothing.
+ *
+ * 🪤 Two separate refusals, deliberately: `JSON.parse` throws on the truncated
+ * tail, and the schema refuses a well-formed object that is not an entry this
+ * build knows. Collapsing them into one `try` around a parse-and-validate would
+ * still work, but the two failures mean different things — damage versus drift —
+ * and only the second is worth a future reader's attention.
+ *
+ * @param line - One line of the log
+ * @returns The entry, or undefined when the line is damaged or unknown
+ */
+function readLine(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (error) {
+        // `JSON.parse` throws exactly one thing for damage, and that is the thing
+        // this `undefined` stands for.
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return undefined;
+    }
+    const parsed = ProgressEntrySchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Which unit was running when the log stopped growing.
+ *
+ * 🔑 The population sentinel is keyed on the population line's ABSENCE rather
+ * than on there being no `start` lines. Those are different states: a run killed
+ * during population has no projection, while a run killed between the population
+ * and the first statement has one.
+ *
+ * 🔑 The startup sentinel is keyed the same way, on the `started` line's
+ * absence — never on an empty log. Before that line the child was still loading
+ * Node and the CLI, nothing had touched the tree, and advice about sizing the
+ * budget against a population would be advice about a unit that never began.
+ *
+ * @param entries - What {@link parseProgressLog} recovered
+ * @returns The unit in flight
+ */
+export function unitInFlight(entries) {
+    if (!entries.some((entry) => entry.kind === 'population')) {
+        return entries.some((entry) => entry.kind === 'started')
+            ? { kind: 'population' }
+            : { kind: 'startup' };
+    }
+    const completed = new Set(entries.filter((entry) => entry.kind === 'check').map((entry) => entry.name));
+    // 🪤 The `completed` set is what makes this unique, NOT the scan direction.
+    // The runner is serial — one statement at a time, its cost filed before the
+    // next `start` — so at most one `start` can lack a cost, and a scan from
+    // either end reaches the same entry. An earlier version scanned backwards and
+    // justified it as "the LAST unfinished start"; reversing it left all 10 unit
+    // tests green, which is the honest tell that the direction was never the
+    // guard. Dropping the `completed` filter, by contrast, reds immediately.
+    const started = entries.find((entry) => entry.kind === 'start' && !completed.has(entry.name));
+    if (started !== undefined)
+        return { kind: 'check', name: started.name };
+    // 🔑 Checked AFTER the in-flight statement, never before. The line means "no
+    // check is running any more"; a `start` without a cost means one still is, and
+    // a log holding both is damaged in a way that must still name the rule.
+    if (entries.some((entry) => entry.kind === 'checks-complete'))
+        return { kind: 'reporting' };
+    return { kind: 'idle' };
+}
+/**
+ * Open the log for append, and hand back the one-line-per-unit writer.
+ *
+ * ⚠️ `appendFileSync`, and it must stay synchronous. The child that writes these
+ * lines is about to enter a blocking native call; an asynchronous write would be
+ * queued behind work the event loop never gets back to, so the line naming the
+ * rule that hangs would exist only in memory — where `SIGKILL` destroys it.
+ *
+ * @param path - Where the supervisor is watching
+ * @returns A writer that appends one entry and returns once it is on disk
+ */
+export function createProgressWriter(path) {
+    return (entry) => {
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, 'utf-8');
+    };
+}
+//# sourceMappingURL=check-progress.js.map

package/dist/commands/resources/check-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-progress.js","sourceRoot":"","sources":["../../../src/commands/resources/check-progress.ts"],"names":[],"mappings":"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"}