@guanghechen/commander 4.7.6 → 4.7.8

package/lib/schema/preset.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guanghechen.github.io/sora/schemas/commander/preset.schema.json",
+  "title": "Commander Preset Config",
+  "description": "Preset profile manifest for @guanghechen/commander --preset-file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "profiles"],
+  "examples": [
+    {
+      "version": 1,
+      "defaults": { "profile": "dev:local" },
+      "profiles": {
+        "dev": {
+          "envFile": "dev.env",
+          "envs": { "NODE_ENV": "development" },
+          "opts": { "logLevel": "debug", "retry": 2 },
+          "defaultVariant": "local",
+          "variants": {
+            "local": { "opts": { "retry": 1 } },
+            "ci": { "envFile": "ci.env", "envs": { "CI": "1" } }
+          }
+        }
+      }
+    }
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema reference for editors (e.g. VSCode)."
+    },
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version."
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "profile": {
+          "$ref": "#/$defs/profileSelector"
+        }
+      },
+      "description": "Default selector when --preset-profile is not provided."
+    },
+    "profiles": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "$ref": "#/$defs/profileName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/profileItem"
+      },
+      "description": "Profiles keyed by profile name."
+    }
+  },
+  "$defs": {
+    "profileName": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
+      "description": "Profile/variant name."
+    },
+    "profileSelector": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)?$",
+      "description": "Selector format: <profile> or <profile>:<variant>."
+    },
+    "optionName": {
+      "type": "string",
+      "pattern": "^(?:--)?(?:[a-z][a-zA-Z0-9]*|[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+)$",
+      "description": "Option key in opts map; aligned with runtime normalization."
+    },
+    "optionValue": {
+      "oneOf": [
+        { "type": "boolean" },
+        { "type": "string" },
+        { "type": "number" },
+        {
+          "type": "array",
+          "items": {
+            "oneOf": [{ "type": "string" }, { "type": "number" }]
+          }
+        }
+      ]
+    },
+    "envMap": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "optsMap": {
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/optionName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/optionValue"
+      }
+    },
+    "variantItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "envFile": {
+          "type": "string",
+          "minLength": 1
+        },
+        "envs": {
+          "$ref": "#/$defs/envMap"
+        },
+        "opts": {
+          "$ref": "#/$defs/optsMap"
+        }
+      }
+    },
+    "variantsMap": {
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/profileName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/variantItem"
+      }
+    },
+    "profileItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "envFile": {
+          "type": "string",
+          "minLength": 1
+        },
+        "envs": {
+          "$ref": "#/$defs/envMap"
+        },
+        "opts": {
+          "$ref": "#/$defs/optsMap"
+        },
+        "defaultVariant": {
+          "$ref": "#/$defs/profileName"
+        },
+        "variants": {
+          "$ref": "#/$defs/variantsMap"
+        }
+      },
+      "description": "defaultVariant existence in variants must still be validated by runtime."
+    }
+  }
+}

package/lib/types/browser.d.ts

@@ -1,13 +1,31 @@
 import { IReporter } from '@guanghechen/reporter';
 
-/**
- * Type definitions for @guanghechen/commander
- *
- * @module @guanghechen/commander
- */
-
 /** Token type: long option, short option, or positional */
 type ICommandTokenType = 'long' | 'short' | 'none';
+/** Token source kind */
+type ICommandTokenSource = 'user' | 'preset';
+/** Preset metadata carried by token/issue source tracing */
+interface ICommandPresetIssueMeta {
+    file?: string;
+    profile?: string;
+    variant?: string;
+    optionKey?: string;
+}
+/** Preset source snapshot metadata carried by ctx.sources.preset.meta */
+interface ICommandPresetSourceMeta {
+    applied: boolean;
+    file?: string;
+    profile?: string;
+    variant?: string;
+}
+/** Preset execution state in input source snapshot */
+type ICommandPresetSourceState = 'skipped' | 'none' | 'applied';
+/** Input segment before tokenize, preserving source attribution */
+interface ICommandArgvSegment {
+    value: string;
+    source: ICommandTokenSource;
+    preset?: ICommandPresetIssueMeta;
+}
 /**
  * Command token after preprocessing.
  *
@@ -25,46 +43,12 @@ interface ICommandToken {
     name: string;
     /** Token type */
     type: ICommandTokenType;
+    /** Source of this token */
+    source: ICommandTokenSource;
+    /** Preset metadata when source='preset' */
+    preset?: ICommandPresetIssueMeta;
 }
-/** Option value type */
-type ICommandOptionType = 'boolean' | 'number' | 'string';
-/** Option argument mode */
-type ICommandOptionArgs = 'none' | 'required' | 'optional' | 'variadic';
-/**
- * Option configuration.
- *
- * `type` and `args` must be specified together. Valid combinations:
- * - boolean + none → boolean
- * - string + required → string
- * - string + optional → string | undefined
- * - number + required → number
- * - string + variadic → string[]
- * - number + variadic → number[]
- *
- * @template T - The type of the option value
- */
-interface ICommandOptionConfig<T = unknown> {
-    /** Long option name (camelCase, required) */
-    long: string;
-    /** Short option (single character) */
-    short?: string;
-    /** Value type (required) */
-    type: ICommandOptionType;
-    /** Argument mode (required) */
-    args: ICommandOptionArgs;
-    /** Description for help text */
-    desc: string;
-    /** Whether this option is required (mutually exclusive with default) */
-    required?: boolean;
-    /** Default value when not provided */
-    default?: T;
-    /** Allowed values for validation and completion */
-    choices?: T extends Array<infer U> ? U[] : T[];
-    /** Single value transformation (called for each value, before choices validation) */
-    coerce?: (rawValue: string) => T extends Array<infer U> ? U : T;
-    /** Callback after parsing, applies value to context */
-    apply?: (value: T, ctx: ICommandContext) => void;
-}
+
 /** Argument kind */
 type ICommandArgumentKind = 'required' | 'optional' | 'variadic' | 'some';
 /** Argument value type */
@@ -95,11 +79,14 @@ interface ICommandArgumentConfig<T = unknown> {
     /** Custom value transformation (takes precedence over type conversion) */
     coerce?: (rawValue: string) => T;
 }
+
 interface ICommandBuiltinOptionConfig {
     /** Enable built-in --version option (requires configured version on target command) */
     version?: boolean;
     /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
     color?: boolean;
+    /** Enable built-in --devmode option */
+    devmode?: boolean;
     /** Enable built-in --log-level option */
     logLevel?: boolean;
     /** Enable built-in --silent option */
@@ -214,6 +201,7 @@ interface ICommand {
     readonly examples: ICommandExample[];
     readonly subcommands: Map<string, ICommand>;
 }
+
 /** Execution context */
 interface ICommandContext {
     /** Current command node */
@@ -233,6 +221,8 @@ interface ICommandContext {
 interface ICommandActionParams {
     /** Execution context */
     ctx: ICommandContext;
+    /** Effective built-in options for current leaf command */
+    builtin: ICommandBuiltinParsedOptions;
     /** Parsed options (keyed by long name) */
     opts: ICommandParsedOpts;
     /** Parsed positional arguments (keyed by argument name) */
@@ -255,6 +245,92 @@ interface ICommandRunParams {
 type ICommandParsedOpts = Record<string, unknown>;
 /** Parsed arguments record */
 type ICommandParsedArgs = Record<string, unknown>;
+/** Input source snapshots for debugging/tracing */
+interface ICommandInputSources {
+    preset: {
+        state: ICommandPresetSourceState;
+        argv: string[];
+        envs: Record<string, string>;
+        meta?: ICommandPresetSourceMeta;
+    };
+    user: {
+        /** Routed command tokens (name/alias as entered by user) */
+        cmds: string[];
+        /** Clean user tail argv after removing command chain/control/preset directives */
+        argv: string[];
+        /** Raw env snapshot from run/parse params */
+        envs: Record<string, string | undefined>;
+    };
+}
+/** Built-in run controls */
+interface ICommandControls {
+    help: boolean;
+    version: boolean;
+}
+/** Built-in option resolution result (internal) */
+interface ICommandBuiltinOptionResolved {
+    version: boolean;
+    color: boolean;
+    devmode: boolean;
+    logLevel: boolean;
+    silent: boolean;
+    logDate: boolean;
+    logColorful: boolean;
+}
+/** Built-in config resolution result (internal) */
+interface ICommandBuiltinResolved {
+    option: ICommandBuiltinOptionResolved;
+}
+/** Effective built-in options exposed to action/parse result */
+interface ICommandBuiltinParsedOptions {
+    devmode: boolean;
+    color?: boolean;
+    logLevel?: string;
+    silent?: boolean;
+    logDate?: boolean;
+    logColorful?: boolean;
+}
+
+/** Option value type */
+type ICommandOptionType = 'boolean' | 'number' | 'string';
+/** Option argument mode */
+type ICommandOptionArgs = 'none' | 'required' | 'optional' | 'variadic';
+/**
+ * Option configuration.
+ *
+ * `type` and `args` must be specified together. Valid combinations:
+ * - boolean + none -> boolean
+ * - string + required -> string
+ * - string + optional -> string | undefined
+ * - number + required -> number
+ * - string + variadic -> string[]
+ * - number + variadic -> number[]
+ *
+ * @template T - The type of the option value
+ */
+interface ICommandOptionConfig<T = unknown> {
+    /** Long option name (camelCase, required) */
+    long: string;
+    /** Short option (single character) */
+    short?: string;
+    /** Value type (required) */
+    type: ICommandOptionType;
+    /** Argument mode (required) */
+    args: ICommandOptionArgs;
+    /** Description for help text */
+    desc: string;
+    /** Whether this option is required (mutually exclusive with default) */
+    required?: boolean;
+    /** Default value when not provided */
+    default?: T;
+    /** Allowed values for validation and completion */
+    choices?: T extends Array<infer U> ? U[] : T[];
+    /** Single value transformation (called for each value, before choices validation) */
+    coerce?: (rawValue: string) => T extends Array<infer U> ? U : T;
+    /** Callback after parsing, applies value to context */
+    apply?: (value: T, ctx: ICommandContext) => void;
+}
+
 /** Route stage result */
 interface ICommandRouteResult<TCommand = ICommand> {
     /** Command chain from root to leaf */
@@ -279,6 +355,8 @@ interface ICommandPresetResult {
     tailArgv: string[];
     /** Effective envs after preset merge */
     envs: Record<string, string | undefined>;
+    /** Source-attributed argv segments consumed by tokenize */
+    segments: ICommandArgvSegment[];
 }
 /** Tokenize stage result */
 interface ICommandTokenizeResult {
@@ -301,50 +379,6 @@ interface ICommandShiftResult {
     /** Remaining tokens to pass to parent */
     remaining: ICommandToken[];
 }
-/** Parse stage result */
-interface ICommandParseResult {
-    /** Execution context */
-    ctx: ICommandContext;
-    /** Parsed options */
-    opts: ICommandParsedOpts;
-    /** Parsed arguments */
-    args: ICommandParsedArgs;
-    /** Raw argument strings */
-    rawArgs: string[];
-}
-/** Input source snapshots for debugging/tracing */
-interface ICommandInputSources {
-    preset: {
-        argv: string[];
-        envs: Record<string, string>;
-    };
-    user: {
-        /** Routed command tokens (name/alias as entered by user) */
-        cmds: string[];
-        /** Clean user tail argv after removing command chain/control/preset directives */
-        argv: string[];
-        /** Raw env snapshot from run/parse params */
-        envs: Record<string, string | undefined>;
-    };
-}
-/** Built-in run controls */
-interface ICommandControls {
-    help: boolean;
-    version: boolean;
-}
-/** Built-in option resolution result (internal) */
-interface ICommandBuiltinOptionResolved {
-    version: boolean;
-    color: boolean;
-    logLevel: boolean;
-    silent: boolean;
-    logDate: boolean;
-    logColorful: boolean;
-}
-/** Built-in config resolution result (internal) */
-interface ICommandBuiltinResolved {
-    option: ICommandBuiltinOptionResolved;
-}
 /** Subcommand registry entry (internal) */
 interface ISubcommandEntry<TCommand = ICommand> {
     name: string;
@@ -381,16 +415,77 @@ interface IHelpData {
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
 }
+/** Parse stage result */
+interface ICommandParseResult {
+    /** Execution context */
+    ctx: ICommandContext;
+    /** Effective built-in options for current leaf command */
+    builtin: ICommandBuiltinParsedOptions;
+    /** Parsed options */
+    opts: ICommandParsedOpts;
+    /** Parsed arguments */
+    args: ICommandParsedArgs;
+    /** Raw argument strings */
+    rawArgs: string[];
+}
+
+type ICommandStage = 'route' | 'control-scan' | 'control-run' | 'preset' | 'tokenize' | 'builtin-resolve' | 'resolve' | 'parse' | 'run';
+type ICommandIssueKind = 'error' | 'hint';
+interface ICommandIssueSourceAttribution {
+    primary?: ICommandTokenSource;
+    related?: ICommandTokenSource[];
+}
+type ICommandIssueScope = 'control' | 'preset' | 'option' | 'argument' | 'command' | 'runtime' | 'action';
+type ICommandErrorIssueCode = 'invalid_option_format' | 'invalid_negative_option' | 'negative_option_with_value' | 'negative_option_type' | 'unknown_option' | 'unknown_subcommand' | 'unexpected_argument' | 'missing_value' | 'invalid_type' | 'unsupported_short_syntax' | 'option_conflict' | 'missing_required' | 'invalid_choice' | 'invalid_boolean_value' | 'missing_required_argument' | 'too_many_arguments' | 'configuration_error' | 'action_failed';
+type ICommandHintIssueCode = 'preset_token_injected' | 'mixed_source_conflict' | 'did_you_mean_subcommand' | 'command_does_not_accept_positional_arguments';
+type ICommandIssueCode = ICommandErrorIssueCode | ICommandHintIssueCode;
+interface ICommandIssueReason {
+    code: ICommandIssueCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface ICommandIssueBase {
+    kind: ICommandIssueKind;
+    stage: ICommandStage;
+    originStage?: ICommandStage;
+    source?: ICommandIssueSourceAttribution;
+    scope: ICommandIssueScope;
+    preset?: ICommandPresetIssueMeta;
+}
+interface ICommandErrorIssue extends ICommandIssueBase {
+    kind: 'error';
+    reason: Omit<ICommandIssueReason, 'code'> & {
+        code: ICommandErrorIssueCode;
+    };
+}
+interface ICommandHintIssue extends ICommandIssueBase {
+    kind: 'hint';
+    reason: Omit<ICommandIssueReason, 'code'> & {
+        code: ICommandHintIssueCode;
+    };
+}
+type ICommandIssue = ICommandErrorIssue | ICommandHintIssue;
+interface ICommandErrorMeta {
+    commandPath: string;
+    token?: string;
+    option?: string;
+    argument?: string;
+    issues: ICommandIssue[];
+}
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
+type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError' | 'ActionFailed';
 /** Commander error with structured information */
 declare class CommanderError extends Error {
     readonly kind: ICommanderErrorKind;
     readonly commandPath: string;
-    constructor(kind: ICommanderErrorKind, message: string, commandPath: string);
+    readonly meta: ICommandErrorMeta | undefined;
+    constructor(kind: ICommanderErrorKind, message: string, commandPath: string, meta?: ICommandErrorMeta);
+    withIssue(issue: ICommandIssue): CommanderError;
+    withIssues(issues: ICommandIssue[]): CommanderError;
     /** Format error with help hint */
     format(): string;
 }
+
 /** Shell type for completion */
 type ICompletionShellType = 'bash' | 'fish' | 'pwsh';
 /** Option metadata for completion */
@@ -454,7 +549,7 @@ interface ICompletionCommandConfig {
 /**
  * Command class - CLI command builder with fluent API
  *
- * Execution flow: route → control-scan → run-control(run) → preset → tokenize → resolve → parse → run
+ * Execution flow: route → control-scan → control-run(run) → preset → tokenize → builtin-resolve → resolve → parse → run
  *
  * @module @guanghechen/commander
  */
@@ -513,36 +608,6 @@ declare function isDomain(rawValue: string): boolean;
  * @module @guanghechen/commander/options
  */
 
-/**
- * Pre-defined --log-level option for setting log verbosity.
- *
- * Supports: debug | info | hint | warn | error (case-insensitive)
- *
- * | Property  | Value                              |
- * | --------- | ---------------------------------- |
- * | long      | 'logLevel'                         |
- * | type      | 'string'                           |
- * | args      | 'required'                         |
- * | default   | 'info'                             |
- * | choices   | LOG_LEVELS                         |
- * | coerce    | resolveLogLevel (case-insensitive) |
- * | apply     | ctx.reporter.setLevel(value)       |
- *
- * @example
- * ```typescript
- * import { logLevelOption } from '@guanghechen/commander'
- *
- * const cmd = new Command('app')
- *   .option(logLevelOption)
- *   .action(({ opts }) => {
- *     console.log(opts.logLevel) // 'debug' | 'info' | 'hint' | 'warn' | 'error'
- *   })
- *
- * // Override with spread syntax
- * .option({ ...logLevelOption, default: 'warn' })
- * ```
- */
-declare const logLevelOption: ICommandOptionConfig<string>;
 /**
  * Pre-defined --log-date option for controlling timestamp output.
  *
@@ -577,7 +642,7 @@ declare const logColorfulOption: ICommandOptionConfig<boolean>;
  *
  * @example
  * ```typescript
- * import { silentOption } from '@guanghechen/commander'
+ * import { silentOption } from '@guanghechen/commander/browser'
  *
  * const cmd = new Command('app')
  *   .option(silentOption)
@@ -607,5 +672,5 @@ declare function createBrowserCommandRuntime(): ICommandRuntime;
 declare function getDefaultCommandRuntime(): ICommandRuntime;
 declare function setDefaultCommandRuntime(runtime: ICommandRuntime): void;
 
-export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, setDefaultCommandRuntime, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandExample, ICommandInputSources, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, setDefaultCommandRuntime, silentOption };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };