@vibe-agent-toolkit/cli 0.2.0-rc.7 → 0.2.0-rc.8

package/dist/utils/command-error.js

@@ -1,13 +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 { inspect } from 'node:util';
-import { countBySeverity } from '@vibe-agent-toolkit/schema';
+import { ExitCode, buildErrorReport, countBySeverity, errorDiagnostics } from '@vibe-agent-toolkit/schema';
 import { writeJsonOutput, writeYamlOutput } from './output.js';
 /**
  * Format duration for human readability
@@ -23,31 +25,6 @@ export function formatDuration(ms) {
     }
     return `${(ms / 60000).toFixed(1)}m`;
 }
-/**
- * Everything about a thrown value that `error.message` alone discards.
- *
- * Exit 2 is the UNEXPECTED failure — an internal bug, not a usage mistake — and
- * the one thing a reader needs there is the frame that threw. A real `TypeError`
- * arrived here as a single line (`Cannot read properties of undefined (reading
- * 'readdir')`) with no file, no frames, and no flag that would produce them; the
- * only way to find the throw site was to hand-patch the built `dist`. A value
- * thrown that is not an `Error` fared worse still — the envelope flattens it to
- * the literal string `Unknown error`, which names neither its type nor its
- * contents.
- *
- * The result rides the logger's **debug** channel (`--debug`), so default output
- * is unchanged and no golden moves.
- *
- * @param error - The value that was thrown
- * @returns Stack trace for an `Error`, or an inspected rendering of a non-`Error`
- */
-export function errorDiagnostics(error) {
-    if (error instanceof Error) {
-        // `stack` is optional in the type and absent on some cross-realm errors.
-        return error.stack ?? `${error.name}: ${error.message}`;
-    }
-    return `Non-Error value thrown: ${inspect(error, { depth: 3 })}`;
-}
 /**
  * Report an unexpected failure on stderr and return the document that describes
  * it, WITHOUT deciding how the caller ends.
@@ -78,8 +55,8 @@ export function reportCommandError(error, logger, startTime, commandName) {
 /**
  * Handle command error with standard formatting and exit.
  *
- * The command-line ending for {@link reportCommandError}. Exit 2 is the
- * UNEXPECTED failure, per the exit-code contract every command's help documents.
+ * 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
@@ -98,25 +75,19 @@ export function reportCommandError(error, logger, startTime, commandName) {
  */
 export function handleCommandError(error, logger, startTime, commandName, format) {
     const document = reportCommandError(error, logger, startTime, commandName);
-    if (format === 'json') {
-        writeJsonOutput(document);
-    }
-    else {
-        writeYamlOutput(document);
-    }
-    process.exit(2);
+    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 exit 2) and {@link handleValidationGateFailure}
- * (a validation gate, always exit 1, 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` exiting 1 for
- * "this project declares no `ard:` block" or 2 for "there is no config file
- * here".
+ * 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
@@ -143,6 +114,16 @@ export function handleExpectedFailure(message, exitCode, startTime, format) {
         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);
     }
@@ -151,6 +132,40 @@ export function handleExpectedFailure(message, exitCode, startTime, format) {
     }
     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.
  *
@@ -163,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.
@@ -174,42 +189,31 @@ export function buildValidationGateFailure(subject, issues) {
  */
 export function handleValidationGateFailure(subject, issues) {
     writeYamlOutput(buildValidationGateFailure(subject, issues));
-    process.exit(1);
+    process.exit(ExitCode.FINDINGS);
 }
-/**
- * The exit code a USAGE mistake ends on: a flag this program does not declare,
- * a verb it does not know, a missing or invalid argument.
- *
- * 🔑 **Two is not a style choice — one was a factual lie.** Every command's
- * `--help` publishes the same three-way contract: `0` no error-severity
- * findings, `1` at least one, `2` a system error. 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, and the operator went
- * looking for a violation that did not exist.
- *
- * The same hole swallowed a mistyped verb (`vat resources chekc`) and every
- * unknown option on all 69 commands. VAT's own refusals were already correct —
- * an unknown `--check` name and an unusable `--budget` both exit 2 — so the
- * inconsistency was Commander's default leaking through the one path VAT had
- * not claimed.
- *
- * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
- * the same `_exit` path with code 0 and must stay 0; only a non-zero commander
- * ending is remapped. See {@link exitCodeForCommanderEnding}.
- */
-export const USAGE_ERROR_EXIT_CODE = 2;
 /**
  * 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
- * {@link USAGE_ERROR_EXIT_CODE}.
+ * 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,
@@ -218,9 +222,9 @@ export const USAGE_ERROR_EXIT_CODE = 2;
  * code commander already computed is the honest discriminator; the string is not.
  *
  * @param commanderExitCode - The `exitCode` commander put on its CommanderError
- * @returns 0 for a successful ending, {@link USAGE_ERROR_EXIT_CODE} otherwise
+ * @returns `OK` for a successful ending, `ERROR` otherwise
  */
 export function exitCodeForCommanderEnding(commanderExitCode) {
-    return commanderExitCode === 0 ? 0 : USAGE_ERROR_EXIT_CODE;
+    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":"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"}
+{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAiE,MAAM,4BAA4B,CAAC;AAG1K,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;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;AASD;;;;;;;;;;;;;;;;;;;GAmBG;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,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IAEzE,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,YAAY,OAAO,EAAE,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB,EACnB,MAA2B;IAE3B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IAC3E,OAAO,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,QAAuB,EACvB,SAAiB,EACjB,MAA2B;IAE3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAyB;QACrC,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;KACjD,CAAC;IACF,OAAO,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,QAAgB,EAAE,MAA0B,EAAE,QAAuB;IAC3F,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;SAAM,CAAC;QACN,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB,EACnB,MAA2B;IAE3B,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IACrF,OAAO,cAAc,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,QAAuB,EACvB,SAAiB,EACjB,MAA2B;IAE3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,cAAc,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC7F,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,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,0BAA0B,CAAC,iBAAyB;IAClE,OAAO,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;AAChE,CAAC"}

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,EAAuD,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAaxH;;;;;;;;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,CAkDzE;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"}
+{"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

@@ -7,7 +7,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { parseConfigAllowingUnknownKeys, ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
-import { safePath } from '@vibe-agent-toolkit/utils';
+import { safePath, VatError } from '@vibe-agent-toolkit/utils';
 import * as yaml from 'yaml';
 const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
 /**
@@ -25,11 +25,10 @@ const warnedConfigPaths = new Set();
  * `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;
@@ -59,12 +58,10 @@ 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.

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

@@ -1 +1 @@
-{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/context-budget-issues.d.ts

@@ -11,7 +11,7 @@
  *
  * A sweep reports every working location, and locations sharing an instruction
  * chain share one budget — that is the whole point of the collapse. Re-measured
- * on VAT's own tree 2026-08-23, after the context population began declining the
+ * on VAT's own tree, after the context population began declining the
  * gitignored half: **366 of 589 directories** pay the single chain
  * `['CLAUDE.md']`, so emitting per location would print 366 byte-identical
  * findings, all blaming one file, the moment the root `CLAUDE.md` crossed the

package/dist/utils/context-budget-issues.js

@@ -11,7 +11,7 @@
  *
  * A sweep reports every working location, and locations sharing an instruction
  * chain share one budget — that is the whole point of the collapse. Re-measured
- * on VAT's own tree 2026-08-23, after the context population began declining the
+ * on VAT's own tree, after the context population began declining the
  * gitignored half: **366 of 589 directories** pay the single chain
  * `['CLAUDE.md']`, so emitting per location would print 366 byte-identical
  * findings, all blaming one file, the moment the root `CLAUDE.md` crossed the

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

@@ -5,34 +5,12 @@
  * 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, and a second copy of it would be free to drift on the one
- * clause that only fails where nobody looks (see {@link escapesCorpusRoot}).
+ * 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.
  */
-/**
- * Does a path already stated against the corpus root fall OUTSIDE it?
- *
- * Three spellings of "outside", not two, and the third is the one that could
- * only fail where nobody would see it. `safePath.relative` says "not under this
- * root" with a `..`-prefixed path in the ordinary case, but returns an ABSOLUTE
- * path when no relative route exists at all — which on Windows is exactly what a
- * different drive letter produces. Without the third test, `vat claude context
- * D:\elsewhere\doc.md` run from a `C:` repo passes the guard and answers `kind:
- * unknown`, indistinguishable from a typo inside the tree, which is the one
- * outcome {@link targetPathWithin}'s `@throws` claims to prevent. Its sibling
- * `escapesRoot` (`closure-extent.ts`) applies the same triple for the same
- * reason.
- *
- * ⛔ Exported so it can be TESTED. On POSIX `safePath.relative` between two
- * absolute paths never returns an absolute string, so the third clause is
- * unreachable through {@link targetPathWithin} on every machine a developer
- * runs — the branch has to be exercised directly or not at all, and "not at
- * all" is how it went missing in the first place.
- *
- * @param normalizedRelative - A forward-slashed path already stated against the
- *   corpus root
- * @returns True when the corpus root does not contain it
- */
-export declare function escapesCorpusRoot(normalizedRelative: string): boolean;
 /**
  * The root-relative path to query, refusing anything outside the corpus.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"corpus-target.d.ts","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAIrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR"}
+{"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

@@ -5,39 +5,13 @@
  * 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, and a second copy of it would be free to drift on the one
- * clause that only fails where nobody looks (see {@link escapesCorpusRoot}).
+ * 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 { isAbsoluteAnyPlatform, safePath } from '@vibe-agent-toolkit/utils';
-/**
- * Does a path already stated against the corpus root fall OUTSIDE it?
- *
- * Three spellings of "outside", not two, and the third is the one that could
- * only fail where nobody would see it. `safePath.relative` says "not under this
- * root" with a `..`-prefixed path in the ordinary case, but returns an ABSOLUTE
- * path when no relative route exists at all — which on Windows is exactly what a
- * different drive letter produces. Without the third test, `vat claude context
- * D:\elsewhere\doc.md` run from a `C:` repo passes the guard and answers `kind:
- * unknown`, indistinguishable from a typo inside the tree, which is the one
- * outcome {@link targetPathWithin}'s `@throws` claims to prevent. Its sibling
- * `escapesRoot` (`closure-extent.ts`) applies the same triple for the same
- * reason.
- *
- * ⛔ Exported so it can be TESTED. On POSIX `safePath.relative` between two
- * absolute paths never returns an absolute string, so the third clause is
- * unreachable through {@link targetPathWithin} on every machine a developer
- * runs — the branch has to be exercised directly or not at all, and "not at
- * all" is how it went missing in the first place.
- *
- * @param normalizedRelative - A forward-slashed path already stated against the
- *   corpus root
- * @returns True when the corpus root does not contain it
- */
-export function escapesCorpusRoot(normalizedRelative) {
-    return normalizedRelative === '..'
-        || normalizedRelative.startsWith('../')
-        || isAbsoluteAnyPlatform(normalizedRelative);
-}
+import { relativeEscapesRoot, safePath } from '@vibe-agent-toolkit/utils';
 /**
  * The root-relative path to query, refusing anything outside the corpus.
  *
@@ -51,7 +25,7 @@ export function escapesCorpusRoot(normalizedRelative) {
  */
 export function targetPathWithin(root, pathArg, commandName) {
     const relative = safePath.relative(root, safePath.resolve(process.cwd(), pathArg ?? '.'));
-    if (escapesCorpusRoot(relative)) {
+    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.');

package/dist/utils/corpus-target.js.map

@@ -1 +1 @@
-{"version":3,"file":"corpus-target.js","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAAC,kBAA0B;IAC1D,OAAO,kBAAkB,KAAK,IAAI;WAC7B,kBAAkB,CAAC,UAAU,CAAC,KAAK,CAAC;WACpC,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAA2B,EAC3B,WAAmB;IAEnB,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1F,IAAI,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,qCAAqC,IAAI,GAAG;cACrE,IAAI,WAAW,yDAAyD;cACxE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"corpus-target.js","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAA2B,EAC3B,WAAmB;IAEnB,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1F,IAAI,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,qCAAqC,IAAI,GAAG;cACrE,IAAI,WAAW,yDAAyD;cACxE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"help-loader.d.ts","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD"}
+{"version":3,"file":"help-loader.d.ts","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD"}

package/dist/utils/help-loader.js

@@ -21,7 +21,6 @@ export function loadVerboseHelp(section) {
     const filename = section ? `${section}.md` : 'index.md';
     const helpPath = safePath.join(packageRoot, 'docs', filename);
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is constructed from known safe components
         const content = readFileSync(helpPath, 'utf-8');
         return content;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"help-loader.js","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,mCAAmC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEtD,wCAAwC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,qHAAqH;QACrH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;;0BAEe,QAAQ;;EAEhC,YAAY;;;CAGb,CAAC;IACA,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACrE,CAAC"}
+{"version":3,"file":"help-loader.js","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,mCAAmC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEtD,wCAAwC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;;0BAEe,QAAQ;;EAEhC,YAAY;;;CAGb,CAAC;IACA,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACrE,CAAC"}

package/dist/utils/issue-rendering.d.ts

@@ -177,8 +177,8 @@ export declare function formatCollapsedFindingsHint(collapsed: number, report: s
  * is not: `files.dependencies` carries only what the link-graph walk discovered, so
  * every file `files:` copied in — each glob match, plus any explicit entry the walk
  * had not already bundled — is absent from the total. A bundle holding SKILL.md, one
- * linked doc and one declared artifact prints `2 files`. That undercount is issue
- * #177 and is deliberately NOT patched here; this wording is only the part that can
+ * linked doc and one declared artifact prints `2 files`. That undercount is a
+ * report-shape defect and is deliberately NOT patched here; this wording is only the part that can
  * be made true today, so nobody reads the number as an inventory of the output.
  *
  * The `+ 1` is the bundle's root `SKILL.md`, which `files.dependencies` does not

package/dist/utils/issue-rendering.js

@@ -259,8 +259,8 @@ export function formatCollapsedFindingsHint(collapsed, report) {
  * is not: `files.dependencies` carries only what the link-graph walk discovered, so
  * every file `files:` copied in — each glob match, plus any explicit entry the walk
  * had not already bundled — is absent from the total. A bundle holding SKILL.md, one
- * linked doc and one declared artifact prints `2 files`. That undercount is issue
- * #177 and is deliberately NOT patched here; this wording is only the part that can
+ * linked doc and one declared artifact prints `2 files`. That undercount is a
+ * report-shape defect and is deliberately NOT patched here; this wording is only the part that can
  * be made true today, so nobody reads the number as an inventory of the output.
  *
  * The `+ 1` is the bundle's root `SKILL.md`, which `files.dependencies` does not

package/dist/utils/optional-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optional-backend.d.ts","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAkBH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,KAAK,CAcpE;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACxD,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,GAC9C,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAalC"}
+{"version":3,"file":"optional-backend.d.ts","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAoBH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,KAAK,CAcpE;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACxD,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,GAC9C,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAalC"}

package/dist/utils/optional-backend.js

@@ -25,6 +25,7 @@
 // of the rag lane's shared helpers live: that module statically imports
 // `@vibe-agent-toolkit/rag-lancedb`, so reaching for its `handleCommandError`
 // here would load the very backend this file exists to defer.
+import { ExitCode } from '@vibe-agent-toolkit/schema';
 import { writeYamlOutput } from './output.js';
 /**
  * Node's code for "the module is genuinely not installed".
@@ -78,7 +79,7 @@ export function reportMissingBackend(backend) {
         error: `${backend.feature} backend not installed: ${backend.packageName}`,
         fix: install,
     });
-    process.exit(2);
+    process.exit(ExitCode.ERROR);
 }
 /**
  * Bind a Commander action that loads its implementation on first invocation.

package/dist/utils/optional-backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"optional-backend.js","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,IAAI;WACd,MAAM,IAAI,KAAK;WACd,KAA4B,CAAC,IAAI,KAAK,gBAAgB,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,MAAM,OAAO,GAAG,eAAe,OAAO,CAAC,WAAW,EAAE,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,OAAO,CAAC,OAAO,6DAA6D;UAC7E,uBAAuB,OAAO,IAAI;UAClC,gFAAgF;UAChF,wDAAwD,CAC3D,CAAC;IACF,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,2BAA2B,OAAO,CAAC,WAAW,EAAE;QACzE,GAAG,EAAE,OAAO;KACb,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,OAAwB,EACxB,IAA+C;IAE/C,OAAO,KAAK,EAAE,GAAG,IAAU,EAAiB,EAAE;QAC5C,IAAI,OAA0C,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,KAAK,CAAC;YACd,CAAC;YACD,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"optional-backend.js","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,8DAA8D;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,IAAI;WACd,MAAM,IAAI,KAAK;WACd,KAA4B,CAAC,IAAI,KAAK,gBAAgB,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,MAAM,OAAO,GAAG,eAAe,OAAO,CAAC,WAAW,EAAE,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,OAAO,CAAC,OAAO,6DAA6D;UAC7E,uBAAuB,OAAO,IAAI;UAClC,gFAAgF;UAChF,wDAAwD,CAC3D,CAAC;IACF,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,2BAA2B,OAAO,CAAC,WAAW,EAAE;QACzE,GAAG,EAAE,OAAO;KACb,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,OAAwB,EACxB,IAA+C;IAE/C,OAAO,KAAK,EAAE,GAAG,IAAU,EAAiB,EAAE;QAC5C,IAAI,OAA0C,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,KAAK,CAAC;YACd,CAAC;YACD,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/output.d.ts

@@ -93,6 +93,15 @@ export declare function writeYamlOutput(data: unknown): void;
  * @param data - Data to serialize as JSON
  */
 export declare function writeJsonOutput(data: unknown): void;
+/**
+ * Write one structured document in the format a `--format` option selected:
+ * `json` → {@link writeJsonOutput}; anything else (including an absent option)
+ * → {@link writeYamlOutput}, the CLI's default document format.
+ *
+ * @param data - The document
+ * @param format - The selected format (`json`, or anything else for YAML)
+ */
+export declare function writeStructuredOutput(data: unknown, format: string | undefined): void;
 /**
  * Write a test-format finding to stderr.
  *

package/dist/utils/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAoCpF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+BN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAWnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAoCpF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+BN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAWnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}

package/dist/utils/output.js

@@ -157,6 +157,22 @@ export function writeYamlOutput(data) {
 export function writeJsonOutput(data) {
     process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
 }
+/**
+ * Write one structured document in the format a `--format` option selected:
+ * `json` → {@link writeJsonOutput}; anything else (including an absent option)
+ * → {@link writeYamlOutput}, the CLI's default document format.
+ *
+ * @param data - The document
+ * @param format - The selected format (`json`, or anything else for YAML)
+ */
+export function writeStructuredOutput(data, format) {
+    if (format === 'json') {
+        writeJsonOutput(data);
+    }
+    else {
+        writeYamlOutput(data);
+    }
+}
 /**
  * Write a test-format finding to stderr.
  *

package/dist/utils/output.js.map

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