icore 1.0.15 → 1.0.16

package/dist/index.js

@@ -1,19 +1,63 @@
 "use strict";
+/**
+ * The package entrypoint exposes the supported command mechanics API.
+ *
+ * Allowed here:
+ * - re-exporting public argv parser contracts;
+ * - re-exporting public option schema contracts;
+ * - re-exporting public command registry contracts;
+ * - re-exporting public presentation and output contracts;
+ * - re-exporting public terminal app composition contracts;
+ *
+ * This file must not contain parser, validator, or command runtime logic.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runCommandFromRegistry = exports.runPreparedCommand = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.prepareCommandFromArgs = exports.parseOptionsDetailed = exports.parseOptions = exports.parseArgv = exports.mergeOptionsSchema = exports.isPreparedCommandName = exports.isCommandName = exports.IcoreError = exports.defineCommandRegistry = exports.defineCommand = void 0;
-var cli_1 = require("./cli");
-Object.defineProperty(exports, "defineCommand", { enumerable: true, get: function () { return cli_1.defineCommand; } });
-Object.defineProperty(exports, "defineCommandRegistry", { enumerable: true, get: function () { return cli_1.defineCommandRegistry; } });
-Object.defineProperty(exports, "IcoreError", { enumerable: true, get: function () { return cli_1.IcoreError; } });
-Object.defineProperty(exports, "isCommandName", { enumerable: true, get: function () { return cli_1.isCommandName; } });
-Object.defineProperty(exports, "isPreparedCommandName", { enumerable: true, get: function () { return cli_1.isPreparedCommandName; } });
-Object.defineProperty(exports, "mergeOptionsSchema", { enumerable: true, get: function () { return cli_1.mergeOptionsSchema; } });
-Object.defineProperty(exports, "parseArgv", { enumerable: true, get: function () { return cli_1.parseArgv; } });
-Object.defineProperty(exports, "parseOptions", { enumerable: true, get: function () { return cli_1.parseOptions; } });
-Object.defineProperty(exports, "parseOptionsDetailed", { enumerable: true, get: function () { return cli_1.parseOptionsDetailed; } });
-Object.defineProperty(exports, "prepareCommandFromArgs", { enumerable: true, get: function () { return cli_1.prepareCommandFromArgs; } });
-Object.defineProperty(exports, "resolveCommand", { enumerable: true, get: function () { return cli_1.resolveCommand; } });
-Object.defineProperty(exports, "resolveCommandFromArgs", { enumerable: true, get: function () { return cli_1.resolveCommandFromArgs; } });
-Object.defineProperty(exports, "runCommand", { enumerable: true, get: function () { return cli_1.runCommand; } });
-Object.defineProperty(exports, "runPreparedCommand", { enumerable: true, get: function () { return cli_1.runPreparedCommand; } });
-Object.defineProperty(exports, "runCommandFromRegistry", { enumerable: true, get: function () { return cli_1.runCommandFromRegistry; } });
+exports.createTerminalApp = exports.createBackpressureTextWriter = exports.createStdoutWriter = exports.createStderrWriter = exports.createOutput = exports.renderPresentationResult = exports.isPresentationResult = exports.renderTextTable = exports.renderJson = exports.renderCsvRow = exports.renderCsv = exports.presentationFormats = exports.presentationFormatOptions = exports.isPresentationFormat = exports.createPresentation = exports.mergeOptionsSchema = exports.parseOptionsSubsetDetailed = exports.parseOptionsDetailed = exports.parseOptions = exports.IcoreError = exports.runCommandFromRegistry = exports.runPreparedCommand = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.prepareCommandFromArgs = exports.isPreparedCommandName = exports.isCommandName = exports.defineCommandRegistry = exports.defineCommand = exports.createCommands = exports.createCommand = exports.parseArgv = void 0;
+var parser_1 = require("./argv/parser");
+Object.defineProperty(exports, "parseArgv", { enumerable: true, get: function () { return parser_1.parseArgv; } });
+var mechanics_1 = require("./command/mechanics");
+Object.defineProperty(exports, "createCommand", { enumerable: true, get: function () { return mechanics_1.createCommand; } });
+Object.defineProperty(exports, "createCommands", { enumerable: true, get: function () { return mechanics_1.createCommands; } });
+Object.defineProperty(exports, "defineCommand", { enumerable: true, get: function () { return mechanics_1.defineCommand; } });
+Object.defineProperty(exports, "defineCommandRegistry", { enumerable: true, get: function () { return mechanics_1.defineCommandRegistry; } });
+Object.defineProperty(exports, "isCommandName", { enumerable: true, get: function () { return mechanics_1.isCommandName; } });
+Object.defineProperty(exports, "isPreparedCommandName", { enumerable: true, get: function () { return mechanics_1.isPreparedCommandName; } });
+Object.defineProperty(exports, "prepareCommandFromArgs", { enumerable: true, get: function () { return mechanics_1.prepareCommandFromArgs; } });
+Object.defineProperty(exports, "resolveCommand", { enumerable: true, get: function () { return mechanics_1.resolveCommand; } });
+Object.defineProperty(exports, "resolveCommandFromArgs", { enumerable: true, get: function () { return mechanics_1.resolveCommandFromArgs; } });
+Object.defineProperty(exports, "runCommand", { enumerable: true, get: function () { return mechanics_1.runCommand; } });
+Object.defineProperty(exports, "runPreparedCommand", { enumerable: true, get: function () { return mechanics_1.runPreparedCommand; } });
+Object.defineProperty(exports, "runCommandFromRegistry", { enumerable: true, get: function () { return mechanics_1.runCommandFromRegistry; } });
+var icore_error_1 = require("./errors/icore-error");
+Object.defineProperty(exports, "IcoreError", { enumerable: true, get: function () { return icore_error_1.IcoreError; } });
+var parser_2 = require("./options/parser");
+Object.defineProperty(exports, "parseOptions", { enumerable: true, get: function () { return parser_2.parseOptions; } });
+Object.defineProperty(exports, "parseOptionsDetailed", { enumerable: true, get: function () { return parser_2.parseOptionsDetailed; } });
+Object.defineProperty(exports, "parseOptionsSubsetDetailed", { enumerable: true, get: function () { return parser_2.parseOptionsSubsetDetailed; } });
+var schema_1 = require("./options/schema");
+Object.defineProperty(exports, "mergeOptionsSchema", { enumerable: true, get: function () { return schema_1.mergeOptionsSchema; } });
+var facade_1 = require("./presentation/facade");
+Object.defineProperty(exports, "createPresentation", { enumerable: true, get: function () { return facade_1.createPresentation; } });
+var format_options_1 = require("./presentation/format-options");
+Object.defineProperty(exports, "isPresentationFormat", { enumerable: true, get: function () { return format_options_1.isPresentationFormat; } });
+Object.defineProperty(exports, "presentationFormatOptions", { enumerable: true, get: function () { return format_options_1.presentationFormatOptions; } });
+Object.defineProperty(exports, "presentationFormats", { enumerable: true, get: function () { return format_options_1.presentationFormats; } });
+var csv_1 = require("./presentation/renderers/csv");
+Object.defineProperty(exports, "renderCsv", { enumerable: true, get: function () { return csv_1.renderCsv; } });
+Object.defineProperty(exports, "renderCsvRow", { enumerable: true, get: function () { return csv_1.renderCsvRow; } });
+var json_1 = require("./presentation/renderers/json");
+Object.defineProperty(exports, "renderJson", { enumerable: true, get: function () { return json_1.renderJson; } });
+var table_1 = require("./presentation/renderers/table");
+Object.defineProperty(exports, "renderTextTable", { enumerable: true, get: function () { return table_1.renderTextTable; } });
+var result_renderer_1 = require("./presentation/result-renderer");
+Object.defineProperty(exports, "isPresentationResult", { enumerable: true, get: function () { return result_renderer_1.isPresentationResult; } });
+Object.defineProperty(exports, "renderPresentationResult", { enumerable: true, get: function () { return result_renderer_1.renderPresentationResult; } });
+var facade_2 = require("./output/facade");
+Object.defineProperty(exports, "createOutput", { enumerable: true, get: function () { return facade_2.createOutput; } });
+var node_writer_1 = require("./output/node-writer");
+Object.defineProperty(exports, "createStderrWriter", { enumerable: true, get: function () { return node_writer_1.createStderrWriter; } });
+Object.defineProperty(exports, "createStdoutWriter", { enumerable: true, get: function () { return node_writer_1.createStdoutWriter; } });
+var text_writer_1 = require("./output/text-writer");
+Object.defineProperty(exports, "createBackpressureTextWriter", { enumerable: true, get: function () { return text_writer_1.createBackpressureTextWriter; } });
+var app_1 = require("./terminal/app");
+Object.defineProperty(exports, "createTerminalApp", { enumerable: true, get: function () { return app_1.createTerminalApp; } });

package/dist/options/parser.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The option parser module validates raw option values against declarative
+ * primitive option contracts.
+ *
+ * Allowed here:
+ * - applying and validating default values;
+ * - producing typed option values and user-provided metadata;
+ *
+ * This file must not contain argv tokenization, command resolution, or
+ * application-specific validation rules.
+ */
+import type { InferOptions, InferProvidedOptions, OptionsSchema, RawOptionValue } from './schema';
+/**
+ * Detailed option parsing result with values and user-provided metadata.
+ */
+export type ParseOptionsResult<TSchema extends OptionsSchema> = {
+    /** Parsed values. */
+    options: InferOptions<TSchema>;
+    /** Explicit option presence metadata. */
+    provided: InferProvidedOptions<TSchema>;
+};
+/**
+ * Detailed option subset parsing result with untouched options for later
+ * command-layer validation.
+ */
+export type ParseOptionsSubsetResult<TSchema extends OptionsSchema> = ParseOptionsResult<TSchema> & {
+    /** Unparsed raw values. */
+    rest: Record<string, RawOptionValue>;
+};
+/**
+ * Validates raw option values against a declarative option schema.
+ */
+export declare function parseOptions<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): InferOptions<TSchema>;
+/**
+ * Validates raw option values and returns parsed values with user-provided
+ * metadata.
+ */
+export declare function parseOptionsDetailed<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): ParseOptionsResult<TSchema>;
+/**
+ * Validates only raw option values known by the given schema and leaves the
+ * remaining raw options untouched.
+ */
+export declare function parseOptionsSubsetDetailed<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): ParseOptionsSubsetResult<TSchema>;

package/dist/{options.js → options/parser.js}

@@ -1,10 +1,9 @@
 "use strict";
 /**
- * The option schema module validates raw option values against declarative
+ * The option parser module validates raw option values against declarative
  * primitive option contracts.
  *
  * Allowed here:
- * - defining string, boolean, and number option contracts;
  * - applying and validating default values;
  * - producing typed option values and user-provided metadata;
  *
@@ -12,18 +11,10 @@
  * application-specific validation rules.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeOptionsSchema = mergeOptionsSchema;
 exports.parseOptions = parseOptions;
 exports.parseOptionsDetailed = parseOptionsDetailed;
-const errors_1 = require("./errors");
-/**
- * Merges option schemas while preserving literal option definition types.
- *
- * Later schemas override earlier schemas with the same option name.
- */
-function mergeOptionsSchema(schema, ...schemas) {
-    return Object.assign({}, schema, ...schemas);
-}
+exports.parseOptionsSubsetDetailed = parseOptionsSubsetDetailed;
+const icore_error_1 = require("../errors/icore-error");
 /**
  * Validates raw option values against a declarative option schema.
  */
@@ -67,6 +58,25 @@ function parseOptionsDetailed(schema, values) {
         provided: provided
     };
 }
+/**
+ * Validates only raw option values known by the given schema and leaves the
+ * remaining raw options untouched.
+ */
+function parseOptionsSubsetDetailed(schema, values) {
+    const subsetValues = {};
+    const rest = {};
+    for (const [name, value] of Object.entries(values)) {
+        if (Object.hasOwn(schema, name)) {
+            subsetValues[name] = value;
+            continue;
+        }
+        rest[name] = value;
+    }
+    return {
+        ...parseOptionsDetailed(schema, subsetValues),
+        rest
+    };
+}
 function parseOptionValue(name, definition, value) {
     if (definition.type === 'string') {
         return parseStringOption(name, definition, value);
@@ -189,13 +199,13 @@ function assertChoice(name, choices, value, source = 'value') {
     throw createInvalidOptionChoiceError(name, choices, value, message);
 }
 function createUnexpectedArgumentError(name) {
-    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
+    return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
         argument: `--${name}`,
         option: name
     });
 }
 function createExpectedRequiredArgumentError(name) {
-    return new errors_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
+    return new icore_error_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
         argument: `--${name}`,
         option: name
     });
@@ -213,14 +223,14 @@ function createExpectedDefaultError(name, expected, value) {
     });
 }
 function createInvalidOptionTypeError(name, message, details) {
-    return new errors_1.IcoreError('INVALID_OPTION_TYPE', message, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_TYPE', message, {
         argument: `--${name}`,
         option: name,
         ...details
     });
 }
 function createInvalidOptionChoiceError(name, choices, value, message) {
-    return new errors_1.IcoreError('INVALID_OPTION_CHOICE', message, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_CHOICE', message, {
         argument: `--${name}`,
         option: name,
         choices: [...choices],
@@ -228,7 +238,7 @@ function createInvalidOptionChoiceError(name, choices, value, message) {
     });
 }
 function createInvalidOptionDefaultError(name, message, details) {
-    return new errors_1.IcoreError('INVALID_OPTION_DEFAULT', message, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_DEFAULT', message, {
         argument: `--${name}`,
         option: name,
         ...details

package/dist/{options.d.ts → options/schema.d.ts}

@@ -1,18 +1,21 @@
 /**
- * The option schema module validates raw option values against declarative
- * primitive option contracts.
+ * The option schema module defines declarative primitive option contracts and
+ * their inferred TypeScript result types.
  *
  * Allowed here:
- * - defining string, boolean, and number option contracts;
- * - applying and validating default values;
- * - producing typed option values and user-provided metadata;
+ * - string, boolean, and number option contracts;
+ * - schema merge mechanics;
+ * - inferred parsed option and provided-option types;
  *
- * This file must not contain argv tokenization, command resolution, or
- * application-specific validation rules.
+ * This file must not contain argv tokenization, value validation, or command
+ * resolution.
  */
 type OptionBase<TType extends string, TValue> = {
+    /** Primitive option kind. */
     type: TType;
+    /** One-letter short alias. */
     alias?: string;
+    /** Requires an explicit value. */
     required?: boolean;
     default?: TValue;
 };
@@ -30,6 +33,7 @@ export type RawOptionValue = string | boolean;
  * is declared with `as const`.
  */
 export type StringOption<TChoices extends readonly string[] = readonly string[]> = OptionBase<'string', TChoices[number] | string> & {
+    /** Allowed string values. */
     choices?: TChoices;
 };
 /**
@@ -39,6 +43,7 @@ export type StringOption<TChoices extends readonly string[] = readonly string[]>
  * syntax is enforced.
  */
 export type BooleanOption = OptionBase<'boolean', boolean> & {
+    /** Restricts boolean syntax. */
     syntax?: 'flag';
 };
 /**
@@ -48,9 +53,13 @@ export type BooleanOption = OptionBase<'boolean', boolean> & {
  * bounds.
  */
 export type NumberOption<TChoices extends readonly number[] = readonly number[]> = OptionBase<'number', TChoices[number] | number> & {
+    /** Allowed numeric values. */
     choices?: TChoices;
+    /** Requires a whole number. */
     integer?: boolean;
+    /** Inclusive lower bound. */
     min?: number;
+    /** Inclusive upper bound. */
     max?: number;
 };
 /**
@@ -109,26 +118,10 @@ export type InferOptions<TSchema extends OptionsSchema> = {
 export type InferProvidedOptions<TSchema extends OptionsSchema> = {
     [TName in keyof TSchema]: boolean;
 };
-/**
- * Detailed option parsing result with values and user-provided metadata.
- */
-export type ParseOptionsResult<TSchema extends OptionsSchema> = {
-    options: InferOptions<TSchema>;
-    provided: InferProvidedOptions<TSchema>;
-};
 /**
  * Merges option schemas while preserving literal option definition types.
  *
  * Later schemas override earlier schemas with the same option name.
  */
 export declare function mergeOptionsSchema<const TSchema extends OptionsSchema, const TSchemas extends readonly OptionsSchema[]>(schema: TSchema, ...schemas: TSchemas): MergeOptionsSchemas<readonly [TSchema, ...TSchemas]>;
-/**
- * Validates raw option values against a declarative option schema.
- */
-export declare function parseOptions<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): InferOptions<TSchema>;
-/**
- * Validates raw option values and returns parsed values with user-provided
- * metadata.
- */
-export declare function parseOptionsDetailed<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): ParseOptionsResult<TSchema>;
 export {};

package/dist/options/schema.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * The option schema module defines declarative primitive option contracts and
+ * their inferred TypeScript result types.
+ *
+ * Allowed here:
+ * - string, boolean, and number option contracts;
+ * - schema merge mechanics;
+ * - inferred parsed option and provided-option types;
+ *
+ * This file must not contain argv tokenization, value validation, or command
+ * resolution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeOptionsSchema = mergeOptionsSchema;
+/**
+ * Merges option schemas while preserving literal option definition types.
+ *
+ * Later schemas override earlier schemas with the same option name.
+ */
+function mergeOptionsSchema(schema, ...schemas) {
+    return Object.assign({}, schema, ...schemas);
+}

package/dist/output/facade.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The output facade exposes semantic stdout and stderr write operations.
+ *
+ * Allowed here:
+ * - creating stdout/stderr writer channels;
+ * - delegating `write` to stdout and `error` to stderr;
+ *
+ * This file must not contain command semantics, rendering rules, or
+ * application-specific diagnostics.
+ */
+import type { BackpressureTextSink, TextWriter } from './text-writer';
+export type Output = {
+    /** Writes regular output. */
+    write(chunk: string): unknown | Promise<unknown>;
+    /** Writes diagnostic output. */
+    error(chunk: string): unknown | Promise<unknown>;
+    stdout: TextWriter;
+    stderr: TextWriter;
+};
+export type OutputOptions = {
+    stdout?: BackpressureTextSink;
+    stderr?: BackpressureTextSink;
+};
+/**
+ * Creates semantic output methods while keeping raw stdout/stderr channels
+ * available for lower-level integrations.
+ */
+export declare function createOutput(options?: OutputOptions): Output;

package/dist/output/facade.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * The output facade exposes semantic stdout and stderr write operations.
+ *
+ * Allowed here:
+ * - creating stdout/stderr writer channels;
+ * - delegating `write` to stdout and `error` to stderr;
+ *
+ * This file must not contain command semantics, rendering rules, or
+ * application-specific diagnostics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOutput = createOutput;
+const node_writer_1 = require("./node-writer");
+/**
+ * Creates semantic output methods while keeping raw stdout/stderr channels
+ * available for lower-level integrations.
+ */
+function createOutput(options = {}) {
+    const stdout = (0, node_writer_1.createStdoutWriter)(options.stdout);
+    const stderr = (0, node_writer_1.createStderrWriter)(options.stderr);
+    return {
+        write(chunk) {
+            return stdout.write(chunk);
+        },
+        error(chunk) {
+            return stderr.write(chunk);
+        },
+        stdout,
+        stderr
+    };
+}

package/dist/output/node-writer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Node writer module exposes stdout and stderr text writer factories.
+ *
+ * Allowed here:
+ * - binding Node-compatible writable streams to text writers;
+ *
+ * This file must not contain rendering rules or command semantics.
+ */
+import { type BackpressureTextSink, type TextWriter } from './text-writer';
+/**
+ * Creates a stdout writer from an already selected Node-compatible sink.
+ */
+export declare function createStdoutWriter(stdout?: BackpressureTextSink): TextWriter;
+/**
+ * Creates a stderr writer from an already selected Node-compatible sink.
+ */
+export declare function createStderrWriter(stderr?: BackpressureTextSink): TextWriter;

package/dist/output/node-writer.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * The Node writer module exposes stdout and stderr text writer factories.
+ *
+ * Allowed here:
+ * - binding Node-compatible writable streams to text writers;
+ *
+ * This file must not contain rendering rules or command semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStdoutWriter = createStdoutWriter;
+exports.createStderrWriter = createStderrWriter;
+const text_writer_1 = require("./text-writer");
+/**
+ * Creates a stdout writer from an already selected Node-compatible sink.
+ */
+function createStdoutWriter(stdout = process.stdout) {
+    return (0, text_writer_1.createBackpressureTextWriter)(stdout);
+}
+/**
+ * Creates a stderr writer from an already selected Node-compatible sink.
+ */
+function createStderrWriter(stderr = process.stderr) {
+    return (0, text_writer_1.createBackpressureTextWriter)(stderr);
+}

package/dist/output/text-writer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The text writer module adapts writable text sinks to backpressure-aware
+ * writer contracts.
+ *
+ * Allowed here:
+ * - the minimal text writer contract;
+ * - promise-returning sink support;
+ * - Node-style `drain` waiting when a writable sink reports backpressure;
+ *
+ * This file must not contain stdout/stderr selection or command semantics.
+ */
+export type TextWriter = {
+    write(chunk: string): unknown | Promise<unknown>;
+};
+/**
+ * Minimal writable stream shape accepted by icore output adapters.
+ */
+export type BackpressureTextSink = {
+    write(chunk: string): unknown;
+    /** Optional `drain` event hook. */
+    once?(event: 'drain', listener: () => void): unknown;
+};
+/**
+ * Creates a text writer that preserves writable-stream backpressure.
+ *
+ * Promise-returning sinks are awaited, and Node-style sinks returning `false`
+ * are resumed after their next `drain` event.
+ */
+export declare function createBackpressureTextWriter(sink: BackpressureTextSink): TextWriter;

package/dist/output/text-writer.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * The text writer module adapts writable text sinks to backpressure-aware
+ * writer contracts.
+ *
+ * Allowed here:
+ * - the minimal text writer contract;
+ * - promise-returning sink support;
+ * - Node-style `drain` waiting when a writable sink reports backpressure;
+ *
+ * This file must not contain stdout/stderr selection or command semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBackpressureTextWriter = createBackpressureTextWriter;
+/**
+ * Creates a text writer that preserves writable-stream backpressure.
+ *
+ * Promise-returning sinks are awaited, and Node-style sinks returning `false`
+ * are resumed after their next `drain` event.
+ */
+function createBackpressureTextWriter(sink) {
+    return {
+        async write(chunk) {
+            const writeResult = sink.write(chunk);
+            if (isPromiseLike(writeResult)) {
+                await writeResult;
+                return;
+            }
+            if (writeResult !== false) {
+                return;
+            }
+            if (typeof sink.once !== 'function') {
+                return;
+            }
+            await waitForDrain(sink.once.bind(sink));
+        }
+    };
+}
+function isPromiseLike(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && 'then' in value
+        && typeof value.then === 'function');
+}
+function waitForDrain(onceDrain) {
+    return new Promise((resolve) => {
+        onceDrain('drain', resolve);
+    });
+}

package/dist/presentation/facade.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The presentation facade exposes reusable terminal view and rendering
+ * mechanics as a small semantic surface.
+ *
+ * Allowed here:
+ * - creating presentation view factories;
+ * - wiring generic JSON, CSV, and text table renderers;
+ * - exposing a single `render` method for terminal app composition;
+ *
+ * This file must not contain application report mapping, command execution, or
+ * stdout/stderr delivery.
+ */
+import { presentationFormats, type PresentationFormat } from './format-options';
+import { type CsvRow, type PresentationResult, type PresentationViewFactory, type TextTableRow } from './view';
+export type PresentationRenderers = {
+    json: {
+        render(value: unknown): string;
+    };
+    table: {
+        render(rows: readonly TextTableRow[]): string;
+    };
+    csv: {
+        render(rows: readonly CsvRow[]): string;
+        renderRow(row: CsvRow): string;
+    };
+};
+export type Presentation = PresentationViewFactory & {
+    formats: typeof presentationFormats;
+    render(result: PresentationResult, format?: PresentationFormat): string;
+    renderers: PresentationRenderers;
+};
+export type { PresentationResult } from './view';
+/**
+ * Creates the presentation facade used by terminal applications.
+ *
+ * The facade owns generic rendering mechanics only; callers still map their
+ * domain objects to presentation views.
+ */
+export declare function createPresentation(): Presentation;

package/dist/presentation/facade.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * The presentation facade exposes reusable terminal view and rendering
+ * mechanics as a small semantic surface.
+ *
+ * Allowed here:
+ * - creating presentation view factories;
+ * - wiring generic JSON, CSV, and text table renderers;
+ * - exposing a single `render` method for terminal app composition;
+ *
+ * This file must not contain application report mapping, command execution, or
+ * stdout/stderr delivery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPresentation = createPresentation;
+const format_options_1 = require("./format-options");
+const csv_1 = require("./renderers/csv");
+const json_1 = require("./renderers/json");
+const table_1 = require("./renderers/table");
+const result_renderer_1 = require("./result-renderer");
+const view_1 = require("./view");
+/**
+ * Creates the presentation facade used by terminal applications.
+ *
+ * The facade owns generic rendering mechanics only; callers still map their
+ * domain objects to presentation views.
+ */
+function createPresentation() {
+    const viewFactory = (0, view_1.createPresentationViewFactory)();
+    return {
+        ...viewFactory,
+        formats: format_options_1.presentationFormats,
+        render: result_renderer_1.renderPresentationResult,
+        renderers: {
+            json: {
+                render: json_1.renderJson
+            },
+            table: {
+                render: table_1.renderTextTable
+            },
+            csv: {
+                render: csv_1.renderCsv,
+                renderRow: csv_1.renderCsvRow
+            }
+        }
+    };
+}

package/dist/presentation/format-options.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The presentation format options module defines shared output format
+ * contracts for terminal commands.
+ *
+ * Allowed here:
+ * - supported presentation format names;
+ * - reusable option schema for `--format`;
+ * - format guards for terminal app composition;
+ *
+ * This file must not contain rendering logic or command execution.
+ */
+/**
+ * Supported output formats for the shared terminal presentation renderer.
+ */
+export declare const presentationFormats: readonly ["json", "table", "csv"];
+/**
+ * Reusable `--format` option schema for commands that return presentation
+ * results.
+ */
+export declare const presentationFormatOptions: {
+    readonly format: {
+        readonly type: "string";
+        readonly choices: readonly ["json", "table", "csv"];
+        readonly default: "table";
+    };
+};
+export type PresentationFormat = typeof presentationFormats[number];
+/**
+ * Narrows unknown option values to supported presentation formats.
+ */
+export declare function isPresentationFormat(value: unknown): value is PresentationFormat;