icore 1.0.18 → 2.0.0

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,64 +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 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);
-            const format = resolveFormat(prepared);
-            await writeTerminalOutput(result, format, 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.
  */
@@ -103,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/examples/two-phase-primitives.md

@@ -104,6 +104,43 @@ finally {
 Resource creation and cleanup stay application-owned. The terminal app only
 runs the prepared command and applies the same output behavior as `app.run(...)`.
 
+## Write Prepared Output
+
+Use `app.writePreparedOutput(...)` when the application needs to inspect the raw
+command result before terminal output is written.
+
+```ts
+const prepared = await app.prepare([
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  strict: true
+});
+
+const context = await createContext(prepared);
+
+try {
+  const result = await app.commands.run(prepared, context);
+
+  if (isShutdownHandle(result)) {
+    installShutdownHooks(result);
+
+    return;
+  }
+
+  await app.writePreparedOutput(prepared, result);
+}
+finally {
+  await cleanup(context);
+}
+```
+
+Only terminal output belongs here: ready text, streaming text, presentation
+results, or no output. Strings are written exactly as provided; include `\n`
+when line output is desired.
+
 ## Prepare From A Registry
 
 `prepareCommandFromArgs(...)` is the standalone primitive behind

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icore",
-  "version": "1.0.18",
+  "version": "2.0.0",
   "description": "Declarative command line interface and terminal presentation mechanics for Node.js",
   "keywords": [
     "command-line",
@@ -34,7 +34,7 @@
   "scripts": {
     "build": "tsc",
     "test": "fwa --prune",
-    "lint": "eslint src"
+    "lint": "eslint"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",