icore 1.0.9 → 1.0.11

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

@@ -35,9 +35,12 @@ export type StringOption<TChoices extends readonly string[] = readonly string[]>
 /**
  * Declarative boolean flag contract.
  *
- * Boolean options accept flag form and explicit `true` / `false` values.
+ * Boolean options accept flag form and explicit `true` / `false` values unless
+ * `flagOnly` is enabled.
  */
-export type BooleanOption = OptionBase<'boolean', boolean>;
+export type BooleanOption = OptionBase<'boolean', boolean> & {
+    flagOnly?: boolean;
+};
 /**
  * Declarative number option contract.
  *
@@ -129,4 +132,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

@@ -71,7 +71,7 @@ function parseOptionValue(name, definition, value) {
         return parseStringOption(name, definition, value);
     }
     if (definition.type === 'boolean') {
-        return parseBooleanOption(name, value);
+        return parseBooleanOption(name, definition, value);
     }
     return parseNumberOption(name, definition, value);
 }
@@ -103,7 +103,13 @@ function parseStringOption(name, definition, value) {
     assertChoice(name, definition.choices, value);
     return value;
 }
-function parseBooleanOption(name, value) {
+function parseBooleanOption(name, definition, value) {
+    if (definition.flagOnly === true) {
+        if (value === true) {
+            return true;
+        }
+        throw new Error(`Expected '--${name}' as boolean flag`);
+    }
     if (value === true || value === 'true') {
         return true;
     }
@@ -144,4 +150,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.11",
   "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",

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`;
+- boolean flags: `--flag`, `--flag=true`, `--flag=false`, `--no-flag` by default;
 - short aliases: `-f`, `-n value`;
 - option terminator: `--`.
 
@@ -74,8 +74,8 @@ Result:
 }
 ```
 
-When an option schema is provided, boolean options are parsed as flag-only
-options without consuming the following positional argument:
+When an option schema is provided, boolean options are parsed as flags without
+consuming the following positional argument:
 
 ```ts
 const argv = parseArgv([
@@ -455,6 +455,21 @@ 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:
+
+```ts
+const schema = {
+  uppercase: {
+    type: 'boolean',
+    default: false,
+    flagOnly: true
+  }
+} as const;
+```
+
+With `flagOnly: true`, `--uppercase` is accepted, while `--uppercase=true`,
+`--uppercase=false`, and `--no-uppercase` are rejected.
+
 ### `type: 'number'`
 
 ```ts
@@ -552,8 +567,9 @@ 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. Unknown negated options and negation for
-string or number options are rejected.
+`cache` is a known boolean option without `flagOnly: true`. Unknown negated
+options, negation for string or number options, and negation for flag-only
+boolean options are rejected.
 
 ## Error Messages