@vibe-agent-toolkit/cli 0.1.41-rc.6 → 0.1.41-rc.8

package/dist/commands/phase-utils.d.ts

@@ -1,14 +1,98 @@
 /**
- * Shared utilities for top-level phase orchestration commands (vat build, vat verify).
+ * Shared utilities for top-level phase orchestration commands (vat build, vat verify, vat validate).
  */
+import { type SeverityCounts } from '@vibe-agent-toolkit/agent-schema';
+import { type Command } from 'commander';
 import { createLogger } from '../utils/logger.js';
 export interface Phase {
     name: string;
     args: string[];
 }
+/**
+ * Declare `--only` on a command that has RETIRED it, solely so the command can
+ * explain itself instead of emitting Commander's bare `error: unknown option
+ * '--only'`.
+ *
+ * This is **not** a backward-compatibility shim — the pre-1.0 policy forbids
+ * those and this obeys it. The flag does not work: {@link rejectRetiredOnly}
+ * fails the run before any phase is selected, so no caller can keep depending
+ * on the old behaviour. What it buys is a diagnosis. An unknown-option error
+ * names the flag and nothing else; the reader cannot tell a typo from a removal
+ * and has no way to learn what replaced it, so the next move is a bug report or
+ * a version pin. Naming the removal, the measurement behind it, and the command
+ * where `--only` still exists turns a dead end into a one-line fix.
+ *
+ * Hidden from `--help` on purpose: a retired flag is not a feature to discover,
+ * and listing it would suggest it still selects something.
+ */
+export declare function addRetiredOnlyOption(command: Command): Command;
+/**
+ * Fail the run when a caller passed the retired `--only`, naming what changed.
+ *
+ * Exit 1, matching both Commander's usage-error convention and the exit code an
+ * unroutable `--only` already produced on these commands, so a CI gate that was
+ * failing on a bad `--only` keeps failing rather than flipping to green.
+ *
+ * @param only - The parsed `--only` value; `undefined` when it was not passed.
+ * @param command - Command name for the message, e.g. `vat validate`.
+ * @param seconds - The measured full-run duration that made the flag not worth
+ *   its coverage risk. Cited so the removal reads as a decision with evidence
+ *   rather than a preference.
+ */
+export declare function rejectRetiredOnly(only: string | undefined, command: string, seconds: number): void;
+/**
+ * Outcome of one orchestrated phase.
+ *
+ * `system-error` is a value of its own because **a phase that could not RUN is
+ * not a phase that found problems.** Collapsing it into `error` (which is what
+ * `result.status === 0 ? 'passed' : 'failed'` did) made the documented exit
+ * code 2 unreachable from every orchestrator, so a CI script could not tell an
+ * invalid config or a killed child from a broken link.
+ *
+ * `warning` reaches a subprocess phase through the child's own reported
+ * `status`, NOT through its exit code — `vat skills validate` exits 0 while
+ * reporting `status: warning`, so an exit-code-only mapping answered `success`
+ * on the very tree where the child said otherwise. In-process phases (e.g.
+ * verify's consistency check) emit it directly.
+ */
+export type PhaseStatus = 'success' | 'warning' | 'error' | 'system-error';
+/** The phase outcome for "we did not learn what this phase would have said". */
+export declare const SYSTEM_ERROR: PhaseStatus;
 export interface PhaseResult {
     name: string;
-    status: string;
+    status: PhaseStatus;
+    /** Child exit code, when the child ran and exited on its own. */
+    exitCode?: number;
+    /** POSIX signal that killed the child, when one did (then `exitCode` is absent). */
+    signal?: string;
+    /** Why the phase could not run at all (the spawn itself failed). */
+    error?: string;
+    /**
+     * Per-severity distribution for in-process phases that hold their own
+     * findings. Absent for subprocess phases: the child owns its own findings,
+     * and inventing counts here would be a second, weaker answer — the child's
+     * are carried verbatim in {@link PhaseResult.report} instead.
+     */
+    issueCounts?: SeverityCounts;
+    /**
+     * The child's own YAML document, parsed and folded in.
+     *
+     * The child used to write this straight onto the parent's stdout (`stdio:
+     * 'inherit'`), which concatenated N documents with no `---` between them: two
+     * phases produced one map carrying `status:` and `durationSecs:` twice, and
+     * `YAML.parse()` threw "Map keys must be unique". Nesting each child's
+     * document under its own phase makes the parent's stdout one parseable
+     * document again and loses nothing.
+     */
+    report?: unknown;
+}
+/** The subset of a `spawnSync` return that decides a phase's outcome. */
+export interface PhaseSpawnOutcome {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error | undefined;
+    /** The child's captured stdout, when it was piped rather than inherited. */
+    stdout?: string | null | undefined;
 }
 /**
  * Resolve the absolute path to the vat binary.
@@ -21,19 +105,164 @@ export interface PhaseContext {
     binPath: string;
 }
 /**
- * Create the shared phase command context: logger, startTime, and validated bin path.
- * Throws if the phases list is empty (indicating an unknown --only value).
+ * Create the shared phase command context: logger, startTime, and bin path.
+ *
+ * It used to THROW when the phase list came out empty — and it was called
+ * before the command's try block, so an unroutable `--only` reached the user as
+ * a raw Node stack trace with zero bytes of stdout and an exit 1 that looked
+ * like "validation errors". `--only` routing is decided by
+ * {@link decidePhaseSelection} and reported by {@link applyPhaseSelection} now,
+ * which emit the command's normal structured document.
+ */
+export declare function createPhaseContext(debugFlag: boolean | undefined): PhaseContext;
+/**
+ * The decision an orchestrator reaches about what `--only` asked for.
+ *
+ * Three arms, because the three answers carry different exit codes and none of
+ * them may be collapsed into another:
+ *   - `run`  — go ahead with these phases.
+ *   - `fail` — the caller named a phase that is unrecognized, or recognized but
+ *              not configured. Exit 1: a CI gate asked for coverage that cannot
+ *              run and must not stay green.
+ *   - `noop` — a bare run in a project that configures nothing. Exit 0, but
+ *              WARNED, so a config typo is not indistinguishable from success.
+ */
+export type PhaseSelection = {
+    kind: 'run';
+    phases: Phase[];
+} | {
+    kind: 'fail';
+    message: string;
+} | {
+    kind: 'noop';
+    warning: string;
+    note: string;
+};
+/** How one orchestrator names the things `--only` selects, for its messages. */
+export interface PhaseVocabulary {
+    /** Capitalized singular: 'Phase' (build, verify) or 'Surface' (validate). */
+    noun: 'Phase' | 'Surface';
+    /** The verb in "nothing to <verb>": 'build', 'verify', 'validate'. */
+    verb: string;
+    /** Every name `--only` accepts, in help order. */
+    validNames: readonly string[];
+    /** Stderr warning + stdout note for a bare run with nothing configured. */
+    noop?: {
+        warning: string;
+        note: string;
+    };
+}
+/**
+ * Decide what an orchestrator should do with its `--only` value and the phase
+ * list its config produced.
+ *
+ * Shared by all three orchestrators because they used to disagree: `vat verify`
+ * built its phase list without consulting the config at all, so `vat verify
+ * --only skills` in a project with no `skills:` block exited 0 while `vat
+ * validate --only skills` on the same project exited 1 — opposite verdicts on
+ * the same question. (`vat verify` has since retired `--only` entirely and now
+ * always passes `only: undefined`; `vat validate` and `vat build` still route
+ * their own `--only` through here.)
+ *
+ * There used to be a third option, `emptyIsValid`, which existed solely so
+ * `vat verify --only consistency` could run with an empty SUBPROCESS list
+ * (consistency runs in-process). It was checked BEFORE `unreadableConfig`, so
+ * `vat verify --only consistency` against an unparseable config answered the
+ * confidently-wrong "no skills: block" instead of reporting the config error.
+ * `--only` is gone from verify, `emptyIsValid` went with it, and that ordering
+ * hazard cannot recur: nothing short-circuits ahead of the config-error arm.
+ *
+ * @param unreadableConfig - The config-load error, when the config exists but
+ *   could not be parsed. A broken config is NOT "the phase is unconfigured":
+ *   we do not know what it declares, so we must not answer with a confident
+ *   "not configured". Only `vat verify` passes it, and only defensively — its
+ *   phase builder pushes every subprocess phase when the config is unreadable
+ *   (so the CHILD reports the real error), which makes the list non-empty and
+ *   this arm unreachable by construction today. It is kept because the arm that
+ *   would otherwise catch an empty list is the "not configured" lie.
+ */
+export declare function decidePhaseSelection(only: string | undefined, phases: Phase[], vocab: PhaseVocabulary, options?: {
+    unreadableConfig?: string | undefined;
+}): PhaseSelection;
+/**
+ * Act on a {@link PhaseSelection}: return the phases to run, or emit the
+ * command's normal structured document and exit.
  *
- * @param debugFlag - Whether debug logging is enabled
- * @param phases - Pre-built list of phases to validate
- * @param onlyValue - The --only flag value (for the error message)
- * @param validPhaseNames - Human-readable list of valid phase names (for error message)
- * @returns Initialized phase context
- * @throws Error if phases list is empty
+ * Both terminal arms go through `writeYamlOutput` deliberately. A `--only`
+ * failure used to be an uncaught throw, so the one output a scripted caller
+ * parses — the YAML document on stdout — was never written at all.
  */
-export declare function createPhaseContext(debugFlag: boolean | undefined, phases: Phase[], onlyValue: string | undefined, validPhaseNames: string): PhaseContext;
+export declare function applyPhaseSelection(selection: PhaseSelection, logger: ReturnType<typeof createLogger>, startTime: number): Phase[];
+/** The worse of two phase statuses, per {@link PHASE_STATUS_ORDER}. */
+export declare function worseOf(a: PhaseStatus, b: PhaseStatus): PhaseStatus;
+/**
+ * Map a spawn outcome to a phase outcome. The pure core of {@link runPhase}.
+ *
+ * Every branch that is NOT "the child ran and told us what it found" is a
+ * system error, because the orchestrator learned nothing about the artifact:
+ *
+ * | spawn outcome            | phase status   | why                                        |
+ * |--------------------------|----------------|--------------------------------------------|
+ * | `error` set              | `system-error` | the child never ran                        |
+ * | killed by a signal       | `system-error` | the child was cut off mid-answer           |
+ * | no exit code, no signal  | `system-error` | there is no answer to read                 |
+ * | stdout not parseable     | `system-error` | the child's answer cannot be read          |
+ * | exit 0                   | `success`      | ran, found nothing actionable              |
+ * | exit 1                   | `error`        | ran, found validation errors               |
+ * | exit 2 (or any other)    | `system-error` | the child itself reported a system error    |
+ *
+ * The exit code is then reconciled with the child's OWN reported `status`,
+ * worst-wins. An exit code has three values and cannot express `warning`, so
+ * `vat skills validate` — which exits 0 while reporting `status: warning` —
+ * was being recorded as `success` by every orchestrator, including the one
+ * VAT's CI dogfoods on VAT itself.
+ */
+export declare function phaseResultFromSpawn(name: string, outcome: PhaseSpawnOutcome): PhaseResult;
 /**
  * Run a single phase by spawning the vat binary with the phase args.
+ *
+ * stdout is CAPTURED, not inherited: the child's YAML document belongs in this
+ * phase's `report`, and letting it stream onto the parent's stdout is what made
+ * `vat validate`'s output a run of documents with no `---` between them.
+ * stderr stays inherited — progress output is on stderr by design and must keep
+ * streaming live rather than arriving in one lump at the end.
  */
 export declare function runPhase(binPath: string, phase: Phase): PhaseResult;
+/**
+ * Worst-wins aggregate across phases. `system-error` outranks `error`: "we could
+ * not determine the answer" must never be filed under "we determined it is bad".
+ */
+export declare function aggregatePhaseStatus(results: readonly PhaseResult[]): PhaseStatus;
+/**
+ * One phase's per-severity distribution, wherever that phase keeps it.
+ *
+ * An in-process phase holds its own findings and publishes {@link
+ * PhaseResult.issueCounts}. A subprocess phase deliberately does not — the child
+ * owns its findings, and its document rides verbatim in {@link
+ * PhaseResult.report}. Reading only the former is why an orchestrator's header
+ * could report `{0, 0, 0}` over children that had just reported 12 warnings.
+ *
+ * Absent or malformed counts read as zero rather than throwing: a phase that
+ * published no distribution contributes nothing to the total, which is the same
+ * answer as before this function existed — just no longer the answer for phases
+ * that DID publish one.
+ */
+export declare function phaseIssueCounts(result: PhaseResult): SeverityCounts;
+/**
+ * Sum every phase's distribution, so an orchestrator's header total reconciles
+ * against the phases printed beneath it.
+ *
+ * The companion to {@link aggregatePhaseStatus}: status has always been
+ * worst-wins ACROSS phases, and a header whose `status` can see the children
+ * while its `issueCounts` cannot is the same contradiction in one document —
+ * `status: warning` beside `warnings: 0`.
+ */
+export declare function aggregatePhaseIssueCounts(results: readonly PhaseResult[]): SeverityCounts;
+/**
+ * The process exit code for a set of phase outcomes, per the exit-code contract
+ * every orchestrator's help text documents: 0 pass, 1 validation failure,
+ * 2 system error. Warnings do not fail a run — they are published in the status
+ * and counts instead.
+ */
+export declare function exitCodeForPhases(results: readonly PhaseResult[]): 0 | 1 | 2;
 //# sourceMappingURL=phase-utils.d.ts.map

package/dist/commands/phase-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phase-utils.d.ts","sourceRoot":"","sources":["../../src/commands/phase-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAKvC;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,MAAM,GACtB,YAAY,CASd;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,WAAW,CAKnE"}
+{"version":3,"file":"phase-utils.d.ts","sourceRoot":"","sources":["../../src/commands/phase-utils.ts"],"names":[],"mappings":"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"}