@guanghechen/commander 1.0.11 → 2.0.1

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.11/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,29 +49,165 @@
 </header>
 <br/>
 
-
-Utility functions for creating command programs 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
+
+### Basic Command
+
+```typescript
+import { Command } from '@guanghechen/commander'
+
+const cli = new Command({
+  name: 'mycli',
+  version: '1.0.0',
+  description: 'My awesome CLI tool',
+})
+
+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']}`)
+    }
+  })
+
+cli.run({
+  argv: process.argv.slice(2),
+  envs: process.env,
+})
+```
+
+### Subcommands
+
+```typescript
+import { Command } from '@guanghechen/commander'
+
+const root = new Command({
+  name: 'git',
+  version: '1.0.0',
+  description: 'A simple git-like CLI',
+})
+
+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'}`)
+  })
+
+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']}`)
+  })
+
+root.subcommand(clone).subcommand(commit)
+
+root.run({ argv: process.argv.slice(2), envs: process.env })
+```
+
+### Shell Completion
+
+```typescript
+import { Command, CompletionCommand } from '@guanghechen/commander'
+
+const root = new Command({
+  name: 'mycli',
+  version: '1.0.0',
+  description: 'My CLI with completion support',
+})
+
+// Add completion subcommand
+root.subcommand(new CompletionCommand(root))
+
+// Generate completion scripts:
+// mycli completion --bash > ~/.local/share/bash-completion/completions/mycli
+// mycli completion --fish > ~/.config/fish/completions/mycli.fish
+// mycli completion --pwsh >> $PROFILE
+```
+
+### Option Types
+
+```typescript
+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'
+  })
+
+  // Number
+  .option({ long: 'port', type: 'number', default: 3000, description: 'Server port' })
+
+  // 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.11/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