icore 1.0.14 → 1.0.16

package/CHANGELOG.md

@@ -13,16 +13,33 @@ conservative.
 
 ### 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
 

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,10 +192,24 @@ 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.
  */
 export declare function isCommandName<const TCommands extends readonly AnyCommandDefinition[]>(registry: CommandRegistry<TCommands>, value: unknown): value is CommandName<TCommands[number]>;
+/**
+ * Checks whether a prepared command has the given command name.
+ */
+export declare function isPreparedCommandName<TPrepared extends PreparedCommand<AnyCommandDefinition>, TName extends TPrepared['name']>(prepared: TPrepared, name: TName): prepared is Extract<TPrepared, {
+    name: TName;
+}>;
 /**
  * Resolves a command from already parsed positional arguments.
  */

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

@@ -14,16 +14,19 @@
 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;
 exports.resolveCommandFromArgs = resolveCommandFromArgs;
 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.
  */
@@ -41,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.
  */
@@ -48,6 +87,12 @@ function isCommandName(registry, value) {
     return typeof value === 'string'
         && registry.commandNames.includes(value);
 }
+/**
+ * Checks whether a prepared command has the given command name.
+ */
+function isPreparedCommandName(prepared, name) {
+    return prepared.name === name;
+}
 /**
  * Resolves a command from already parsed positional arguments.
  */
@@ -65,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.
@@ -81,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.
@@ -121,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),
@@ -136,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);
@@ -147,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,
@@ -174,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]
@@ -259,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, 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';

package/dist/index.js

@@ -1,18 +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.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, "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>;