@guanghechen/commander 4.5.1 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

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