icore 1.0.9 → 1.0.10

package/dist/argv.d.ts

@@ -22,4 +22,3 @@ export type ParsedArgv = {
  * Parses raw CLI arguments into positionals and raw long-option values.
  */
 export declare function parseArgv(args: readonly string[], schema?: OptionsSchema): ParsedArgv;
-//# sourceMappingURL=argv.d.ts.map

package/dist/argv.js

@@ -138,4 +138,3 @@ function assertShortAlias(name, alias) {
 function isShortOptionToken(arg) {
     return arg.length === 2 && arg.startsWith('-') && !arg.startsWith('--');
 }
-//# sourceMappingURL=argv.js.map

package/dist/cli.d.ts

@@ -9,6 +9,5 @@
  * This file must not contain parser, validator, or command runtime logic.
  */
 export { parseArgv, type ParsedArgv } from './argv';
-export { defineCommand, defineCommandRegistry, isCommandName, resolveCommand, resolveCommandFromArgs, runCommand, runCommandFromRegistry, type CommandDefinition, type CommandInput, type CommandName, type CommandRegistry, type ResolvedCommand } from './commands';
+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 { 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';
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -10,19 +10,20 @@
  * 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.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = exports.isCommandName = exports.defineCommandRegistry = exports.defineCommand = exports.parseArgv = void 0;
+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;
 var argv_1 = require("./argv");
 Object.defineProperty(exports, "parseArgv", { enumerable: true, get: function () { return argv_1.parseArgv; } });
 var commands_1 = require("./commands");
 Object.defineProperty(exports, "defineCommand", { enumerable: true, get: function () { return commands_1.defineCommand; } });
 Object.defineProperty(exports, "defineCommandRegistry", { enumerable: true, get: function () { return commands_1.defineCommandRegistry; } });
 Object.defineProperty(exports, "isCommandName", { enumerable: true, get: function () { return commands_1.isCommandName; } });
+Object.defineProperty(exports, "prepareCommandFromArgs", { enumerable: true, get: function () { return commands_1.prepareCommandFromArgs; } });
 Object.defineProperty(exports, "resolveCommand", { enumerable: true, get: function () { return commands_1.resolveCommand; } });
 Object.defineProperty(exports, "resolveCommandFromArgs", { enumerable: true, get: function () { return commands_1.resolveCommandFromArgs; } });
 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 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; } });
 Object.defineProperty(exports, "parseOptionsDetailed", { enumerable: true, get: function () { return options_1.parseOptionsDetailed; } });
-//# sourceMappingURL=cli.js.map

package/dist/commands.d.ts

@@ -12,12 +12,18 @@
  */
 import { type InferOptions, type InferProvidedOptions, type OptionsSchema } from './options';
 /**
- * Input passed to a command handler after command path and option validation.
+ * Input produced after command path and option validation, before runtime
+ * context is attached.
  */
-export type CommandInput<TSchema extends OptionsSchema, TContext> = {
+export type PreparedCommandInput<TSchema extends OptionsSchema> = {
     options: InferOptions<TSchema>;
     provided: InferProvidedOptions<TSchema>;
     positionals: string[];
+};
+/**
+ * Input passed to a command handler after command path and option validation.
+ */
+export type CommandInput<TSchema extends OptionsSchema, TContext> = PreparedCommandInput<TSchema> & {
     context: TContext;
 };
 /**
@@ -27,19 +33,22 @@ export type CommandInput<TSchema extends OptionsSchema, TContext> = {
  * 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[]]> = {
+export type CommandDefinition<TSchema extends OptionsSchema, TContext, TResult, TPath extends readonly [string, ...string[]] = readonly [string, ...string[]], TMetadata = unknown> = {
     path: TPath;
     options: TSchema;
+    metadata?: TMetadata;
     allowExtraPositionals?: boolean;
+    prepare?(input: PreparedCommandInput<TSchema>): void | Promise<void>;
     handle(input: CommandInput<TSchema, TContext>): TResult | Promise<TResult>;
 };
-type AnyCommandDefinition = CommandDefinition<OptionsSchema, unknown, 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;
 /**
  * Infers the public command name from a command path.
  */
@@ -60,10 +69,21 @@ export type ResolvedCommand<TCommand extends AnyCommandDefinition> = {
     command: TCommand;
     positionals: string[];
 };
+/**
+ * Command resolved and validated without runtime context.
+ */
+export type PreparedCommand<TCommand extends AnyCommandDefinition> = {
+    name: CommandName<TCommand>;
+    path: TCommand['path'];
+    command: TCommand;
+    options: InferOptions<CommandSchema<TCommand>>;
+    provided: InferProvidedOptions<CommandSchema<TCommand>>;
+    positionals: string[];
+};
 /**
  * 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>(command: CommandDefinition<TSchema, TContext, TResult, TPath>): CommandDefinition<TSchema, TContext, TResult, TPath>;
+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>;
 /**
  * Defines a command registry while preserving literal command path types.
  */
@@ -80,6 +100,14 @@ export declare function resolveCommand<const TCommands extends readonly AnyComma
  * Resolves a command from raw CLI arguments using each command's option schema.
  */
 export declare function resolveCommandFromArgs<const TCommands extends readonly AnyCommandDefinition[]>(registry: CommandRegistry<TCommands>, args: readonly string[]): ResolvedCommand<TCommands[number]>;
+/**
+ * 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]>>;
+/**
+ * Runs a prepared command with caller-provided runtime context.
+ */
+export declare function runPreparedCommand<TCommand extends AnyCommandDefinition>(prepared: PreparedCommand<TCommand>, context: CommandContext<TCommand>): Promise<CommandResult<TCommand>>;
 /**
  * Resolves a command from a registry and runs its handler.
  */
@@ -90,4 +118,3 @@ export declare function runCommandFromRegistry<const TCommands extends readonly
  */
 export declare function runCommand<const TSchema extends OptionsSchema, TContext, TResult>(command: CommandDefinition<TSchema, TContext, TResult>, args: readonly string[], context: TContext): Promise<TResult>;
 export {};
-//# sourceMappingURL=commands.d.ts.map

package/dist/commands.js

@@ -17,6 +17,8 @@ exports.defineCommandRegistry = defineCommandRegistry;
 exports.isCommandName = isCommandName;
 exports.resolveCommand = resolveCommand;
 exports.resolveCommandFromArgs = resolveCommandFromArgs;
+exports.prepareCommandFromArgs = prepareCommandFromArgs;
+exports.runPreparedCommand = runPreparedCommand;
 exports.runCommandFromRegistry = runCommandFromRegistry;
 exports.runCommand = runCommand;
 const argv_1 = require("./argv");
@@ -70,30 +72,77 @@ function resolveCommandFromArgs(registry, args) {
     }
     throw new Error(`Unknown command: ${formatCommandPositionals((0, argv_1.parseArgv)(args).positionals)}`);
 }
+/**
+ * Resolves and validates a command without requiring runtime context.
+ */
+async function prepareCommandFromArgs(registry, args) {
+    for (const command of commandsBySpecificity(registry.commands)) {
+        const argv = (0, argv_1.parseArgv)(args, command.options);
+        const resolved = resolveCommandCandidate(command, argv.positionals);
+        if (resolved !== undefined) {
+            return prepareResolvedCommand(resolved, argv.options);
+        }
+    }
+    throw new Error(`Unknown command: ${formatCommandPositionals((0, argv_1.parseArgv)(args).positionals)}`);
+}
+/**
+ * Runs a prepared command with caller-provided runtime context.
+ */
+async function runPreparedCommand(prepared, context) {
+    const result = await prepared.command.handle({
+        options: prepared.options,
+        provided: prepared.provided,
+        positionals: prepared.positionals,
+        context
+    });
+    return result;
+}
 /**
  * Resolves a command from a registry and runs its handler.
  */
 async function runCommandFromRegistry(registry, args, context) {
-    const resolved = resolveCommandFromArgs(registry, args);
-    return runCommand(resolved.command, args, context);
+    const prepared = await prepareCommandFromArgs(registry, args);
+    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);
+    return runPreparedCommand(prepared, context);
+}
+async function prepareCommand(command, args) {
     const argv = (0, argv_1.parseArgv)(args, command.options);
     const extraPositionals = resolveCommandPositionals(command.path, argv.positionals);
-    if (extraPositionals.length > 0 && command.allowExtraPositionals !== true) {
-        throw new Error(`Unexpected positional argument for '${command.path.join(' ')}': ${extraPositionals[0] ?? ''}`);
+    const resolved = {
+        name: commandPathToName(command.path),
+        path: command.path,
+        command,
+        positionals: extraPositionals
+    };
+    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 parsed = (0, options_1.parseOptionsDetailed)(command.options, argv.options);
-    return command.handle({
+    const parsed = (0, options_1.parseOptionsDetailed)(command.options, rawOptions);
+    const input = {
         options: parsed.options,
         provided: parsed.provided,
-        positionals: extraPositionals,
-        context
-    });
+        positionals: resolved.positionals
+    };
+    await command.prepare?.(input);
+    return {
+        name: resolved.name,
+        path: resolved.path,
+        command,
+        options: parsed.options,
+        provided: parsed.provided,
+        positionals: resolved.positionals
+    };
 }
 function resolveCommandPositionals(path, positionals) {
     for (let index = 0; index < path.length; index += 1) {
@@ -141,4 +190,3 @@ function resolveMatchingCommandPositionals(path, positionals) {
 function formatCommandPositionals(positionals) {
     return positionals.length === 0 ? '<empty>' : positionals.join(' ');
 }
-//# sourceMappingURL=commands.js.map

package/dist/index.d.ts

@@ -1,2 +1 @@
-export { defineCommand, defineCommandRegistry, isCommandName, mergeOptionsSchema, parseArgv, parseOptions, parseOptionsDetailed, resolveCommand, resolveCommandFromArgs, runCommand, 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 RawOptionValue, type ResolvedCommand, type StringOption } from './cli';
-//# sourceMappingURL=index.d.ts.map
+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';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runCommandFromRegistry = exports.runCommand = exports.resolveCommandFromArgs = exports.resolveCommand = 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.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; } });
@@ -9,8 +9,9 @@ Object.defineProperty(exports, "mergeOptionsSchema", { enumerable: true, get: fu
 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; } });
-//# sourceMappingURL=index.js.map

package/dist/options.d.ts

@@ -129,4 +129,3 @@ export declare function parseOptions<const TSchema extends OptionsSchema>(schema
  */
 export declare function parseOptionsDetailed<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): ParseOptionsResult<TSchema>;
 export {};
-//# sourceMappingURL=options.d.ts.map

package/dist/options.js

@@ -144,4 +144,3 @@ function assertChoice(name, choices, value) {
     }
     throw new Error(`Expected '--${name}' as one of: ${choices.join(', ')}`);
 }
-//# sourceMappingURL=options.js.map

package/package.json

@@ -1,12 +1,7 @@
 {
   "name": "icore",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Declarative command line interface mechanics for Node.js",
-  "author": {
-    "name": "Stanislav Potemkin",
-    "email": "woodger@ya.ru"
-  },
-  "license": "MIT",
   "keywords": [
     "command-line",
     "argv",
@@ -17,9 +12,14 @@
     "typed-cli",
     "declarative-cli"
   ],
+  "author": {
+    "name": "Stanislav Potemkin",
+    "email": "woodger@ya.ru"
+  },
+  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/woodger/icore.git"
+    "url": "git+https://github.com/woodger/icore.git"
   },
   "engines": {
     "node": ">=16.9.0"
@@ -29,9 +29,8 @@
   "scripts": {
     "build": "tsc",
     "test": "node --test dist/*.test.js",
-    "lint": "eslint src eslint.config.mjs"
+    "lint": "eslint src"
   },
-  "dependencies": {},
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@types/node": "^26.0.1",