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

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,8BAA8B,EAAE,mBAAmB,EAAsB,MAAM,+BAA+B,CAAC;AACxH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,eAAe,GAAG,gCAAgC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAClC,WAAW,CAAS;IAC7B,YAAY,WAAmB,EAAE,KAAc;QAC7C,KAAK,CAAC,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7E,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,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEnC,yDAAyD;QACzD,EAAE;QACF,4EAA4E;QAC5E,2EAA2E;QAC3E,6EAA6E;QAC7E,wEAAwE;QACxE,sEAAsE;QACtE,4DAA4D;QAC5D,4EAA4E;QAC5E,4EAA4E;QAC5E,sEAAsE;QACtE,4EAA4E;QAC5E,uEAAuE;QACvE,uDAAuD;QACvD,OAAO,8BAA8B,CACnC,mBAAmB,EACnB,MAAM,EACN,CAAC,OAAO,EAAE,EAAE;YACV,IAAI,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC;gBAAE,OAAO;YAC9C,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACvC,CAAC,EACD,EAAE,UAAU,EAAE,CACf,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,qEAAqE;YACrE,wEAAwE;YACxE,0EAA0E;YAC1E,4EAA4E;YAC5E,uEAAuE;YACvE,8CAA8C;YAC9C,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/E,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;IACvB,6EAA6E;IAC7E,yEAAyE;IACzE,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,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

@@ -18,7 +18,7 @@
  * @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
+ * @throws {CommandRefusalError} `USAGE_INVALID` 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
  */

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;;;;;;;;;;;;GAYG;AAsCH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM,CAcR"}
+{"version":3,"file":"corpus-target.d.ts","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyCH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM,CAeR"}

package/dist/utils/corpus-target.js

@@ -13,6 +13,7 @@
  */
 import { dirname } from 'node:path';
 import { canonicalPath, relativeEscapesRoot, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
+import { CommandRefusalError } from './command-refusal.js';
 /**
  * The argument's root-relative spelling, or `undefined` when no ancestor of it
  * IS the root.
@@ -35,14 +36,15 @@ import { canonicalPath, relativeEscapesRoot, safePath, toForwardSlash } from '@v
  * @param target - The absolute, resolved argument
  */
 function relativeThroughRoot(root, target) {
-    const canonicalRoot = canonicalPath(root);
+    // The root and every ancestor of the typed argument are the operator's own: each is its own `within`.
+    const canonicalRoot = canonicalPath(root, root);
     const ancestors = [];
     for (let current = toForwardSlash(target);; current = toForwardSlash(dirname(current))) {
         ancestors.unshift(current);
         if (toForwardSlash(dirname(current)) === current)
             break;
     }
-    const anchor = ancestors.find((ancestor) => canonicalPath(ancestor) === canonicalRoot);
+    const anchor = ancestors.find((ancestor) => canonicalPath(ancestor, ancestor) === canonicalRoot);
     return anchor === undefined ? undefined : safePath.relative(anchor, target);
 }
 /**
@@ -52,7 +54,7 @@ function relativeThroughRoot(root, target) {
  * @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
+ * @throws {CommandRefusalError} `USAGE_INVALID` 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
  */
@@ -63,7 +65,7 @@ export function targetPathWithin(root, pathArg, commandName) {
     // a spelling that escapes lexically is asked the filesystem's opinion.
     const relative = relativeEscapesRoot(lexical) ? relativeThroughRoot(root, target) : lexical;
     if (relative === undefined || relativeEscapesRoot(relative)) {
-        throw new Error(`${pathArg ?? process.cwd()} resolves outside the corpus root ${root}.`
+        throw new CommandRefusalError('USAGE_INVALID', `${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;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,mBAAmB,CAAC,IAAY,EAAE,MAAc;IACvD,MAAM,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,IAAI,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,GAAI,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACxF,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO;YAAE,MAAM;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,aAAa,CAAC,CAAC;IACvF,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAA2B,EAC3B,WAAmB;IAEnB,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChD,6EAA6E;IAC7E,uEAAuE;IACvE,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5F,IAAI,QAAQ,KAAK,SAAS,IAAI,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5D,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,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEzG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,mBAAmB,CAAC,IAAY,EAAE,MAAc;IACvD,sGAAsG;IACtG,MAAM,aAAa,GAAG,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAChD,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,IAAI,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,GAAI,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACxF,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO;YAAE,MAAM;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,aAAa,CAAC,CAAC;IACjG,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAA2B,EAC3B,WAAmB;IAEnB,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChD,6EAA6E;IAC7E,uEAAuE;IACvE,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5F,IAAI,QAAQ,KAAK,SAAS,IAAI,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,mBAAmB,CAC3B,eAAe,EACf,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/debug-diagnostics.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether this run asked for `--debug` — read by the refusal path, which has
+ * no logger of its own.
+ *
+ * `--debug` exists to name the THROW SITE. A refusal is a user's mistake, so
+ * without the flag it publishes its message alone; with it, every refusal
+ * writes its diagnostics (the stack) to stderr, and `INTERNAL_ERROR` always
+ * does. `bin.ts` sets this once, at dispatch, from the parsed option.
+ */
+/**
+ * Record whether this run asked for `--debug`.
+ *
+ * @param on - The parsed `--debug` value
+ */
+export declare function setDebugDiagnostics(on: boolean): void;
+/** Whether every refusal should write its diagnostics to stderr. */
+export declare function debugDiagnosticsEnabled(): boolean;
+//# sourceMappingURL=debug-diagnostics.d.ts.map

package/dist/utils/debug-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-diagnostics.d.ts","sourceRoot":"","sources":["../../src/utils/debug-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAErD;AAED,oEAAoE;AACpE,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}

package/dist/utils/debug-diagnostics.js

@@ -0,0 +1,23 @@
+/**
+ * Whether this run asked for `--debug` — read by the refusal path, which has
+ * no logger of its own.
+ *
+ * `--debug` exists to name the THROW SITE. A refusal is a user's mistake, so
+ * without the flag it publishes its message alone; with it, every refusal
+ * writes its diagnostics (the stack) to stderr, and `INTERNAL_ERROR` always
+ * does. `bin.ts` sets this once, at dispatch, from the parsed option.
+ */
+let enabled = false;
+/**
+ * Record whether this run asked for `--debug`.
+ *
+ * @param on - The parsed `--debug` value
+ */
+export function setDebugDiagnostics(on) {
+    enabled = on;
+}
+/** Whether every refusal should write its diagnostics to stderr. */
+export function debugDiagnosticsEnabled() {
+    return enabled;
+}
+//# sourceMappingURL=debug-diagnostics.js.map

package/dist/utils/debug-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-diagnostics.js","sourceRoot":"","sources":["../../src/utils/debug-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,IAAI,OAAO,GAAG,KAAK,CAAC;AAEpB;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAW;IAC7C,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,uBAAuB;IACrC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/document-writer.d.ts

@@ -0,0 +1,191 @@
+/**
+ * The ONE writer of a `vat` command's stdout document.
+ *
+ * Every shape a command publishes is registered in `report-schemas.ts`, and
+ * this module is how it leaves: the document is looked up by verb, passed
+ * through the run-integrity refusal the registry's denominator declares,
+ * validated against its own published schema, rendered as yaml, json or text,
+ * and — for the `end…` functions — the process ends on the code the WRITTEN
+ * document derives. `local/no-stdout-outside-writer` keeps every other route
+ * to stdout out of `commands/`.
+ *
+ * 🔑 **Validated before a byte leaves.** A document the published schema
+ * rejects is a defect in VAT, and it throws here — the last resort ends it on
+ * `ERROR` — rather than shipping a shape an adopter's parser was promised
+ * would never appear.
+ */
+import { type Finding, type Gate, type RefusalCode, type Report, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { type DocumentFormat, type ExternalOutcome, type ExternalVerb, type LegacyVerb, type ReportVerb } from '../report-schemas.js';
+/**
+ * The document a report verb publishes, without writing it: the run-integrity
+ * refusal its registered denominator declares, then its published schema.
+ *
+ * For a lane that needs the published document before writing it — a command
+ * that warns on stderr with the refusal the writer adds. {@link writeDocument}
+ * goes through it too. (A phase of `vat build` / `validate` / `verify` hands
+ * back its report BEFORE this pass: the orchestrator judges zero examined on
+ * the whole run.)
+ *
+ * @param verb - The registered verb
+ * @param report - The document as the verb built it
+ * @returns The document as published
+ * @throws When the verb is unregistered or its schema rejects the document (a defect)
+ */
+export declare function publishedReport<T>(verb: ReportVerb, report: Report<T>): Report<T>;
+/**
+ * Publish a report verb's document.
+ *
+ * @param verb - The registered verb, as typed after `vat`
+ * @param report - The document as the verb built it
+ * @param format - How to render it
+ * @returns The document actually written — after the run-integrity refusal
+ * @throws When the verb is unregistered or its schema rejects the document (a defect)
+ */
+export declare function writeDocument<T>(verb: ReportVerb, report: Report<T>, format: DocumentFormat): Report<T>;
+/**
+ * Publish a report verb's document and end on the code it derives.
+ *
+ * @param verb - The registered verb
+ * @param report - The document as the verb built it
+ * @param format - How to render it
+ */
+export declare function endWithReport<T>(verb: ReportVerb, report: Report<T>, format: DocumentFormat): never;
+/** What finished before a refusal: the work a partial run already did. */
+export interface FinishedWork {
+    readonly examined: number;
+    readonly findings: readonly Finding[];
+    readonly data: unknown;
+}
+/** The explicit "nothing finished" — spelled out at the call site, never defaulted. */
+export declare const NOTHING_FINISHED: FinishedWork;
+/**
+ * Publish the envelope's error branch — the run could not do its job — with
+ * whatever finished, and end on `ERROR`.
+ *
+ * The message also goes to stderr, where a human reads it; `INTERNAL_ERROR`
+ * adds the stack, since that one is VAT's defect to report, and under
+ * `--debug` every refusal does — the flag exists to name the throw site.
+ *
+ * @param verb - The registered verb
+ * @param code - Which refusal: `USAGE_INVALID` for the invocation's mistake,
+ *   `INPUT_UNREADABLE` for an input that cannot be read, `INTERNAL_ERROR` only
+ *   for a failure VAT did not anticipate
+ * @param error - The thrown value, or the message
+ * @param format - How to render the document
+ * @param gate - The gate the run was judged by
+ * @param finished - The work that finished, or {@link NOTHING_FINISHED}
+ */
+export declare function endWithRefusal(verb: ReportVerb, code: RefusalCode, error: unknown, format: DocumentFormat, gate: Gate, finished: FinishedWork): never;
+/**
+ * The envelope's error branch for a refusal, with its human half already on
+ * stderr — what {@link endWithRefusal} writes, for the lane that hands the
+ * report on instead (a phase an orchestrator folds, or an orchestrator's own
+ * refusal).
+ *
+ * @param code - Which refusal (see {@link endWithRefusal})
+ * @param error - The thrown value, or the message
+ * @param gate - The gate the run was judged by
+ * @param finished - The work that finished, or {@link NOTHING_FINISHED}
+ * @returns The error report, not yet published
+ */
+export declare function refusalReport(code: RefusalCode, error: unknown, gate: Gate, finished: FinishedWork): Report<unknown>;
+/**
+ * What the failure path could not clean up — a temporary directory, a staged tree —
+ * recorded beside the thrown error (`suppressedFaultsOf`), as warnings naming each.
+ * Recorded beside, never on its cause chain: a leftover is never the run's refusal.
+ */
+export declare function leftoverFindingsOf(error: unknown): Array<ValidationIssue & Finding>;
+/**
+ * The {@link leftoverIssue} a failure to remove something stands for: its message, and — for a
+ * classified fault — the path it names (the entry left).
+ *
+ * @param fault - What the removal threw: a parked entry an uninstall or a clear could not delete
+ *   (`applyTreePlanOrLeftover`'s `leftover`), or a suppressed fault beside a refusal
+ */
+export declare function leftoverIssueOf(fault: unknown): ValidationIssue & Finding;
+/**
+ * Something a run made and could not remove — a temporary directory, a staged or parked tree —
+ * as the ONE warning every lane names it with ({@link TREE_CLEANUP_INCOMPLETE_CODE}), whether the
+ * run then refused or finished.
+ *
+ * @param message - What was left, and why it stayed
+ * @param path - The entry left, when known: its `link`
+ */
+export declare function leftoverIssue(message: string, path: string | undefined): ValidationIssue & Finding;
+/** A document another `vat` process wrote, checked to be its verb's, with the report it parses to. */
+export interface ForwardedDocument {
+    readonly text: string;
+    readonly report: Report<unknown>;
+}
+/**
+ * Read a report verb's document another `vat` process already wrote — a
+ * supervised child — checking it IS that verb's document: parsed in the format
+ * it was asked for and validated against the published schema.
+ *
+ * @param verb - The registered verb whose document `text` claims to be
+ * @param text - The document as the child wrote it
+ * @param format - The format the child was asked for
+ * @returns The text with the report it parses to, for {@link endWithForwardedDocument}
+ * @throws When `text` does not parse, or its schema rejects it — a truncated
+ *   write among them, which the caller decides how to report
+ */
+export declare function readForwardedDocument(verb: ReportVerb, text: string, format: Exclude<DocumentFormat, 'text'>): ForwardedDocument;
+/**
+ * Publish a forwarded document byte for byte and end on the code the document
+ * derives — never on the code the process that wrote it happened to exit with.
+ *
+ * @param document - What {@link readForwardedDocument} accepted
+ */
+export declare function endWithForwardedDocument(document: ForwardedDocument): never;
+/**
+ * Publish an externally owned payload verbatim and end on the code its
+ * registered adapter maps `outcome` to.
+ *
+ * @param verb - A verb of an `external` entry
+ * @param payload - The payload as its owner shaped it
+ * @param format - How to render it (`text` renders YAML)
+ * @param outcome - What the external write did
+ */
+export declare function writeExternalDocument(verb: ExternalVerb, payload: unknown, format: DocumentFormat, outcome: ExternalOutcome): never;
+/**
+ * End an external verb whose run threw: publish `{ error: { code, message } }`
+ * — the one failure payload every external verb shares, since the payload it
+ * would have passed through never arrived — and end on the code its adapter
+ * maps `failed` to. The code is the thrown value's own ({@link refusalCodeOf}):
+ * a missing key or a bad argument is `USAGE_INVALID`, a refused or unanswered
+ * API call `EXTERNAL_API_FAILED`, anything uncoded `INTERNAL_ERROR`.
+ *
+ * @param verb - A verb of an `external` entry
+ * @param error - What the run threw
+ * @param format - How to render the payload
+ */
+export declare function endWithExternalRefusal(verb: ExternalVerb, error: unknown, format: DocumentFormat): never;
+/**
+ * The one serializer for a `legacy` entry's document: unvalidated, and typed
+ * to the legacy verbs so no report verb can take this path.
+ *
+ * @param _verb - A verb of a `legacy` entry
+ * @param document - The legacy document
+ * @param format - How to render it
+ * @param text - The verb's own `--format text` rendering, written as-is; with
+ *   none (a refusal has no human rendering of its own) `text` renders YAML.
+ *   Required, so a caller says which it means
+ */
+export declare function writeLegacyDocument(_verb: LegacyVerb, document: unknown, format: DocumentFormat, text: string | undefined): void;
+/**
+ * Publish a stdout artifact — a config to paste, a file's text — and nothing else.
+ *
+ * @param name - The registered stdout artifact
+ * @param payload - The artifact; a string for `raw`
+ * @param format - `yaml` / `json`, or `raw` to write a string as-is
+ */
+export declare function writeArtifact(name: string, payload: unknown, format: Exclude<DocumentFormat, 'text'> | 'raw'): void;
+/**
+ * Write a registered file artifact: YAML for a `.yaml`/`.yml` path, JSON otherwise.
+ *
+ * @param name - The registered file artifact
+ * @param path - Where to write it
+ * @param payload - The artifact
+ */
+export declare function writeArtifactFile(name: string, path: string, payload: unknown): void;
+//# sourceMappingURL=document-writer.d.ts.map

package/dist/utils/document-writer.d.ts.map

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

package/dist/utils/document-writer.js

@@ -0,0 +1,319 @@
+/**
+ * The ONE writer of a `vat` command's stdout document.
+ *
+ * Every shape a command publishes is registered in `report-schemas.ts`, and
+ * this module is how it leaves: the document is looked up by verb, passed
+ * through the run-integrity refusal the registry's denominator declares,
+ * validated against its own published schema, rendered as yaml, json or text,
+ * and — for the `end…` functions — the process ends on the code the WRITTEN
+ * document derives. `local/no-stdout-outside-writer` keeps every other route
+ * to stdout out of `commands/`.
+ *
+ * 🔑 **Validated before a byte leaves.** A document the published schema
+ * rejects is a defect in VAT, and it throws here — the last resort ends it on
+ * `ERROR` — rather than shipping a shape an adopter's parser was promised
+ * would never appear.
+ */
+import { writeFileSync } from 'node:fs';
+import { buildErrorReport, CODE_REGISTRY, errorDiagnostics, exitCodeForReport, } from '@vibe-agent-toolkit/schema';
+import { isFsFaultError, suppressedFaultsOf, TREE_CLEANUP_INCOMPLETE_CODE } from '@vibe-agent-toolkit/utils';
+import { parse as parseYaml } from 'yaml';
+import { artifactShapeFor, exitCodeForExternal, reportShapeFor, } from '../report-schemas.js';
+import { errorMessageOf, refusalCodeOf, withFsFaultRemedy } from './command-refusal.js';
+import { debugDiagnosticsEnabled } from './debug-diagnostics.js';
+import { renderYamlDocument, writeStdoutSync } from './output.js';
+import { withRunIntegrity } from './run-integrity.js';
+/** One finding as a compiler-style line: `location:line:column: severity: message [code]`. */
+function findingLine(finding) {
+    const anchor = [finding.location, finding.line, finding.column].filter((part) => part !== undefined).join(':');
+    const line = `${finding.severity}: ${finding.message} [${finding.code}]`;
+    return anchor === '' ? line : `${anchor}: ${line}`;
+}
+/**
+ * The generic `--format text` rendering: one line per finding, then the status
+ * line with the counts and the denominator.
+ */
+function renderReportText(report, unit) {
+    const { errors, warnings, info } = report.summary;
+    const lines = report.findings.map(findingLine);
+    if (report.status === 'error')
+        lines.push(`error: ${report.error.message} [${report.error.code}]`);
+    lines.push(`status: ${report.status} — ${errors} errors, ${warnings} warnings, ${info} info (examined ${report.examined} ${unit})`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Write `document` in a structured format — `text` has no structure, so it is YAML.
+ *
+ * YAML opens with `---` and has NO trailing marker: `---` opens a document, so a
+ * trailer made every stdout a two-document stream a plain `YAML.parse()` refused.
+ *
+ * The ordinary stream write, not {@link writeStdoutSync}: a document follows
+ * progress written through `console.log`, and a synchronous fd-1 write would
+ * jump ahead of anything still buffered there. `makeStdioBlocking()` at startup
+ * makes both channels synchronous, so nothing is lost at `process.exit`.
+ */
+function writeStructured(document, format) {
+    process.stdout.write(format === 'json' ? `${JSON.stringify(document, null, 2)}\n` : `---\n${renderYamlDocument(document)}`);
+}
+/**
+ * The document a report verb publishes, without writing it: the run-integrity
+ * refusal its registered denominator declares, then its published schema.
+ *
+ * For a lane that needs the published document before writing it — a command
+ * that warns on stderr with the refusal the writer adds. {@link writeDocument}
+ * goes through it too. (A phase of `vat build` / `validate` / `verify` hands
+ * back its report BEFORE this pass: the orchestrator judges zero examined on
+ * the whole run.)
+ *
+ * @param verb - The registered verb
+ * @param report - The document as the verb built it
+ * @returns The document as published
+ * @throws When the verb is unregistered or its schema rejects the document (a defect)
+ */
+export function publishedReport(verb, report) {
+    const entry = reportShapeFor(verb);
+    const published = withRunIntegrity(report, entry.examined);
+    entry.schema.parse(published);
+    return published;
+}
+/**
+ * Publish a report verb's document.
+ *
+ * @param verb - The registered verb, as typed after `vat`
+ * @param report - The document as the verb built it
+ * @param format - How to render it
+ * @returns The document actually written — after the run-integrity refusal
+ * @throws When the verb is unregistered or its schema rejects the document (a defect)
+ */
+export function writeDocument(verb, report, format) {
+    const entry = reportShapeFor(verb);
+    const written = publishedReport(verb, report);
+    if (format === 'text') {
+        const text = entry.renderText === undefined
+            ? renderReportText(written, entry.examined.unit)
+            : entry.renderText(written);
+        if (text !== '')
+            process.stdout.write(text);
+    }
+    else {
+        writeStructured(written, format);
+    }
+    return written;
+}
+/**
+ * Publish a report verb's document and end on the code it derives.
+ *
+ * @param verb - The registered verb
+ * @param report - The document as the verb built it
+ * @param format - How to render it
+ */
+export function endWithReport(verb, report, format) {
+    process.exit(exitCodeForReport(writeDocument(verb, report, format)));
+}
+/** The explicit "nothing finished" — spelled out at the call site, never defaulted. */
+export const NOTHING_FINISHED = Object.freeze({ examined: 0, findings: [], data: null });
+/**
+ * Publish the envelope's error branch — the run could not do its job — with
+ * whatever finished, and end on `ERROR`.
+ *
+ * The message also goes to stderr, where a human reads it; `INTERNAL_ERROR`
+ * adds the stack, since that one is VAT's defect to report, and under
+ * `--debug` every refusal does — the flag exists to name the throw site.
+ *
+ * @param verb - The registered verb
+ * @param code - Which refusal: `USAGE_INVALID` for the invocation's mistake,
+ *   `INPUT_UNREADABLE` for an input that cannot be read, `INTERNAL_ERROR` only
+ *   for a failure VAT did not anticipate
+ * @param error - The thrown value, or the message
+ * @param format - How to render the document
+ * @param gate - The gate the run was judged by
+ * @param finished - The work that finished, or {@link NOTHING_FINISHED}
+ */
+export function endWithRefusal(verb, code, error, format, gate, finished) {
+    process.exit(exitCodeForReport(writeDocument(verb, refusalReport(code, error, gate, finished), format)));
+}
+/**
+ * A refusal's human half: its message on stderr — the code's own description
+ * when the thrown value carries none — plus the stack for a VAT defect, or for
+ * any refusal under `--debug`, which exists to name the throw site.
+ *
+ * @returns The message the published document carries
+ */
+function announceRefusal(code, error) {
+    const raw = errorMessageOf(error);
+    const message = raw === '' ? CODE_REGISTRY[code].description : withFsFaultRemedy(raw, error);
+    process.stderr.write(`${message}\n`);
+    if (code === 'INTERNAL_ERROR' || debugDiagnosticsEnabled())
+        process.stderr.write(`${errorDiagnostics(error)}\n`);
+    return message;
+}
+/**
+ * The envelope's error branch for a refusal, with its human half already on
+ * stderr — what {@link endWithRefusal} writes, for the lane that hands the
+ * report on instead (a phase an orchestrator folds, or an orchestrator's own
+ * refusal).
+ *
+ * @param code - Which refusal (see {@link endWithRefusal})
+ * @param error - The thrown value, or the message
+ * @param gate - The gate the run was judged by
+ * @param finished - The work that finished, or {@link NOTHING_FINISHED}
+ * @returns The error report, not yet published
+ */
+export function refusalReport(code, error, gate, finished) {
+    const message = announceRefusal(code, error);
+    return buildErrorReport({
+        error: { code, message },
+        gate,
+        examined: finished.examined,
+        findings: [...finished.findings, ...leftoverFindingsOf(error)],
+        data: finished.data,
+    });
+}
+/**
+ * What the failure path could not clean up — a temporary directory, a staged tree —
+ * recorded beside the thrown error (`suppressedFaultsOf`), as warnings naming each.
+ * Recorded beside, never on its cause chain: a leftover is never the run's refusal.
+ */
+export function leftoverFindingsOf(error) {
+    return suppressedFaultsOf(error).map((fault) => {
+        process.stderr.write(`warning: ${errorMessageOf(fault)}\n`);
+        return leftoverIssueOf(fault);
+    });
+}
+/**
+ * The {@link leftoverIssue} a failure to remove something stands for: its message, and — for a
+ * classified fault — the path it names (the entry left).
+ *
+ * @param fault - What the removal threw: a parked entry an uninstall or a clear could not delete
+ *   (`applyTreePlanOrLeftover`'s `leftover`), or a suppressed fault beside a refusal
+ */
+export function leftoverIssueOf(fault) {
+    return leftoverIssue(errorMessageOf(fault), isFsFaultError(fault) ? fault.path : undefined);
+}
+/**
+ * Something a run made and could not remove — a temporary directory, a staged or parked tree —
+ * as the ONE warning every lane names it with ({@link TREE_CLEANUP_INCOMPLETE_CODE}), whether the
+ * run then refused or finished.
+ *
+ * @param message - What was left, and why it stayed
+ * @param path - The entry left, when known: its `link`
+ */
+export function leftoverIssue(message, path) {
+    return {
+        code: TREE_CLEANUP_INCOMPLETE_CODE,
+        severity: 'warning',
+        message,
+        // `link`, never `location`: a report's location is project-relative, and this is an absolute path (a temp dir, a staged tree).
+        ...(path === undefined ? {} : { link: path }),
+        fix: 'Remove what the message names yourself, making it writable first if the OS refused; nothing VAT made uses it.',
+    };
+}
+/**
+ * Read a report verb's document another `vat` process already wrote — a
+ * supervised child — checking it IS that verb's document: parsed in the format
+ * it was asked for and validated against the published schema.
+ *
+ * @param verb - The registered verb whose document `text` claims to be
+ * @param text - The document as the child wrote it
+ * @param format - The format the child was asked for
+ * @returns The text with the report it parses to, for {@link endWithForwardedDocument}
+ * @throws When `text` does not parse, or its schema rejects it — a truncated
+ *   write among them, which the caller decides how to report
+ */
+export function readForwardedDocument(verb, text, format) {
+    const parsed = format === 'json' ? JSON.parse(text) : parseYaml(text);
+    reportShapeFor(verb).schema.parse(parsed);
+    return { text, report: parsed };
+}
+/**
+ * Publish a forwarded document byte for byte and end on the code the document
+ * derives — never on the code the process that wrote it happened to exit with.
+ *
+ * @param document - What {@link readForwardedDocument} accepted
+ */
+export function endWithForwardedDocument(document) {
+    writeStdoutSync(document.text);
+    process.exit(exitCodeForReport(document.report));
+}
+/**
+ * Publish an externally owned payload verbatim and end on the code its
+ * registered adapter maps `outcome` to.
+ *
+ * @param verb - A verb of an `external` entry
+ * @param payload - The payload as its owner shaped it
+ * @param format - How to render it (`text` renders YAML)
+ * @param outcome - What the external write did
+ */
+export function writeExternalDocument(verb, payload, format, outcome) {
+    writeStructured(payload, format);
+    process.exit(exitCodeForExternal(verb, outcome));
+}
+/**
+ * End an external verb whose run threw: publish `{ error: { code, message } }`
+ * — the one failure payload every external verb shares, since the payload it
+ * would have passed through never arrived — and end on the code its adapter
+ * maps `failed` to. The code is the thrown value's own ({@link refusalCodeOf}):
+ * a missing key or a bad argument is `USAGE_INVALID`, a refused or unanswered
+ * API call `EXTERNAL_API_FAILED`, anything uncoded `INTERNAL_ERROR`.
+ *
+ * @param verb - A verb of an `external` entry
+ * @param error - What the run threw
+ * @param format - How to render the payload
+ */
+export function endWithExternalRefusal(verb, error, format) {
+    const code = refusalCodeOf(error);
+    const message = announceRefusal(code, error);
+    writeExternalDocument(verb, { error: { code, message } }, format, { kind: 'failed', cause: message });
+}
+/**
+ * The one serializer for a `legacy` entry's document: unvalidated, and typed
+ * to the legacy verbs so no report verb can take this path.
+ *
+ * @param _verb - A verb of a `legacy` entry
+ * @param document - The legacy document
+ * @param format - How to render it
+ * @param text - The verb's own `--format text` rendering, written as-is; with
+ *   none (a refusal has no human rendering of its own) `text` renders YAML.
+ *   Required, so a caller says which it means
+ */
+export function writeLegacyDocument(_verb, document, format, text) {
+    // The verb's TYPE is the guarantee — only a legacy verb compiles here.
+    if (format === 'text' && text !== undefined) {
+        // Synchronously, as `claude context` always wrote it: its text can run long and the verb exits straight after.
+        writeStdoutSync(text);
+        return;
+    }
+    writeStructured(document, format);
+}
+/** Validate a payload against its artifact entry's schema, when it declares one. */
+function validatedArtifact(name, channel, payload) {
+    artifactShapeFor(name, channel).schema?.parse(payload);
+}
+/**
+ * Publish a stdout artifact — a config to paste, a file's text — and nothing else.
+ *
+ * @param name - The registered stdout artifact
+ * @param payload - The artifact; a string for `raw`
+ * @param format - `yaml` / `json`, or `raw` to write a string as-is
+ */
+export function writeArtifact(name, payload, format) {
+    validatedArtifact(name, 'stdout', payload);
+    if (format === 'raw') {
+        process.stdout.write(String(payload));
+        return;
+    }
+    writeStructured(payload, format);
+}
+/**
+ * Write a registered file artifact: YAML for a `.yaml`/`.yml` path, JSON otherwise.
+ *
+ * @param name - The registered file artifact
+ * @param path - Where to write it
+ * @param payload - The artifact
+ */
+export function writeArtifactFile(name, path, payload) {
+    validatedArtifact(name, 'file', payload);
+    const text = /\.ya?ml$/.test(path) ? renderYamlDocument(payload) : `${JSON.stringify(payload, null, 2)}\n`;
+    writeFileSync(path, text, 'utf-8');
+}
+//# sourceMappingURL=document-writer.js.map