icore 1.0.19 → 2.0.1

package/CHANGELOG.md

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

package/dist/argv/parser.js

@@ -18,7 +18,7 @@ const icore_error_1 = require("../errors/icore-error");
  */
 function parseArgv(args, schema) {
     const positionals = [];
-    const options = {};
+    const options = Object.create(null);
     const aliases = buildShortAliasMap(schema);
     let parseOptions = true;
     for (let index = 0; index < args.length; index += 1) {
@@ -68,10 +68,10 @@ function parseArgv(args, schema) {
         if (name === '') {
             throw createUnexpectedArgumentError(arg);
         }
-        const definition = schema?.[name];
+        const definition = getOwnOptionDefinition(schema, name);
         if (separatorIndex === -1 && definition === undefined && name.startsWith('no-')) {
             const negatedName = name.slice(3);
-            const negatedDefinition = schema?.[negatedName];
+            const negatedDefinition = getOwnOptionDefinition(schema, negatedName);
             if (negatedDefinition?.type === 'boolean') {
                 if (Object.hasOwn(options, negatedName)) {
                     throw createDuplicateArgumentError(negatedName);
@@ -106,9 +106,15 @@ function parseArgv(args, schema) {
     }
     return {
         positionals,
-        options
+        options: { ...options }
     };
 }
+function getOwnOptionDefinition(schema, name) {
+    if (schema === undefined || !Object.hasOwn(schema, name)) {
+        return undefined;
+    }
+    return schema[name];
+}
 function buildShortAliasMap(schema) {
     const aliases = new Map();
     if (schema === undefined) {
@@ -147,6 +153,7 @@ function createDuplicateArgumentError(name) {
 }
 function createUnexpectedArgumentError(argument) {
     return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '${argument}'`, {
+        reason: 'malformed-option',
         argument
     });
 }

package/dist/command/mechanics.js

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

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

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

package/dist/errors/icore-error.js

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -12,7 +12,7 @@
  * This file must not contain parser, validator, or command runtime logic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTerminalApp = exports.createBackpressureTextWriter = exports.createStdoutWriter = exports.createStderrWriter = exports.createOutput = exports.renderPresentationResult = exports.isPresentationResult = exports.renderTextTable = exports.renderJson = exports.renderCsvRow = exports.renderCsv = exports.presentationFormats = exports.presentationFormatOptions = exports.isPresentationFormat = exports.createPresentation = exports.mergeOptionsSchema = exports.parseOptionsSubsetDetailed = exports.parseOptionsDetailed = exports.parseOptions = exports.IcoreError = exports.runCommandFromRegistry = exports.runPreparedCommand = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.prepareCommandFromArgs = exports.isPreparedCommandName = exports.isCommandName = exports.defineCommandRegistry = exports.defineCommand = exports.createCommands = exports.createCommand = exports.parseArgv = void 0;
+exports.createTerminalApp = exports.createBackpressureTextWriter = exports.createStdoutWriter = exports.createStderrWriter = exports.createOutput = exports.renderPresentationResult = exports.isPresentationResult = exports.renderTextTable = exports.renderJson = exports.renderCsvRow = exports.renderCsv = exports.presentationFormats = exports.presentationFormatOptions = exports.isPresentationFormat = exports.createPresentation = exports.mergeOptionsSchema = exports.parseOptionsSubsetDetailed = exports.parseOptionsDetailed = exports.parseOptions = exports.isIcoreError = exports.IcoreError = exports.runCommandFromRegistry = exports.runPreparedCommand = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.prepareCommandFromArgs = exports.isPreparedCommandName = exports.isCommandName = exports.defineCommandRegistry = exports.defineCommand = exports.createCommands = exports.createCommand = exports.parseArgv = void 0;
 var parser_1 = require("./argv/parser");
 Object.defineProperty(exports, "parseArgv", { enumerable: true, get: function () { return parser_1.parseArgv; } });
 var mechanics_1 = require("./command/mechanics");
@@ -30,6 +30,7 @@ Object.defineProperty(exports, "runPreparedCommand", { enumerable: true, get: fu
 Object.defineProperty(exports, "runCommandFromRegistry", { enumerable: true, get: function () { return mechanics_1.runCommandFromRegistry; } });
 var icore_error_1 = require("./errors/icore-error");
 Object.defineProperty(exports, "IcoreError", { enumerable: true, get: function () { return icore_error_1.IcoreError; } });
+Object.defineProperty(exports, "isIcoreError", { enumerable: true, get: function () { return icore_error_1.isIcoreError; } });
 var parser_2 = require("./options/parser");
 Object.defineProperty(exports, "parseOptions", { enumerable: true, get: function () { return parser_2.parseOptions; } });
 Object.defineProperty(exports, "parseOptionsDetailed", { enumerable: true, get: function () { return parser_2.parseOptionsDetailed; } });

package/dist/options/parser.js

@@ -26,8 +26,8 @@ function parseOptions(schema, values) {
  * metadata.
  */
 function parseOptionsDetailed(schema, values) {
-    const parsed = {};
-    const provided = {};
+    const parsed = Object.create(null);
+    const provided = Object.create(null);
     for (const name of Object.keys(values)) {
         if (!Object.hasOwn(schema, name)) {
             throw createUnexpectedArgumentError(name);
@@ -35,27 +35,30 @@ function parseOptionsDetailed(schema, values) {
     }
     for (const name of Object.keys(schema)) {
         const definition = schema[name];
-        const value = values[String(name)];
+        const optionName = String(name);
+        const value = Object.hasOwn(values, optionName)
+            ? values[optionName]
+            : undefined;
         if (definition === undefined) {
             continue;
         }
         provided[name] = value !== undefined;
         if (value === undefined) {
             if ('default' in definition) {
-                parsed[name] = parseDefaultOptionValue(String(name), definition);
+                parsed[name] = parseDefaultOptionValue(optionName, definition);
                 continue;
             }
             if (definition.required === true) {
-                throw createExpectedRequiredArgumentError(String(name));
+                throw createExpectedRequiredArgumentError(optionName);
             }
             parsed[name] = undefined;
             continue;
         }
-        parsed[name] = parseOptionValue(String(name), definition, value);
+        parsed[name] = parseOptionValue(optionName, definition, value);
     }
     return {
-        options: parsed,
-        provided: provided
+        options: { ...parsed },
+        provided: { ...provided }
     };
 }
 /**
@@ -63,8 +66,8 @@ function parseOptionsDetailed(schema, values) {
  * remaining raw options untouched.
  */
 function parseOptionsSubsetDetailed(schema, values) {
-    const subsetValues = {};
-    const rest = {};
+    const subsetValues = Object.create(null);
+    const rest = Object.create(null);
     for (const [name, value] of Object.entries(values)) {
         if (Object.hasOwn(schema, name)) {
             subsetValues[name] = value;
@@ -74,7 +77,7 @@ function parseOptionsSubsetDetailed(schema, values) {
     }
     return {
         ...parseOptionsDetailed(schema, subsetValues),
-        rest
+        rest: { ...rest }
     };
 }
 function parseOptionValue(name, definition, value) {
@@ -151,7 +154,10 @@ function validateNumberConstraints(name, definition, parsed, source = 'value') {
                 value: parsed
             });
         }
-        throw createExpectedOptionTypeError(name, 'integer', parsed);
+        throw createInvalidOptionTypeError(name, `Expected '--${name}' as integer`, {
+            expected: 'integer',
+            value: parsed
+        });
     }
     if (definition.min !== undefined && parsed < definition.min) {
         const message = `Expected '--${name}' to be greater than or equal to ${String(definition.min)}`;
@@ -192,6 +198,7 @@ function assertChoice(name, choices, value, source = 'value') {
     const message = `Expected '--${name}' as one of: ${choices.join(', ')}`;
     if (source === 'default') {
         throw createInvalidOptionDefaultError(name, message, {
+            expected: 'choice',
             choices: [...choices],
             value
         });
@@ -200,12 +207,14 @@ function assertChoice(name, choices, value, source = 'value') {
 }
 function createUnexpectedArgumentError(name) {
     return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
+        reason: 'unknown-option',
         argument: `--${name}`,
         option: name
     });
 }
 function createExpectedRequiredArgumentError(name) {
     return new icore_error_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
+        reason: 'option',
         argument: `--${name}`,
         option: name
     });

package/dist/options/schema.js

@@ -19,5 +19,6 @@ exports.mergeOptionsSchema = mergeOptionsSchema;
  * Later schemas override earlier schemas with the same option name.
  */
 function mergeOptionsSchema(schema, ...schemas) {
-    return Object.assign({}, schema, ...schemas);
+    const merged = Object.assign(Object.create(null), schema, ...schemas);
+    return { ...merged };
 }