icore 1.0.19 → 2.0.1

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

@@ -5,7 +5,7 @@
  * Allowed here:
  * - the minimal text writer contract;
  * - promise-returning sink support;
- * - Node-style `drain` waiting when a writable sink reports backpressure;
+ * - Node-style backpressure and writable lifecycle handling;
  *
  * This file must not contain stdout/stderr selection or command semantics.
  */
@@ -24,6 +24,7 @@ export type BackpressureTextSink = {
  * 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.
+ * are resumed after their next `drain` event. EventEmitter-compatible sinks
+ * reject when they emit `error` or `close` before draining.
  */
 export declare function createBackpressureTextWriter(sink: BackpressureTextSink): TextWriter;

package/dist/output/text-writer.js

@@ -6,7 +6,7 @@
  * Allowed here:
  * - the minimal text writer contract;
  * - promise-returning sink support;
- * - Node-style `drain` waiting when a writable sink reports backpressure;
+ * - Node-style backpressure and writable lifecycle handling;
  *
  * This file must not contain stdout/stderr selection or command semantics.
  */
@@ -16,7 +16,8 @@ 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.
+ * are resumed after their next `drain` event. EventEmitter-compatible sinks
+ * reject when they emit `error` or `close` before draining.
  */
 function createBackpressureTextWriter(sink) {
     return {
@@ -32,6 +33,10 @@ function createBackpressureTextWriter(sink) {
             if (typeof sink.once !== 'function') {
                 return;
             }
+            if (isEventedBackpressureTextSink(sink)) {
+                await waitForEventedDrain(sink);
+                return;
+            }
             await waitForDrain(sink.once.bind(sink));
         }
     };
@@ -47,3 +52,38 @@ function waitForDrain(onceDrain) {
         onceDrain('drain', resolve);
     });
 }
+function waitForEventedDrain(sink) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        function cleanup() {
+            sink.off('drain', handleDrain);
+            sink.off('error', handleError);
+            sink.off('close', handleClose);
+        }
+        function settle(action) {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            action();
+        }
+        function handleDrain() {
+            settle(resolve);
+        }
+        function handleError(error) {
+            settle(() => reject(error));
+        }
+        function handleClose() {
+            settle(() => reject(new Error('Writable sink closed before drain')));
+        }
+        sink.once('error', handleError);
+        sink.once('close', handleClose);
+        sink.once('drain', handleDrain);
+    });
+}
+function isEventedBackpressureTextSink(sink) {
+    const candidate = sink;
+    return (typeof sink.once === 'function'
+        && typeof candidate.off === 'function');
+}

package/dist/presentation/renderers/csv.d.ts

@@ -3,7 +3,7 @@
  *
  * Allowed here:
  * - CSV row joining;
- * - CSV cell escaping for comma, quote, and newline values;
+ * - CSV cell escaping for comma, quote, carriage return, and newline values;
  *
  * This file must not contain application report mapping.
  */

package/dist/presentation/renderers/csv.js

@@ -4,7 +4,7 @@
  *
  * Allowed here:
  * - CSV row joining;
- * - CSV cell escaping for comma, quote, and newline values;
+ * - CSV cell escaping for comma, quote, carriage return, and newline values;
  *
  * This file must not contain application report mapping.
  */
@@ -28,7 +28,7 @@ function renderCsv(rows) {
 }
 function renderCsvValue(value) {
     const text = String(value);
-    if (!/[",\n]/.test(text)) {
+    if (!/[",\r\n]/.test(text)) {
         return text;
     }
     return `"${text.replaceAll('"', '""')}"`;

package/dist/presentation/renderers/json.d.ts

@@ -9,5 +9,7 @@
  */
 /**
  * Renders an already prepared value as pretty JSON with a trailing newline.
+ *
+ * Throws when the value has no top-level JSON representation.
  */
 export declare function renderJson(value: unknown): string;

package/dist/presentation/renderers/json.js

@@ -12,7 +12,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderJson = renderJson;
 /**
  * Renders an already prepared value as pretty JSON with a trailing newline.
+ *
+ * Throws when the value has no top-level JSON representation.
  */
 function renderJson(value) {
-    return `${JSON.stringify(value, null, 2)}\n`;
+    const json = JSON.stringify(value, null, 2);
+    if (json === undefined) {
+        throw new TypeError('Expected a JSON-serializable value');
+    }
+    return `${json}\n`;
 }

package/dist/presentation/result-renderer.js

@@ -70,10 +70,13 @@ function isPresentationResult(value) {
         return result['value'] === null || isRecord(result['value']);
     }
     if (result['type'] === 'records') {
-        return Array.isArray(result['value']);
+        return isArrayOf(result['value'], isRecord);
     }
-    if (result['type'] === 'table' || result['type'] === 'csv') {
-        return Array.isArray(result['rows']);
+    if (result['type'] === 'table') {
+        return isArrayOf(result['rows'], isTextTableRow);
+    }
+    if (result['type'] === 'csv') {
+        return isArrayOf(result['rows'], isCsvRow);
     }
     return false;
 }
@@ -182,3 +185,25 @@ function assertNever(value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isTextTableRow(value) {
+    return isArrayOf(value, (cell) => typeof cell === 'string');
+}
+function isCsvRow(value) {
+    return isArrayOf(value, isCsvCell);
+}
+function isCsvCell(value) {
+    return (typeof value === 'string'
+        || typeof value === 'number'
+        || typeof value === 'boolean');
+}
+function isArrayOf(value, isValue) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    for (const element of value) {
+        if (!isValue(element)) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/terminal/app.d.ts

@@ -5,6 +5,7 @@
  * - preparing and running command facades;
  * - rendering presentation results;
  * - writing command output through the output facade;
+ * - reporting terminal errors through caller-configured policy;
  *
  * This file must not contain argv tokenization, option validation internals,
  * domain behavior, or application-specific report mapping.
@@ -21,6 +22,32 @@ import { type Output } from '../output/facade';
  * no output. Other result shapes are rejected before writing to stdout.
  */
 export type TerminalCommandOutput = string | AsyncIterable<string> | PresentationResult | undefined;
+/** Terminal operation in which an error was observed. */
+export type TerminalErrorPhase = 'prepare' | 'execute' | 'render' | 'write' | 'external';
+/**
+ * Context supplied to terminal error policy callbacks.
+ *
+ * Prepared command data is guaranteed for command execution and terminal
+ * output phases. Errors outside terminal app operations may provide either
+ * arguments, prepared command data, or neither.
+ */
+export type TerminalErrorContext<TPrepared> = {
+    phase: 'prepare';
+    args: readonly string[];
+} | {
+    phase: 'execute' | 'render' | 'write';
+    prepared: TPrepared;
+    args?: readonly string[];
+} | {
+    phase: 'external';
+    args?: readonly string[];
+    prepared?: TPrepared;
+};
+/** Caller-owned terminal error rendering and process exit-code policy. */
+export type TerminalErrorPolicy<TPrepared> = {
+    renderError?(error: unknown, context: TerminalErrorContext<TPrepared>): string;
+    resolveExitCode?(error: unknown, context: TerminalErrorContext<TPrepared>): number;
+};
 type BivariantCallback<TInput, TOutput> = {
     bivarianceHack(input: TInput): TOutput;
 }['bivarianceHack'];
@@ -47,6 +74,8 @@ export type TerminalAppOptions<TCommands extends readonly TerminalCommandDefinit
     presentation?: Presentation;
     /** Custom output facade. */
     output?: Output;
+    /** Custom terminal error rendering and exit-code policy. */
+    errorPolicy?: TerminalErrorPolicy<PreparedCommand<TCommands[number]>>;
     /** Resolves output format. */
     resolveFormat?(prepared: PreparedCommand<TCommands[number]>): PresentationFormat | undefined;
 };
@@ -54,6 +83,8 @@ export type TerminalApp<TCommands extends readonly TerminalCommandDefinition[]>
     commands: Commands<TCommands>;
     presentation: Presentation;
     output: Output;
+    /** Renders an error to stderr and returns its process-style exit code. */
+    reportError(error: unknown, context?: TerminalErrorContext<PreparedCommand<TCommands[number]>>): Promise<number>;
     /** No application context required. */
     prepare(args: readonly string[], options?: CommandResolutionOptions): Promise<PreparedCommand<TCommands[number]>>;
     /** Runs an already prepared command through terminal rendering and output. */

package/dist/terminal/app.js

@@ -6,6 +6,7 @@
  * - preparing and running command facades;
  * - rendering presentation results;
  * - writing command output through the output facade;
+ * - reporting terminal errors through caller-configured policy;
  *
  * This file must not contain argv tokenization, option validation internals,
  * domain behavior, or application-specific report mapping.
@@ -27,68 +28,113 @@ function createTerminalApp(options) {
     const presentation = options.presentation ?? (0, facade_1.createPresentation)();
     const output = options.output ?? (0, facade_2.createOutput)();
     const resolveFormat = options.resolveFormat ?? resolvePreparedFormat;
+    async function reportError(error, context = {
+        phase: 'external'
+    }) {
+        const renderedError = options.errorPolicy?.renderError === undefined
+            ? renderTerminalError(error)
+            : options.errorPolicy.renderError(error, context);
+        await output.error(renderedError);
+        return options.errorPolicy?.resolveExitCode === undefined
+            ? resolveTerminalExitCode()
+            : options.errorPolicy.resolveExitCode(error, context);
+    }
     async function writePreparedOutput(prepared, terminalOutput) {
-        const format = resolveFormat(prepared);
-        await writeTerminalOutput(terminalOutput, format, presentation, output);
+        const renderedOutput = renderTerminalOutput(terminalOutput, resolveFormat(prepared), presentation);
+        await writeTerminalOutput(renderedOutput, output);
     }
     async function runPrepared(prepared, context) {
+        return runPreparedFromArgs(prepared, context);
+    }
+    async function runPreparedFromArgs(prepared, context, args) {
+        let result;
         try {
-            const result = await options.commands.run(prepared, context);
-            await writeTerminalOutput(result, resolveFormat(prepared), presentation, output);
+            result = await options.commands.run(prepared, context);
+        }
+        catch (error) {
+            return reportError(error, createPreparedErrorContext('execute', prepared, args));
+        }
+        let renderedOutput;
+        try {
+            renderedOutput = renderTerminalOutput(result, resolveFormat(prepared), presentation);
+        }
+        catch (error) {
+            return reportError(error, createPreparedErrorContext('render', prepared, args));
+        }
+        try {
+            await writeTerminalOutput(renderedOutput, output);
             return 0;
         }
         catch (error) {
-            await output.error(renderTerminalError(error));
-            return 1;
+            return reportError(error, createPreparedErrorContext('write', prepared, args));
         }
     }
     return {
         commands: options.commands,
         presentation,
         output,
+        reportError,
         prepare(args, commandOptions) {
             return options.commands.prepare(args, commandOptions);
         },
         runPrepared,
         writePreparedOutput,
         async run(args, context, commandOptions) {
+            let prepared;
             try {
-                const prepared = await options.commands.prepare(args, commandOptions);
-                return runPrepared(prepared, context);
+                prepared = await options.commands.prepare(args, commandOptions);
             }
             catch (error) {
-                await output.error(renderTerminalError(error));
-                return 1;
+                return reportError(error, {
+                    phase: 'prepare',
+                    args
+                });
             }
+            return runPreparedFromArgs(prepared, context, args);
         }
     };
 }
-/**
- * Writes only terminal-supported command output shapes.
- *
- * This keeps the terminal boundary explicit: application objects must be
- * mapped to text or presentation views before they reach stdout.
- */
-async function writeTerminalOutput(result, format, presentation, output) {
+function renderTerminalOutput(result, format, presentation) {
     if (result === undefined) {
-        return;
+        return undefined;
     }
     if (typeof result === 'string') {
-        await output.write(result);
-        return;
+        return result;
     }
     if (isAsyncIterable(result)) {
-        for await (const chunk of result) {
-            await output.write(chunk);
-        }
-        return;
+        return result;
     }
     if ((0, result_renderer_1.isPresentationResult)(result)) {
-        await output.write(presentation.render(result, format));
-        return;
+        return presentation.render(result, format);
     }
     throw new Error('Expected terminal command output');
 }
+/** Writes already rendered terminal text while preserving stream backpressure. */
+async function writeTerminalOutput(result, output) {
+    if (result === undefined) {
+        return;
+    }
+    if (typeof result === 'string') {
+        await output.write(result);
+        return;
+    }
+    for await (const chunk of result) {
+        await output.write(chunk);
+    }
+}
+function createPreparedErrorContext(phase, prepared, args) {
+    if (args === undefined) {
+        return {
+            phase,
+            prepared
+        };
+    }
+    return {
+        phase,
+        prepared,
+        args
+    };
+}
 /**
  * Keeps the default format convention local to terminal composition.
  */
@@ -107,6 +153,9 @@ function renderTerminalError(error) {
     }
     return `${String(error)}\n`;
 }
+function resolveTerminalExitCode() {
+    return 1;
+}
 function isAsyncIterable(value) {
     return (typeof value === 'object'
         && value !== null

package/examples/terminal-app.md

@@ -116,3 +116,70 @@ const appWithFormatPolicy = createTerminalApp({
 This is useful when one command has a different default output contract. It is
 also a point where the application can make a bad abstraction: avoid hiding
 format decisions here when a normal `--format` option would be clearer.
+
+## Reuse Error Reporting In A Custom Lifecycle
+
+Configure one error policy when the application sometimes uses `app.run(...)`
+and sometimes owns command execution itself. The built-in flow and explicit
+`app.reportError(...)` calls use the same policy.
+
+```ts
+import { isIcoreError } from 'icore';
+
+const appWithErrorPolicy = createTerminalApp({
+  commands,
+  presentation,
+  output: createOutput(),
+  errorPolicy: {
+    renderError(error) {
+      const message = error instanceof Error
+        ? error.message
+        : String(error);
+
+      return `${message}\n`;
+    },
+    resolveExitCode(error) {
+      return isIcoreError(error) && error.category === 'usage'
+        ? 2
+        : 1;
+    }
+  }
+});
+```
+
+When the application owns context creation and cleanup, it can prepare and run
+the command explicitly while keeping terminal diagnostics consistent:
+
+```ts
+const prepared = await appWithErrorPolicy.prepare(args, {
+  strict: true
+});
+let result;
+
+try {
+  result = await appWithErrorPolicy.commands.run(prepared, context);
+}
+catch (error) {
+  process.exitCode = await appWithErrorPolicy.reportError(error, {
+    phase: 'execute',
+    args,
+    prepared
+  });
+
+  return;
+}
+
+try {
+  await appWithErrorPolicy.writePreparedOutput(prepared, result);
+}
+catch (error) {
+  process.exitCode = await appWithErrorPolicy.reportError(error, {
+    phase: 'write',
+    args,
+    prepared
+  });
+}
+```
+
+The application still owns help text and lifecycle behavior. The policy only
+provides a shared terminal reporting boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icore",
-  "version": "1.0.19",
+  "version": "2.0.1",
   "description": "Declarative command line interface and terminal presentation mechanics for Node.js",
   "keywords": [
     "command-line",
@@ -33,8 +33,9 @@
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
+    "prepack": "tsc",
     "test": "fwa --prune",
-    "lint": "eslint src"
+    "lint": "eslint"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",