icore 1.0.18 → 2.0.0

package/CHANGELOG.md

@@ -9,40 +9,81 @@ Historical entries before this file was introduced were reconstructed from npm
 publish metadata and local git history. Older entries are intentionally
 conservative.
 
-Version boundaries between `1.0.12` and `1.0.15` are draft-level and should be
-verified against git tags.
+Version boundaries from `1.0.12` through `1.0.19` were checked against npm
+`gitHead` metadata and local git history.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-07-14
+
 ### Added
 
-- Added `TerminalApp.runPrepared(...)` for running prepared commands through terminal rendering and output.
+- Added reusable terminal error rendering and exit-code policy with prepare,
+  execute, render, write, and external phase context.
+- Added `TerminalApp.reportError(...)` for caller-owned lifecycle flows that
+  need the same stderr and exit-code behavior as `run(...)` and
+  `runPrepared(...)`.
+- Added `IcoreError.category` to distinguish usage failures from invalid
+  command and option definitions.
+- Added the public `IcoreErrorDetailsMap`, generic `IcoreErrorDetails<TCode>`,
+  and distributed `AnyIcoreError` contracts for code-specific error details.
+- Added `isIcoreError(...)` overloads for narrowing any `IcoreError` or one
+  exact error code while preserving its details type.
 
 ### Changed
 
-- Changed `createTerminalApp` typing to accept command registries with void and prepared payloads.
-- Updated testing instructions to use `yarn build` and `yarn test`.
+- Clarified that extra positionals after a matched command path are rejected
+  during prepare unless the command declares `allowExtraPositionals: true`.
+- Changed `TerminalApp.run(...)` and `TerminalApp.runPrepared(...)` to share the
+  configured terminal error policy while preserving the default error text and
+  exit code.
+- **Breaking:** changed the `IcoreError` constructor to require code-specific
+  `details`; direct callers must now provide the third argument.
+- Added explicit variant discriminators to `UNKNOWN_COMMAND`,
+  `UNEXPECTED_ARGUMENT`, `EXPECTED_REQUIRED_ARGUMENT`, and
+  `INVALID_OPTION_DEFAULT` details.
 
-## [1.0.16]
+## [1.0.19]
 
 ### Added
 
-- Added `createTerminalApp()` as the top-level terminal application composition API.
-- Added semantic presentation facade: `createPresentation()`.
-- Added semantic output facade: `createOutput()` with `output.write(...)` and `output.error(...)`.
-- Added terminal-ready command output support: text, async text streams, presentation results, and empty output.
-- Added guide-style examples for terminal app, command flow, option schemas, presentation, output, and lower-level mechanics.
+- Added `TerminalApp.writePreparedOutput(...)` for rendering and writing already obtained terminal output.
+- Added `docs/roadmap.md` for directional project decisions that are not release history.
 
 ### Changed
 
-- Documentation was reorganized around `command`, `presentation`, and `output`.
-- Examples were grouped by usage level: Terminal Application, Layer Toolkit, Primitive Mechanics.
-- Public README now positions `icore` as terminal application mechanics, not only argv parsing.
+- Changed `createTerminalApp` typing to allow custom command results when consumers run prepared commands themselves.
+- Documented the caller-owned flow for command execution results that may be
+  lifecycle handles before terminal output is written.
+- Documented that terminal string output is written exactly as provided.
 
-## [1.0.15]
+## [1.0.18]
 
 ### Added
 
+- Added `TerminalApp.runPrepared(...)` for running prepared commands through terminal rendering and output.
+
+### Changed
+
+- Documented the `app.prepare(...)` and `app.runPrepared(...)` flow for applications
+  that create and clean up runtime context themselves.
+
+## [1.0.17]
+
+### Changed
+
+- Relaxed `createTerminalApp` typing so command registries with commands
+  without `prepare()` hooks and with void payloads compile without adapter casts.
+
+## [1.0.16]
+
+### Added
+
+- Added `createTerminalApp()` as the top-level terminal application composition API.
+- Added command mechanics facade: `createCommand()`.
+- Added semantic presentation facade: `createPresentation()`.
+- Added semantic output facade: `createOutput()` with `output.write(...)` and `output.error(...)`.
+- Added terminal-ready command output support: text, async text streams, presentation results, and empty output.
 - Added presentation primitives and renderers:
   - `renderJson`
   - `renderCsv`
@@ -54,67 +95,62 @@ verified against git tags.
   - `createStdoutWriter`
   - `createStderrWriter`
   - `createBackpressureTextWriter`
+- Added typed option subset parsing with `parseOptionsSubsetDetailed`.
+- Added guide-style examples for terminal app, command flow, option schemas, presentation, output, and lower-level mechanics.
 
 ### Changed
 
-- Extracted generic JSON/CSV/table rendering mechanics from project-specific CLI code.
+- Documentation was reorganized around `command`, `presentation`, and `output`.
+- Examples were grouped by usage level: Terminal Application, Layer Toolkit, Primitive Mechanics.
+- Public README now positions `icore` as terminal application mechanics, not only argv parsing.
+- Source files were reorganized by framework area: argv, command, options,
+  presentation, output, and terminal app.
+- Updated tests to run with `fwa --prune`.
+- Restored `CHANGELOG.md` to published package contents.
 
-## [1.0.14]
+### Removed
+
+- Removed the redundant CLI barrel module.
+- Removed the legacy `git-flow.md` document.
+- Removed the `prepare` package script.
+
+## [1.0.15]
 
 ### Added
 
-- Added command mechanics facade: `createCommand()`.
-- Added command registry flow:
-  - `command.define(...)`
-  - `command.registry(...)`
-  - `commands.prepare(...)`
-  - `commands.run(...)`
-  - `commands.runFromArgs(...)`
-- Added lower-level command primitives:
-  - `defineCommand`
-  - `defineCommandRegistry`
-  - `createCommands`
-  - `resolveCommand`
-  - `prepareCommandFromArgs`
-  - `runPreparedCommand`
-  - `runCommandFromRegistry`
-  - `runCommand`
+- Added `isPreparedCommandName` for narrowing prepared command unions by command name.
 
 ### Changed
 
-- CLI command execution became explicitly two-phase: prepare without runtime context, then run with context.
+- Temporarily excluded `CHANGELOG.md` from published package contents.
+
+## [1.0.14]
+
+### Changed
+
+- Preserved prepared command payload correlation when narrowing registry unions.
+- Reformatted `CHANGELOG.md` according to Keep a Changelog.
 
 ## [1.0.13]
 
 ### Added
 
-- Added typed option schema composition with `mergeOptionsSchema`.
-- Added option inference helpers for parsed values and provided metadata.
-- Added command-name guards:
-  - `isCommandName`
-  - `isPreparedCommandName`
-- Added detailed option parsing contracts for cases where caller needs explicit provided/not-provided metadata.
+- Added machine-readable `IcoreError` codes and details.
+- Added strict command resolution mode with `strict: true`.
+- Added strict mode support to direct `runCommand(...)` calls.
+- Added typed prepared command payloads.
+- Added `CHANGELOG.md`.
 
 ### Changed
 
-- Boolean option handling was tightened around flag syntax: `--flag` and `--no-flag`.
+- Boolean option handling was tightened to flag syntax only.
 
 ## [1.0.12]
 
-### Added
+### Changed
 
-- Added core typed CLI option mechanics based on literal schemas:
-  - `type: 'string'`
-  - `type: 'boolean'`
-  - `type: 'number'`
-- Added GNU-style argv parsing:
-  - `--name value`
-  - `--name=value`
-  - `--flag`
-  - short aliases
-  - `--` terminator
-- Added machine-readable `IcoreError`.
-- Added initial TypeScript-first public API for command-line mechanics.
+- Replaced the preliminary `flagOnly` boolean option setting with typed
+  `syntax: 'flag'`.
 
 ## [1.0.11] - 2026-07-02
 
@@ -266,6 +302,9 @@ verified against git tags.
 - Detailed changelog entries were not maintained for these releases.
 
 [Unreleased]: https://github.com/woodger/icore/commits/develop
+[1.0.19]: https://www.npmjs.com/package/icore/v/1.0.19
+[1.0.18]: https://www.npmjs.com/package/icore/v/1.0.18
+[1.0.17]: https://www.npmjs.com/package/icore/v/1.0.17
 [1.0.16]: https://www.npmjs.com/package/icore/v/1.0.16
 [1.0.15]: https://www.npmjs.com/package/icore/v/1.0.15
 [1.0.14]: https://www.npmjs.com/package/icore/v/1.0.14

package/dist/argv/parser.js

@@ -147,6 +147,7 @@ function createDuplicateArgumentError(name) {
 }
 function createUnexpectedArgumentError(argument) {
     return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+        reason: 'malformed-option',
         argument
     });
 }

package/dist/command/mechanics.js

@@ -220,6 +220,7 @@ function resolveCommandPositionals(path, positionals) {
         if (positionals[index] !== path[index]) {
             const command = path.join(' ');
             throw new icore_error_1.IcoreError('UNKNOWN_COMMAND', `Expected command '${command}'`, {
+                reason: 'path-mismatch',
                 command,
                 path: [...path],
                 positionals: [...positionals]
@@ -305,12 +306,14 @@ function isOptionBeforeCommand(arg) {
 function createUnknownCommandError(positionals) {
     const command = formatCommandPositionals(positionals);
     return new icore_error_1.IcoreError('UNKNOWN_COMMAND', `Unknown command: ${command}`, {
+        reason: 'unresolved',
         command,
         positionals: [...positionals]
     });
 }
 function createUnexpectedArgumentError(argument) {
     return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+        reason: 'option-before-command',
         argument
     });
 }

package/dist/errors/icore-error.d.ts

@@ -3,27 +3,150 @@
  *
  * Allowed here:
  * - defining stable error codes;
+ * - correlating error codes with structured details;
  * - preserving human-readable messages on Error instances;
  * - carrying structured details for application-level handling;
+ * - narrowing unknown errors by their stable codes;
  *
  * This file must not contain parser, validator, or command resolution logic.
  */
+type OptionIdentityDetails = {
+    argument: string;
+    option: string;
+};
+type UnknownCommandDetails = {
+    reason: 'unresolved';
+    command: string;
+    positionals: readonly string[];
+} | {
+    reason: 'path-mismatch';
+    command: string;
+    path: readonly string[];
+    positionals: readonly string[];
+};
+type UnexpectedArgumentDetails = {
+    reason: 'malformed-option';
+    argument: string;
+} | {
+    reason: 'unknown-option';
+    argument: string;
+    option: string;
+} | {
+    reason: 'option-before-command';
+    argument: string;
+};
+type ExpectedRequiredArgumentDetails = {
+    reason: 'option';
+    argument: string;
+    option: string;
+} | {
+    reason: 'positional';
+    argument: string;
+    positional: string;
+};
+type InvalidOptionTypeDetails = OptionIdentityDetails & ({
+    expected: 'string' | 'boolean flag' | 'number';
+    value: unknown;
+} | {
+    expected: 'integer';
+    value: number;
+} | {
+    expected: 'minimum';
+    min: number;
+    value: number;
+} | {
+    expected: 'maximum';
+    max: number;
+    value: number;
+});
+type InvalidOptionDefaultDetails = OptionIdentityDetails & ({
+    expected: 'string' | 'boolean' | 'number';
+    value: unknown;
+} | {
+    expected: 'integer';
+    value: number;
+} | {
+    expected: 'minimum';
+    min: number;
+    value: number;
+} | {
+    expected: 'maximum';
+    max: number;
+    value: number;
+} | {
+    expected: 'choice';
+    choices: readonly (string | number)[];
+    value: string | number;
+});
+/** Structured details protocol keyed by every stable `IcoreError` code. */
+export type IcoreErrorDetailsMap = {
+    UNKNOWN_COMMAND: UnknownCommandDetails;
+    UNEXPECTED_ARGUMENT: UnexpectedArgumentDetails;
+    DUPLICATE_ARGUMENT: OptionIdentityDetails;
+    EXPECTED_REQUIRED_ARGUMENT: ExpectedRequiredArgumentDetails;
+    INVALID_OPTION_TYPE: InvalidOptionTypeDetails;
+    INVALID_OPTION_CHOICE: OptionIdentityDetails & {
+        choices: readonly (string | number)[];
+        value: string | number;
+    };
+    UNEXPECTED_POSITIONAL: {
+        command: string;
+        positional: string;
+        positionals: readonly string[];
+    };
+    INVALID_OPTION_ALIAS: OptionIdentityDetails & {
+        alias: unknown;
+    };
+    DUPLICATE_ALIAS: {
+        argument: string;
+        alias: string;
+    };
+    INVALID_OPTION_DEFAULT: InvalidOptionDefaultDetails;
+    DUPLICATE_COMMAND: {
+        command: string;
+    };
+};
+/** Stable machine-readable error code for `icore` CLI mechanics errors. */
+export type IcoreErrorCode = keyof IcoreErrorDetailsMap;
+/** Structured details for one exact `IcoreError` code. */
+export type IcoreErrorDetails<TCode extends IcoreErrorCode> = Readonly<IcoreErrorDetailsMap[TCode]>;
 /**
- * Stable machine-readable error code for `icore` CLI mechanics errors.
+ * Stable category for distinguishing user input failures from invalid command
+ * or option definitions.
  */
-export type IcoreErrorCode = 'UNKNOWN_COMMAND' | 'UNEXPECTED_ARGUMENT' | 'DUPLICATE_ARGUMENT' | 'EXPECTED_REQUIRED_ARGUMENT' | 'INVALID_OPTION_TYPE' | 'INVALID_OPTION_CHOICE' | 'UNEXPECTED_POSITIONAL' | 'INVALID_OPTION_ALIAS' | 'DUPLICATE_ALIAS' | 'INVALID_OPTION_DEFAULT' | 'DUPLICATE_COMMAND';
-/**
- * Structured context for application-level error handling.
- */
-export type IcoreErrorDetails = Readonly<Record<string, unknown>>;
+export type IcoreErrorCategory = 'usage' | 'definition';
+declare const icoreErrorCategoryByCode: {
+    readonly UNKNOWN_COMMAND: "usage";
+    readonly UNEXPECTED_ARGUMENT: "usage";
+    readonly DUPLICATE_ARGUMENT: "usage";
+    readonly EXPECTED_REQUIRED_ARGUMENT: "usage";
+    readonly INVALID_OPTION_TYPE: "usage";
+    readonly INVALID_OPTION_CHOICE: "usage";
+    readonly UNEXPECTED_POSITIONAL: "usage";
+    readonly INVALID_OPTION_ALIAS: "definition";
+    readonly DUPLICATE_ALIAS: "definition";
+    readonly INVALID_OPTION_DEFAULT: "definition";
+    readonly DUPLICATE_COMMAND: "definition";
+};
 /**
  * Error thrown by `icore` for CLI parsing, option validation, command
  * resolution, and schema configuration failures.
  */
-export declare class IcoreError extends Error {
+export declare class IcoreError<TCode extends IcoreErrorCode = IcoreErrorCode> extends Error {
     /** Stable machine-readable code. */
-    readonly code: IcoreErrorCode;
+    readonly code: TCode;
+    /** Stable high-level error category. */
+    readonly category: typeof icoreErrorCategoryByCode[TCode];
     /** Structured error context. */
-    readonly details: IcoreErrorDetails;
-    constructor(code: IcoreErrorCode, message: string, details?: IcoreErrorDetails);
+    readonly details: IcoreErrorDetails<TCode>;
+    constructor(code: TCode, message: string, details: IcoreErrorDetails<TCode>);
 }
+/** Distributed union preserving the correlation between code and details. */
+export type AnyIcoreError = {
+    [TCode in IcoreErrorCode]: IcoreError<TCode>;
+}[IcoreErrorCode];
+/** Checks whether an unknown value is any supported `IcoreError`. */
+export declare function isIcoreError(error: unknown): error is AnyIcoreError;
+/** Checks and narrows an unknown value to one exact `IcoreError` code. */
+export declare function isIcoreError<TCode extends IcoreErrorCode>(error: unknown, code: TCode): error is IcoreError<TCode>;
+export {};

package/dist/errors/icore-error.js

@@ -4,13 +4,29 @@
  *
  * Allowed here:
  * - defining stable error codes;
+ * - correlating error codes with structured details;
  * - preserving human-readable messages on Error instances;
  * - carrying structured details for application-level handling;
+ * - narrowing unknown errors by their stable codes;
  *
  * This file must not contain parser, validator, or command resolution logic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IcoreError = void 0;
+exports.isIcoreError = isIcoreError;
+const icoreErrorCategoryByCode = {
+    UNKNOWN_COMMAND: 'usage',
+    UNEXPECTED_ARGUMENT: 'usage',
+    DUPLICATE_ARGUMENT: 'usage',
+    EXPECTED_REQUIRED_ARGUMENT: 'usage',
+    INVALID_OPTION_TYPE: 'usage',
+    INVALID_OPTION_CHOICE: 'usage',
+    UNEXPECTED_POSITIONAL: 'usage',
+    INVALID_OPTION_ALIAS: 'definition',
+    DUPLICATE_ALIAS: 'definition',
+    INVALID_OPTION_DEFAULT: 'definition',
+    DUPLICATE_COMMAND: 'definition'
+};
 /**
  * Error thrown by `icore` for CLI parsing, option validation, command
  * resolution, and schema configuration failures.
@@ -18,14 +34,21 @@ exports.IcoreError = void 0;
 class IcoreError extends Error {
     /** Stable machine-readable code. */
     code;
+    /** Stable high-level error category. */
+    category;
     /** Structured error context. */
     details;
-    constructor(code, message, details = {}) {
+    constructor(code, message, details) {
         super(message);
         this.name = 'IcoreError';
         this.code = code;
+        this.category = icoreErrorCategoryByCode[code];
         this.details = details;
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 exports.IcoreError = IcoreError;
+function isIcoreError(error, code) {
+    return error instanceof IcoreError
+        && (code === undefined || error.code === code);
+}

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  */
 export { parseArgv, type ParsedArgv } from './argv/parser';
 export { createCommand, createCommands, defineCommand, defineCommandRegistry, isCommandName, isPreparedCommandName, prepareCommandFromArgs, resolveCommand, resolveCommandFromArgs, runCommand, runPreparedCommand, runCommandFromRegistry, type Command, type CommandDefinition, type CommandContext, type CommandInput, type CommandName, type CommandPayload, type CommandRegistry, type CommandResolutionOptions, type CommandResult, type Commands, type PreparedCommand, type PreparedCommandInput, type ResolvedCommand } from './command/mechanics';
-export { IcoreError, type IcoreErrorCode, type IcoreErrorDetails } from './errors/icore-error';
+export { IcoreError, isIcoreError, type AnyIcoreError, type IcoreErrorCategory, type IcoreErrorCode, type IcoreErrorDetails, type IcoreErrorDetailsMap } from './errors/icore-error';
 export { parseOptions, parseOptionsDetailed, parseOptionsSubsetDetailed, type ParseOptionsResult, type ParseOptionsSubsetResult } from './options/parser';
 export { mergeOptionsSchema, type BooleanOption, type InferOptions, type InferProvidedOptions, type MergeOptionsSchemas, type NumberOption, type OptionDefinition, type OptionsSchema, type RawOptionValue, type StringOption } from './options/schema';
 export { createPresentation, type Presentation, type PresentationRenderers } from './presentation/facade';
@@ -25,4 +25,4 @@ export { type CsvCell, type CsvRow, type CsvPresentationView, type EmptyPresenta
 export { createOutput, type Output, type OutputOptions } from './output/facade';
 export { createStderrWriter, createStdoutWriter } from './output/node-writer';
 export { createBackpressureTextWriter, type BackpressureTextSink, type TextWriter } from './output/text-writer';
-export { createTerminalApp, type TerminalApp, type TerminalAppOptions, type TerminalCommandOutput } from './terminal/app';
+export { createTerminalApp, type TerminalApp, type TerminalAppOptions, type TerminalCommandOutput, type TerminalErrorContext, type TerminalErrorPhase, type TerminalErrorPolicy } from './terminal/app';

package/dist/index.js

@@ -12,7 +12,7 @@
  * This file must not contain parser, validator, or command runtime logic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+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.isIcoreError = 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");
@@ -30,6 +30,7 @@ Object.defineProperty(exports, "runPreparedCommand", { enumerable: true, get: fu
 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; } });
+Object.defineProperty(exports, "isIcoreError", { enumerable: true, get: function () { return icore_error_1.isIcoreError; } });
 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; } });

package/dist/options/parser.js

@@ -151,7 +151,10 @@ function validateNumberConstraints(name, definition, parsed, source = 'value') {
                 value: parsed
             });
         }
-        throw createExpectedOptionTypeError(name, 'integer', parsed);
+        throw createInvalidOptionTypeError(name, `Expected '--${name}' as integer`, {
+            expected: 'integer',
+            value: parsed
+        });
     }
     if (definition.min !== undefined && parsed < definition.min) {
         const message = `Expected '--${name}' to be greater than or equal to ${String(definition.min)}`;
@@ -192,6 +195,7 @@ function assertChoice(name, choices, value, source = 'value') {
     const message = `Expected '--${name}' as one of: ${choices.join(', ')}`;
     if (source === 'default') {
         throw createInvalidOptionDefaultError(name, message, {
+            expected: 'choice',
             choices: [...choices],
             value
         });
@@ -200,12 +204,14 @@ function assertChoice(name, choices, value, source = 'value') {
 }
 function createUnexpectedArgumentError(name) {
     return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
+        reason: 'unknown-option',
         argument: `--${name}`,
         option: name
     });
 }
 function createExpectedRequiredArgumentError(name) {
     return new icore_error_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
+        reason: 'option',
         argument: `--${name}`,
         option: name
     });

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.
@@ -15,12 +16,38 @@ import { type Presentation, type PresentationResult } from '../presentation/faca
 import { type PresentationFormat } from '../presentation/format-options';
 import { type Output } from '../output/facade';
 /**
- * Supported handler result shapes for the terminal app boundary.
+ * Supported terminal output shapes for the terminal app boundary.
  *
- * Domain commands may return ready text, streaming text, a presentation view,
- * or no output. Other result shapes are rejected before writing to stdout.
+ * Terminal output may be ready text, streaming text, a presentation view, or
+ * 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'];
@@ -30,7 +57,7 @@ type TerminalCommandDefinition = {
     metadata?: unknown;
     allowExtraPositionals?: boolean;
     prepare?: BivariantCallback<PreparedCommandInput, unknown | Promise<unknown>>;
-    handle: BivariantCallback<TerminalCommandInput, TerminalCommandOutput | Promise<TerminalCommandOutput>>;
+    handle: BivariantCallback<TerminalCommandInput, unknown | Promise<unknown>>;
 };
 type PreparedCommandInput = {
     options: Record<string, unknown>;
@@ -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,10 +83,19 @@ 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. */
     runPrepared(prepared: PreparedCommand<TCommands[number]>, context: CommandContext<TCommands[number]>): Promise<number>;
+    /**
+     * Renders and writes already obtained terminal output.
+     *
+     * String output is written exactly as provided; add a trailing newline in the
+     * command result when line output is desired.
+     */
+    writePreparedOutput(prepared: PreparedCommand<TCommands[number]>, output: TerminalCommandOutput): Promise<void>;
     /** Returns a process-style exit code. */
     run(args: readonly string[], context: CommandContext<TCommands[number]>, options?: CommandResolutionOptions): Promise<number>;
 };