@guanghechen/commander 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## 4.6.0
+
+### Minor Changes
+
+- Add preset-root and command-level preset resolution for commander, align control/preset pipeline
+  behavior with spec, and include updated preset parsing and validation semantics.
+
+## 4.5.1
+
+### Patch Changes
+
+- Add built-in host and network validators (ip, domain, host), expose is helpers, and extend coerce
+  factories with port and choice support.
+
 ## 4.5.0
 
 ### Minor Changes

package/README.md

@@ -52,6 +52,8 @@
 A minimal, type-safe command-line interface builder with fluent API. Supports subcommands, option
 parsing, shell completion generation (bash, fish, pwsh), and built-in help/version handling.
 
+`opts` / `args` are designed for strong type inference from the current command's own declarations.
+
 ## Install
 
 - npm
@@ -76,7 +78,7 @@ import { Command } from '@guanghechen/commander'
 const cli = new Command({
   name: 'mycli',
   version: '1.0.0',
-  description: 'My awesome CLI tool',
+  desc: 'My awesome CLI tool',
 })
 
 cli
@@ -84,25 +86,27 @@ cli
     long: 'verbose',
     short: 'v',
     type: 'boolean',
-    description: 'Enable verbose output',
+    args: 'none',
+    desc: 'Enable verbose output',
   })
   .option({
     long: 'output',
     short: 'o',
     type: 'string',
-    description: 'Output file path',
+    args: 'required',
+    desc: 'Output file path',
     default: './output.txt',
   })
   .argument({
     name: 'file',
     kind: 'required',
-    description: 'Input file to process',
+    desc: 'Input file to process',
   })
   .action(({ opts, args, ctx }) => {
-    const [file] = args
+    const file = String(args.file)
     ctx.reporter.info(`Processing ${file}...`)
-    if (opts['verbose']) {
-      ctx.reporter.debug(`Output: ${opts['output']}`)
+    if (opts.verbose) {
+      ctx.reporter.debug(`Output: ${opts.output}`)
     }
   })
 
@@ -120,25 +124,25 @@ import { Command } from '@guanghechen/commander'
 const root = new Command({
   name: 'git',
   version: '1.0.0',
-  description: 'A simple git-like CLI',
+  desc: 'A simple git-like CLI',
 })
 
 const clone = new Command({
-  description: 'Clone a repository',
+  desc: 'Clone a repository',
 })
-  .argument({ name: 'url', kind: 'required', description: 'Repository URL' })
-  .option({ long: 'depth', type: 'number', description: 'Shallow clone depth' })
+  .argument({ name: 'url', kind: 'required', desc: 'Repository URL' })
+  .option({ long: 'depth', type: 'number', args: 'required', desc: 'Shallow clone depth' })
   .action(({ args, opts }) => {
-    console.log(`Cloning ${args[0]} with depth ${opts['depth'] ?? 'full'}`)
+    console.log(`Cloning ${args.url} with depth ${opts.depth ?? 'full'}`)
   })
 
 const commit = new Command({
-  description: 'Record changes to the repository',
+  desc: 'Record changes to the repository',
 })
-  .option({ long: 'message', short: 'm', type: 'string', required: true, description: 'Commit message' })
-  .option({ long: 'amend', type: 'boolean', description: 'Amend previous commit' })
+  .option({ long: 'message', short: 'm', type: 'string', args: 'required', required: true, desc: 'Commit message' })
+  .option({ long: 'amend', type: 'boolean', args: 'none', desc: 'Amend previous commit' })
   .action(({ opts }) => {
-    console.log(`Committing: ${opts['message']}`)
+    console.log(`Committing: ${opts.message}`)
   })
 
 root.subcommand('clone', clone).subcommand('commit', commit).subcommand('ci', commit)
@@ -154,7 +158,7 @@ import { Command, CompletionCommand } from '@guanghechen/commander'
 const root = new Command({
   name: 'mycli',
   version: '1.0.0',
-  description: 'My CLI with completion support',
+  desc: 'My CLI with completion support',
 })
 
 // Add completion subcommand
@@ -171,37 +175,89 @@ root.subcommand('completion', new CompletionCommand(root))
 ```typescript
 import { Command } from '@guanghechen/commander'
 
-new Command({ name: 'example', description: 'Option types demo' })
+new Command({ name: 'example', desc: 'Option types demo' })
   // Boolean (flags)
-  .option({ long: 'debug', type: 'boolean', description: 'Enable debug mode' })
+  .option({ long: 'debug', type: 'boolean', args: 'none', desc: 'Enable debug mode' })
 
   // String with choices
   .option({
     long: 'format',
     type: 'string',
+    args: 'required',
     choices: ['json', 'yaml', 'toml'],
     default: 'json',
-    description: 'Output format'
+    desc: 'Output format'
   })
 
   // Number
-  .option({ long: 'port', type: 'number', default: 3000, description: 'Server port' })
+  .option({ long: 'port', type: 'number', args: 'required', default: 3000, desc: 'Server port' })
 
-  // Array (can be specified multiple times)
-  .option({ long: 'include', type: 'string[]', description: 'Files to include' })
+  // Array (generated by variadic args, not a standalone type)
+  .option({ long: 'include', type: 'string', args: 'variadic', desc: 'Files to include' })
 
   // Required option
-  .option({ long: 'config', type: 'string', required: true, description: 'Config file' })
+  .option({ long: 'config', type: 'string', args: 'required', required: true, desc: 'Config file' })
 
   // Custom coercion
   .option({
     long: 'date',
     type: 'string',
+    args: 'required',
     coerce: (value) => new Date(value),
-    description: 'Date value',
+    desc: 'Date value',
   })
 ```
 
+### Planned: Preset Input Files
+
+> This is a proposed feature and not released yet.
+> README is an overview only. Authoritative semantics are defined in `packages/commander/spec/*.md`.
+
+The proposed `--preset-opts=<file>` and `--preset-envs=<file>` flags allow injecting preset argv and
+env inputs before normal CLI parsing.
+
+```bash
+mycli --preset-opts=./options.argv --preset-envs=./preset.env --log-level debug --color
+```
+
+Proposed behavior:
+
+1. Route command chain from user argv (name/alias only, no argv rewrite), then store route tokens in `sources.user.cmds`.
+2. Run `control-scan` on user tail argv before preset merge: detect `--help` / `--version` by token scan (`--version` only when `supportsBuiltinVersion(leaf)`), detect `help` only when it is the first tail token, write `ctx.controls`, and strip control tokens from parse input.
+3. In `run()`, execute `run-control` before preset merge: short-circuit by `help > version`. If short-circuit hits, preset files are not loaded.
+4. Scan preset directives before `--`, remove them from control-tail argv, and store cleaned tokens in `sources.user.argv`.
+5. Read options preset file(s) and tokenize by whitespace to `sources.preset.argv`.
+6. Read env preset file(s) and parse via `@guanghechen/env.parse` to `sources.preset.envs`.
+7. Build `effectiveTailArgv = [...sources.preset.argv, ...sources.user.argv]`.
+8. Build `ctx.envs = { ...sources.user.envs, ...sources.preset.envs }`.
+9. Expose source snapshots through `ctx.sources` and reuse existing tokenize/resolve/parse pipeline.
+
+Proposed precedence for same option key:
+
+1. User CLI tokens (highest)
+2. Tokens loaded from `--preset-opts`
+3. Option `default` / implicit defaults
+4. `NO_COLOR` fallback for color rendering only (applies only when no explicit `--color/--no-color` token appears)
+
+Proposed precedence for same env key:
+
+1. Key-values loaded from `--preset-envs` (highest)
+2. User envs (e.g. `process.env`)
+
+Additional notes:
+
+1. `variadic` options append in appearance order.
+2. `NO_COLOR` is evaluated from `ctx.envs` and remains a fallback only when no color token is explicitly provided.
+3. The `--preset-opts` file is expected to contain option fragments (`-x`/`--xxx` and their values), not command-route tokens.
+4. The `--preset-envs` file must be parseable by `@guanghechen/env`.
+5. Only preset flags before `--` are processed; after `--` they are treated as normal args.
+6. Repeated preset flags are processed in appearance order.
+7. Built-in control semantics recognize `--help` / `help` / `--version` only (no short aliases).
+8. `long: 'help'` and `long: 'version'` are reserved and must not be user-defined in `.option()`.
+9. `--help` / `help` / `--version` are forbidden in `--preset-opts` files; loading should fail fast.
+10. `--` is forbidden inside `--preset-opts` files; loading should fail fast.
+11. `parse()` never executes control handlers; it only records control hits in `ctx.controls`.
+
 ### Built-in Coerce Factories
 
 ```typescript
@@ -229,6 +285,41 @@ new Command({ name: 'example', desc: 'Coerce demo' })
     coerce: Coerce.positiveNumber('--duration'),
     desc: 'Duration in seconds',
   })
+  .option({
+    long: 'port',
+    type: 'number',
+    args: 'required',
+    coerce: Coerce.port('--port'),
+    desc: 'Server port',
+  })
+  .option({
+    long: 'domain',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.domain('--domain'),
+    desc: 'Domain name',
+  })
+  .option({
+    long: 'ip',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.ip('--ip'),
+    desc: 'IP address',
+  })
+  .option({
+    long: 'host',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.host('--host'),
+    desc: 'Host (IP or domain)',
+  })
+  .option({
+    long: 'mode',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.choice('--mode', ['dev', 'test', 'prod'] as const),
+    desc: 'Deploy mode',
+  })
   .option({
     long: 'scale',
     type: 'number',
@@ -246,6 +337,17 @@ Default error message format:
 
 You can still override the message via `Coerce.xxx(name, 'custom error message')`.
 
+### Built-in Is Helpers
+
+```typescript
+import { isDomain, isIp, isIpv4, isIpv6 } from '@guanghechen/commander'
+
+isIpv4('127.0.0.1') // true
+isIpv6('::1') // true
+isIp('2001:db8::1') // true
+isDomain('example.com') // true
+```
+
 ### Help Examples
 
 ```typescript
@@ -263,11 +365,11 @@ await cli.run({ argv: ['--help'], envs: process.env })
 
 `usage` 是相对当前 command path 的片段，help 中会自动补齐前缀，例如 `mycli build --watch`。
 
-`--color` / `--no-color` 仅控制 help 文本的终端着色；
-`--log-colorful` / `--no-log-colorful` 控制 `Reporter` 的日志着色。
+`--color` / `--no-color` 仅控制 help 文本的终端着色； `--log-colorful` / `--no-log-colorful` 控制
+`Reporter` 的日志着色。
 
-当环境变量 `NO_COLOR` 存在时，help 渲染默认视为 `--no-color`；
-显式传入 `--color` 可以覆盖这个默认值。
+当环境变量 `NO_COLOR` 存在时，help 渲染默认视为 `--no-color`；显式传入 `--color`
+可以覆盖这个默认值。
 
 ## Reference