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

package/dist/utils/operator-notices.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The ONE route for a notice addressed to the operator — a config-loader warning, a projection-store
+ * notice — and the ONE predicate that says whether this process is a supervised checks child.
+ *
+ * ## 🔑 Each notice prints once per run, from the process that owes it
+ *
+ * `vat resources check` runs its checks in a supervised CHILD (`--supervised-by`), and `vat validate`
+ * runs that same child as its `checks` phase. The child reads the same config and keys the same
+ * store as the process that spawned it, and its stderr is inherited — so a notice both printed was
+ * printed twice for one run.
+ *
+ * Who owes what:
+ *
+ * - **A config warning** — the invoking process. It loads the config itself in both invocations
+ *   (`vat validate` to choose its phases, a standalone `vat resources check` to say whether the
+ *   project declares checks of its own), so a supervised child never prints one.
+ * - **The store notice** — whichever process keys the store first. `vat validate` opens its store
+ *   scope before any phase runs, so a child started as its phase stays quiet; a standalone
+ *   `vat resources check` opens no store at all — keying one is a git snapshot, unbounded work a
+ *   supervisor must not do before its watchdog exists — so the child it started prints it.
+ *
+ * The audience is decided ONCE, at the command's entry, from its explicit argv
+ * ({@link isSupervisedChild}), and entered as a scope ({@link withNoticeAudience}) the command's
+ * whole run sits inside. Nothing sets it as a side effect, and it ends with the scope — so a unit
+ * test, or a second command in one process, starts from "print everything".
+ *
+ * ## 🔑 "Once" belongs to the same scope
+ *
+ * A notice that would repeat — one config governing many skills, one unkeyable root asked about by
+ * every nested population scope — carries a `once` key, and the ledger that remembers it lives in
+ * the SAME scope as the audience: {@link withNoticeAudience} starts a fresh one, and so does the
+ * outermost population scope ({@link withNoticeLedger}) — starting from what was printed before it,
+ * so a config loaded both before and inside it warns once — so a second command in one process
+ * says it again. There is one ledger mechanism, not one per notice kind. Outside every scope (a config
+ * loaded before any population, a unit test) the ledger is the process's own, reset with the config
+ * cache ({@link resetUnscopedNoticeLedger}).
+ *
+ * ⚠️ Only NOTICES go through here: news that does not change what the run decides. A refusal's
+ * message, and anything that explains the document the child publishes, is the child's to print.
+ */
+/** What a notice is about — which decides which process owes it. */
+export type NoticeKind = 'config' | 'store';
+/** Which notices this process prints. Outside any scope, every one. */
+export type NoticeAudience = Readonly<Record<NoticeKind, boolean>>;
+/** Every notice — the audience of any process that is not a supervised child. */
+export declare const EVERY_NOTICE: NoticeAudience;
+/**
+ * Is this process the child a supervisor spawned to run the checks?
+ *
+ * 🔑 The ONE predicate, read from the explicit argv: `--supervised-by` is what a supervisor hands
+ * its child and nothing else passes (the child refuses it unless its parent is the supervisor the
+ * value names). Every decision that turns on "am I the child" asks this — which process runs the
+ * checks, which prints the "no checks of its own" warning, which notices it owes.
+ *
+ * @param argv - The command's parsed options
+ * @param argv.supervisedBy - The hidden `--supervised-by` value, or undefined
+ * @returns True in the supervised child
+ */
+export declare function isSupervisedChild<T extends {
+    readonly supervisedBy: string | undefined;
+}>(argv: T): argv is T & {
+    readonly supervisedBy: string;
+};
+/**
+ * Run `work` with `audience` deciding which notices this process prints, and a fresh `once` ledger.
+ *
+ * @param audience - Which notices to print
+ * @param work - The command's run
+ * @returns Whatever `work` returned
+ */
+export declare function withNoticeAudience<T>(audience: NoticeAudience, work: () => T): T;
+/**
+ * Run `work` inside a notice scope: the enclosing one when there is one, else a fresh scope that
+ * prints every notice — so `once` means once per command run, never once per process.
+ *
+ * 🚨 The fresh scope STARTS from what was already printed outside every scope, and copies it: a
+ * command loads its config before it opens its population scope (`vat validate`, to choose its
+ * phases) and again inside it, so a scope starting empty printed that config warning twice for one
+ * run. A copy, not the set itself, so what the scope prints stays its own and the next run says it
+ * again.
+ *
+ * @param work - The run
+ * @returns Whatever `work` returned
+ */
+export declare function withNoticeLedger<T>(work: () => T): T;
+/** Forget the `once` notices printed outside every scope — with the config cache they describe. */
+export declare function resetUnscopedNoticeLedger(): void;
+/**
+ * Write one notice to the operator's stderr — unless the enclosing scope says another process owes
+ * it, or it carries a `once` key this scope has already printed.
+ *
+ * @param kind - What the notice is about
+ * @param message - The notice, without a trailing newline
+ * @param once - When set, print this notice at most once per scope for this key
+ */
+export declare function noticeToOperator(kind: NoticeKind, message: string, once?: string): void;
+//# sourceMappingURL=operator-notices.d.ts.map

package/dist/utils/operator-notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-notices.d.ts","sourceRoot":"","sources":["../../src/utils/operator-notices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5C,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAEnE,iFAAiF;AACjF,eAAO,MAAM,YAAY,EAAE,cAA8C,CAAC;AAa1E;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EACvF,IAAI,EAAE,CAAC,GACN,IAAI,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAEhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAIpD;AAED,mGAAmG;AACnG,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAUvF"}

package/dist/utils/operator-notices.js

@@ -0,0 +1,115 @@
+/**
+ * The ONE route for a notice addressed to the operator — a config-loader warning, a projection-store
+ * notice — and the ONE predicate that says whether this process is a supervised checks child.
+ *
+ * ## 🔑 Each notice prints once per run, from the process that owes it
+ *
+ * `vat resources check` runs its checks in a supervised CHILD (`--supervised-by`), and `vat validate`
+ * runs that same child as its `checks` phase. The child reads the same config and keys the same
+ * store as the process that spawned it, and its stderr is inherited — so a notice both printed was
+ * printed twice for one run.
+ *
+ * Who owes what:
+ *
+ * - **A config warning** — the invoking process. It loads the config itself in both invocations
+ *   (`vat validate` to choose its phases, a standalone `vat resources check` to say whether the
+ *   project declares checks of its own), so a supervised child never prints one.
+ * - **The store notice** — whichever process keys the store first. `vat validate` opens its store
+ *   scope before any phase runs, so a child started as its phase stays quiet; a standalone
+ *   `vat resources check` opens no store at all — keying one is a git snapshot, unbounded work a
+ *   supervisor must not do before its watchdog exists — so the child it started prints it.
+ *
+ * The audience is decided ONCE, at the command's entry, from its explicit argv
+ * ({@link isSupervisedChild}), and entered as a scope ({@link withNoticeAudience}) the command's
+ * whole run sits inside. Nothing sets it as a side effect, and it ends with the scope — so a unit
+ * test, or a second command in one process, starts from "print everything".
+ *
+ * ## 🔑 "Once" belongs to the same scope
+ *
+ * A notice that would repeat — one config governing many skills, one unkeyable root asked about by
+ * every nested population scope — carries a `once` key, and the ledger that remembers it lives in
+ * the SAME scope as the audience: {@link withNoticeAudience} starts a fresh one, and so does the
+ * outermost population scope ({@link withNoticeLedger}) — starting from what was printed before it,
+ * so a config loaded both before and inside it warns once — so a second command in one process
+ * says it again. There is one ledger mechanism, not one per notice kind. Outside every scope (a config
+ * loaded before any population, a unit test) the ledger is the process's own, reset with the config
+ * cache ({@link resetUnscopedNoticeLedger}).
+ *
+ * ⚠️ Only NOTICES go through here: news that does not change what the run decides. A refusal's
+ * message, and anything that explains the document the child publishes, is the child's to print.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Every notice — the audience of any process that is not a supervised child. */
+export const EVERY_NOTICE = { config: true, store: true };
+const noticeScope = new AsyncLocalStorage();
+/** The `once` ledger outside every scope. */
+const unscopedPrinted = new Set();
+/**
+ * Is this process the child a supervisor spawned to run the checks?
+ *
+ * 🔑 The ONE predicate, read from the explicit argv: `--supervised-by` is what a supervisor hands
+ * its child and nothing else passes (the child refuses it unless its parent is the supervisor the
+ * value names). Every decision that turns on "am I the child" asks this — which process runs the
+ * checks, which prints the "no checks of its own" warning, which notices it owes.
+ *
+ * @param argv - The command's parsed options
+ * @param argv.supervisedBy - The hidden `--supervised-by` value, or undefined
+ * @returns True in the supervised child
+ */
+export function isSupervisedChild(argv) {
+    return argv.supervisedBy !== undefined;
+}
+/**
+ * Run `work` with `audience` deciding which notices this process prints, and a fresh `once` ledger.
+ *
+ * @param audience - Which notices to print
+ * @param work - The command's run
+ * @returns Whatever `work` returned
+ */
+export function withNoticeAudience(audience, work) {
+    return noticeScope.run({ audience, printed: new Set() }, work);
+}
+/**
+ * Run `work` inside a notice scope: the enclosing one when there is one, else a fresh scope that
+ * prints every notice — so `once` means once per command run, never once per process.
+ *
+ * 🚨 The fresh scope STARTS from what was already printed outside every scope, and copies it: a
+ * command loads its config before it opens its population scope (`vat validate`, to choose its
+ * phases) and again inside it, so a scope starting empty printed that config warning twice for one
+ * run. A copy, not the set itself, so what the scope prints stays its own and the next run says it
+ * again.
+ *
+ * @param work - The run
+ * @returns Whatever `work` returned
+ */
+export function withNoticeLedger(work) {
+    return noticeScope.getStore() === undefined
+        ? noticeScope.run({ audience: EVERY_NOTICE, printed: new Set(unscopedPrinted) }, work)
+        : work();
+}
+/** Forget the `once` notices printed outside every scope — with the config cache they describe. */
+export function resetUnscopedNoticeLedger() {
+    unscopedPrinted.clear();
+}
+/**
+ * Write one notice to the operator's stderr — unless the enclosing scope says another process owes
+ * it, or it carries a `once` key this scope has already printed.
+ *
+ * @param kind - What the notice is about
+ * @param message - The notice, without a trailing newline
+ * @param once - When set, print this notice at most once per scope for this key
+ */
+export function noticeToOperator(kind, message, once) {
+    const scope = noticeScope.getStore();
+    if (!(scope?.audience ?? EVERY_NOTICE)[kind])
+        return;
+    if (once !== undefined) {
+        const printed = scope?.printed ?? unscopedPrinted;
+        const key = `${kind}:${once}`;
+        if (printed.has(key))
+            return;
+        printed.add(key);
+    }
+    process.stderr.write(`${message}\n`);
+}
+//# sourceMappingURL=operator-notices.js.map

package/dist/utils/operator-notices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-notices.js","sourceRoot":"","sources":["../../src/utils/operator-notices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAQrD,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAQ1E,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAe,CAAC;AAEzD,6CAA6C;AAC7C,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAO;IAEP,OAAO,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAI,QAAwB,EAAE,IAAa;IAC3E,OAAO,WAAW,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAI,IAAa;IAC/C,OAAO,WAAW,CAAC,QAAQ,EAAE,KAAK,SAAS;QACzC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC;QACtF,CAAC,CAAC,IAAI,EAAE,CAAC;AACb,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,yBAAyB;IACvC,eAAe,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,OAAe,EAAE,IAAa;IAC/E,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;IACrC,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,IAAI,YAAY,CAAC,CAAC,IAAI,CAAC;QAAE,OAAO;IACrD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,eAAe,CAAC;QAClD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC7B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACvC,CAAC"}

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

@@ -21,6 +21,8 @@
  * error naming the package to install, and nothing more — the point is that
  * the failure is readable, not that it is survivable.
  */
+import type { ReportVerb } from '../report-schemas.js';
+import { CommandRefusalError } from './command-refusal.js';
 /**
  * Whether a thrown value is Node's "module not installed" error.
  *
@@ -32,23 +34,19 @@
  */
 export declare function isModuleMissing(error: unknown): boolean;
 /**
- * Report an uninstalled backend and exit, in the shape every other command
- * failure takes.
+ * The refusal for an uninstalled backend: `BACKEND_UNAVAILABLE`, exit **2** — a
+ * fact about the installation, not about the user's corpus, and a caller
+ * scripting `vat` must be able to tell those apart from the exit code alone.
  *
- * Exit code **2** — a system error, not a validation failure. An absent
- * optional package is a fact about the installation rather than about the
- * user's corpus, and a caller scripting `vat` must be able to tell those apart
- * from the exit code alone.
- *
- * Exported for the backends that are not selected by a Commander action —
- * {@link lazyAction} is the shape most take, but a store chosen by an
- * environment variable is loaded from inside a command rather than in place of
- * one, and it must fail the same way.
+ * Returned, not thrown and not written, so the verb that needed the backend
+ * publishes it in its own shape: {@link lazyAction} ends through the writer, and
+ * a store chosen from inside a command (the projection store) throws it into
+ * that command's catch.
  *
  * @param backend - What to name and how to install it
- * @returns Never; the process exits
+ * @returns The coded refusal; its message names the package and the install command
  */
-export declare function reportMissingBackend(backend: OptionalBackend): never;
+export declare function missingBackendError(backend: OptionalBackend): CommandRefusalError;
 /** One optional backend, as a user is told to install it. */
 export interface OptionalBackend {
     /** Human name used in the error message, e.g. `RAG`. */
@@ -65,14 +63,19 @@ export interface OptionalBackend {
  * stay eagerly available, which is exactly why the split is at the action
  * rather than at the command.
  *
+ * An absent backend ends the run through the writer as `verb`'s
+ * `BACKEND_UNAVAILABLE` refusal — every leaf behind this seam is a report verb
+ * with no `--format` and no `--strict`, so the document is YAML and the gate fixed.
+ *
+ * @param verb - The report verb the action is, for the refusal document
  * @param backend - What to name in the error when the import fails to resolve
  * @param load - Imports the module and returns the handler out of it
  * @returns A Commander action that loads, then delegates
  *
  * @example
  * ```typescript
- * .action(lazyAction(RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
+ * .action(lazyAction('rag index', RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
  * ```
  */
-export declare function lazyAction<Args extends readonly unknown[]>(backend: OptionalBackend, load: () => Promise<(...args: Args) => unknown>): (...args: Args) => Promise<void>;
+export declare function lazyAction<Args extends readonly unknown[]>(verb: ReportVerb, backend: OptionalBackend, load: () => Promise<(...args: Args) => unknown>): (...args: Args) => Promise<void>;
 //# sourceMappingURL=optional-backend.d.ts.map

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;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"}
+{"version":3,"file":"optional-backend.d.ts","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAa3D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,mBAAmB,CAOjF;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACxD,IAAI,EAAE,UAAU,EAChB,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

@@ -21,12 +21,8 @@
  * error naming the package to install, and nothing more — the point is that
  * the failure is readable, not that it is survivable.
  */
-// Deliberately NOT `commands/rag/command-helpers.js`, which is where the rest
-// 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';
+import { CommandRefusalError } from './command-refusal.js';
+import { endWithRefusal, NOTHING_FINISHED } from './document-writer.js';
 /**
  * Node's code for "the module is genuinely not installed".
  *
@@ -52,34 +48,22 @@ export function isModuleMissing(error) {
         && error.code === MODULE_NOT_FOUND);
 }
 /**
- * Report an uninstalled backend and exit, in the shape every other command
- * failure takes.
+ * The refusal for an uninstalled backend: `BACKEND_UNAVAILABLE`, exit **2** — a
+ * fact about the installation, not about the user's corpus, and a caller
+ * scripting `vat` must be able to tell those apart from the exit code alone.
  *
- * Exit code **2** — a system error, not a validation failure. An absent
- * optional package is a fact about the installation rather than about the
- * user's corpus, and a caller scripting `vat` must be able to tell those apart
- * from the exit code alone.
- *
- * Exported for the backends that are not selected by a Commander action —
- * {@link lazyAction} is the shape most take, but a store chosen by an
- * environment variable is loaded from inside a command rather than in place of
- * one, and it must fail the same way.
+ * Returned, not thrown and not written, so the verb that needed the backend
+ * publishes it in its own shape: {@link lazyAction} ends through the writer, and
+ * a store chosen from inside a command (the projection store) throws it into
+ * that command's catch.
  *
  * @param backend - What to name and how to install it
- * @returns Never; the process exits
+ * @returns The coded refusal; its message names the package and the install command
  */
-export function reportMissingBackend(backend) {
-    const install = `npm install ${backend.packageName}`;
-    process.stderr.write(`${backend.feature} is an optional feature and its backend is not installed.\n`
-        + `\nInstall it with:  ${install}\n`
-        + '\nIt ships separately because it carries a platform-native binary that every\n'
-        + 'other vat command would otherwise download and load.\n');
-    writeYamlOutput({
-        status: 'error',
-        error: `${backend.feature} backend not installed: ${backend.packageName}`,
-        fix: install,
-    });
-    process.exit(ExitCode.ERROR);
+export function missingBackendError(backend) {
+    return new CommandRefusalError('BACKEND_UNAVAILABLE', `${backend.feature} is an optional feature and its backend is not installed. `
+        + `Install it with: npm install ${backend.packageName} — it ships separately because it carries `
+        + 'a platform-native binary that every other vat command would otherwise download and load.');
 }
 /**
  * Bind a Commander action that loads its implementation on first invocation.
@@ -90,16 +74,21 @@ export function reportMissingBackend(backend) {
  * stay eagerly available, which is exactly why the split is at the action
  * rather than at the command.
  *
+ * An absent backend ends the run through the writer as `verb`'s
+ * `BACKEND_UNAVAILABLE` refusal — every leaf behind this seam is a report verb
+ * with no `--format` and no `--strict`, so the document is YAML and the gate fixed.
+ *
+ * @param verb - The report verb the action is, for the refusal document
  * @param backend - What to name in the error when the import fails to resolve
  * @param load - Imports the module and returns the handler out of it
  * @returns A Commander action that loads, then delegates
  *
  * @example
  * ```typescript
- * .action(lazyAction(RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
+ * .action(lazyAction('rag index', RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
  * ```
  */
-export function lazyAction(backend, load) {
+export function lazyAction(verb, backend, load) {
     return async (...args) => {
         let handler;
         try {
@@ -109,7 +98,7 @@ export function lazyAction(backend, load) {
             if (!isModuleMissing(error)) {
                 throw error;
             }
-            reportMissingBackend(backend);
+            endWithRefusal(verb, 'BACKEND_UNAVAILABLE', missingBackendError(backend), 'yaml', { strict: false }, NOTHING_FINISHED);
         }
         await handler(...args);
     };

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,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"}
+{"version":3,"file":"optional-backend.js","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExE;;;;;;;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;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAwB;IAC1D,OAAO,IAAI,mBAAmB,CAC5B,qBAAqB,EACrB,GAAG,OAAO,CAAC,OAAO,4DAA4D;UAC5E,gCAAgC,OAAO,CAAC,WAAW,4CAA4C;UAC/F,0FAA0F,CAC7F,CAAC;AACJ,CAAC;AAUD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,UAAU,CACxB,IAAgB,EAChB,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,cAAc,CAAC,IAAI,EAAE,qBAAqB,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;QACzH,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/output.d.ts

@@ -57,51 +57,13 @@ export interface WriteAllSyncOptions {
  */
 export declare function writeAllSync(write: SyncWriter, buffer: Buffer, options?: WriteAllSyncOptions): void;
 /**
- * Write a single YAML document to stdout, opened with `---`.
+ * The one YAML rendering of a published document — on stdout and in a file
+ * artifact alike, so the same data never serializes two ways.
  *
- * There is deliberately NO trailing marker. `---` OPENS a document in YAML; the
- * end-of-document marker is `...`. Emitting `---` at the end therefore opened a
- * second, empty document, so every command's stdout was a two-document stream and
- * a plain `YAML.parse()` threw `Source contains multiple documents` — on output
- * this CLI documents as "YAML summary → stdout (for programmatic parsing)".
- *
- * The repo's own test helper had already been written around it: `executeCli…`
- * calls `parseAllDocuments(...)` and takes `docs[0]`, with a comment saying "to
- * handle document markers". That workaround is what kept the defect invisible —
- * every consumer that did the obvious thing instead got an exception.
- *
- * Dropping the trailer also makes this agree with the seven hand-rolled emit
- * sites elsewhere in the CLI, none of which ever wrote one.
- *
- * @param data - Data to serialize as YAML
- */
-export declare function writeYamlOutput(data: unknown): void;
-/**
- * Write a single JSON document to stdout.
- *
- * The sibling of {@link writeYamlOutput}, for the same payloads, and it exists
- * because a consumer that has to parse YAML needs a YAML parser: JSON is the
- * format every language reads without one. `vat resources validate` already
- * offers `--format json` for exactly this reason; a scan document that could
- * only be had as YAML made the population it reports the harder of the two to
- * consume programmatically, which is backwards.
- *
- * Written the same way as its YAML sibling, and the comment there applies
- * verbatim: the ordinary stream write keeps this summary behind any
- * human-readable progress already buffered on the same channel.
- *
- * @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)
+ * @param data - Data to serialize
+ * @returns The YAML text, without a document marker
  */
-export declare function writeStructuredOutput(data: unknown, format: string | undefined): void;
+export declare function renderYamlDocument(data: unknown): string;
 /**
  * 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;;;;;;;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"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;;;;;;;;;;;;;;;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;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAExD;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

@@ -3,6 +3,7 @@
  * YAML output on stdout, logs on stderr
  */
 import { writeSync } from 'node:fs';
+import { isWouldBlockError } from '@vibe-agent-toolkit/utils';
 import * as yaml from 'yaml';
 /**
  * Write `content` to stdout SYNCHRONOUSLY, in a loop until every byte is handed
@@ -97,7 +98,7 @@ export function writeAllSync(write, buffer, options = {}) {
             // A non-blocking pipe whose buffer is momentarily full raises EAGAIN; a
             // reader that is draining will free space, so retry. Anything else is a
             // genuine write failure.
-            if (error.code !== 'EAGAIN')
+            if (!isWouldBlockError(error))
                 throw error;
             consecutiveRetries++;
             if (consecutiveRetries > maxRetries) {
@@ -108,70 +109,14 @@ export function writeAllSync(write, buffer, options = {}) {
     }
 }
 /**
- * Write a single YAML document to stdout, opened with `---`.
+ * The one YAML rendering of a published document — on stdout and in a file
+ * artifact alike, so the same data never serializes two ways.
  *
- * There is deliberately NO trailing marker. `---` OPENS a document in YAML; the
- * end-of-document marker is `...`. Emitting `---` at the end therefore opened a
- * second, empty document, so every command's stdout was a two-document stream and
- * a plain `YAML.parse()` threw `Source contains multiple documents` — on output
- * this CLI documents as "YAML summary → stdout (for programmatic parsing)".
- *
- * The repo's own test helper had already been written around it: `executeCli…`
- * calls `parseAllDocuments(...)` and takes `docs[0]`, with a comment saying "to
- * handle document markers". That workaround is what kept the defect invisible —
- * every consumer that did the obvious thing instead got an exception.
- *
- * Dropping the trailer also makes this agree with the seven hand-rolled emit
- * sites elsewhere in the CLI, none of which ever wrote one.
- *
- * @param data - Data to serialize as YAML
+ * @param data - Data to serialize
+ * @returns The YAML text, without a document marker
  */
-export function writeYamlOutput(data) {
-    // Deliberately the ordinary stream write, NOT writeStdoutSync: this summary
-    // follows human-readable progress output written via console.log, and a
-    // synchronous fd-1 write would jump ahead of anything still buffered there.
-    // Completeness is guaranteed instead by makeStdioBlocking() at startup, which
-    // makes BOTH channels synchronous and keeps them in order.
-    process.stdout.write(`---\n${yaml.stringify(data, {
-        indent: 2,
-        lineWidth: 120,
-        aliasDuplicateObjects: false,
-    })}`);
-}
-/**
- * Write a single JSON document to stdout.
- *
- * The sibling of {@link writeYamlOutput}, for the same payloads, and it exists
- * because a consumer that has to parse YAML needs a YAML parser: JSON is the
- * format every language reads without one. `vat resources validate` already
- * offers `--format json` for exactly this reason; a scan document that could
- * only be had as YAML made the population it reports the harder of the two to
- * consume programmatically, which is backwards.
- *
- * Written the same way as its YAML sibling, and the comment there applies
- * verbatim: the ordinary stream write keeps this summary behind any
- * human-readable progress already buffered on the same channel.
- *
- * @param data - Data to serialize as JSON
- */
-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);
-    }
+export function renderYamlDocument(data) {
+    return yaml.stringify(data, { indent: 2, lineWidth: 120, aliasDuplicateObjects: false });
 }
 /**
  * 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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"}

package/dist/utils/package-json.d.ts

@@ -15,10 +15,9 @@
 /**
  * The parsed manifest, or `undefined` when there is none at `pkgPath`.
  *
- * @throws {Error} naming the file when it exists but is not a JSON object;
- *   the parse error is the `cause`.
- * @throws whatever the filesystem threw for anything that is not an absence
- *   (a refusal stays a refusal).
+ * @throws {CommandRefusalError} `INPUT_UNREADABLE` naming the file when it
+ *   exists but is not a JSON object (the parse error is the `cause`), or when
+ *   the OS refused the read (a refusal stays a refusal, never an absence).
  */
 export declare function readPackageJsonOrAbsent(pkgPath: string): Record<string, unknown> | undefined;
 //# sourceMappingURL=package-json.d.ts.map

package/dist/utils/package-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-json.d.ts","sourceRoot":"","sources":["../../src/utils/package-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAoB5F"}
+{"version":3,"file":"package-json.d.ts","sourceRoot":"","sources":["../../src/utils/package-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAoB5F"}

package/dist/utils/package-json.js

@@ -13,14 +13,14 @@
  * already broken; the reader's job is to say so, not to proceed around it.
  */
 import { readFileSync } from 'node:fs';
-import { isPathAbsentError } from '@vibe-agent-toolkit/utils';
+import { classifyFsFault, isPathAbsentError } from '@vibe-agent-toolkit/utils';
+import { CommandRefusalError } from './command-refusal.js';
 /**
  * The parsed manifest, or `undefined` when there is none at `pkgPath`.
  *
- * @throws {Error} naming the file when it exists but is not a JSON object;
- *   the parse error is the `cause`.
- * @throws whatever the filesystem threw for anything that is not an absence
- *   (a refusal stays a refusal).
+ * @throws {CommandRefusalError} `INPUT_UNREADABLE` naming the file when it
+ *   exists but is not a JSON object (the parse error is the `cause`), or when
+ *   the OS refused the read (a refusal stays a refusal, never an absence).
  */
 export function readPackageJsonOrAbsent(pkgPath) {
     let raw;
@@ -30,7 +30,7 @@ export function readPackageJsonOrAbsent(pkgPath) {
     catch (error) {
         if (isPathAbsentError(error))
             return undefined;
-        throw error;
+        throw classifyFsFault(error, { side: 'source', origin: 'content', action: 'read package.json', path: pkgPath });
     }
     let parsed;
     try {
@@ -39,10 +39,10 @@ export function readPackageJsonOrAbsent(pkgPath) {
     catch (error) {
         if (!(error instanceof SyntaxError))
             throw error;
-        throw new Error(`${pkgPath} is not valid JSON: ${error.message}`, { cause: error });
+        throw new CommandRefusalError('INPUT_UNREADABLE', `${pkgPath} is not valid JSON: ${error.message}`, { cause: error });
     }
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`${pkgPath} is not a JSON object, so it is not a package manifest`);
+        throw new CommandRefusalError('INPUT_UNREADABLE', `${pkgPath} is not a JSON object, so it is not a package manifest`);
     }
     return parsed;
 }