@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

package/dist/utils/command-error.d.ts

@@ -1,12 +1,15 @@
 /**
  * Shared command error handling utilities.
  *
- * THE single implementation of each failure exit. `commands/skills/` used to
+ * The failure endings a command may take, each publishing a document and
+ * ending on one member of the `ExitCode` contract. `commands/skills/` used to
  * carry its own `handleCommandError` that logged to stderr and exited 2 having
  * written nothing to stdout — same name, same signature, same documented
- * contract, silently different behaviour. Every command family routes here.
+ * contract, silently different behaviour. A command that ends some other way
+ * still names its code from `ExitCode`; the lint rule
+ * `no-literal-process-exit` refuses a bare number.
  */
-import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+import { type ExitCodeValue, type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/schema';
 import type { Logger } from './logger.js';
 /**
  * Format duration for human readability
@@ -14,14 +17,114 @@ import type { Logger } from './logger.js';
  * @returns Formatted duration string (e.g., "500ms", "1.5s", "1.5m")
  */
 export declare function formatDuration(ms: number): string;
+/** The document a command publishes when an unexpected failure stops it. */
+export interface CommandErrorDocument {
+    status: 'error';
+    error: string;
+    duration: string;
+}
+/**
+ * Report an unexpected failure on stderr and return the document that describes
+ * it, WITHOUT deciding how the caller ends.
+ *
+ * Split out of {@link handleCommandError} because the same failure now has two
+ * endings and must not grow two policies. A command run from the command line
+ * writes this document to stdout and exits 2; the same command run as a phase of
+ * `vat validate` / `vat verify` / `vat build` runs in the orchestrator's own
+ * process, where exiting would kill the whole run and skip every later phase —
+ * so it hands the document back and the orchestrator nests it under that phase's
+ * `report`, exactly as it used to nest the child's captured stdout.
+ *
+ * The stderr half is identical in both lanes: progress and diagnostics have
+ * always streamed live, and that is unchanged by there no longer being a child.
+ *
+ * @param error - The value that was thrown
+ * @param logger - Logger instance for error output
+ * @param startTime - Command start time (from Date.now())
+ * @param commandName - Name of the command (for the error message)
+ */
+export declare function reportCommandError(error: unknown, logger: Logger, startTime: number, commandName: string): CommandErrorDocument;
 /**
- * Handle command error with standard formatting and exit
+ * Handle command error with standard formatting and exit.
+ *
+ * The command-line ending for {@link reportCommandError}. `ExitCode.ERROR` is
+ * the UNEXPECTED failure, per the exit-code contract every command's help documents.
+ *
+ * 🔑 **`format` is not decoration.** Every command offering `--format json`
+ * honoured it on the success path and emitted YAML here, so the one document a
+ * CI wrapper most needs to read — the one explaining why the command failed —
+ * arrived in a format its parser rejects. A consumer running
+ * `vat resources check --format json | jq .error` got a parse error on top of
+ * whatever went wrong, and had to guess at the second failure to find the first.
+ * A caller that has a `--format` option MUST pass it.
+ *
  * @param error - The error that occurred
  * @param logger - Logger instance for error output
  * @param startTime - Command start time (from Date.now())
  * @param commandName - Name of the command (for error message)
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML — matching the success path's own two-branch switch
+ */
+export declare function handleCommandError(error: unknown, logger: Logger, startTime: number, commandName: string, format?: string | undefined): never;
+/**
+ * Publish an EXPECTED failure in the format the operator asked for, then exit
+ * with the code the command's own contract assigns it.
+ *
+ * The third ending of one failure, beside {@link handleCommandError} (the
+ * UNEXPECTED failure, always `ERROR`) and {@link handleValidationGateFailure}
+ * (a validation gate, always `FINDINGS`, always YAML). This one covers the
+ * failure that is neither: the command ran, understood the project, and has a
+ * documented non-zero code for what it found — `vat ard emit` ending on
+ * `FINDINGS` for "this project declares no `ard:` block" or `ERROR` for "there
+ * is no config file here".
+ *
+ * 🔑 It exists because those endings were written inline, and an inline ending
+ * publishes nothing: `ard emit` honoured `--format json` on its success path
+ * and through `handleCommandError`, then wrote **zero bytes to stdout** on the
+ * two exits a repository actually reaches — the commonest being the first run
+ * of any repository that never opted into ARD. A CI wrapper reading stdout got
+ * an empty document and a bare non-zero code, which is the exact failure the
+ * `format` note on {@link handleCommandError} exists to forbid.
+ *
+ * The message goes to stderr as it always did — humans read it there — and the
+ * document goes to stdout, matching what both neighbours already do.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now()), so the document
+ *   reports the run's real duration rather than a fabricated zero
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML — the same two-branch switch the success path uses
  */
-export declare function handleCommandError(error: unknown, logger: Logger, startTime: number, commandName: string): never;
+export declare function handleExpectedFailure(message: string, exitCode: ExitCodeValue, startTime: number, format?: string | undefined): never;
+/**
+ * {@link handleCommandError} for a command whose document is the shared
+ * `Report<T>` envelope: the failure document IS the envelope
+ * (`buildErrorReport`), so the emitted `schemas/<command>.json` describes the
+ * failed run too. Every command registered as `report` in `report-schemas.ts`
+ * ends its unexpected failures here; `handleCommandError`'s
+ * `CommandErrorDocument` is the shape the legacy documents keep.
+ *
+ * @param error - The value that was thrown
+ * @param logger - Logger instance for error output
+ * @param startTime - Command start time (from Date.now())
+ * @param commandName - Name of the command (for the stderr line)
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export declare function handleReportCommandError(error: unknown, logger: Logger, startTime: number, commandName: string, format?: string | undefined): never;
+/**
+ * {@link handleExpectedFailure} for a command whose document is the shared
+ * `Report<T>` envelope — same document as {@link handleReportCommandError},
+ * with the exit code the command's own contract assigns.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now())
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export declare function handleReportExpectedFailure(message: string, exitCode: ExitCodeValue, startTime: number, format?: string | undefined): never;
 /** The payload a command publishes when its own validation gate stops it. */
 export interface ValidationGateFailure {
     status: 'error';
@@ -39,9 +142,9 @@ export interface ValidationGateFailure {
 export declare function buildValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): ValidationGateFailure;
 /**
  * Publish the documented failure payload for a command stopped by its OWN
- * validation gate, then exit 1.
+ * validation gate, then end on `FINDINGS`.
  *
- * {@link handleCommandError} above covers the UNEXPECTED failure (exit 2). This
+ * {@link handleCommandError} above covers the UNEXPECTED failure (`ERROR`). This
  * covers the expected one, and `vat skills build` / `vat skills package` both
  * exited it after writing zero bytes to stdout — while their `--help` texts
  * document a YAML summary on stdout and reserve exit 1 for exactly this case.
@@ -49,4 +152,38 @@ export declare function buildValidationGateFailure(subject: string, issues: read
  * a bare non-zero code.
  */
 export declare function handleValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): never;
+/**
+ * Map a commander termination to the exit code VAT's contract promises.
+ *
+ * A USAGE mistake — a flag this program does not declare, a verb it does not
+ * know, a missing or invalid argument — ends on `ExitCode.ERROR`, and the
+ * reason is not style. Commander's default for a usage mistake is
+ * `process.exit(1)`, so `vat resources check --json` (the option is
+ * `--format json`) exited **1** — which, read against the contract the command
+ * itself prints, asserts that at least one check was violated. Nothing had
+ * run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings` therefore
+ * reported findings that were never computed. The same hole swallowed a
+ * mistyped verb (`vat resources chekc`) and every unknown option on every
+ * command.
+ *
+ * Commander reports BOTH successful and failing terminations through the same
+ * `CommanderError`: `--help` and `--version` carry `exitCode` 0, while an
+ * unknown option, an unknown command and `help({ error: true })` carry non-zero.
+ * Anything non-zero is a usage mistake by construction — commander raises these
+ * only while parsing, before any action runs — so it maps to `ERROR`.
+ *
+ * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
+ * the same `_exit` path with code 0 and must stay `OK`; only a non-zero
+ * commander ending is remapped.
+ *
+ * 🪤 Do NOT switch on `error.code` (`commander.unknownOption`, `commander.help`,
+ * …). The unknown-COMMAND path arrives as `commander.help` with exitCode 1,
+ * because the `command:*` handler renders help with `{ error: true }` — so the
+ * code string says "help" for a case that is emphatically not one. The exit
+ * code commander already computed is the honest discriminator; the string is not.
+ *
+ * @param commanderExitCode - The `exitCode` commander put on its CommanderError
+ * @returns `OK` for a successful ending, `ERROR` otherwise
+ */
+export declare function exitCodeForCommanderEnding(commanderExitCode: number): ExitCodeValue;
 //# sourceMappingURL=command-error.d.ts.map

package/dist/utils/command-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAE9G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,KAAK,CAWP;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,qBAAqB,CAEvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,KAAK,CAGP"}
+{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAiE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE1K,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAQtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAGP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAQP;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAGP;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAGP;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,qBAAqB,CAEvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,KAAK,CAGP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAEnF"}

package/dist/utils/command-error.js

@@ -1,13 +1,16 @@
 /**
  * Shared command error handling utilities.
  *
- * THE single implementation of each failure exit. `commands/skills/` used to
+ * The failure endings a command may take, each publishing a document and
+ * ending on one member of the `ExitCode` contract. `commands/skills/` used to
  * carry its own `handleCommandError` that logged to stderr and exited 2 having
  * written nothing to stdout — same name, same signature, same documented
- * contract, silently different behaviour. Every command family routes here.
+ * contract, silently different behaviour. A command that ends some other way
+ * still names its code from `ExitCode`; the lint rule
+ * `no-literal-process-exit` refuses a bare number.
  */
-import { countBySeverity } from '@vibe-agent-toolkit/agent-schema';
-import { writeYamlOutput } from './output.js';
+import { ExitCode, buildErrorReport, countBySeverity, errorDiagnostics } from '@vibe-agent-toolkit/schema';
+import { writeJsonOutput, writeYamlOutput } from './output.js';
 /**
  * Format duration for human readability
  * @param ms - Duration in milliseconds
@@ -23,21 +26,145 @@ export function formatDuration(ms) {
     return `${(ms / 60000).toFixed(1)}m`;
 }
 /**
- * Handle command error with standard formatting and exit
+ * Report an unexpected failure on stderr and return the document that describes
+ * it, WITHOUT deciding how the caller ends.
+ *
+ * Split out of {@link handleCommandError} because the same failure now has two
+ * endings and must not grow two policies. A command run from the command line
+ * writes this document to stdout and exits 2; the same command run as a phase of
+ * `vat validate` / `vat verify` / `vat build` runs in the orchestrator's own
+ * process, where exiting would kill the whole run and skip every later phase —
+ * so it hands the document back and the orchestrator nests it under that phase's
+ * `report`, exactly as it used to nest the child's captured stdout.
+ *
+ * The stderr half is identical in both lanes: progress and diagnostics have
+ * always streamed live, and that is unchanged by there no longer being a child.
+ *
+ * @param error - The value that was thrown
+ * @param logger - Logger instance for error output
+ * @param startTime - Command start time (from Date.now())
+ * @param commandName - Name of the command (for the error message)
+ */
+export function reportCommandError(error, logger, startTime, commandName) {
+    const duration = Date.now() - startTime;
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logger.error(`${commandName} failed: ${message}`);
+    logger.debug(errorDiagnostics(error));
+    return { status: 'error', error: message, duration: formatDuration(duration) };
+}
+/**
+ * Handle command error with standard formatting and exit.
+ *
+ * The command-line ending for {@link reportCommandError}. `ExitCode.ERROR` is
+ * the UNEXPECTED failure, per the exit-code contract every command's help documents.
+ *
+ * 🔑 **`format` is not decoration.** Every command offering `--format json`
+ * honoured it on the success path and emitted YAML here, so the one document a
+ * CI wrapper most needs to read — the one explaining why the command failed —
+ * arrived in a format its parser rejects. A consumer running
+ * `vat resources check --format json | jq .error` got a parse error on top of
+ * whatever went wrong, and had to guess at the second failure to find the first.
+ * A caller that has a `--format` option MUST pass it.
+ *
  * @param error - The error that occurred
  * @param logger - Logger instance for error output
  * @param startTime - Command start time (from Date.now())
  * @param commandName - Name of the command (for error message)
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML — matching the success path's own two-branch switch
  */
-export function handleCommandError(error, logger, startTime, commandName) {
-    const duration = Date.now() - startTime;
-    logger.error(`${commandName} failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    writeYamlOutput({
+export function handleCommandError(error, logger, startTime, commandName, format) {
+    const document = reportCommandError(error, logger, startTime, commandName);
+    return publishFailure(document, format, ExitCode.ERROR);
+}
+/**
+ * Publish an EXPECTED failure in the format the operator asked for, then exit
+ * with the code the command's own contract assigns it.
+ *
+ * The third ending of one failure, beside {@link handleCommandError} (the
+ * UNEXPECTED failure, always `ERROR`) and {@link handleValidationGateFailure}
+ * (a validation gate, always `FINDINGS`, always YAML). This one covers the
+ * failure that is neither: the command ran, understood the project, and has a
+ * documented non-zero code for what it found — `vat ard emit` ending on
+ * `FINDINGS` for "this project declares no `ard:` block" or `ERROR` for "there
+ * is no config file here".
+ *
+ * 🔑 It exists because those endings were written inline, and an inline ending
+ * publishes nothing: `ard emit` honoured `--format json` on its success path
+ * and through `handleCommandError`, then wrote **zero bytes to stdout** on the
+ * two exits a repository actually reaches — the commonest being the first run
+ * of any repository that never opted into ARD. A CI wrapper reading stdout got
+ * an empty document and a bare non-zero code, which is the exact failure the
+ * `format` note on {@link handleCommandError} exists to forbid.
+ *
+ * The message goes to stderr as it always did — humans read it there — and the
+ * document goes to stdout, matching what both neighbours already do.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now()), so the document
+ *   reports the run's real duration rather than a fabricated zero
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML — the same two-branch switch the success path uses
+ */
+export function handleExpectedFailure(message, exitCode, startTime, format) {
+    process.stderr.write(`${message}\n`);
+    const document = {
         status: 'error',
-        error: error instanceof Error ? error.message : 'Unknown error',
-        duration: formatDuration(duration),
-    });
-    process.exit(2);
+        error: message,
+        duration: formatDuration(Date.now() - startTime),
+    };
+    return publishFailure(document, format, exitCode);
+}
+/**
+ * Publish a failure document in the operator's format, then end on `exitCode`.
+ *
+ * @param document - What to write to stdout
+ * @param format - `json`, or anything else (and omitted) for YAML
+ * @param exitCode - The member of the contract this ending is
+ */
+function publishFailure(document, format, exitCode) {
+    if (format === 'json') {
+        writeJsonOutput(document);
+    }
+    else {
+        writeYamlOutput(document);
+    }
+    process.exit(exitCode);
+}
+/**
+ * {@link handleCommandError} for a command whose document is the shared
+ * `Report<T>` envelope: the failure document IS the envelope
+ * (`buildErrorReport`), so the emitted `schemas/<command>.json` describes the
+ * failed run too. Every command registered as `report` in `report-schemas.ts`
+ * ends its unexpected failures here; `handleCommandError`'s
+ * `CommandErrorDocument` is the shape the legacy documents keep.
+ *
+ * @param error - The value that was thrown
+ * @param logger - Logger instance for error output
+ * @param startTime - Command start time (from Date.now())
+ * @param commandName - Name of the command (for the stderr line)
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export function handleReportCommandError(error, logger, startTime, commandName, format) {
+    const { error: message } = reportCommandError(error, logger, startTime, commandName);
+    return publishFailure(buildErrorReport(message, Date.now() - startTime), format, ExitCode.ERROR);
+}
+/**
+ * {@link handleExpectedFailure} for a command whose document is the shared
+ * `Report<T>` envelope — same document as {@link handleReportCommandError},
+ * with the exit code the command's own contract assigns.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now())
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export function handleReportExpectedFailure(message, exitCode, startTime, format) {
+    process.stderr.write(`${message}\n`);
+    return publishFailure(buildErrorReport(message, Date.now() - startTime), format, exitCode);
 }
 /**
  * Pure: the document {@link handleValidationGateFailure} writes.
@@ -51,9 +178,9 @@ export function buildValidationGateFailure(subject, issues) {
 }
 /**
  * Publish the documented failure payload for a command stopped by its OWN
- * validation gate, then exit 1.
+ * validation gate, then end on `FINDINGS`.
  *
- * {@link handleCommandError} above covers the UNEXPECTED failure (exit 2). This
+ * {@link handleCommandError} above covers the UNEXPECTED failure (`ERROR`). This
  * covers the expected one, and `vat skills build` / `vat skills package` both
  * exited it after writing zero bytes to stdout — while their `--help` texts
  * document a YAML summary on stdout and reserve exit 1 for exactly this case.
@@ -62,6 +189,42 @@ export function buildValidationGateFailure(subject, issues) {
  */
 export function handleValidationGateFailure(subject, issues) {
     writeYamlOutput(buildValidationGateFailure(subject, issues));
-    process.exit(1);
+    process.exit(ExitCode.FINDINGS);
+}
+/**
+ * Map a commander termination to the exit code VAT's contract promises.
+ *
+ * A USAGE mistake — a flag this program does not declare, a verb it does not
+ * know, a missing or invalid argument — ends on `ExitCode.ERROR`, and the
+ * reason is not style. Commander's default for a usage mistake is
+ * `process.exit(1)`, so `vat resources check --json` (the option is
+ * `--format json`) exited **1** — which, read against the contract the command
+ * itself prints, asserts that at least one check was violated. Nothing had
+ * run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings` therefore
+ * reported findings that were never computed. The same hole swallowed a
+ * mistyped verb (`vat resources chekc`) and every unknown option on every
+ * command.
+ *
+ * Commander reports BOTH successful and failing terminations through the same
+ * `CommanderError`: `--help` and `--version` carry `exitCode` 0, while an
+ * unknown option, an unknown command and `help({ error: true })` carry non-zero.
+ * Anything non-zero is a usage mistake by construction — commander raises these
+ * only while parsing, before any action runs — so it maps to `ERROR`.
+ *
+ * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
+ * the same `_exit` path with code 0 and must stay `OK`; only a non-zero
+ * commander ending is remapped.
+ *
+ * 🪤 Do NOT switch on `error.code` (`commander.unknownOption`, `commander.help`,
+ * …). The unknown-COMMAND path arrives as `commander.help` with exitCode 1,
+ * because the `command:*` handler renders help with `{ error: true }` — so the
+ * code string says "help" for a case that is emphatically not one. The exit
+ * code commander already computed is the honest discriminator; the string is not.
+ *
+ * @param commanderExitCode - The `exitCode` commander put on its CommanderError
+ * @returns `OK` for a successful ending, `ERROR` otherwise
+ */
+export function exitCodeForCommanderEnding(commanderExitCode) {
+    return commanderExitCode === 0 ? ExitCode.OK : ExitCode.ERROR;
 }
 //# sourceMappingURL=command-error.js.map

package/dist/utils/command-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAA6C,MAAM,kCAAkC,CAAC;AAG9G,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QACd,OAAO,GAAG,EAAE,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,YAAY,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;IAEnG,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;QAC/D,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC;KACnC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,MAAkC;IAElC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,MAAkC;IAElC,eAAe,CAAC,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"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"}

package/dist/utils/config-loader.d.ts

@@ -5,6 +5,7 @@
  * - VAT_TEST_CONFIG: Override config file path for testing (absolute path)
  */
 import { type ProjectConfig } from '@vibe-agent-toolkit/resources';
+import { VatError } from '@vibe-agent-toolkit/utils';
 /**
  * A `vibe-agent-toolkit.config.yaml` exists but failed to parse or validate.
  *
@@ -14,7 +15,7 @@ import { type ProjectConfig } from '@vibe-agent-toolkit/resources';
  * `vat skill test`) should surface this; a bulk linter (`vat audit`) may catch
  * it and fall back to config-free validation.
  */
-export declare class ConfigLoadError extends Error {
+export declare class ConfigLoadError extends VatError {
     readonly projectRoot: string;
     constructor(projectRoot: string, cause: unknown);
 }

package/dist/utils/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMxF;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAMhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CA8BzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB/E"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAuD,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxH,OAAO,EAAY,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAY/D;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAKhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgDzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB/E"}

package/dist/utils/config-loader.js

@@ -6,10 +6,16 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
-import { safePath } from '@vibe-agent-toolkit/utils';
+import { parseConfigAllowingUnknownKeys, ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
+import { safePath, VatError } from '@vibe-agent-toolkit/utils';
 import * as yaml from 'yaml';
 const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
+/**
+ * Config paths already warned about for unknown keys, so one config governing
+ * many skills produces one line rather than one per skill. Cleared with the
+ * config cache, which is what a test isolating a fixture resets.
+ */
+const warnedConfigPaths = new Set();
 /**
  * A `vibe-agent-toolkit.config.yaml` exists but failed to parse or validate.
  *
@@ -19,11 +25,10 @@ const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
  * `vat skill test`) should surface this; a bulk linter (`vat audit`) may catch
  * it and fall back to config-free validation.
  */
-export class ConfigLoadError extends Error {
+export class ConfigLoadError extends VatError {
     projectRoot;
     constructor(projectRoot, cause) {
-        super(cause instanceof Error ? cause.message : String(cause));
-        this.name = 'ConfigLoadError';
+        super('CONFIG_LOAD', cause instanceof Error ? cause.message : String(cause));
         this.projectRoot = projectRoot;
         if (cause instanceof Error)
             this.cause = cause;
@@ -53,24 +58,42 @@ export class ConfigLoadError extends Error {
 export function loadConfig(projectRoot) {
     // Override for testing: VAT_TEST_CONFIG provides explicit config path
     const configPath = process.env['VAT_TEST_CONFIG'] ?? safePath.join(projectRoot, CONFIG_FILENAME);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is derived from projectRoot parameter or env override
     if (!existsSync(configPath)) {
         return undefined;
     }
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is derived from projectRoot parameter
         const content = readFileSync(configPath, 'utf-8');
         const parsed = yaml.parse(content);
-        // Validate with canonical schema from resources package
-        const result = ProjectConfigSchema.safeParse(parsed);
-        if (!result.success) {
-            throw new Error(`Invalid configuration file: ${result.error.message}`);
-        }
-        return result.data;
+        // Validate with canonical schema from resources package.
+        //
+        // 🔑 The message comes from the shared formatter, NOT from `error.message`.
+        // In Zod 3 that property is a **JSON dump of the issue array**, and it was
+        // what an adopter got: five verbs exiting 2 in under a second on a blob that
+        // never named this file, never said which key was refused in words, and
+        // offered no remedy. Every strict block in the schema is a refusal an
+        // adopter has to be able to act on from the terminal alone.
+        // An UNKNOWN key warns and is dropped; every other validation failure still
+        // throws. See `parseConfigAllowingUnknownKeys` for the reasoning — briefly:
+        // a key VAT has no field for is a key VAT was already discarding, and
+        // turning that into an exit 2 broke commands that never read the section it
+        // was in. Warned once per config path, because `loadConfigCached` will
+        // otherwise re-warn for every skill under one project.
+        return parseConfigAllowingUnknownKeys(ProjectConfigSchema, parsed, (message) => {
+            if (warnedConfigPaths.has(configPath))
+                return;
+            warnedConfigPaths.add(configPath);
+            process.stderr.write(`${message}\n`);
+        }, { configPath });
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new Error(`Failed to load config: ${error.message}`);
+            // `cause` is load-bearing, not decoration: callers decide whether to
+            // degrade or abort by asking `isFilesystemAccessError`, which reads the
+            // errno off the error. Re-wrapping without it produced a plain Error with
+            // no `code`, so an unreadable config read as "a bug in VAT" and aborted the
+            // whole run — the exact failure `vat audit`'s guard exists to prevent,
+            // reintroduced by a message-formatting layer.
+            throw new Error(`Failed to load config: ${error.message}`, { cause: error });
         }
         throw error;
     }
@@ -107,6 +130,9 @@ const loadErrorCache = new Map();
 export function resetLoadedConfigCache() {
     loadedConfigCache.clear();
     loadErrorCache.clear();
+    // The warn-once ledger is part of this cache's state: a test that resets the
+    // caches and re-loads the same fixture expects to see the warning again.
+    warnedConfigPaths.clear();
 }
 /**
  * Cached variant of {@link loadConfig} keyed by `projectRoot`.

package/dist/utils/config-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,mBAAmB,EAAsB,MAAM,+BAA+B,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,eAAe,GAAG,gCAAgC,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,WAAW,CAAS;IAC7B,YAAY,WAAmB,EAAE,KAAc;QAC7C,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,KAAK,YAAY,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACjD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,sEAAsE;IACtE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IAEjG,uIAAuI;IACvI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,uHAAuH;QACvH,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEnC,wDAAwD;QACxD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAErD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,+BAA+B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CACtD,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,iBAAiB,GAAsC,IAAI,GAAG,EAAE,CAAC;AAEvE;;;;GAIG;AACH,MAAM,cAAc,GAAiC,IAAI,GAAG,EAAE,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,KAAK,EAAE,CAAC;IAC1B,cAAc,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACpD,IAAI,WAAW,KAAK,SAAS;QAAE,MAAM,WAAW,CAAC;IACjD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAClD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,IAAI,SAAS,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;QACvC,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,8EAA8E;QAC9E,MAAM,SAAS,GAAG,GAAG,YAAY,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QAC/F,cAAc,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAC3C,MAAM,SAAS,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/corpus-target.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolving a command-line path argument into a target INSIDE a corpus root.
+ *
+ * Shared by every command that populates one tree and then answers questions
+ * about positions in it — `vat claude context` and `vat claude budget` today.
+ * They ask different questions and default differently when no path is named,
+ * but "is this argument inside the tree I enumerated, and what is it called
+ * there" is one rule. The predicate itself is `relativeEscapesRoot` from
+ * `@vibe-agent-toolkit/utils` — the one lexical classifier every lane shares,
+ * so the clause that only fails on Windows (a cross-drive `relative()` comes
+ * back ABSOLUTE, not `..`-prefixed) is tested once, there, with the string
+ * Windows really produces.
+ */
+/**
+ * The root-relative path to query, refusing anything outside the corpus.
+ *
+ * @param root - The discovered project root
+ * @param pathArg - The path argument, or undefined for the current directory
+ * @param commandName - The command saying so, for the refusal's wording
+ * @returns The root-relative, forward-slashed target. `''` is the corpus root
+ * @throws When the argument resolves outside `root` — answering for it would
+ *   mean querying a corpus this projection never enumerated, and a confident
+ *   "nothing here" would be indistinguishable from a typo inside the tree
+ */
+export declare function targetPathWithin(root: string, pathArg: string | undefined, commandName: string): string;
+//# sourceMappingURL=corpus-target.d.ts.map

package/dist/utils/corpus-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-target.d.ts","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR"}

package/dist/utils/corpus-target.js

@@ -0,0 +1,35 @@
+/**
+ * Resolving a command-line path argument into a target INSIDE a corpus root.
+ *
+ * Shared by every command that populates one tree and then answers questions
+ * about positions in it — `vat claude context` and `vat claude budget` today.
+ * They ask different questions and default differently when no path is named,
+ * but "is this argument inside the tree I enumerated, and what is it called
+ * there" is one rule. The predicate itself is `relativeEscapesRoot` from
+ * `@vibe-agent-toolkit/utils` — the one lexical classifier every lane shares,
+ * so the clause that only fails on Windows (a cross-drive `relative()` comes
+ * back ABSOLUTE, not `..`-prefixed) is tested once, there, with the string
+ * Windows really produces.
+ */
+import { relativeEscapesRoot, safePath } from '@vibe-agent-toolkit/utils';
+/**
+ * The root-relative path to query, refusing anything outside the corpus.
+ *
+ * @param root - The discovered project root
+ * @param pathArg - The path argument, or undefined for the current directory
+ * @param commandName - The command saying so, for the refusal's wording
+ * @returns The root-relative, forward-slashed target. `''` is the corpus root
+ * @throws When the argument resolves outside `root` — answering for it would
+ *   mean querying a corpus this projection never enumerated, and a confident
+ *   "nothing here" would be indistinguishable from a typo inside the tree
+ */
+export function targetPathWithin(root, pathArg, commandName) {
+    const relative = safePath.relative(root, safePath.resolve(process.cwd(), pathArg ?? '.'));
+    if (relativeEscapesRoot(relative)) {
+        throw new Error(`${pathArg ?? process.cwd()} resolves outside the corpus root ${root}.`
+            + ` ${commandName} answers only for paths inside the root it discovered —`
+            + ' run it from within the project you mean to ask about.');
+    }
+    return relative;
+}
+//# sourceMappingURL=corpus-target.js.map