@guanghechen/commander 4.7.5 → 4.7.7

package/lib/schema/preset.config.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guanghechen.github.io/sora/schemas/commander/preset.config.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/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

@@ -124,12 +124,48 @@ interface ICommandExample {
 }
 /** Command preset defaults */
 interface ICommandPresetConfig {
-    /** Preset root directory (absolute path) */
-    root?: string;
-    /** Default preset options file */
-    opt?: string;
-    /** Default preset envs file */
-    env?: string;
+    /** Default preset profile file */
+    file?: string;
+    /** Default preset profile selector: <profile> or <profile>:<variant> */
+    profile?: string;
+}
+/** Allowed inline profile option value */
+type ICommandPresetProfileOptionValue = boolean | string | number | ReadonlyArray<string | number>;
+/** Variant item nested under a preset profile */
+interface ICommandPresetProfileVariantItem {
+    /** Optional env file path to parse (relative to preset file directory when non-absolute) */
+    envFile?: string;
+    /** Inline env overrides */
+    envs?: Record<string, string>;
+    /** Inline option overrides */
+    opts?: Record<string, ICommandPresetProfileOptionValue>;
+}
+/** Profile item in preset manifest */
+interface ICommandPresetProfileItem {
+    /** Optional env file path to parse (relative to preset file directory when non-absolute) */
+    envFile?: string;
+    /** Inline env overrides */
+    envs?: Record<string, string>;
+    /** Inline option overrides */
+    opts?: Record<string, ICommandPresetProfileOptionValue>;
+    /** Default selected variant name */
+    defaultVariant?: string;
+    /** Optional variants keyed by variant name */
+    variants?: Record<string, ICommandPresetProfileVariantItem>;
+}
+/** Profile manifest defaults */
+interface ICommandPresetProfileDefaults {
+    /** Default selected profile selector: <profile> or <profile>:<variant> */
+    profile?: string;
+}
+/** Profile manifest structure loaded from --preset-file */
+interface ICommandPresetProfileManifest {
+    /** Schema version */
+    version: 1;
+    /** Optional defaults */
+    defaults?: ICommandPresetProfileDefaults;
+    /** Profiles keyed by profile name */
+    profiles: Record<string, ICommandPresetProfileItem>;
 }
 /** Runtime file stats abstraction */
 interface ICommandRuntimeStats {
@@ -572,4 +608,4 @@ 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, ICommandPresetResult, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+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 };

package/lib/types/node.d.ts

@@ -124,12 +124,48 @@ interface ICommandExample {
 }
 /** Command preset defaults */
 interface ICommandPresetConfig {
-    /** Preset root directory (absolute path) */
-    root?: string;
-    /** Default preset options file */
-    opt?: string;
-    /** Default preset envs file */
-    env?: string;
+    /** Default preset profile file */
+    file?: string;
+    /** Default preset profile selector: <profile> or <profile>:<variant> */
+    profile?: string;
+}
+/** Allowed inline profile option value */
+type ICommandPresetProfileOptionValue = boolean | string | number | ReadonlyArray<string | number>;
+/** Variant item nested under a preset profile */
+interface ICommandPresetProfileVariantItem {
+    /** Optional env file path to parse (relative to preset file directory when non-absolute) */
+    envFile?: string;
+    /** Inline env overrides */
+    envs?: Record<string, string>;
+    /** Inline option overrides */
+    opts?: Record<string, ICommandPresetProfileOptionValue>;
+}
+/** Profile item in preset manifest */
+interface ICommandPresetProfileItem {
+    /** Optional env file path to parse (relative to preset file directory when non-absolute) */
+    envFile?: string;
+    /** Inline env overrides */
+    envs?: Record<string, string>;
+    /** Inline option overrides */
+    opts?: Record<string, ICommandPresetProfileOptionValue>;
+    /** Default selected variant name */
+    defaultVariant?: string;
+    /** Optional variants keyed by variant name */
+    variants?: Record<string, ICommandPresetProfileVariantItem>;
+}
+/** Profile manifest defaults */
+interface ICommandPresetProfileDefaults {
+    /** Default selected profile selector: <profile> or <profile>:<variant> */
+    profile?: string;
+}
+/** Profile manifest structure loaded from --preset-file */
+interface ICommandPresetProfileManifest {
+    /** Schema version */
+    version: 1;
+    /** Optional defaults */
+    defaults?: ICommandPresetProfileDefaults;
+    /** Profiles keyed by profile name */
+    profiles: Record<string, ICommandPresetProfileItem>;
 }
 /** Runtime file stats abstraction */
 interface ICommandRuntimeStats {
@@ -625,4 +661,4 @@ declare class PwshCompletion {
 }
 
 export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, createBrowserCommandRuntime, createNodeCommandRuntime, 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, ICommandPresetResult, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.7.5",
+  "version": "4.7.7",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",