wingfoil 0.2.1 → 0.3.0

package/dist/agent/schema.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The agent adapter manifest schema (`spec-016-agent-execution` §2.2, task-177): how to launch one
+ * agent CLI, declared in `.wingfoil/agents/{built-in,custom}/<name>.yaml`.
+ *
+ * Unlike every pillar file, each object node is **strict** (`z.strictObject`), so an unknown key is a
+ * Pass-1 validation error rather than `spec-009` §2's tolerated warning: a misspelt `args` would
+ * otherwise launch the agent without its MCP registration (§2.2). This is the one structural layer.
+ * The rules that cross fields — what a value of one field makes required in another (§2.2's "Req."
+ * column), and where each placeholder is legal (§2.3) — are Pass-2 checks in `./manifest.ts`, because
+ * they read several fields at once and must name the field they fault.
+ *
+ * There is deliberately no `env:` field (§2.2): credentials stay inside the agent CLI (`adr-012` point 1).
+ * The TypeScript type is derived with `z.infer`.
+ */
+import { z } from 'zod';
+import { ADAPTER_MANIFEST_FORMAT } from '../validation/format';
+/**
+ * The manifest format this build reads (`spec-016` §2.2 `format`). A new manifest field bumps it.
+ * Declared in `src/validation/format.ts` beside every other file kind's format (task-251, `dl-149`).
+ */
+export { ADAPTER_MANIFEST_FORMAT };
+/**
+ * One adapter manifest, `spec-016` §2.2, field for field. A field the table marks "required with"
+ * another field's value is optional here and enforced in Pass 2 (`adapterManifestIssues`,
+ * `./manifest.ts`).
+ */
+export declare const AdapterManifest: z.ZodObject<{
+    name: z.ZodString;
+    format: z.ZodLiteral<1>;
+    command: z.ZodString;
+    verified_with: z.ZodOptional<z.ZodString>;
+    version_args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    launch: z.ZodObject<{
+        interactive: z.ZodObject<{
+            args: z.ZodArray<z.ZodString>;
+            terminal: z.ZodDefault<z.ZodEnum<{
+                optional: "optional";
+                required: "required";
+            }>>;
+        }, z.core.$strict>;
+        headless: z.ZodOptional<z.ZodObject<{
+            args: z.ZodArray<z.ZodString>;
+            output: z.ZodEnum<{
+                none: "none";
+                json: "json";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    prompt: z.ZodObject<{
+        via: z.ZodEnum<{
+            file: "file";
+            arg: "arg";
+            stdin: "stdin";
+        }>;
+    }, z.core.$strict>;
+    mcp: z.ZodObject<{
+        via: z.ZodEnum<{
+            args: "args";
+            "config-file": "config-file";
+            "config-arg": "config-arg";
+        }>;
+        template: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    session: z.ZodObject<{
+        id: z.ZodEnum<{
+            output: "output";
+            assign: "assign";
+            none: "none";
+            lookup: "lookup";
+        }>;
+        assign_args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lookup_args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        field: z.ZodOptional<z.ZodString>;
+        resume: z.ZodObject<{
+            supported: z.ZodBoolean;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    usage: z.ZodObject<{
+        from: z.ZodEnum<{
+            output: "output";
+            none: "none";
+            lookup: "lookup";
+        }>;
+        lookup_args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fields: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            input: z.ZodOptional<z.ZodString>;
+            output: z.ZodOptional<z.ZodString>;
+            cache_read: z.ZodOptional<z.ZodString>;
+            cache_write: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    summary: z.ZodOptional<z.ZodObject<{
+        export_args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A validated adapter manifest (`spec-016` §2.2), `launch.interactive.terminal` defaulted. */
+export type AdapterManifest = z.infer<typeof AdapterManifest>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/agent/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/agent/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAC;AA8BnC;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsC1B,CAAC;AAEH,+FAA+F;AAC/F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/agent/schema.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterManifest = exports.ADAPTER_MANIFEST_FORMAT = void 0;
+/**
+ * The agent adapter manifest schema (`spec-016-agent-execution` §2.2, task-177): how to launch one
+ * agent CLI, declared in `.wingfoil/agents/{built-in,custom}/<name>.yaml`.
+ *
+ * Unlike every pillar file, each object node is **strict** (`z.strictObject`), so an unknown key is a
+ * Pass-1 validation error rather than `spec-009` §2's tolerated warning: a misspelt `args` would
+ * otherwise launch the agent without its MCP registration (§2.2). This is the one structural layer.
+ * The rules that cross fields — what a value of one field makes required in another (§2.2's "Req."
+ * column), and where each placeholder is legal (§2.3) — are Pass-2 checks in `./manifest.ts`, because
+ * they read several fields at once and must name the field they fault.
+ *
+ * There is deliberately no `env:` field (§2.2): credentials stay inside the agent CLI (`adr-012` point 1).
+ * The TypeScript type is derived with `z.infer`.
+ */
+const zod_1 = require("zod");
+const format_1 = require("../validation/format");
+Object.defineProperty(exports, "ADAPTER_MANIFEST_FORMAT", { enumerable: true, get: function () { return format_1.ADAPTER_MANIFEST_FORMAT; } });
+const id_1 = require("../validation/id");
+/** An argv template: a list of whole arguments, never a shell string (`dl-090` Q3 (a)). */
+const Argv = zod_1.z.array(zod_1.z.string());
+/** A non-empty string: a field whose empty value could only be a mistake. */
+const NonEmpty = zod_1.z.string().min(1, 'must not be empty');
+/** `launch.interactive` — the v0.3 launch, the agent owning the terminal (`adr-012` point 4). */
+const InteractiveLaunch = zod_1.z.strictObject({
+    args: Argv,
+    /** Whether the launch needs a terminal on stdin and stdout (§3.3 step 12); `required` when absent. */
+    terminal: zod_1.z.enum(['required', 'optional']).default('required'),
+});
+/** `launch.headless` — no terminal, a structured result; read from v1.0 (§3.5). */
+const HeadlessLaunch = zod_1.z.strictObject({
+    args: Argv,
+    output: zod_1.z.enum(['json', 'none']),
+});
+/** The JSON paths `usage.fields` may declare (§2.2); an undeclared one yields `not-reported`. */
+const UsageFields = zod_1.z.strictObject({
+    model: NonEmpty.optional(),
+    input: NonEmpty.optional(),
+    output: NonEmpty.optional(),
+    cache_read: NonEmpty.optional(),
+    cache_write: NonEmpty.optional(),
+});
+/**
+ * One adapter manifest, `spec-016` §2.2, field for field. A field the table marks "required with"
+ * another field's value is optional here and enforced in Pass 2 (`adapterManifestIssues`,
+ * `./manifest.ts`).
+ */
+exports.AdapterManifest = zod_1.z.strictObject({
+    name: zod_1.z.string().refine(id_1.isIdPiece, { message: `must be an id: characters [${id_1.ID_CHAR_CLASS}] only (spec-009 §1)` }),
+    format: zod_1.z.literal(format_1.ADAPTER_MANIFEST_FORMAT),
+    command: NonEmpty,
+    verified_with: NonEmpty.optional(),
+    version_args: Argv.optional(),
+    launch: zod_1.z.strictObject({
+        interactive: InteractiveLaunch,
+        headless: HeadlessLaunch.optional(),
+    }),
+    prompt: zod_1.z.strictObject({
+        via: zod_1.z.enum(['arg', 'stdin', 'file']),
+    }),
+    mcp: zod_1.z.strictObject({
+        // No `none`: an adapter that cannot register the `wingfoil` MCP server is refused (`adr-012`).
+        via: zod_1.z.enum(['config-file', 'config-arg', 'args']),
+        template: NonEmpty.optional(),
+    }),
+    session: zod_1.z.strictObject({
+        id: zod_1.z.enum(['assign', 'output', 'lookup', 'none']),
+        assign_args: Argv.optional(),
+        lookup_args: Argv.optional(),
+        field: NonEmpty.optional(),
+        resume: zod_1.z.strictObject({
+            supported: zod_1.z.boolean(),
+            args: Argv.optional(),
+        }),
+    }),
+    usage: zod_1.z.strictObject({
+        from: zod_1.z.enum(['output', 'lookup', 'none']),
+        lookup_args: Argv.optional(),
+        fields: UsageFields.optional(),
+    }),
+    summary: zod_1.z
+        .strictObject({
+        export_args: Argv.optional(),
+    })
+        .optional(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/agent/schema.js.map

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

package/dist/agent/step.d.ts

@@ -0,0 +1,41 @@
+import type { DnaYaml } from '../dna/schema';
+import type { ExecutionContextElement } from '../core/context';
+import { type CoreResult } from '../core/types';
+import { type NextResult, type Step } from '../core/workflow-next';
+import type { Instance } from '../workflow/deduce';
+/** P5.3.1 sc. 3, verbatim (§3.7 `NO_NEXT_STEP`). */
+export declare const NO_NEXT_STEP_MESSAGE = "no next step to execute";
+/** Which step a run takes (§3.1): absent fields select the active instance and its next step. */
+export interface StepSelector {
+    /** `--workflow <ref>`: a workflow name (its most recently started open instance) or an open instance id. */
+    readonly workflow?: string;
+    /** `--step <key>`: a `spec-017` §4.9 step key on the selected instance's frontier. */
+    readonly key?: string;
+}
+/**
+ * `workflow next`'s deduction for `ref` at `HEAD` (`workflowNextAtHead`), its throws mapped as `workflow
+ * next` maps them: a `spec-003` error in the registry is `VALIDATION`, its first error the message and every
+ * diagnostic in `details.diagnostics`; another invalid committed file (`roles.yaml`, a directive) is
+ * `VALIDATION` with its issues. A `ref` naming no workflow, or no open instance, is the `NOT_FOUND` it returns.
+ */
+export declare function readNextAtHead(root: string, ref: string | undefined): CoreResult<NextResult>;
+/**
+ * §3.2 step 1: the frontier step `key` names — `NextResult.next` or one of the further ready steps — else,
+ * without `key`, `NextResult.next`. No open instance, or an empty frontier without `key`, is `NO_NEXT_STEP`;
+ * a `key` that is not on the selected instance's frontier is `spec-017` §10's `CONFLICT`.
+ */
+export declare function selectFrontierStep(next: NextResult, key: string | undefined): CoreResult<Step>;
+/**
+ * §3.2 step 2: `--element` if given, else the step's scope element, else the instance's bound element
+ * (`spec-017` §3.4). A step with none of the three — a collection-entry or empty scope on an instance with no
+ * bound element — is `NO_STEP_ELEMENT`. Whether the element exists at `HEAD` is the pipeline's check.
+ */
+export declare function stepTargetElement(step: Step, instance: Instance | null, override: ExecutionContextElement | undefined): CoreResult<ExecutionContextElement>;
+/**
+ * §3.2 step 3 (P5.3.2): `--role` if given — the pipeline checks it as it checks every `--role` — else the
+ * step's role. A step with no role is `NO_STEP_ROLE`; a step role `dna.yaml` does not define is refused here as a
+ * defence only: the registry refuses such a role at load (`E_PHASE_ROLE_UNKNOWN`, task-194, P5.3.2 sc. 3) against
+ * the same `dna.yaml`, so this check holds only for a step deduced from a registry that did not check it.
+ */
+export declare function resolveStepRole(dna: DnaYaml, step: Step, override: string | undefined): CoreResult<string>;
+//# sourceMappingURL=step.d.ts.map

package/dist/agent/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/agent/step.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAsB,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAEvF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAE9D,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,4GAA4G;IAC5G,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,CAQ5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAQ9F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAE,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,UAAU,CAAC,uBAAuB,CAAC,CAK3J;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAK1G"}

package/dist/agent/step.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_NEXT_STEP_MESSAGE = void 0;
+exports.readNextAtHead = readNextAtHead;
+exports.selectFrontierStep = selectFrontierStep;
+exports.stepTargetElement = stepTargetElement;
+exports.resolveStepRole = resolveStepRole;
+/**
+ * `agent execute`'s step forms (task-235; `spec-016-agent-execution` §3.1 `--next`, `--workflow <ref>`,
+ * `--step <key>`; §3.2 steps 1–3; §3.7's step rows; approver ruling R16): the step comes from `spec-017`'s
+ * `workflow next` deduction (`NextResult`, task-216), and gives the run its workflow, phase, element and
+ * role.
+ *
+ * - {@link readNextAtHead}: the deduction for the instance `--workflow <ref>` selects, else the active
+ *   instance (`spec-017` §3.3), at `HEAD`; a `spec-003` error in the registry is `VALIDATION` with every
+ *   diagnostic in `details`, as `workflow next` refuses it (§3.7's second row).
+ * - {@link selectFrontierStep}: `--step <key>` on that instance's frontier, else `NextResult.next`.
+ * - {@link stepTargetElement}: `--element`, else the step's scope element, else the instance's bound element.
+ * - {@link resolveStepRole}: `--role`, else the step's role, which `dna.yaml` must define.
+ *
+ * All four are pure but the first, which reads `HEAD` only (`dl-080` (B)): the step a run takes is a
+ * function of committed state and the request (`REQ-SYS-07`). The phase's separation of executors is not
+ * checked (P4.12, v1.0) and every v0.3 run is `fresh` whatever the phase allows (§3.2 step 6, `dl-135`
+ * point 3): neither executor attribute of the step is read here.
+ */
+const roles_1 = require("../dna/roles");
+const types_1 = require("../core/types");
+const workflow_next_1 = require("../core/workflow-next");
+const validation_1 = require("../validation");
+/** P5.3.1 sc. 3, verbatim (§3.7 `NO_NEXT_STEP`). */
+exports.NO_NEXT_STEP_MESSAGE = 'no next step to execute';
+/**
+ * `workflow next`'s deduction for `ref` at `HEAD` (`workflowNextAtHead`), its throws mapped as `workflow
+ * next` maps them: a `spec-003` error in the registry is `VALIDATION`, its first error the message and every
+ * diagnostic in `details.diagnostics`; another invalid committed file (`roles.yaml`, a directive) is
+ * `VALIDATION` with its issues. A `ref` naming no workflow, or no open instance, is the `NOT_FOUND` it returns.
+ */
+function readNextAtHead(root, ref) {
+    try {
+        return (0, workflow_next_1.workflowNextAtHead)(root, ref);
+    }
+    catch (error) {
+        if (error instanceof validation_1.DiagnosticsError)
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: error.message, details: { diagnostics: error.diagnostics } });
+        if (error instanceof validation_1.ValidationError)
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: error.message, details: { issues: error.issues } });
+        throw error;
+    }
+}
+/**
+ * §3.2 step 1: the frontier step `key` names — `NextResult.next` or one of the further ready steps — else,
+ * without `key`, `NextResult.next`. No open instance, or an empty frontier without `key`, is `NO_NEXT_STEP`;
+ * a `key` that is not on the selected instance's frontier is `spec-017` §10's `CONFLICT`.
+ */
+function selectFrontierStep(next, key) {
+    const noNextStep = (0, types_1.coreErr)({ code: 'NOT_FOUND', message: exports.NO_NEXT_STEP_MESSAGE });
+    if (next.instance === null)
+        return noNextStep;
+    if (key === undefined)
+        return next.next === null ? noNextStep : (0, types_1.coreOk)(next.next);
+    const found = [...(next.next === null ? [] : [next.next]), ...next.more].find((step) => step.key === key);
+    if (found !== undefined)
+        return (0, types_1.coreOk)(found);
+    const instance = next.instance.id;
+    return (0, types_1.coreErr)({ code: 'CONFLICT', message: `step '${key}' is not on the frontier of ${instance}`, details: { step: key, instance } });
+}
+/**
+ * §3.2 step 2: `--element` if given, else the step's scope element, else the instance's bound element
+ * (`spec-017` §3.4). A step with none of the three — a collection-entry or empty scope on an instance with no
+ * bound element — is `NO_STEP_ELEMENT`. Whether the element exists at `HEAD` is the pipeline's check.
+ */
+function stepTargetElement(step, instance, override) {
+    if (override !== undefined)
+        return (0, types_1.coreOk)(override);
+    const scope = step.scope !== null && 'element' in step.scope ? step.scope.element : (instance?.element ?? null);
+    if (scope !== null)
+        return (0, types_1.coreOk)({ type: scope.type, id: scope.id });
+    return (0, types_1.coreErr)({ code: 'VALIDATION', message: `step '${step.key}' has no element: give --element <type>:<id>` });
+}
+/**
+ * §3.2 step 3 (P5.3.2): `--role` if given — the pipeline checks it as it checks every `--role` — else the
+ * step's role. A step with no role is `NO_STEP_ROLE`; a step role `dna.yaml` does not define is refused here as a
+ * defence only: the registry refuses such a role at load (`E_PHASE_ROLE_UNKNOWN`, task-194, P5.3.2 sc. 3) against
+ * the same `dna.yaml`, so this check holds only for a step deduced from a registry that did not check it.
+ */
+function resolveStepRole(dna, step, override) {
+    if (override !== undefined)
+        return (0, types_1.coreOk)(override);
+    if (step.role === null)
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: `step '${step.key}' declares no role: give --role <role>` });
+    if (!(0, roles_1.isRoleDefined)(dna, step.role))
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: `step role '${step.role}' not defined in dna.yaml` });
+    return (0, types_1.coreOk)(step.role);
+}
+//# sourceMappingURL=step.js.map

package/dist/agent/step.js.map

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

package/dist/build-info.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.3.0",
+  "commit": "cc31d7a8ca3940c6ec96dca4e0ef77f32f52dfb1"
+}

package/dist/cli/error.d.ts

@@ -1,11 +1,20 @@
+import type { ErrorDetail } from '../core/error-details';
 import type { OutputFormat } from './output';
 /**
  * Write an error to stderr in the consistent spec-005 §3 format for the active `--format`: a
- * `{error, hint?}` object for `json`/`yaml`, or `error: <reason>` (+ optional `hint:` line) for
- * `console`. Writes only; the caller terminates via {@link exitWith}.
+ * `{error, hint?, details?}` object for `json`/`yaml`, or `error: <reason>` (+ optional `hint:` line,
+ * + one indented line per detail) for `console`. Writes only; the caller terminates via
+ * {@link exitWith}.
+ *
+ * `details` (task-130, `dl-055` option 1) is additive in every format: the `error:` line stays the
+ * first line and byte-identical, and the structured `details` key is omitted when the list is empty,
+ * so a consumer that reads only `error` is unaffected. A detail line is indented, and so is every
+ * continuation line of a multi-line detail, so no line of it can begin with the greppable `error: `
+ * or `hint: ` token.
  */
 export declare function emitError(reason: string, opts: {
     format: OutputFormat;
     hint?: string;
+    details?: readonly ErrorDetail[];
 }): void;
 //# sourceMappingURL=error.d.ts.map

package/dist/cli/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/cli/error.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS7F"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/cli/error.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,GAC9E,IAAI,CAgBN"}

package/dist/cli/error.js

@@ -2,26 +2,47 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.emitError = emitError;
 /**
- * The consistent error format (spec-005-cli-command-contract §3, REQ-INT-08). Written verbatim
- * from the spec's own code listing so `src/cli` and the spec cannot drift.
+ * The consistent error format (spec-005-cli-command-contract §3, REQ-INT-08). Written from the
+ * spec's own code listing so `src/cli` and the spec cannot drift.
  */
 const js_yaml_1 = require("js-yaml");
 /**
  * Write an error to stderr in the consistent spec-005 §3 format for the active `--format`: a
- * `{error, hint?}` object for `json`/`yaml`, or `error: <reason>` (+ optional `hint:` line) for
- * `console`. Writes only; the caller terminates via {@link exitWith}.
+ * `{error, hint?, details?}` object for `json`/`yaml`, or `error: <reason>` (+ optional `hint:` line,
+ * + one indented line per detail) for `console`. Writes only; the caller terminates via
+ * {@link exitWith}.
+ *
+ * `details` (task-130, `dl-055` option 1) is additive in every format: the `error:` line stays the
+ * first line and byte-identical, and the structured `details` key is omitted when the list is empty,
+ * so a consumer that reads only `error` is unaffected. A detail line is indented, and so is every
+ * continuation line of a multi-line detail, so no line of it can begin with the greppable `error: `
+ * or `hint: ` token.
  */
 function emitError(reason, opts) {
+    const details = opts.details ?? [];
+    const payload = {
+        error: reason,
+        ...(opts.hint ? { hint: opts.hint } : {}),
+        ...(details.length > 0 ? { details } : {}),
+    };
     if (opts.format === 'json') {
-        process.stderr.write(JSON.stringify({ error: reason, ...(opts.hint ? { hint: opts.hint } : {}) }) + '\n');
+        process.stderr.write(JSON.stringify(payload) + '\n');
     }
     else if (opts.format === 'yaml') {
-        process.stderr.write((0, js_yaml_1.dump)({ error: reason, ...(opts.hint ? { hint: opts.hint } : {}) }));
+        process.stderr.write((0, js_yaml_1.dump)(payload));
     }
     else {
         process.stderr.write(`error: ${reason}\n`);
         if (opts.hint)
             process.stderr.write(`hint: ${opts.hint}\n`);
+        for (const detail of details)
+            process.stderr.write(`  ${detailLine(detail).replace(/\n/g, '\n    ')}\n`);
     }
 }
+/** One console detail line: `<file>: <detail>`, or whichever of the two the entry has. */
+function detailLine(detail) {
+    if (detail.file !== undefined && detail.detail !== undefined)
+        return `${detail.file}: ${detail.detail}`;
+    return detail.file ?? detail.detail ?? '';
+}
 //# sourceMappingURL=error.js.map

package/dist/cli/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/cli/error.ts"],"names":[],"mappings":";;AAaA,8BASC;AAtBD;;;GAGG;AACH,qCAA2C;AAI3C;;;;GAIG;AACH,SAAgB,SAAS,CAAC,MAAc,EAAE,IAA6C;IACrF,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5G,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAA,cAAQ,EAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/F,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,MAAM,IAAI,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/cli/error.ts"],"names":[],"mappings":";;AAsBA,8BAmBC;AAzCD;;;GAGG;AACH,qCAA2C;AAM3C;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CACvB,MAAc,EACd,IAA+E;IAE/E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG;QACd,KAAK,EAAE,MAAM;QACb,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3C,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAA,cAAQ,EAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,MAAM,IAAI,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QAC5D,KAAK,MAAM,MAAM,IAAI,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3G,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,SAAS,UAAU,CAAC,MAAmB;IACrC,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;IACxG,OAAO,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;AAC5C,CAAC"}

package/dist/cli/exit.d.ts

@@ -7,13 +7,43 @@
  * which outcome maps to which code — lives in `src/core` (`exitCodeForError`/`exitCodeForResult`),
  * shared with the MCP surface per REQ-SYS-05 (task-012); `ExitCode` is re-exported from there so the
  * CLI never redeclares the contract's shape.
+ *
+ * The mechanism lets the output drain first (task-249, `bug-222`). A write to a pipe is asynchronous
+ * in Node: the kernel takes what fits in the pipe buffer (64 KiB on Linux) and the rest stays queued
+ * in the stream. `process.exit` drops whatever is queued, so a payload larger than the buffer reached
+ * a `| jq` cut short while the process still exited `0`. A file or a TTY is written synchronously and
+ * never has anything queued, which is why the same command redirected to a file was complete.
  */
 import type { ExitCode } from '../core';
 export type { ExitCode };
+/**
+ * Thrown by a caller that cannot simply return after {@link exitWith} deferred the exit — today only
+ * the Commander `exitOverride` in `./program.ts`, because Commander calls `process.exit` itself, with
+ * its own code, as soon as that callback returns. The entry points (`src/cli.ts`, the test harness)
+ * recognise it by its `name` (a copy of this module loaded elsewhere throws the same name) and let the
+ * deferred exit happen instead of reporting an error.
+ */
+export declare class DeferredExit extends Error {
+    readonly code: ExitCode;
+    constructor(code: ExitCode);
+}
 /**
  * The single process-exit mechanism for the CLI (spec-005 §1, REQ-INT-04): optionally write
- * `message` to stderr, then `process.exit(code)`. Every invocation terminates through here so the
- * `0`/`1`/`2` contract cannot be bypassed. Returns `never`.
+ * `message` to stderr, then end the process with `code` through the one `process.exit` call.
+ *
+ * When stdout and stderr have nothing queued — a file, a TTY, or a pipe that took everything — the
+ * process ends here and now. When either still holds output for a pipe (task-249, `bug-222`), the exit
+ * is deferred until each has written it: `process.exitCode` is set to `code` at once, and
+ * `process.exit(code)` runs when the last queued write completes — or fails, as when the reader has
+ * gone away (`EPIPE`), which ends the process with the same `code` rather than an unhandled stream
+ * error. Either way the code is the one passed here, and the exit is the single `process.exit` call.
+ *
+ * Every caller returns right after this call, so which of the two happened does not matter to it; the
+ * one caller that cannot return normally reads the result.
+ *
+ * @returns `true` when the exit is deferred until the output drains — the process is still running
+ * only to finish writing, and the caller must do nothing else. (When the exit happened, nothing returns
+ * at all outside a test that stubs `process.exit`.)
  */
-export declare function exitWith(code: ExitCode, message?: string): never;
+export declare function exitWith(code: ExitCode, message?: string): boolean;
 //# sourceMappingURL=exit.d.ts.map

package/dist/cli/exit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../src/cli/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAGhE"}
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../src/cli/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ;gBAAd,IAAI,EAAE,QAAQ;CAIpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAsBlE"}

package/dist/cli/exit.js

@@ -1,14 +1,65 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeferredExit = void 0;
 exports.exitWith = exitWith;
+/**
+ * Thrown by a caller that cannot simply return after {@link exitWith} deferred the exit — today only
+ * the Commander `exitOverride` in `./program.ts`, because Commander calls `process.exit` itself, with
+ * its own code, as soon as that callback returns. The entry points (`src/cli.ts`, the test harness)
+ * recognise it by its `name` (a copy of this module loaded elsewhere throws the same name) and let the
+ * deferred exit happen instead of reporting an error.
+ */
+class DeferredExit extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${String(code)} deferred until the output drains`);
+        this.code = code;
+        this.name = 'DeferredExit';
+    }
+}
+exports.DeferredExit = DeferredExit;
 /**
  * The single process-exit mechanism for the CLI (spec-005 §1, REQ-INT-04): optionally write
- * `message` to stderr, then `process.exit(code)`. Every invocation terminates through here so the
- * `0`/`1`/`2` contract cannot be bypassed. Returns `never`.
+ * `message` to stderr, then end the process with `code` through the one `process.exit` call.
+ *
+ * When stdout and stderr have nothing queued — a file, a TTY, or a pipe that took everything — the
+ * process ends here and now. When either still holds output for a pipe (task-249, `bug-222`), the exit
+ * is deferred until each has written it: `process.exitCode` is set to `code` at once, and
+ * `process.exit(code)` runs when the last queued write completes — or fails, as when the reader has
+ * gone away (`EPIPE`), which ends the process with the same `code` rather than an unhandled stream
+ * error. Either way the code is the one passed here, and the exit is the single `process.exit` call.
+ *
+ * Every caller returns right after this call, so which of the two happened does not matter to it; the
+ * one caller that cannot return normally reads the result.
+ *
+ * @returns `true` when the exit is deferred until the output drains — the process is still running
+ * only to finish writing, and the caller must do nothing else. (When the exit happened, nothing returns
+ * at all outside a test that stubs `process.exit`.)
  */
 function exitWith(code, message) {
     if (message)
         process.stderr.write(message + '\n');
-    process.exit(code);
+    const queued = [process.stdout, process.stderr].filter((stream) => stream.writableLength > 0);
+    if (queued.length === 0) {
+        process.exit(code);
+        return false;
+    }
+    process.exitCode = code;
+    let waiting = queued.length;
+    for (const stream of queued) {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            waiting -= 1;
+            if (waiting === 0)
+                process.exit(code);
+        };
+        // An empty write completes after every write queued before it; an `error` (EPIPE) ends the wait too.
+        stream.once('error', settle);
+        stream.write('', settle);
+    }
+    return true;
 }
 //# sourceMappingURL=exit.js.map

package/dist/cli/exit.js.map

@@ -1 +1 @@
-{"version":3,"file":"exit.js","sourceRoot":"","sources":["../../src/cli/exit.ts"],"names":[],"mappings":";;AAmBA,4BAGC;AARD;;;;GAIG;AACH,SAAgB,QAAQ,CAAC,IAAc,EAAE,OAAgB;IACvD,IAAI,OAAO;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC"}
+{"version":3,"file":"exit.js","sourceRoot":"","sources":["../../src/cli/exit.ts"],"names":[],"mappings":";;;AAoDA,4BAsBC;AAtDD;;;;;;GAMG;AACH,MAAa,YAAa,SAAQ,KAAK;IAChB;IAArB,YAAqB,IAAc;QACjC,KAAK,CAAC,QAAQ,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAD5C,SAAI,GAAJ,IAAI,CAAU;QAEjC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AALD,oCAKC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,QAAQ,CAAC,IAAc,EAAE,OAAgB;IACvD,IAAI,OAAO;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IACxB,IAAI,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5B,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,IAAI,CAAC,CAAC;YACb,IAAI,OAAO,KAAK,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC,CAAC;QACF,qGAAqG;QACrG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `cli` module — human interface (Commander.js + chalk); the `wingfoil` command surface.
+ * `cli` module — human interface (Commander.js); the `wingfoil` command surface.
  *
  * task-006-dual-interface-shared-core adds the thin adapter (spec-006 §2): `buildCliCommands`
  * (`./registrar.ts`) derives one `wingfoil <noun> <verb>` command descriptor per operation from a
@@ -16,7 +16,7 @@ export declare const MODULE_NAME: "cli";
 export { buildCliCommands, listRegisteredCliCommands } from './registrar';
 export type { BuildCommandsOptions, CliCommand } from './registrar';
 export { buildProgram } from './program';
-export { exitWith } from './exit';
+export { DeferredExit, exitWith } from './exit';
 export type { ExitCode } from './exit';
 export { isValidFormat, renderSuccess } from './output';
 export type { OutputFormat } from './output';

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,EAAG,KAAc,CAAC;AAE1C,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,EAAG,KAAc,CAAC;AAE1C,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAChD,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/cli/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runMcp = exports.createReadlinePrompt = exports.runInit = exports.emitError = exports.renderSuccess = exports.isValidFormat = exports.exitWith = exports.buildProgram = exports.listRegisteredCliCommands = exports.buildCliCommands = exports.MODULE_NAME = void 0;
+exports.runMcp = exports.createReadlinePrompt = exports.runInit = exports.emitError = exports.renderSuccess = exports.isValidFormat = exports.exitWith = exports.DeferredExit = exports.buildProgram = exports.listRegisteredCliCommands = exports.buildCliCommands = exports.MODULE_NAME = void 0;
 /**
- * `cli` module — human interface (Commander.js + chalk); the `wingfoil` command surface.
+ * `cli` module — human interface (Commander.js); the `wingfoil` command surface.
  *
  * task-006-dual-interface-shared-core adds the thin adapter (spec-006 §2): `buildCliCommands`
  * (`./registrar.ts`) derives one `wingfoil <noun> <verb>` command descriptor per operation from a
@@ -22,6 +22,7 @@ Object.defineProperty(exports, "listRegisteredCliCommands", { enumerable: true,
 var program_1 = require("./program");
 Object.defineProperty(exports, "buildProgram", { enumerable: true, get: function () { return program_1.buildProgram; } });
 var exit_1 = require("./exit");
+Object.defineProperty(exports, "DeferredExit", { enumerable: true, get: function () { return exit_1.DeferredExit; } });
 Object.defineProperty(exports, "exitWith", { enumerable: true, get: function () { return exit_1.exitWith; } });
 var output_1 = require("./output");
 Object.defineProperty(exports, "isValidFormat", { enumerable: true, get: function () { return output_1.isValidFormat; } });

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACU,QAAA,WAAW,GAAG,KAAc,CAAC;AAE1C,yCAA0E;AAAjE,6GAAA,gBAAgB,OAAA;AAAE,sHAAA,yBAAyB,OAAA;AAEpD,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,+BAAkC;AAAzB,gGAAA,QAAQ,OAAA;AAEjB,mCAAwD;AAA/C,uGAAA,aAAa,OAAA;AAAE,uGAAA,aAAa,OAAA;AAErC,iCAAoC;AAA3B,kGAAA,SAAS,OAAA;AAClB,+CAA+D;AAAtD,uGAAA,OAAO,OAAA;AAAE,oHAAA,oBAAoB,OAAA;AAEtC,6CAAuC;AAA9B,qGAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACU,QAAA,WAAW,GAAG,KAAc,CAAC;AAE1C,yCAA0E;AAAjE,6GAAA,gBAAgB,OAAA;AAAE,sHAAA,yBAAyB,OAAA;AAEpD,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,+BAAgD;AAAvC,oGAAA,YAAY,OAAA;AAAE,gGAAA,QAAQ,OAAA;AAE/B,mCAAwD;AAA/C,uGAAA,aAAa,OAAA;AAAE,uGAAA,aAAa,OAAA;AAErC,iCAAoC;AAA3B,kGAAA,SAAS,OAAA;AAClB,+CAA+D;AAAtD,uGAAA,OAAO,OAAA;AAAE,oHAAA,oBAAoB,OAAA;AAEtC,6CAAuC;AAA9B,qGAAA,MAAM,OAAA"}