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

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/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,25 +17,6 @@ import type { Logger } from './logger.js';
  * @returns Formatted duration string (e.g., "500ms", "1.5s", "1.5m")
  */
 export declare function formatDuration(ms: number): string;
-/**
- * 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 declare function errorDiagnostics(error: unknown): string;
 /** The document a command publishes when an unexpected failure stops it. */
 export interface CommandErrorDocument {
     status: 'error';
@@ -63,8 +47,8 @@ export declare function reportCommandError(error: unknown, logger: Logger, start
 /**
  * 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
@@ -87,12 +71,12 @@ export declare function handleCommandError(error: unknown, logger: Logger, start
  * 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
@@ -112,7 +96,35 @@ export declare function handleCommandError(error: unknown, logger: Logger, start
  * @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 handleExpectedFailure(message: string, exitCode: number, startTime: number, format?: string | undefined): 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';
@@ -130,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.
@@ -140,40 +152,29 @@ export declare function buildValidationGateFailure(subject: string, issues: read
  * a bare non-zero code.
  */
 export declare function handleValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): never;
-/**
- * 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 declare 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,
@@ -182,7 +183,7 @@ export declare 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 declare function exitCodeForCommanderEnding(commanderExitCode: number): number;
+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;AAIH,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAExG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMvD;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,CAQP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAaP;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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAE5E"}
+{"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,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":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAA6C,MAAM,4BAA4B,CAAC;AAGxG,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;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,yEAAyE;QACzE,OAAO,KAAK,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,2BAA2B,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AACnE,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,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,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,QAAgB,EAChB,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,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;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;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B,CAAC,iBAAyB;IAClE,OAAO,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC;AAC7D,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,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/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"}