icore 1.0.11 → 1.0.13

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable user-facing changes to this package are documented here.
+
+This file was reconstructed from npm publish metadata and local git history.
+Older releases did not have a maintained changelog, so early entries are
+intentionally conservative.
+
+## 1.0.13 - Unreleased
+
+### Added
+
+- Added machine-readable `IcoreError` codes and details.
+- 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 this changelog.
+
+### Changed
+
+- Boolean options reject explicit values such as `--flag=true` and `--flag=false`; use `--flag` and `--no-flag`.
+
+## 1.0.12 - 2026-07-02
+
+- Replaced the preliminary flag-only boolean option naming with `syntax: 'flag'`.
+- Documented flag-only boolean option behavior.
+
+## 1.0.11 - 2026-07-02
+
+- Added preliminary flag-only boolean option support.
+
+## 1.0.10 - 2026-07-02
+
+- Added two-phase command execution.
+- Added `PreparedCommandInput`.
+- Added `PreparedCommand`.
+- Added `prepareCommandFromArgs`.
+- Added `runPreparedCommand`.
+- Added command `metadata`.
+- Added command `prepare` hook.
+- Changed `runCommand` and `runCommandFromRegistry` to use the prepare-and-run flow internally.
+- Added focused tests for prepare-time validation and handler safety.
+
+## 1.0.9 - 2026-07-02
+
+- Refined npm package metadata.
+- Updated repository metadata for npm.
+- Simplified published package contents.
+
+## 1.0.8 - 2026-07-02
+
+- Updated package author metadata.
+- Normalized README heading structure.
+
+## 1.0.7 - 2026-07-02
+
+- Renamed README examples from `upper` to `uppercase`.
+- Cleaned duplicated command test coverage without changing public behavior.
+
+## 1.0.6 - 2026-07-02
+
+- 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
+
+- Rebuilt README as the main public documentation entry point.
+- Removed separate generated reference docs from the published documentation flow.
+
+## 1.0.4 - 2026-07-01
+
+- Reorganized README and documentation references.
+
+## 1.0.3 - 2026-07-01
+
+- Added README table of contents.
+- Polished README formatting and emphasis.
+
+## 1.0.2 - 2026-06-30
+
+- Clarified CLI scope and supported syntax in README.
+- Added module boundary comments to production source files.
+- Updated package description and keywords.
+
+## 1.0.1 - 2026-06-30
+
+- 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
+
+- 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.
+- Lowered the runtime Node.js engine to `>=16.9.0`.
+
+## 1.0.0-alpha - 2026-06-28
+
+- 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
+
+- Final legacy web-framework line release.
+- Added legacy tests and documentation.
+- Updated the legacy package description.
+- Trimmed legacy runtime dependencies.
+
+## 0.0.37 and earlier
+
+- Original legacy npm package line published between 2017 and 2019.
+- Legacy history is preserved for package provenance.
+- Detailed changelog entries were not maintained for these releases.

package/dist/argv.js

@@ -12,6 +12,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseArgv = parseArgv;
+const errors_1 = require("./errors");
 /**
  * Parses raw CLI arguments into positionals and raw long-option values.
  */
@@ -40,7 +41,7 @@ function parseArgv(args, schema) {
                 continue;
             }
             if (Object.hasOwn(options, alias.name)) {
-                throw new Error(`Unexpected duplicate argument '--${alias.name}'`);
+                throw createDuplicateArgumentError(alias.name);
             }
             if (alias.definition.type === 'boolean') {
                 options[alias.name] = true;
@@ -65,7 +66,7 @@ function parseArgv(args, schema) {
             ? option
             : option.slice(0, separatorIndex);
         if (name === '') {
-            throw new Error(`Unexpected argument '${arg}'`);
+            throw createUnexpectedArgumentError(arg);
         }
         const definition = schema?.[name];
         if (separatorIndex === -1 && definition === undefined && name.startsWith('no-')) {
@@ -73,14 +74,14 @@ function parseArgv(args, schema) {
             const negatedDefinition = schema?.[negatedName];
             if (negatedDefinition?.type === 'boolean') {
                 if (Object.hasOwn(options, negatedName)) {
-                    throw new Error(`Unexpected duplicate argument '--${negatedName}'`);
+                    throw createDuplicateArgumentError(negatedName);
                 }
                 options[negatedName] = false;
                 continue;
             }
         }
         if (Object.hasOwn(options, name)) {
-            throw new Error(`Unexpected duplicate argument '--${name}'`);
+            throw createDuplicateArgumentError(name);
         }
         if (separatorIndex !== -1) {
             options[name] = option.slice(separatorIndex + 1);
@@ -120,7 +121,7 @@ function buildShortAliasMap(schema) {
         }
         assertShortAlias(name, definition.alias);
         if (aliases.has(definition.alias)) {
-            throw new Error(`Unexpected duplicate alias '-${definition.alias}'`);
+            throw createDuplicateAliasError(definition.alias);
         }
         aliases.set(definition.alias, {
             name,
@@ -133,8 +134,32 @@ function assertShortAlias(name, alias) {
     if (/^[A-Za-z]$/.test(alias)) {
         return;
     }
-    throw new Error(`Expected alias for '--${name}' as single ASCII letter`);
+    throw createInvalidOptionAliasError(name, alias);
 }
 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}'`, {
+        argument: `--${name}`,
+        option: name
+    });
+}
+function createUnexpectedArgumentError(argument) {
+    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+        argument
+    });
+}
+function createDuplicateAliasError(alias) {
+    return new errors_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`, {
+        argument: `--${name}`,
+        option: name,
+        alias
+    });
+}

package/dist/cli.d.ts

@@ -9,5 +9,6 @@
  * This file must not contain parser, validator, or command runtime logic.
  */
 export { parseArgv, type ParsedArgv } from './argv';
-export { defineCommand, defineCommandRegistry, isCommandName, prepareCommandFromArgs, resolveCommand, resolveCommandFromArgs, runCommand, runPreparedCommand, runCommandFromRegistry, type CommandDefinition, type CommandInput, type CommandName, type CommandRegistry, type PreparedCommand, type PreparedCommandInput, type ResolvedCommand } from './commands';
+export { defineCommand, defineCommandRegistry, isCommandName, prepareCommandFromArgs, resolveCommand, resolveCommandFromArgs, runCommand, runPreparedCommand, runCommandFromRegistry, type CommandDefinition, type CommandInput, type CommandName, type CommandRegistry, type CommandResolutionOptions, type PreparedCommand, type PreparedCommandInput, type ResolvedCommand } from './commands';
+export { IcoreError, type IcoreErrorCode, type IcoreErrorDetails } from './errors';
 export { mergeOptionsSchema, parseOptions, parseOptionsDetailed, type BooleanOption, type InferOptions, type InferProvidedOptions, type MergeOptionsSchemas, type NumberOption, type OptionDefinition, type OptionsSchema, type ParseOptionsResult, type RawOptionValue, type StringOption } from './options';

package/dist/cli.js

@@ -10,7 +10,7 @@
  * This file must not contain parser, validator, or command runtime logic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOptionsDetailed = exports.parseOptions = exports.mergeOptionsSchema = exports.runCommandFromRegistry = exports.runPreparedCommand = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.prepareCommandFromArgs = exports.isCommandName = exports.defineCommandRegistry = exports.defineCommand = exports.parseArgv = void 0;
+exports.parseOptionsDetailed = exports.parseOptions = exports.mergeOptionsSchema = exports.IcoreError = exports.runCommandFromRegistry = exports.runPreparedCommand = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.prepareCommandFromArgs = exports.isCommandName = exports.defineCommandRegistry = exports.defineCommand = exports.parseArgv = void 0;
 var argv_1 = require("./argv");
 Object.defineProperty(exports, "parseArgv", { enumerable: true, get: function () { return argv_1.parseArgv; } });
 var commands_1 = require("./commands");
@@ -23,6 +23,8 @@ Object.defineProperty(exports, "resolveCommandFromArgs", { enumerable: true, get
 Object.defineProperty(exports, "runCommand", { enumerable: true, get: function () { return commands_1.runCommand; } });
 Object.defineProperty(exports, "runPreparedCommand", { enumerable: true, get: function () { return commands_1.runPreparedCommand; } });
 Object.defineProperty(exports, "runCommandFromRegistry", { enumerable: true, get: function () { return commands_1.runCommandFromRegistry; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "IcoreError", { enumerable: true, get: function () { return errors_1.IcoreError; } });
 var options_1 = require("./options");
 Object.defineProperty(exports, "mergeOptionsSchema", { enumerable: true, get: function () { return options_1.mergeOptionsSchema; } });
 Object.defineProperty(exports, "parseOptions", { enumerable: true, get: function () { return options_1.parseOptions; } });

package/dist/commands.d.ts

@@ -23,9 +23,15 @@ export type PreparedCommandInput<TSchema extends OptionsSchema> = {
 /**
  * Input passed to a command handler after command path and option validation.
  */
-export type CommandInput<TSchema extends OptionsSchema, TContext> = PreparedCommandInput<TSchema> & {
+export type CommandInput<TSchema extends OptionsSchema, TContext, TPayload = void> = PreparedCommandInput<TSchema> & {
     context: TContext;
-};
+} & ([
+    TPayload
+] extends [void] ? {
+    payload?: TPayload;
+} : {
+    payload: TPayload;
+});
 /**
  * Declarative command contract.
  *
@@ -33,22 +39,49 @@ export type CommandInput<TSchema extends OptionsSchema, TContext> = PreparedComm
  * application-specific work such as API calls, request building, and output
  * formatting.
  */
-export type CommandDefinition<TSchema extends OptionsSchema, TContext, TResult, TPath extends readonly [string, ...string[]] = readonly [string, ...string[]], TMetadata = unknown> = {
+export type CommandDefinition<TSchema extends OptionsSchema, TContext, TResult, TPath extends readonly [string, ...string[]] = readonly [string, ...string[]], TMetadata = unknown, TPayload = void> = {
     path: TPath;
     options: TSchema;
     metadata?: TMetadata;
     allowExtraPositionals?: boolean;
-    prepare?(input: PreparedCommandInput<TSchema>): void | Promise<void>;
-    handle(input: CommandInput<TSchema, TContext>): TResult | Promise<TResult>;
+    prepare?(input: PreparedCommandInput<TSchema>): TPayload | Promise<TPayload>;
+    handle(input: CommandInput<TSchema, TContext, TPayload>): TResult | Promise<TResult>;
+};
+type AnyCommandInput = PreparedCommandInput<OptionsSchema> & {
+    context: unknown;
+    payload?: unknown;
+};
+type AnyCommandDefinition = {
+    path: readonly [string, ...string[]];
+    options: OptionsSchema;
+    metadata?: unknown;
+    allowExtraPositionals?: boolean;
+    prepare?(input: PreparedCommandInput<OptionsSchema>): unknown | Promise<unknown>;
+    handle(input: AnyCommandInput): unknown | Promise<unknown>;
 };
-type AnyCommandDefinition = CommandDefinition<OptionsSchema, unknown, unknown, readonly [string, ...string[]], unknown>;
 type CommandPathName<TPath extends readonly string[]> = number extends TPath['length'] ? string : TPath extends readonly [infer THead extends string] ? THead : TPath extends readonly [
     infer THead extends string,
     ...infer TRest extends readonly string[]
 ] ? `${THead} ${CommandPathName<TRest>}` : never;
-type CommandContext<TCommand extends AnyCommandDefinition> = TCommand extends CommandDefinition<OptionsSchema, infer TContext, unknown> ? TContext : never;
-type CommandResult<TCommand extends AnyCommandDefinition> = TCommand extends CommandDefinition<OptionsSchema, unknown, infer TResult> ? Awaited<TResult> : never;
-type CommandSchema<TCommand extends AnyCommandDefinition> = TCommand extends CommandDefinition<infer TSchema, unknown, unknown> ? TSchema : never;
+type CommandDefinitionParts<TCommand extends AnyCommandDefinition> = TCommand extends CommandDefinition<infer TSchema, infer TContext, infer TResult, infer TPath, infer TMetadata, infer TPayload> ? {
+    schema: TSchema;
+    context: TContext;
+    result: TResult;
+    path: TPath;
+    metadata: TMetadata;
+    payload: TPayload;
+} : {
+    schema: TCommand['options'];
+    context: unknown;
+    result: unknown;
+    path: TCommand['path'];
+    metadata: TCommand['metadata'];
+    payload: unknown;
+};
+type CommandContext<TCommand extends AnyCommandDefinition> = CommandDefinitionParts<TCommand>['context'];
+type CommandResult<TCommand extends AnyCommandDefinition> = Awaited<CommandDefinitionParts<TCommand>['result']>;
+type CommandSchema<TCommand extends AnyCommandDefinition> = CommandDefinitionParts<TCommand>['schema'];
+type CommandPayload<TCommand extends AnyCommandDefinition> = CommandDefinitionParts<TCommand>['payload'];
 /**
  * Infers the public command name from a command path.
  */
@@ -60,6 +93,17 @@ export type CommandRegistry<TCommands extends readonly AnyCommandDefinition[]> =
     commands: TCommands;
     commandNames: readonly CommandName<TCommands[number]>[];
 };
+/**
+ * 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.
+     */
+    strict?: boolean;
+};
 /**
  * Result of resolving a command from user positionals.
  */
@@ -79,11 +123,12 @@ export type PreparedCommand<TCommand extends AnyCommandDefinition> = {
     options: InferOptions<CommandSchema<TCommand>>;
     provided: InferProvidedOptions<CommandSchema<TCommand>>;
     positionals: string[];
+    payload: CommandPayload<TCommand>;
 };
 /**
  * Defines a command while preserving literal option schema types.
  */
-export declare function defineCommand<const TSchema extends OptionsSchema, const TPath extends readonly [string, ...string[]], TContext = undefined, TResult = unknown, TMetadata = unknown>(command: CommandDefinition<TSchema, TContext, TResult, TPath, TMetadata>): CommandDefinition<TSchema, TContext, TResult, TPath, TMetadata>;
+export declare function defineCommand<const TSchema extends OptionsSchema, const TPath extends readonly [string, ...string[]], TContext = undefined, TResult = unknown, TMetadata = unknown, TPayload = void>(command: CommandDefinition<TSchema, TContext, TResult, TPath, TMetadata, TPayload>): CommandDefinition<TSchema, TContext, TResult, TPath, TMetadata, TPayload>;
 /**
  * Defines a command registry while preserving literal command path types.
  */
@@ -103,7 +148,7 @@ export declare function resolveCommandFromArgs<const TCommands extends readonly
 /**
  * Resolves and validates a command without requiring runtime context.
  */
-export declare function prepareCommandFromArgs<const TCommands extends readonly AnyCommandDefinition[]>(registry: CommandRegistry<TCommands>, args: readonly string[]): Promise<PreparedCommand<TCommands[number]>>;
+export declare function prepareCommandFromArgs<const TCommands extends readonly AnyCommandDefinition[]>(registry: CommandRegistry<TCommands>, args: readonly string[], options?: CommandResolutionOptions): Promise<PreparedCommand<TCommands[number]>>;
 /**
  * Runs a prepared command with caller-provided runtime context.
  */
@@ -111,10 +156,10 @@ export declare function runPreparedCommand<TCommand extends AnyCommandDefinition
 /**
  * Resolves a command from a registry and runs its handler.
  */
-export declare function runCommandFromRegistry<const TCommands extends readonly AnyCommandDefinition[]>(registry: CommandRegistry<TCommands>, args: readonly string[], context: CommandContext<TCommands[number]>): Promise<CommandResult<TCommands[number]>>;
+export declare function runCommandFromRegistry<const TCommands extends readonly AnyCommandDefinition[]>(registry: CommandRegistry<TCommands>, args: readonly string[], context: CommandContext<TCommands[number]>, options?: CommandResolutionOptions): Promise<CommandResult<TCommands[number]>>;
 /**
  * Parses arguments, validates command mechanics, and executes a command
  * handler.
  */
-export declare function runCommand<const TSchema extends OptionsSchema, TContext, TResult>(command: CommandDefinition<TSchema, TContext, TResult>, args: readonly string[], context: TContext): Promise<TResult>;
+export declare function runCommand<const TSchema extends OptionsSchema, TContext, TResult, const TPath extends readonly [string, ...string[]] = readonly [string, ...string[]], TMetadata = unknown, TPayload = void>(command: CommandDefinition<TSchema, TContext, TResult, TPath, TMetadata, TPayload>, args: readonly string[], context: TContext, options?: CommandResolutionOptions): Promise<TResult>;
 export {};

package/dist/commands.js

@@ -22,6 +22,7 @@ exports.runPreparedCommand = runPreparedCommand;
 exports.runCommandFromRegistry = runCommandFromRegistry;
 exports.runCommand = runCommand;
 const argv_1 = require("./argv");
+const errors_1 = require("./errors");
 const options_1 = require("./options");
 /**
  * Defines a command while preserving literal option schema types.
@@ -57,7 +58,7 @@ function resolveCommand(registry, positionals) {
             return resolved;
         }
     }
-    throw new Error(`Unknown command: ${formatCommandPositionals(positionals)}`);
+    throw createUnknownCommandError(positionals);
 }
 /**
  * Resolves a command from raw CLI arguments using each command's option schema.
@@ -70,12 +71,15 @@ function resolveCommandFromArgs(registry, args) {
             return resolved;
         }
     }
-    throw new Error(`Unknown command: ${formatCommandPositionals((0, argv_1.parseArgv)(args).positionals)}`);
+    throw createUnknownCommandError((0, argv_1.parseArgv)(args).positionals);
 }
 /**
  * Resolves and validates a command without requiring runtime context.
  */
-async function prepareCommandFromArgs(registry, args) {
+async function prepareCommandFromArgs(registry, args, options = {}) {
+    if (options.strict === true) {
+        return prepareCommandFromArgsStrict(registry, args);
+    }
     for (const command of commandsBySpecificity(registry.commands)) {
         const argv = (0, argv_1.parseArgv)(args, command.options);
         const resolved = resolveCommandCandidate(command, argv.positionals);
@@ -83,7 +87,7 @@ async function prepareCommandFromArgs(registry, args) {
             return prepareResolvedCommand(resolved, argv.options);
         }
     }
-    throw new Error(`Unknown command: ${formatCommandPositionals((0, argv_1.parseArgv)(args).positionals)}`);
+    throw createUnknownCommandError((0, argv_1.parseArgv)(args).positionals);
 }
 /**
  * Runs a prepared command with caller-provided runtime context.
@@ -93,26 +97,30 @@ async function runPreparedCommand(prepared, context) {
         options: prepared.options,
         provided: prepared.provided,
         positionals: prepared.positionals,
-        context
+        context,
+        payload: prepared.payload
     });
     return result;
 }
 /**
  * Resolves a command from a registry and runs its handler.
  */
-async function runCommandFromRegistry(registry, args, context) {
-    const prepared = await prepareCommandFromArgs(registry, args);
+async function runCommandFromRegistry(registry, args, context, options = {}) {
+    const prepared = await prepareCommandFromArgs(registry, args, options);
     return runPreparedCommand(prepared, context);
 }
 /**
  * Parses arguments, validates command mechanics, and executes a command
  * handler.
  */
-async function runCommand(command, args, context) {
-    const prepared = await prepareCommand(command, args);
+async function runCommand(command, args, context, options = {}) {
+    const prepared = await prepareCommand(command, args, options);
     return runPreparedCommand(prepared, context);
 }
-async function prepareCommand(command, args) {
+async function prepareCommand(command, args, options = {}) {
+    if (options.strict === true) {
+        assertNoOptionBeforeCommand(args);
+    }
     const argv = (0, argv_1.parseArgv)(args, command.options);
     const extraPositionals = resolveCommandPositionals(command.path, argv.positionals);
     const resolved = {
@@ -123,10 +131,27 @@ async function prepareCommand(command, args) {
     };
     return prepareResolvedCommand(resolved, argv.options);
 }
+async function prepareCommandFromArgsStrict(registry, args) {
+    const command = findStrictCommand(registry, args);
+    if (command === undefined) {
+        throw createUnknownCommandError(commandPositionalsBeforeOptions(args));
+    }
+    const argv = (0, argv_1.parseArgv)(args, command.options);
+    const resolved = resolveCommandCandidate(command, argv.positionals);
+    if (resolved === undefined) {
+        throw createUnknownCommandError(argv.positionals);
+    }
+    return prepareResolvedCommand(resolved, argv.options);
+}
 async function prepareResolvedCommand(resolved, rawOptions) {
     const { command } = resolved;
     if (resolved.positionals.length > 0 && command.allowExtraPositionals !== true) {
-        throw new Error(`Unexpected positional argument for '${command.path.join(' ')}': ${resolved.positionals[0] ?? ''}`);
+        const positional = resolved.positionals[0] ?? '';
+        throw new errors_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 input = {
@@ -134,20 +159,26 @@ async function prepareResolvedCommand(resolved, rawOptions) {
         provided: parsed.provided,
         positionals: resolved.positionals
     };
-    await command.prepare?.(input);
+    const payload = await command.prepare?.(input);
     return {
         name: resolved.name,
         path: resolved.path,
         command,
         options: parsed.options,
         provided: parsed.provided,
-        positionals: resolved.positionals
+        positionals: resolved.positionals,
+        payload
     };
 }
 function resolveCommandPositionals(path, positionals) {
     for (let index = 0; index < path.length; index += 1) {
         if (positionals[index] !== path[index]) {
-            throw new Error(`Expected command '${path.join(' ')}'`);
+            const command = path.join(' ');
+            throw new errors_1.IcoreError('UNKNOWN_COMMAND', `Expected command '${command}'`, {
+                command,
+                path: [...path],
+                positionals: [...positionals]
+            });
         }
     }
     return positionals.slice(path.length);
@@ -159,7 +190,7 @@ function assertNoDuplicateCommandNames(commandNames) {
     const seen = new Set();
     for (const name of commandNames) {
         if (seen.has(name)) {
-            throw new Error(`Unexpected duplicate command '${name}'`);
+            throw createDuplicateCommandError(name);
         }
         seen.add(name);
     }
@@ -167,6 +198,21 @@ function assertNoDuplicateCommandNames(commandNames) {
 function commandsBySpecificity(commands) {
     return [...commands].sort((left, right) => right.path.length - left.path.length);
 }
+function findStrictCommand(registry, args) {
+    assertNoOptionBeforeCommand(args);
+    for (const command of commandsBySpecificity(registry.commands)) {
+        if (commandPathMatchesArgs(command.path, args)) {
+            return command;
+        }
+    }
+    return undefined;
+}
+function assertNoOptionBeforeCommand(args) {
+    const firstArg = args[0];
+    if (firstArg !== undefined && isOptionBeforeCommand(firstArg)) {
+        throw createUnexpectedArgumentError(firstArg);
+    }
+}
 function resolveCommandCandidate(command, positionals) {
     const extraPositionals = resolveMatchingCommandPositionals(command.path, positionals);
     if (extraPositionals === undefined) {
@@ -190,3 +236,41 @@ function resolveMatchingCommandPositionals(path, positionals) {
 function formatCommandPositionals(positionals) {
     return positionals.length === 0 ? '<empty>' : positionals.join(' ');
 }
+function commandPathMatchesArgs(path, args) {
+    for (let index = 0; index < path.length; index += 1) {
+        if (args[index] !== path[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+function commandPositionalsBeforeOptions(args) {
+    const positionals = [];
+    for (const arg of args) {
+        if (isOptionBeforeCommand(arg)) {
+            break;
+        }
+        positionals.push(arg);
+    }
+    return positionals;
+}
+function isOptionBeforeCommand(arg) {
+    return arg !== '-' && arg.startsWith('-');
+}
+function createUnknownCommandError(positionals) {
+    const command = formatCommandPositionals(positionals);
+    return new errors_1.IcoreError('UNKNOWN_COMMAND', `Unknown command: ${command}`, {
+        command,
+        positionals: [...positionals]
+    });
+}
+function createUnexpectedArgumentError(argument) {
+    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+        argument
+    });
+}
+function createDuplicateCommandError(command) {
+    return new errors_1.IcoreError('DUPLICATE_COMMAND', `Unexpected duplicate command '${command}'`, {
+        command
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The error module defines machine-readable errors emitted by CLI mechanics.
+ *
+ * Allowed here:
+ * - defining stable error codes;
+ * - preserving human-readable messages on Error instances;
+ * - carrying structured details for application-level handling;
+ *
+ * This file must not contain parser, validator, or command resolution logic.
+ */
+/**
+ * Stable machine-readable error code for `icore` CLI mechanics errors.
+ */
+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>>;
+/**
+ * Error thrown by `icore` for CLI parsing, option validation, command
+ * resolution, and schema configuration failures.
+ */
+export declare class IcoreError extends Error {
+    readonly code: IcoreErrorCode;
+    readonly details: IcoreErrorDetails;
+    constructor(code: IcoreErrorCode, message: string, details?: IcoreErrorDetails);
+}

package/dist/errors.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * The error module defines machine-readable errors emitted by CLI mechanics.
+ *
+ * Allowed here:
+ * - defining stable error codes;
+ * - preserving human-readable messages on Error instances;
+ * - carrying structured details for application-level handling;
+ *
+ * This file must not contain parser, validator, or command resolution logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IcoreError = void 0;
+/**
+ * Error thrown by `icore` for CLI parsing, option validation, command
+ * resolution, and schema configuration failures.
+ */
+class IcoreError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'IcoreError';
+        this.code = code;
+        this.details = details;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.IcoreError = IcoreError;

package/dist/index.d.ts

@@ -1 +1 @@
-export { defineCommand, defineCommandRegistry, isCommandName, mergeOptionsSchema, parseArgv, parseOptions, parseOptionsDetailed, prepareCommandFromArgs, resolveCommand, resolveCommandFromArgs, runCommand, runPreparedCommand, runCommandFromRegistry, type BooleanOption, type CommandDefinition, type CommandInput, type CommandName, type CommandRegistry, type InferOptions, type InferProvidedOptions, type MergeOptionsSchemas, type NumberOption, type OptionDefinition, type OptionsSchema, type ParseOptionsResult, type ParsedArgv, type PreparedCommand, type PreparedCommandInput, type RawOptionValue, type ResolvedCommand, type StringOption } from './cli';
+export { defineCommand, defineCommandRegistry, IcoreError, isCommandName, mergeOptionsSchema, parseArgv, parseOptions, parseOptionsDetailed, prepareCommandFromArgs, resolveCommand, resolveCommandFromArgs, runCommand, runPreparedCommand, runCommandFromRegistry, type BooleanOption, type CommandDefinition, type CommandInput, type CommandName, type CommandRegistry, type CommandResolutionOptions, 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';

package/dist/index.js

@@ -1,9 +1,10 @@
 "use strict";
 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.defineCommandRegistry = exports.defineCommand = void 0;
+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; } });

package/dist/options.d.ts

@@ -35,11 +35,11 @@ export type StringOption<TChoices extends readonly string[] = readonly string[]>
 /**
  * Declarative boolean flag contract.
  *
- * Boolean options accept flag form and explicit `true` / `false` values unless
- * `flagOnly` is enabled.
+ * Boolean options accept flag form and schema-known negation unless flag
+ * syntax is enforced.
  */
 export type BooleanOption = OptionBase<'boolean', boolean> & {
-    flagOnly?: boolean;
+    syntax?: 'flag';
 };
 /**
  * Declarative number option contract.

package/dist/options.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mergeOptionsSchema = mergeOptionsSchema;
 exports.parseOptions = parseOptions;
 exports.parseOptionsDetailed = parseOptionsDetailed;
+const errors_1 = require("./errors");
 /**
  * Merges option schemas while preserving literal option definition types.
  *
@@ -38,7 +39,7 @@ function parseOptionsDetailed(schema, values) {
     const provided = {};
     for (const name of Object.keys(values)) {
         if (!Object.hasOwn(schema, name)) {
-            throw new Error(`Unexpected argument '--${name}'`);
+            throw createUnexpectedArgumentError(name);
         }
     }
     for (const name of Object.keys(schema)) {
@@ -54,7 +55,7 @@ function parseOptionsDetailed(schema, values) {
                 continue;
             }
             if (definition.required === true) {
-                throw new Error(`Expected required argument '--${String(name)}'`);
+                throw createExpectedRequiredArgumentError(String(name));
             }
             parsed[name] = undefined;
             continue;
@@ -79,74 +80,157 @@ function parseDefaultOptionValue(name, definition) {
     const value = definition.default;
     if (definition.type === 'string') {
         if (typeof value !== 'string' || value.trim() === '') {
-            throw new Error(`Expected default for '--${name}' as string`);
+            throw createExpectedDefaultError(name, 'string', value);
         }
-        assertChoice(name, definition.choices, value);
+        assertChoice(name, definition.choices, value, 'default');
         return value;
     }
     if (definition.type === 'boolean') {
         if (typeof value !== 'boolean') {
-            throw new Error(`Expected default for '--${name}' as boolean`);
+            throw createExpectedDefaultError(name, 'boolean', value);
         }
         return value;
     }
     if (typeof value !== 'number' || !Number.isFinite(value)) {
-        throw new Error(`Expected default for '--${name}' as number`);
+        throw createExpectedDefaultError(name, 'number', value);
     }
-    validateNumberConstraints(name, definition, value);
+    validateNumberConstraints(name, definition, value, 'default');
     return value;
 }
 function parseStringOption(name, definition, value) {
     if (typeof value !== 'string' || value.trim() === '') {
-        throw new Error(`Expected '--${name}' as string`);
+        throw createExpectedOptionTypeError(name, 'string', value);
     }
     assertChoice(name, definition.choices, value);
     return value;
 }
 function parseBooleanOption(name, definition, value) {
-    if (definition.flagOnly === true) {
+    if (definition.syntax === 'flag') {
         if (value === true) {
             return true;
         }
-        throw new Error(`Expected '--${name}' as boolean flag`);
+        throw createExpectedOptionTypeError(name, 'boolean flag', value);
     }
-    if (value === true || value === 'true') {
+    if (value === true) {
         return true;
     }
-    if (value === false || value === 'false') {
+    if (value === false) {
         return false;
     }
-    throw new Error(`Expected '--${name}' as boolean flag`);
+    throw createExpectedOptionTypeError(name, 'boolean flag', value);
 }
 function parseNumberOption(name, definition, value) {
     if (typeof value !== 'string' || value.trim() === '') {
-        throw new Error(`Expected '--${name}' as number`);
+        throw createExpectedOptionTypeError(name, 'number', value);
     }
     if (!/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
-        throw new Error(`Expected '--${name}' as number`);
+        throw createExpectedOptionTypeError(name, 'number', value);
     }
     const parsed = Number(value);
     if (!Number.isFinite(parsed)) {
-        throw new Error(`Expected '--${name}' as number`);
+        throw createExpectedOptionTypeError(name, 'number', value);
     }
     validateNumberConstraints(name, definition, parsed);
     return parsed;
 }
-function validateNumberConstraints(name, definition, parsed) {
+function validateNumberConstraints(name, definition, parsed, source = 'value') {
     if (definition.integer === true && !Number.isInteger(parsed)) {
-        throw new Error(`Expected '--${name}' as integer`);
+        if (source === 'default') {
+            throw createInvalidOptionDefaultError(name, `Expected '--${name}' as integer`, {
+                expected: 'integer',
+                value: parsed
+            });
+        }
+        throw createExpectedOptionTypeError(name, 'integer', parsed);
     }
     if (definition.min !== undefined && parsed < definition.min) {
-        throw new Error(`Expected '--${name}' to be greater than or equal to ${String(definition.min)}`);
+        const message = `Expected '--${name}' to be greater than or equal to ${String(definition.min)}`;
+        if (source === 'default') {
+            throw createInvalidOptionDefaultError(name, message, {
+                expected: 'minimum',
+                min: definition.min,
+                value: parsed
+            });
+        }
+        throw createInvalidOptionTypeError(name, message, {
+            expected: 'minimum',
+            min: definition.min,
+            value: parsed
+        });
     }
     if (definition.max !== undefined && parsed > definition.max) {
-        throw new Error(`Expected '--${name}' to be less than or equal to ${String(definition.max)}`);
+        const message = `Expected '--${name}' to be less than or equal to ${String(definition.max)}`;
+        if (source === 'default') {
+            throw createInvalidOptionDefaultError(name, message, {
+                expected: 'maximum',
+                max: definition.max,
+                value: parsed
+            });
+        }
+        throw createInvalidOptionTypeError(name, message, {
+            expected: 'maximum',
+            max: definition.max,
+            value: parsed
+        });
     }
-    assertChoice(name, definition.choices, parsed);
+    assertChoice(name, definition.choices, parsed, source);
 }
-function assertChoice(name, choices, value) {
+function assertChoice(name, choices, value, source = 'value') {
     if (choices === undefined || choices.includes(value)) {
         return;
     }
-    throw new Error(`Expected '--${name}' as one of: ${choices.join(', ')}`);
+    const message = `Expected '--${name}' as one of: ${choices.join(', ')}`;
+    if (source === 'default') {
+        throw createInvalidOptionDefaultError(name, message, {
+            choices: [...choices],
+            value
+        });
+    }
+    throw createInvalidOptionChoiceError(name, choices, value, message);
+}
+function createUnexpectedArgumentError(name) {
+    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
+        argument: `--${name}`,
+        option: name
+    });
+}
+function createExpectedRequiredArgumentError(name) {
+    return new errors_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
+        argument: `--${name}`,
+        option: name
+    });
+}
+function createExpectedOptionTypeError(name, expected, value) {
+    return createInvalidOptionTypeError(name, `Expected '--${name}' as ${expected}`, {
+        expected,
+        value
+    });
+}
+function createExpectedDefaultError(name, expected, value) {
+    return createInvalidOptionDefaultError(name, `Expected default for '--${name}' as ${expected}`, {
+        expected,
+        value
+    });
+}
+function createInvalidOptionTypeError(name, message, details) {
+    return new errors_1.IcoreError('INVALID_OPTION_TYPE', message, {
+        argument: `--${name}`,
+        option: name,
+        ...details
+    });
+}
+function createInvalidOptionChoiceError(name, choices, value, message) {
+    return new errors_1.IcoreError('INVALID_OPTION_CHOICE', message, {
+        argument: `--${name}`,
+        option: name,
+        choices: [...choices],
+        value
+    });
+}
+function createInvalidOptionDefaultError(name, message, details) {
+    return new errors_1.IcoreError('INVALID_OPTION_DEFAULT', message, {
+        argument: `--${name}`,
+        option: name,
+        ...details
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icore",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Declarative command line interface mechanics for Node.js",
   "keywords": [
     "command-line",

package/readme.md

@@ -10,7 +10,7 @@ Small dependency-free command line interface mechanics for [Node.js®](https://n
 Supports a practical GNU-style option syntax:
 
 - long options: `--name value`, `--name=value`;
-- boolean flags: `--flag`, `--flag=true`, `--flag=false`, `--no-flag` by default;
+- boolean flags: `--flag`, `--no-flag`;
 - short aliases: `-f`, `-n value`;
 - option terminator: `--`.
 
@@ -34,9 +34,10 @@ npm install icore
   - [`isCommandName(registry, value)`](#iscommandnameregistry-value)
   - [`resolveCommand(registry, positionals)`](#resolvecommandregistry-positionals)
   - [`resolveCommandFromArgs(registry, args)`](#resolvecommandfromargsregistry-args)
-  - [`runCommandFromRegistry(registry, args, context)`](#runcommandfromregistryregistry-args-context)
+  - [`prepareCommandFromArgs(registry, args, options?)`](#preparecommandfromargsregistry-args-options)
+  - [`runCommandFromRegistry(registry, args, context, options?)`](#runcommandfromregistryregistry-args-context-options)
   - [`mergeOptionsSchema(...schemas)`](#mergeoptionsschemaschemas)
-  - [`runCommand(command, args, context)`](#runcommandcommand-args-context)
+  - [`runCommand(command, args, context, options?)`](#runcommandcommand-args-context-options)
 - [How It Works](#how-it-works)
 - [Example](#example)
 - [Option Schemas](#option-schemas)
@@ -278,7 +279,71 @@ const resolved = resolveCommandFromArgs(registry, [
 ]);
 ```
 
-### `runCommandFromRegistry(registry, args, context)`
+`resolveCommandFromArgs` keeps legacy option-anywhere command resolution. Use
+`prepareCommandFromArgs(..., { strict: true })` when command path diagnostics
+should reject options before the command path.
+
+### `prepareCommandFromArgs(registry, args, options?)`
+
+Resolves and validates a command without requiring runtime context or calling
+the command handler.
+
+```ts
+const prepared = await prepareCommandFromArgs(
+  registry,
+  ['hello', '--name', 'Alice', '--uppercase'],
+  {
+    strict: true
+  }
+);
+```
+
+A command `prepare` hook can return a typed payload. The payload is available
+on the prepared command before runtime context is created, then passed to the
+handler:
+
+```ts
+const helloCommand = defineCommand({
+  path: ['hello'],
+  options: {
+    name: {
+      type: 'string',
+      required: true
+    }
+  },
+  prepare({ options }) {
+    return {
+      normalizedName: options.name.trim().toLowerCase()
+    };
+  },
+  handle({ payload, context }) {
+    return context.greeter.greet(payload.normalizedName);
+  }
+});
+
+const prepared = await prepareCommandFromArgs(registry, [
+  'hello',
+  '--name',
+  ' Alice '
+]);
+
+prepared.payload.normalizedName;
+```
+
+Use payload for derived CLI data. Runtime resources such as databases, sockets,
+or SDK clients should still be created outside `icore` and passed as `context`.
+
+With `strict: true`, the command path must appear before options:
+
+```console
+$ node cli.js --unknown hello
+Unexpected argument '--unknown'
+```
+
+Without strict mode, legacy candidate-schema resolution is preserved for
+backward compatibility.
+
+### `runCommandFromRegistry(registry, args, context, options?)`
 
 Resolves a command from a registry and runs its handler.
 
@@ -286,7 +351,10 @@ Resolves a command from a registry and runs its handler.
 const output = await runCommandFromRegistry(
   registry,
   ['hello', '--name', 'Alice', '--uppercase'],
-  context
+  context,
+  {
+    strict: true
+  }
 );
 ```
 
@@ -317,7 +385,7 @@ const greetingOptions = {
 const options = mergeOptionsSchema(nameOptions, greetingOptions);
 ```
 
-### `runCommand(command, args, context)`
+### `runCommand(command, args, context, options?)`
 
 Parses arguments, validates options, checks command positionals, and runs the
 handler.
@@ -326,13 +394,19 @@ handler.
 const output = await runCommand(
   command,
   ['hello', '--name', 'Alice', '--uppercase'],
-  context
+  context,
+  {
+    strict: true
+  }
 );
 ```
 
 **By default**, extra positionals are rejected. A command can opt in to extra
 positionals with `allowExtraPositionals: true`.
 
+With `strict: true`, direct command execution also requires the command path to
+appear before options.
+
 ## How It Works
 
 ![yuml diagram](http://yuml.me/diagram/scruffy;dir:LR;/class/[*argv*%20{bg:gray}|External;hello%20--name%20Alice%20--uppercase]->[*matches*%20{bg:lavender}|System;parse,%20resolve,%20validate,%20infer]->[*typed%20result*%20{bg:honeydew}|Container;command=hello;%20name=Alice;%20uppercase=true]->[*your%20app*%20{bg:cornsilk}|System;business%20logic%20and%20output])
@@ -378,7 +452,7 @@ HELLO, ALICE!
 ```
 
 The command handler receives parsed options, user-provided option metadata,
-remaining positionals, and caller provided context.
+remaining positionals, prepared payload, and caller provided context.
 
 ## Option Schemas
 
@@ -435,19 +509,18 @@ const schema = {
 } as const;
 ```
 
-Boolean options accept **flag form**, explicit `true` / `false` values, and
-schema-known negation:
+Boolean options accept **flag form** and schema-known negation:
 
 ```sh
 --uppercase
---uppercase=true
---uppercase=false
 --no-uppercase
 ```
 
-Invalid explicit values are rejected:
+Explicit values are rejected:
 
 ```sh
+--uppercase=true
+--uppercase=false
 --uppercase=yes
 --uppercase=
 ```
@@ -455,20 +528,20 @@ Invalid explicit values are rejected:
 `--uppercase false` keeps `--uppercase` as `true` and leaves `false` as a positional
 argument.
 
-Use `flagOnly: true` when a boolean option should accept only flag form:
+Use `syntax: 'flag'` when a boolean option should accept only flag form:
 
 ```ts
 const schema = {
   uppercase: {
     type: 'boolean',
     default: false,
-    flagOnly: true
+    syntax: 'flag'
   }
 } as const;
 ```
 
-With `flagOnly: true`, `--uppercase` is accepted, while `--uppercase=true`,
-`--uppercase=false`, and `--no-uppercase` are rejected.
+With `syntax: 'flag'`, `--uppercase` is accepted, while `--uppercase=value`
+and `--no-uppercase` are rejected.
 
 ### `type: 'number'`
 
@@ -567,15 +640,51 @@ Attached short values such as `-nvalue` and grouped short booleans such as
 compatibility.
 
 Negated syntax such as `--no-cache` is interpreted as `cache: false` when
-`cache` is a known boolean option without `flagOnly: true`. Unknown negated
+`cache` is a known boolean option without `syntax: 'flag'`. Unknown negated
 options, negation for string or number options, and negation for flag-only
 boolean options are rejected.
 
 ## Error Messages
 
-`icore` throws regular `Error` objects with predictable user-facing messages.
-Applications should treat these messages as **display text**, not as a
-**machine-readable API**.
+`icore` throws `IcoreError` objects for CLI parsing, option validation, and
+command resolution failures. `IcoreError` extends the regular `Error` class and
+adds a stable machine-readable `code` plus structured `details`.
+
+Applications should treat `error.message` as **display text**. Use `error.code`
+for machine-readable handling:
+
+```ts
+import { IcoreError } from 'icore';
+
+try {
+  await main(args);
+} catch (error) {
+  if (error instanceof IcoreError && error.code === 'UNKNOWN_COMMAND') {
+    printHelp();
+    process.exitCode = 2;
+    return;
+  }
+
+  throw error;
+}
+```
+
+Supported error codes:
+
+```ts
+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';
+```
 
 Applications can catch these errors and decide how to print them. For example,
 after printing `error.message`, terminal output can look like this:
@@ -591,6 +700,9 @@ $ node cli.js hello --name=
 Expected '--name' as string
 ```
 
+Errors thrown by command `prepare` and `handle` functions are application errors
+and pass through unchanged.
+
 ## Project Boundary
 
 `icore` is intended to be a **small CLI mechanics module**. It should **not**