icore 1.0.15 → 1.0.17

package/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Historical entries before this file was introduced were reconstructed from npm
+publish metadata and local git history. Older entries are intentionally
+conservative.
+
+## [Unreleased]
+
+### Added
+
+- Added `createCommand` as a semantic command mechanics facade.
+- Added `createCommands` as a high-level command mechanics facade.
+- Added `createPresentation` and `PresentationResult` for terminal view-model rendering.
+- Added semantic `Presentation` view factory methods such as `presentation.records(...)`.
+- Added `createOutput` as a stdout/stderr output boundary facade.
+- Added semantic `Output.write()` and `Output.error()` methods.
+- Added `createTerminalApp` to compose command, presentation, and output mechanics.
+- Added generic terminal presentation renderers for JSON, CSV, and text tables.
+- Added reusable stdout/stderr text writers with backpressure handling.
+- Added shared `presentationFormatOptions` for common `--format` command options.
+- Added machine-readable `IcoreError` codes and details.
+- Added `parseOptionsSubsetDetailed` for validating known option subsets while preserving unknown raw options.
+- Added opt-in `strict: true` command resolution for rejecting options before command paths.
+- Added `strict: true` support to direct `runCommand` execution.
+- Added typed prepared command `payload` returned from `prepare` and passed to `handle`.
+- Added public `CommandPayload`, `CommandContext`, and `CommandResult` helper types.
+- Added `isPreparedCommandName` for narrowing prepared command unions by name.
+- Added this changelog.
+
+### Changed
+
+- Changed `PreparedCommand` typing to preserve payload correlation when narrowing registry unions by command name.
+- Changed output writers to await promise-returning custom sinks.
+- Reorganized internal source files by CLI framework responsibility without changing the root public API.
+- Split option schema contracts from option value parsing internals.
+- Changed npm package contents to include `CHANGELOG.md`.
+- Removed the redundant `cli` barrel so `index` is the only package entrypoint.
+
+### Removed
+
+- Removed explicit boolean values such as `--flag=true` and `--flag=false`; use `--flag` and `--no-flag`.
+
+## [1.0.12] - 2026-07-02
+
+### Changed
+
+- Replaced the preliminary flag-only boolean option naming with `syntax: 'flag'`.
+- Documented flag-only boolean option behavior.
+
+## [1.0.11] - 2026-07-02
+
+### Added
+
+- Added preliminary flag-only boolean option support.
+
+## [1.0.10] - 2026-07-02
+
+### Added
+
+- Added two-phase command execution.
+- Added `PreparedCommandInput`.
+- Added `PreparedCommand`.
+- Added `prepareCommandFromArgs`.
+- Added `runPreparedCommand`.
+- Added command `metadata`.
+- Added command `prepare` hook.
+- Added focused tests for prepare-time validation and handler safety.
+
+### Changed
+
+- Changed `runCommand` and `runCommandFromRegistry` to use the prepare-and-run flow internally.
+
+## [1.0.9] - 2026-07-02
+
+### Changed
+
+- Refined npm package metadata.
+- Updated repository metadata for npm.
+- Simplified published package contents.
+
+## [1.0.8] - 2026-07-02
+
+### Changed
+
+- Updated package author metadata.
+- Normalized README heading structure.
+
+## [1.0.7] - 2026-07-02
+
+### Changed
+
+- Renamed README examples from `upper` to `uppercase`.
+- Cleaned duplicated command test coverage without changing public behavior.
+
+## [1.0.6] - 2026-07-02
+
+### Added
+
+- Added explicit long boolean values such as `--flag=true` and `--flag=false`.
+- Added schema-known boolean negation such as `--no-flag`.
+- Added short option aliases such as `-f` and `-n value`.
+- Added alias validation and duplicate detection between short and long option forms.
+- Documented supported option syntax.
+
+## [1.0.5] - 2026-07-01
+
+### Changed
+
+- Rebuilt README as the main public documentation entry point.
+
+### Removed
+
+- Removed separate generated reference docs from the published documentation flow.
+
+## [1.0.4] - 2026-07-01
+
+### Changed
+
+- Reorganized README and documentation references.
+
+## [1.0.3] - 2026-07-01
+
+### Added
+
+- Added README table of contents.
+
+### Changed
+
+- Polished README formatting and emphasis.
+
+## [1.0.2] - 2026-06-30
+
+### Added
+
+- Added module boundary comments to production source files.
+
+### Changed
+
+- Clarified CLI scope and supported syntax in README.
+- Updated package description and keywords.
+
+## [1.0.1] - 2026-06-30
+
+### Changed
+
+- Published documentation updates after the first stable release.
+- No dedicated version commit is present in local git history for this patch.
+
+## [1.0.0] - 2026-06-30
+
+### Added
+
+- First stable release of the new `icore` CLI mechanics package.
+- Added declarative option parsing and validation.
+- Added schema-aware argv parsing.
+- Added option presence metadata through `parseOptionsDetailed`.
+- Added option schema composition through `mergeOptionsSchema`.
+- Added command registry routing.
+- Added typed command handler input.
+- Added CommonJS package entry points and TypeScript declarations.
+
+### Changed
+
+- Lowered the runtime Node.js engine to `>=16.9.0`.
+
+## [1.0.0-alpha] - 2026-06-28
+
+### Added
+
+- Started the new CLI mechanics codebase after pruning the legacy package code.
+- Added the initial TypeScript build, test, and lint setup for the new package.
+
+## [0.1.38] - 2019-06-12
+
+### Added
+
+- Added legacy tests and documentation.
+
+### Changed
+
+- Final legacy web-framework line release.
+- Updated the legacy package description.
+
+### Removed
+
+- Trimmed legacy runtime dependencies.
+
+## [0.0.37 and earlier]
+
+### Added
+
+- Original legacy npm package line published between 2017 and 2019.
+- Legacy history is preserved for package provenance.
+
+### Changed
+
+- Detailed changelog entries were not maintained for these releases.
+
+[Unreleased]: https://github.com/woodger/icore/commits/develop
+[1.0.12]: https://www.npmjs.com/package/icore/v/1.0.12
+[1.0.11]: https://www.npmjs.com/package/icore/v/1.0.11
+[1.0.10]: https://www.npmjs.com/package/icore/v/1.0.10
+[1.0.9]: https://www.npmjs.com/package/icore/v/1.0.9
+[1.0.8]: https://www.npmjs.com/package/icore/v/1.0.8
+[1.0.7]: https://www.npmjs.com/package/icore/v/1.0.7
+[1.0.6]: https://www.npmjs.com/package/icore/v/1.0.6
+[1.0.5]: https://www.npmjs.com/package/icore/v/1.0.5
+[1.0.4]: https://www.npmjs.com/package/icore/v/1.0.4
+[1.0.3]: https://www.npmjs.com/package/icore/v/1.0.3
+[1.0.2]: https://www.npmjs.com/package/icore/v/1.0.2
+[1.0.1]: https://www.npmjs.com/package/icore/v/1.0.1
+[1.0.0]: https://www.npmjs.com/package/icore/v/1.0.0
+[1.0.0-alpha]: https://www.npmjs.com/package/icore/v/1.0.0-alpha
+[0.1.38]: https://www.npmjs.com/package/icore/v/0.1.38
+[0.0.37 and earlier]: https://www.npmjs.com/package/icore?activeTab=versions

package/dist/{argv.d.ts → argv/parser.d.ts}

@@ -9,13 +9,15 @@
  *
  * This file must not contain typed option validation or command resolution.
  */
-import type { OptionsSchema, RawOptionValue } from './options';
+import type { OptionsSchema, RawOptionValue } from '../options/schema';
 /**
  * Parsed CLI arguments split into positional command path segments and raw
  * named options.
  */
 export type ParsedArgv = {
+    /** Non-option tokens. */
     positionals: string[];
+    /** Unvalidated option values. */
     options: Record<string, RawOptionValue>;
 };
 /**

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

@@ -12,7 +12,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseArgv = parseArgv;
-const errors_1 = require("./errors");
+const icore_error_1 = require("../errors/icore-error");
 /**
  * Parses raw CLI arguments into positionals and raw long-option values.
  */
@@ -140,24 +140,24 @@ function isShortOptionToken(arg) {
     return arg.length === 2 && arg.startsWith('-') && !arg.startsWith('--');
 }
 function createDuplicateArgumentError(name) {
-    return new errors_1.IcoreError('DUPLICATE_ARGUMENT', `Unexpected duplicate argument '--${name}'`, {
+    return new icore_error_1.IcoreError('DUPLICATE_ARGUMENT', `Unexpected duplicate argument '--${name}'`, {
         argument: `--${name}`,
         option: name
     });
 }
 function createUnexpectedArgumentError(argument) {
-    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+    return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
         argument
     });
 }
 function createDuplicateAliasError(alias) {
-    return new errors_1.IcoreError('DUPLICATE_ALIAS', `Unexpected duplicate alias '-${alias}'`, {
+    return new icore_error_1.IcoreError('DUPLICATE_ALIAS', `Unexpected duplicate alias '-${alias}'`, {
         alias,
         argument: `-${alias}`
     });
 }
 function createInvalidOptionAliasError(name, alias) {
-    return new errors_1.IcoreError('INVALID_OPTION_ALIAS', `Expected alias for '--${name}' as single ASCII letter`, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_ALIAS', `Expected alias for '--${name}' as single ASCII letter`, {
         argument: `--${name}`,
         option: name,
         alias

package/dist/{commands.d.ts → command/mechanics.d.ts}

@@ -10,26 +10,32 @@
  * This file must not contain raw token parsing, option schema validation,
  * domain behavior, SDK calls, or output formatting.
  */
-import { type InferOptions, type InferProvidedOptions, type OptionsSchema } from './options';
+import type { InferOptions, InferProvidedOptions, OptionsSchema } from '../options/schema';
 /**
  * Input produced after command path and option validation, before runtime
  * context is attached.
  */
 export type PreparedCommandInput<TSchema extends OptionsSchema> = {
+    /** Parsed option values. */
     options: InferOptions<TSchema>;
+    /** Explicit option presence metadata. */
     provided: InferProvidedOptions<TSchema>;
+    /** Positionals after the command path. */
     positionals: string[];
 };
 /**
  * Input passed to a command handler after command path and option validation.
  */
 export type CommandInput<TSchema extends OptionsSchema, TContext, TPayload = void> = PreparedCommandInput<TSchema> & {
+    /** Application runtime context. */
     context: TContext;
 } & ([
     TPayload
 ] extends [void] ? {
+    /** Optional prepared payload. */
     payload?: TPayload;
 } : {
+    /** Prepared payload. */
     payload: TPayload;
 });
 /**
@@ -40,11 +46,17 @@ export type CommandInput<TSchema extends OptionsSchema, TContext, TPayload = voi
  * formatting.
  */
 export type CommandDefinition<TSchema extends OptionsSchema, TContext, TResult, TPath extends readonly [string, ...string[]] = readonly [string, ...string[]], TMetadata = unknown, TPayload = void> = {
+    /** Command path segments. */
     path: TPath;
+    /** Command option schema. */
     options: TSchema;
+    /** Caller-owned static metadata. */
     metadata?: TMetadata;
+    /** Allows extra positionals. */
     allowExtraPositionals?: boolean;
+    /** Prepares payload before runtime context. */
     prepare?(input: PreparedCommandInput<TSchema>): TPayload | Promise<TPayload>;
+    /** Runs application command behavior. */
     handle(input: CommandInput<TSchema, TContext, TPayload>): TResult | Promise<TResult>;
 };
 type AnyCommandInput = PreparedCommandInput<OptionsSchema> & {
@@ -78,9 +90,18 @@ type CommandDefinitionParts<TCommand extends AnyCommandDefinition> = TCommand ex
     metadata: TCommand['metadata'];
     payload: unknown;
 };
+/**
+ * Infers the runtime context type required by a command.
+ */
 export type CommandContext<TCommand extends AnyCommandDefinition> = CommandDefinitionParts<TCommand>['context'];
+/**
+ * Infers the awaited command handler result type.
+ */
 export type CommandResult<TCommand extends AnyCommandDefinition> = Awaited<CommandDefinitionParts<TCommand>['result']>;
 type CommandSchema<TCommand extends AnyCommandDefinition> = CommandDefinitionParts<TCommand>['schema'];
+/**
+ * Infers the payload type produced by a command prepare hook.
+ */
 export type CommandPayload<TCommand extends AnyCommandDefinition> = CommandDefinitionParts<TCommand>['payload'];
 /**
  * Infers the public command name from a command path.
@@ -90,39 +111,77 @@ export type CommandName<TCommand extends AnyCommandDefinition> = CommandPathName
  * Declarative command registry used to resolve command paths.
  */
 export type CommandRegistry<TCommands extends readonly AnyCommandDefinition[]> = {
+    /** Registered command definitions. */
     commands: TCommands;
+    /** Derived public command names. */
     commandNames: readonly CommandName<TCommands[number]>[];
 };
+/**
+ * High-level command mechanics facade for terminal applications.
+ */
+export type Commands<TCommands extends readonly AnyCommandDefinition[]> = {
+    /** Original command definitions. */
+    definitions: TCommands;
+    /** Public command names. */
+    names: readonly CommandName<TCommands[number]>[];
+    /** Lower-level command registry. */
+    registry: CommandRegistry<TCommands>;
+    /** Resolves from positionals. */
+    resolve(positionals: readonly string[]): ResolvedCommand<TCommands[number]>;
+    /** Resolves from raw argv. */
+    resolveFromArgs(args: readonly string[]): ResolvedCommand<TCommands[number]>;
+    /** Prepares without runtime context. */
+    prepare(args: readonly string[], options?: CommandResolutionOptions): Promise<PreparedCommand<TCommands[number]>>;
+    /** Runs a prepared command. */
+    run(prepared: PreparedCommand<TCommands[number]>, context: CommandContext<TCommands[number]>): Promise<CommandResult<TCommands[number]>>;
+    /** Resolves, prepares, and runs. */
+    runFromArgs(args: readonly string[], context: CommandContext<TCommands[number]>, options?: CommandResolutionOptions): Promise<CommandResult<TCommands[number]>>;
+};
+/**
+ * Semantic facade for command mechanics.
+ */
+export type Command = {
+    define: typeof defineCommand;
+    registry: typeof createCommands;
+    run: typeof runCommand;
+};
 /**
  * Options for command resolution from raw CLI arguments.
  */
 export type CommandResolutionOptions = {
-    /**
-     * When enabled, command path must appear before options. Options before the
-     * command path are rejected instead of participating in legacy candidate
-     * schema parsing.
-     */
+    /** Rejects options before command path. */
     strict?: boolean;
 };
 /**
  * Result of resolving a command from user positionals.
  */
 export type ResolvedCommand<TCommand extends AnyCommandDefinition> = {
+    /** Space-joined command name. */
     name: CommandName<TCommand>;
+    /** Literal command path. */
     path: TCommand['path'];
+    /** Selected command definition. */
     command: TCommand;
+    /** Positionals after the command path. */
     positionals: string[];
 };
 /**
  * Command resolved and validated without runtime context.
  */
 export type PreparedCommand<TCommand extends AnyCommandDefinition> = TCommand extends AnyCommandDefinition ? {
+    /** Space-joined command name. */
     name: CommandName<TCommand>;
+    /** Literal command path. */
     path: TCommand['path'];
+    /** Selected command definition. */
     command: TCommand;
+    /** Parsed option values. */
     options: InferOptions<CommandSchema<TCommand>>;
+    /** Explicit option presence metadata. */
     provided: InferProvidedOptions<CommandSchema<TCommand>>;
+    /** Positionals after the command path. */
     positionals: string[];
+    /** Prepared payload. */
     payload: CommandPayload<TCommand>;
 } : never;
 /**
@@ -133,6 +192,14 @@ export declare function defineCommand<const TSchema extends OptionsSchema, const
  * Defines a command registry while preserving literal command path types.
  */
 export declare function defineCommandRegistry<const TCommands extends readonly AnyCommandDefinition[]>(commands: TCommands): CommandRegistry<TCommands>;
+/**
+ * Creates a command mechanics facade from declarative command definitions.
+ */
+export declare function createCommands<const TCommands extends readonly AnyCommandDefinition[]>(definitions: TCommands): Commands<TCommands>;
+/**
+ * Creates a semantic command mechanics facade.
+ */
+export declare function createCommand(): Command;
 /**
  * Checks whether a value is a command name registered in the given registry.
  */

package/dist/{commands.js → command/mechanics.js}

@@ -14,6 +14,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineCommand = defineCommand;
 exports.defineCommandRegistry = defineCommandRegistry;
+exports.createCommands = createCommands;
+exports.createCommand = createCommand;
 exports.isCommandName = isCommandName;
 exports.isPreparedCommandName = isPreparedCommandName;
 exports.resolveCommand = resolveCommand;
@@ -22,9 +24,9 @@ exports.prepareCommandFromArgs = prepareCommandFromArgs;
 exports.runPreparedCommand = runPreparedCommand;
 exports.runCommandFromRegistry = runCommandFromRegistry;
 exports.runCommand = runCommand;
-const argv_1 = require("./argv");
-const errors_1 = require("./errors");
-const options_1 = require("./options");
+const parser_1 = require("../argv/parser");
+const icore_error_1 = require("../errors/icore-error");
+const parser_2 = require("../options/parser");
 /**
  * Defines a command while preserving literal option schema types.
  */
@@ -42,6 +44,42 @@ function defineCommandRegistry(commands) {
         commandNames: commandNames
     };
 }
+/**
+ * Creates a command mechanics facade from declarative command definitions.
+ */
+function createCommands(definitions) {
+    const registry = defineCommandRegistry(definitions);
+    return {
+        definitions,
+        names: registry.commandNames,
+        registry,
+        resolve(positionals) {
+            return resolveCommand(registry, positionals);
+        },
+        resolveFromArgs(args) {
+            return resolveCommandFromArgs(registry, args);
+        },
+        prepare(args, options) {
+            return prepareCommandFromArgs(registry, args, options);
+        },
+        run(prepared, context) {
+            return runPreparedCommand(prepared, context);
+        },
+        runFromArgs(args, context, options) {
+            return runCommandFromRegistry(registry, args, context, options);
+        }
+    };
+}
+/**
+ * Creates a semantic command mechanics facade.
+ */
+function createCommand() {
+    return {
+        define: defineCommand,
+        registry: createCommands,
+        run: runCommand
+    };
+}
 /**
  * Checks whether a value is a command name registered in the given registry.
  */
@@ -72,13 +110,13 @@ function resolveCommand(registry, positionals) {
  */
 function resolveCommandFromArgs(registry, args) {
     for (const command of commandsBySpecificity(registry.commands)) {
-        const argv = (0, argv_1.parseArgv)(args, command.options);
+        const argv = (0, parser_1.parseArgv)(args, command.options);
         const resolved = resolveCommandCandidate(command, argv.positionals);
         if (resolved !== undefined) {
             return resolved;
         }
     }
-    throw createUnknownCommandError((0, argv_1.parseArgv)(args).positionals);
+    throw createUnknownCommandError((0, parser_1.parseArgv)(args).positionals);
 }
 /**
  * Resolves and validates a command without requiring runtime context.
@@ -88,13 +126,13 @@ async function prepareCommandFromArgs(registry, args, options = {}) {
         return prepareCommandFromArgsStrict(registry, args);
     }
     for (const command of commandsBySpecificity(registry.commands)) {
-        const argv = (0, argv_1.parseArgv)(args, command.options);
+        const argv = (0, parser_1.parseArgv)(args, command.options);
         const resolved = resolveCommandCandidate(command, argv.positionals);
         if (resolved !== undefined) {
             return prepareResolvedCommand(resolved, argv.options);
         }
     }
-    throw createUnknownCommandError((0, argv_1.parseArgv)(args).positionals);
+    throw createUnknownCommandError((0, parser_1.parseArgv)(args).positionals);
 }
 /**
  * Runs a prepared command with caller-provided runtime context.
@@ -128,7 +166,7 @@ async function prepareCommand(command, args, options = {}) {
     if (options.strict === true) {
         assertNoOptionBeforeCommand(args);
     }
-    const argv = (0, argv_1.parseArgv)(args, command.options);
+    const argv = (0, parser_1.parseArgv)(args, command.options);
     const extraPositionals = resolveCommandPositionals(command.path, argv.positionals);
     const resolved = {
         name: commandPathToName(command.path),
@@ -143,7 +181,7 @@ async function prepareCommandFromArgsStrict(registry, args) {
     if (command === undefined) {
         throw createUnknownCommandError(commandPositionalsBeforeOptions(args));
     }
-    const argv = (0, argv_1.parseArgv)(args, command.options);
+    const argv = (0, parser_1.parseArgv)(args, command.options);
     const resolved = resolveCommandCandidate(command, argv.positionals);
     if (resolved === undefined) {
         throw createUnknownCommandError(argv.positionals);
@@ -154,13 +192,13 @@ async function prepareResolvedCommand(resolved, rawOptions) {
     const { command } = resolved;
     if (resolved.positionals.length > 0 && command.allowExtraPositionals !== true) {
         const positional = resolved.positionals[0] ?? '';
-        throw new errors_1.IcoreError('UNEXPECTED_POSITIONAL', `Unexpected positional argument for '${command.path.join(' ')}': ${positional}`, {
+        throw new icore_error_1.IcoreError('UNEXPECTED_POSITIONAL', `Unexpected positional argument for '${command.path.join(' ')}': ${positional}`, {
             command: command.path.join(' '),
             positional,
             positionals: [...resolved.positionals]
         });
     }
-    const parsed = (0, options_1.parseOptionsDetailed)(command.options, rawOptions);
+    const parsed = (0, parser_2.parseOptionsDetailed)(command.options, rawOptions);
     const input = {
         options: parsed.options,
         provided: parsed.provided,
@@ -181,7 +219,7 @@ function resolveCommandPositionals(path, positionals) {
     for (let index = 0; index < path.length; index += 1) {
         if (positionals[index] !== path[index]) {
             const command = path.join(' ');
-            throw new errors_1.IcoreError('UNKNOWN_COMMAND', `Expected command '${command}'`, {
+            throw new icore_error_1.IcoreError('UNKNOWN_COMMAND', `Expected command '${command}'`, {
                 command,
                 path: [...path],
                 positionals: [...positionals]
@@ -266,18 +304,18 @@ function isOptionBeforeCommand(arg) {
 }
 function createUnknownCommandError(positionals) {
     const command = formatCommandPositionals(positionals);
-    return new errors_1.IcoreError('UNKNOWN_COMMAND', `Unknown command: ${command}`, {
+    return new icore_error_1.IcoreError('UNKNOWN_COMMAND', `Unknown command: ${command}`, {
         command,
         positionals: [...positionals]
     });
 }
 function createUnexpectedArgumentError(argument) {
-    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+    return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
         argument
     });
 }
 function createDuplicateCommandError(command) {
-    return new errors_1.IcoreError('DUPLICATE_COMMAND', `Unexpected duplicate command '${command}'`, {
+    return new icore_error_1.IcoreError('DUPLICATE_COMMAND', `Unexpected duplicate command '${command}'`, {
         command
     });
 }

package/dist/{errors.d.ts → errors/icore-error.d.ts}

@@ -21,7 +21,9 @@ export type IcoreErrorDetails = Readonly<Record<string, unknown>>;
  * resolution, and schema configuration failures.
  */
 export declare class IcoreError extends Error {
+    /** Stable machine-readable code. */
     readonly code: IcoreErrorCode;
+    /** Structured error context. */
     readonly details: IcoreErrorDetails;
     constructor(code: IcoreErrorCode, message: string, details?: IcoreErrorDetails);
 }

package/dist/{errors.js → errors/icore-error.js}

@@ -16,7 +16,9 @@ exports.IcoreError = void 0;
  * resolution, and schema configuration failures.
  */
 class IcoreError extends Error {
+    /** Stable machine-readable code. */
     code;
+    /** Structured error context. */
     details;
     constructor(code, message, details = {}) {
         super(message);

package/dist/index.d.ts

@@ -1 +1,28 @@
-export { defineCommand, defineCommandRegistry, IcoreError, isCommandName, isPreparedCommandName, mergeOptionsSchema, parseArgv, parseOptions, parseOptionsDetailed, prepareCommandFromArgs, resolveCommand, resolveCommandFromArgs, runCommand, runPreparedCommand, runCommandFromRegistry, type BooleanOption, type CommandDefinition, type CommandContext, type CommandInput, type CommandName, type CommandPayload, type CommandRegistry, type CommandResolutionOptions, type CommandResult, type InferOptions, type InferProvidedOptions, type IcoreErrorCode, type IcoreErrorDetails, type MergeOptionsSchemas, type NumberOption, type OptionDefinition, type OptionsSchema, type ParseOptionsResult, type ParsedArgv, type PreparedCommand, type PreparedCommandInput, type RawOptionValue, type ResolvedCommand, type StringOption } from './cli';
+/**
+ * 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.
+ */
+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 { 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';
+export { isPresentationFormat, presentationFormatOptions, presentationFormats, type PresentationFormat } from './presentation/format-options';
+export { renderCsv, renderCsvRow } from './presentation/renderers/csv';
+export { renderJson } from './presentation/renderers/json';
+export { renderTextTable } from './presentation/renderers/table';
+export { isPresentationResult, renderPresentationResult } from './presentation/result-renderer';
+export { type CsvCell, type CsvRow, type CsvPresentationView, type EmptyPresentationView, type PresentationRecord, type PresentationResult, type PresentationView, type PresentationViewFactory, type RecordPresentationView, type RecordsPresentationView, type TablePresentationView, type TextPresentationView, type TextTableRow } from './presentation/view';
+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';