@guanghechen/commander 1.0.12 → 2.1.0

package/CHANGELOG.md

@@ -1,115 +1,33 @@
 # Change Log
 
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+All notable changes to this project will be documented in this file. See
+[Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## <small>1.0.12 (2025-08-29)</small>
+## 2.1.0 (2025-02-08)
 
-* improve: refine READMEs ([c41c1f2](https://github.com/guanghechen/node-scaffolds/commit/c41c1f2))
-* :wrench: chore: upgrade dependencies & update the node requirement from ([8ddfde1](https://github.com/guanghechen/node-scaffolds/commit/8ddfde1))
+### Features
 
+- Add `--write` option to `CompletionCommand` for direct file output
+- Add `help` subcommand support for commands with subcommands
+- Detect `--help`/`--version` before parsing to avoid required argument errors
+- Add `#normalizeArgv()` preprocessing to simplify `--no-*` option handling
+- Add `implements ICommand` for explicit interface implementation
 
+## 2.0.1 (2025-02-07)
 
+### Documentation
 
+- Update README.md
 
-## <small>1.0.11 (2025-07-04)</small>
+### Miscellaneous
 
-* :bookmark:  release ([2313a96](https://github.com/guanghechen/node-scaffolds/commit/2313a96))
-* :bookmark:  release ([fbef5fd](https://github.com/guanghechen/node-scaffolds/commit/fbef5fd))
-* :wrench: chore: upgrade dependencies ([8623304](https://github.com/guanghechen/node-scaffolds/commit/8623304))
-* chore: upgrade dependencies ([a5b7a87](https://github.com/guanghechen/node-scaffolds/commit/a5b7a87))
+- Add LICENSE file
+- Clean up build configs and standardize package exports
+- Migrate from lerna to changesets
 
+## 2.0.0 (2025-01-15)
 
+### Features
 
+- Initial stable release: A minimal, type-safe command-line interface builder with fluent API
 
-
-## <small>1.0.10 (2025-03-30)</small>
-
-* chore: upgrade dependencies ([a5b7a87](https://github.com/guanghechen/node-scaffolds/commit/a5b7a87))
-
-
-
-
-
-## <small>1.0.9 (2025-02-26)</small>
-
-* :bookmark:  release ([9d47297](https://github.com/guanghechen/node-scaffolds/commit/9d47297))
-* chore: sharp dependencies ([914ba6f](https://github.com/guanghechen/node-scaffolds/commit/914ba6f))
-
-
-
-
-
-## <small>1.0.8 (2025-02-26)</small>
-
-* chore: sharp dependencies ([914ba6f](https://github.com/guanghechen/node-scaffolds/commit/914ba6f))
-* chore: upgrade devDependencies ([ca5de6d](https://github.com/guanghechen/node-scaffolds/commit/ca5de6d))
-* :bookmark:  release ([6fe5681](https://github.com/guanghechen/node-scaffolds/commit/6fe5681))
-
-
-
-
-
-## <small>1.0.7 (2025-02-07)</small>
-
-* chore: upgrade devDependencies ([ca5de6d](https://github.com/guanghechen/node-scaffolds/commit/ca5de6d))
-* :arrow_up: chore: upgrade dependencies & no longer rely on globby since it breaking build ([b5d0fdd](https://github.com/guanghechen/node-scaffolds/commit/b5d0fdd))
-* :bookmark:  release ([6524942](https://github.com/guanghechen/node-scaffolds/commit/6524942))
-
-
-
-
-
-## <small>1.0.6 (2025-01-09)</small>
-
-* :arrow_up: chore: upgrade dependencies & no longer rely on globby since it breaking build ([b5d0fdd](https://github.com/guanghechen/node-scaffolds/commit/b5d0fdd))
-
-
-
-
-
-## <small>1.0.5 (2024-10-03)</small>
-
-* :arrow_up:  chore: upgrade dependencies ([ba63623](https://github.com/guanghechen/node-scaffolds/commit/ba63623))
-
-
-
-
-
-## <small>1.0.4 (2024-10-03)</small>
-
-* :arrow_up:  chore: upgrade dependencies ([e41de75](https://github.com/guanghechen/node-scaffolds/commit/e41de75))
-* :wrench:  chore: don't gen sourcemap in production env ([f7075d1](https://github.com/guanghechen/node-scaffolds/commit/f7075d1))
-
-
-
-
-
-## <small>1.0.3 (2024-09-29)</small>
-
-**Note:** Version bump only for package @guanghechen/commander
-
-
-
-
-
-## <small>1.0.2 (2024-09-29)</small>
-
-* :art:  improve(commander): remove unnecessary third-party dependencies ([d5cb553](https://github.com/guanghechen/node-scaffolds/commit/d5cb553))
-
-
-
-
-
-## <small>1.0.1 (2024-09-28)</small>
-
-* :art:  improve: reuse @guanghechen/cli ([6c8e6a0](https://github.com/guanghechen/node-scaffolds/commit/6c8e6a0))
-* :wrench:  chore: fix publish issues ([7316526](https://github.com/guanghechen/node-scaffolds/commit/7316526))
-
-
-
-
-
-## <small>1.0.1 (2024-09-28)</small>
-
-* :art:  improve: reuse @guanghechen/cli ([6c8e6a0](https://github.com/guanghechen/node-scaffolds/commit/6c8e6a0))

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2023 guanghechen (https://github.com/guanghechen)
+Copyright (c) 2023-present guanghechen (https://github.com/guanghechen)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 <header>
   <h1 align="center">
-    <a href="https://github.com/guanghechen/node-scaffolds/tree/@guanghechen/commander@1.0.12/packages/commander#readme">@guanghechen/commander</a>
+    <a href="https://github.com/guanghechen/sora/tree/@guanghechen/commander@1.0.0/packages/commander#readme">@guanghechen/commander</a>
   </h1>
   <div align="center">
     <a href="https://www.npmjs.com/package/@guanghechen/commander">
@@ -33,12 +33,6 @@
         src="https://img.shields.io/node/v/@guanghechen/commander"
       />
     </a>
-    <a href="https://github.com/facebook/jest">
-      <img
-        alt="ESLint Version"
-        src="https://img.shields.io/npm/dependency-version/@guanghechen/commander/peer/jest"
-      />
-    </a>
     <a href="https://github.com/facebook/jest">
       <img
         alt="Tested with Jest"
@@ -55,247 +49,165 @@
 </header>
 <br/>
 
-Utility functions for creating command program tools based on [commander.js][].
+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.
 
 ## Install
 
-* npm
+- npm
 
   ```bash
-  npm install --save-dev @guanghechen/commander
+  npm install --save @guanghechen/commander
   ```
 
-* yarn
+- yarn
 
   ```bash
-  yarn add --dev @guanghechen/commander
+  yarn add @guanghechen/commander
   ```
 
 ## Usage
 
-This package extends [commander.js][] with enhanced functionality for building CLI applications with configuration management and sub-command support.
-
-### Enhanced Command Class
-
-```typescript
-import { Command, type ICommandActionCallback } from '@guanghechen/commander'
-
-interface IMyOptions extends ICommandConfigurationOptions {
-  readonly input: string
-  readonly output: string
-}
-
-const command = new Command()
-  .name('my-tool')
-  .description('My awesome CLI tool')
-  .action<IMyOptions>((args, options, extra, self) => {
-    console.log('Arguments:', args)
-    console.log('Options:', options)
-    console.log('Extra args:', extra)
-  })
-```
-
-### Creating Top-Level Commands
+### Basic Command
 
 ```typescript
-import { createTopCommand } from '@guanghechen/commander'
+import { Command } from '@guanghechen/commander'
 
-const program = createTopCommand('my-cli', '1.0.0')
-// The command comes pre-configured with:
-// - Configuration file options (--config-path, --parastic-config-path, etc.)
-// - Logging options (--log-level, --log-encoding, etc.)
-// - Workspace option (--workspace)
-```
-
-### Main Command Utilities
-
-```typescript
-import {
-  createMainCommandMounter,
-  createMainCommandExecutor,
-  type IMainCommandProcessor,
-  type IMainCommandCreator
-} from '@guanghechen/commander'
-
-// Define your main command processor
-const processor: IMainCommandProcessor<IMyOptions> = async (options) => {
-  console.log('Processing with options:', options)
-}
-
-// Create a command creator
-const creator: IMainCommandCreator<IMyOptions> = (handle) => {
-  return new Command()
-    .name('build')
-    .description('Build the project')
-    .action(handle ? (opts) => handle(opts) : () => {})
-}
-
-// Create and use a mounter for adding to parent command
-const mounter = createMainCommandMounter(creator, processor)
-mounter(program)
-
-// Or create an executor for direct execution
-const executor = createMainCommandExecutor(creator, processor)
-await executor(process.argv)
-```
-
-### Sub-Command Architecture
+const cli = new Command({
+  name: 'mycli',
+  version: '1.0.0',
+  description: 'My awesome CLI tool',
+})
 
-```typescript
-import { SubCommand, type ISubCommandOptions, type ISubCommandProcessor } from '@guanghechen/commander'
-
-interface IBuildOptions extends ISubCommandOptions {
-  readonly target: string
-  readonly production: boolean
-}
-
-class BuildCommand extends SubCommand<IBuildOptions> {
-  public readonly subCommandName = 'build'
-  public readonly aliases = ['b']
-
-  public command(processor: ISubCommandProcessor<IBuildOptions>): Command {
-    return new Command()
-      .name(this.subCommandName)
-      .aliases(this.aliases)
-      .description('Build the project')
-      .option('--target <target>', 'Build target', 'development')
-      .option('--production', 'Production build', false)
-      .action(async (args, options, extra) => {
-        await processor.process(args, options)
-      })
-  }
-
-  public async resolveProcessor(args: string[], options: IBuildOptions): Promise<ISubCommandProcessor<IBuildOptions>> {
-    return {
-      process: async (args, options) => {
-        console.log(`Building for ${options.target}`)
-        if (options.production) {
-          console.log('Production mode enabled')
-        }
-      }
+cli
+  .option({
+    long: 'verbose',
+    short: 'v',
+    type: 'boolean',
+    description: 'Enable verbose output',
+  })
+  .option({
+    long: 'output',
+    short: 'o',
+    type: 'string',
+    description: 'Output file path',
+    default: './output.txt',
+  })
+  .argument({
+    name: 'file',
+    kind: 'required',
+    description: 'Input file to process',
+  })
+  .action(({ opts, args, ctx }) => {
+    const [file] = args
+    ctx.reporter.info(`Processing ${file}...`)
+    if (opts['verbose']) {
+      ctx.reporter.debug(`Output: ${opts['output']}`)
     }
-  }
-}
+  })
 
-// Usage
-const buildCmd = new BuildCommand()
-buildCmd.mount(program, { isDefault: false })
+cli.run({
+  argv: process.argv.slice(2),
+  envs: process.env,
+})
 ```
 
-### Utility Functions
+### Subcommands
 
 ```typescript
-import { hasGitInstalled, installDependencies } from '@guanghechen/commander'
-
-// Check if Git is available
-if (hasGitInstalled()) {
-  console.log('Git is available')
-}
-
-// Install dependencies with user selection
-await installDependencies({
-  cwd: process.cwd(),
-  plopBypass: [], // Or ['yarn'] to skip user prompt
-  reporter: myReporter
-})
-```
+import { Command } from '@guanghechen/commander'
 
-## API Reference
+const root = new Command({
+  name: 'git',
+  version: '1.0.0',
+  description: 'A simple git-like CLI',
+})
 
-| Name | Signature | Description |
-|------|-----------|-------------|
-| `Command` | Class | Enhanced version with improved TypeScript support |
-| `SubCommand` | `abstract class SubCommand<O>` | Abstract base class for implementing sub-commands with configuration support |
-| `createTopCommand` | `(commandName: string, version: string) => Command` | Creates a top-level command with pre-configured common options |
-| `createMainCommandMounter` | `<O>(creator, handle) => IMainCommandMounter` | Creates a function for mounting main commands to parent commands |
-| `createMainCommandExecutor` | `<O>(creator, handle) => IMainCommandExecutor` | Creates a function for executing main commands directly |
-| `hasGitInstalled` | `() => boolean` | Checks if Git is installed and available in PATH |
-| `installDependencies` | `(params) => Promise<void>` | Prompts user to install dependencies using npm or yarn |
+const clone = new Command({
+  name: 'clone',
+  description: 'Clone a repository',
+})
+  .argument({ name: 'url', kind: 'required', description: 'Repository URL' })
+  .option({ long: 'depth', type: 'number', description: 'Shallow clone depth' })
+  .action(({ args, opts }) => {
+    console.log(`Cloning ${args[0]} with depth ${opts['depth'] ?? 'full'}`)
+  })
 
-### Detailed Interfaces
+const commit = new Command({
+  name: 'commit',
+  aliases: ['ci'],
+  description: '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' })
+  .action(({ opts }) => {
+    console.log(`Committing: ${opts['message']}`)
+  })
 
-#### `Command` Class Methods
+root.subcommand(clone).subcommand(commit)
 
-```typescript
-class Command {
-  action<T>(fn: ICommandActionCallback<T>): this  // Register action callback with enhanced type safety
-  opts<T>(): T                                   // Get options with proper type inference
-}
+root.run({ argv: process.argv.slice(2), envs: process.env })
 ```
 
-#### `SubCommand<O>` Abstract Class
+### Shell Completion
 
 ```typescript
-abstract class SubCommand<O extends ISubCommandOptions> {
-  // Abstract properties
-  abstract readonly subCommandName: string      // The name of the sub-command
-  abstract readonly aliases: string[]           // Command aliases
-
-  // Abstract methods
-  abstract command(processor: ISubCommandProcessor<O>): Command
-  abstract resolveProcessor(args: string[], options: O): Promise<ISubCommandProcessor<O>>
-
-  // Instance methods
-  mount(parentCommand: Command, opts?: { isDefault?: boolean }): void
-  execute(parentCommand: Command, rawArgs: string[]): Promise<void>
-  process(args: string[], options: O): Promise<void>
-}
-```
+import { Command, CompletionCommand } from '@guanghechen/commander'
 
-#### `createTopCommand` Pre-configured Options
+const root = new Command({
+  name: 'mycli',
+  version: '1.0.0',
+  description: 'My CLI with completion support',
+})
 
-The command comes with these built-in options:
+// Add completion subcommand
+root.subcommand(new CompletionCommand(root))
 
-```typescript
---config-path, -c          // Configuration file paths
---parastic-config-path     // Parasitic configuration file path
---parastic-config-entry    // Entry key in parasitic config
---workspace               // Working directory
---log-level              // Logging level
---log-encoding           // Log file encoding
---log-filepath           // Log file path
---log-name              // Logger name
---log-mode              // Log format mode
---log-flight            // Logger flight options
+// Generate completion scripts:
+// mycli completion --bash > ~/.local/share/bash-completion/completions/mycli
+// mycli completion --fish > ~/.config/fish/completions/mycli.fish
+// mycli completion --pwsh >> $PROFILE
 ```
 
-#### `installDependencies` Parameters
+### Option Types
 
 ```typescript
-interface IInstallDependenciesParams {
-  cwd: string                    // Working directory
-  plopBypass: string[]          // Pre-selected choices to bypass prompts
-  reporter?: IReporter          // Optional logger
-}
-```
+import { Command } from '@guanghechen/commander'
+
+new Command({ name: 'example', description: 'Option types demo' })
+  // Boolean (flags)
+  .option({ long: 'debug', type: 'boolean', description: 'Enable debug mode' })
+
+  // String with choices
+  .option({
+    long: 'format',
+    type: 'string',
+    choices: ['json', 'yaml', 'toml'],
+    default: 'json',
+    description: 'Output format'
+  })
 
-#### Type Definitions
+  // Number
+  .option({ long: 'port', type: 'number', default: 3000, description: 'Server port' })
 
-```typescript
-// Action callback function signature
-type ICommandActionCallback<T> = (
-  args: string[],
-  options: T,
-  extra: string[],
-  self: Command,
-) => void | Promise<void> | never
-
-// Sub-command processor interface
-interface ISubCommandProcessor<O> {
-  process(args: string[], options: O): Promise<void>
-}
-
-// Base interface for sub-command options
-interface ISubCommandOptions extends ICommandConfigurationOptions {
-  // Inherits all configuration options
-}
-```
+  // Array (can be specified multiple times)
+  .option({ long: 'include', type: 'string[]', description: 'Files to include' })
 
-## Related
+  // Required option
+  .option({ long: 'config', type: 'string', required: true, description: 'Config file' })
 
-* [commander.js][]
+  // Custom coercion
+  .option({
+    long: 'date',
+    type: 'string',
+    coerce: (value) => new Date(value),
+    description: 'Date value',
+  })
+```
 
+## Reference
 
-[homepage]: https://github.com/guanghechen/node-scaffolds/tree/@guanghechen/commander@1.0.12/packages/commander#readme
-[commander.js]: https://github.com/tj/commander.js/
+- [homepage][homepage]
 
+[homepage]:
+  https://github.com/guanghechen/sora/tree/@guanghechen/commander@1.0.0/packages/commander#readme