@bemoje/cli 1.0.6 → 1.1.0

package/README.md

@@ -1,46 +1,33 @@
 # @bemoje/cli
 
-A type-safe CLI builder focused on command composition and help generation without execution coupling. Parse arguments, generate help, and integrate with existing CLI frameworks through a clean, fluent API.
+A type-safe CLI composer that can parse argv and generate help without execution coupling.
 
 ## Key Features
 
-- **🎯 Composition-Focused**: Build command structures without execution logic - parse arguments and generate help only
+- **🎯 Composition-Focused**: Build command structures without execution logic.
 - **🔒 Type-Safe**: Full TypeScript support with type inference for arguments and options
-- **🚀 Focused API**: Streamlined interface designed specifically for parsing and help generation
 - **🎨 Flexible Help**: Fork of commander.js Help class with enhanced API and adapter support
 - **✅ Validation**: Built-in CLI argument ordering validation and name conflict detection
-- **🔗 Commander.js Compatible**: Adapter allows using this Help system with existing commander.js commands
-
-## Core Philosophy
-
-While commander.js provides a comprehensive solution that combines command definition with action execution, `@bemoje/cli` takes a different approach by focusing purely on:
-
-1. **Command Structure Definition** - Define arguments, options, and subcommands
-2. **Argument Parsing** - Parse `process.argv` into structured data
-3. **Help Generation** - Render formatted help text with customizable styling
-
-This separation of concerns allows for architectures where CLI parsing logic is decoupled from business logic, making it ideal for scenarios where you want to handle argument parsing and action execution in separate layers.
 
 ## Quick Start
 
 ```ts
 import { Command } from '@bemoje/cli'
 
-// Define command structure
 const cmd = new Command('myapp')
   .setVersion('1.0.0')
   .setDescription('My awesome CLI application')
-  .argument('<input>', 'Input file path')
-  .argument('[output]', 'Output file path', { defaultValue: 'out.txt' })
-  .option('-v, --verbose', 'Enable verbose output')
-  .option('-f, --format <type>', 'Output format', { choices: ['json', 'xml', 'yaml'] })
-
-// Parse command line arguments
-const result = cmd.parse(process.argv.slice(2))
+  .addArgument('<input>', 'Input file path')
+  .addArgument('[output]', 'Output file path', { defaultValue: 'out.txt' })
+  .addOption('-v, --verbose', 'Enable verbose output')
+  .addOption('-f, --format <type>', 'Output format', { choices: ['json', 'xml', 'yaml'] })
 
-console.log('Arguments:', result.arguments) // ['input.txt', 'out.txt']
-console.log('Options:', result.options) // { verbose: true, format: 'json' }
-console.log('Command:', result.command.name) // 'myapp'
+console.log(cmd.parseArgv(['input.txt', '-v', '-f', 'json']))
+// {
+//   command: [Getter],
+//   arguments: [ 'input.txt', 'out.txt' ],
+//   options: { verbose: true, format: 'json' }
+// }
 ```
 
 ## Command Definition
@@ -61,40 +48,40 @@ Arguments follow strict ordering rules: required → optional → variadic
 
 ```ts
 // Required argument
-cmd.argument('<input>', 'Input file path')
+cmd.addArgument('<input>', 'Input file path')
 
 // Optional argument with default
-cmd.argument('[output]', 'Output file path', { defaultValue: 'dist/output.txt' })
+cmd.addArgument('[output]', 'Output file path', { defaultValue: 'dist/output.txt' })
 
 // Required variadic (multiple values)
-cmd.argument('<files...>', 'Multiple input files')
+cmd.addArgument('<files...>', 'Multiple input files')
 
 // Optional variadic with defaults
-cmd.argument('[patterns...]', 'Glob patterns', { defaultValue: ['**/*.js'] })
+cmd.addArgument('[patterns...]', 'Glob patterns', { defaultValue: ['**/*.js'] })
 ```
 
 ### Options (Named Parameters)
 
 ```ts
 // Boolean flag
-cmd.option('-v, --verbose', 'Enable verbose output')
+cmd.addOption('-v, --verbose', 'Enable verbose output')
 
 // Required string option
-cmd.option('-f, --format <type>', 'Output format')
+cmd.addOption('-f, --format <type>', 'Output format')
 
 // Optional string option with default
-cmd.option('-o, --output [path]', 'Output directory', { defaultValue: 'dist' })
+cmd.addOption('-o, --output [path]', 'Output directory', { defaultValue: 'dist' })
 
 // Required variadic option
-cmd.option('-i, --include <patterns...>', 'Include patterns')
+cmd.addOption('-i, --include <patterns...>', 'Include patterns')
 
 // Optional variadic option with defaults
-cmd.option('-e, --exclude [patterns...]', 'Exclude patterns', {
+cmd.addOption('-e, --exclude [patterns...]', 'Exclude patterns', {
   defaultValue: ['node_modules', '.git'],
 })
 
 // Option with choices and environment variable
-cmd.option('-l, --log-level [level]', 'Log level', {
+cmd.addOption('-l, --log-level [level]', 'Log level', {
   choices: ['error', 'warn', 'info', 'debug'],
   defaultValue: 'info',
   env: 'LOG_LEVEL',
@@ -106,12 +93,12 @@ cmd.option('-l, --log-level [level]', 'Log level', {
 Options defined on parent commands are available to subcommands:
 
 ```ts
-const app = new Command('myapp').option('-c, --config <file>', 'Config file')
+const app = new Command('myapp').addOption('-c, --config <file>', 'Config file')
 
-app.subcommand('build').option('-w, --watch', 'Watch mode')
+app.addSubcommand('build').addOption('-w, --watch', 'Watch mode')
 
 // Both --config and --watch are available to 'build' subcommand
-const result = app.parse(['build', '--config', 'myconfig.json', '--watch'])
+const result = app.parseArgv(['build', '--config', 'myconfig.json', '--watch'])
 ```
 
 ### Subcommands
@@ -121,47 +108,23 @@ const cmd = new Command('git')
 
 // Create subcommand
 const add = cmd
-  .subcommand('add')
+  .addSubcommand('add')
   .setDescription('Add files to staging area')
-  .argument('<files...>', 'Files to add')
-  .option('-A, --all', 'Add all files')
+  .addArgument('<files...>', 'Files to add')
+  .addOption('-A, --all', 'Add all files')
 
 const commit = cmd
-  .subcommand('commit')
+  .addSubcommand('commit')
   .setDescription('Create a commit')
-  .argument('[message]', 'Commit message')
-  .option('-m, --message <msg>', 'Commit message')
-  .option('-a, --all', 'Commit all changes')
+  .addArgument('[message]', 'Commit message')
+  .addOption('-m, --message <msg>', 'Commit message')
+  .addOption('-a, --all', 'Commit all changes')
 
 // Parsing automatically routes to subcommands
-const result = cmd.parse(['add', 'file1.js', 'file2.js', '-A'])
+const result = cmd.parseArgv(['add', 'file1.js', 'file2.js', '-A'])
 // result.command === add subcommand instance
 ```
 
-## Parsing Results
-
-The `parse()` method returns a structured result:
-
-```ts
-interface ParseResult {
-  command: Command // The command that was executed (handles subcommands)
-  arguments: unknown[] // Parsed positional arguments
-  options: Record<string, unknown> // Parsed options/flags
-}
-```
-
-### Argument Types
-
-- **Single values**: `string`
-- **Optional with defaults**: `string` (default applied if not provided)
-- **Variadic**: `string[]` (array of values)
-
-### Option Types
-
-- **Boolean flags**: `boolean`
-- **String options**: `string`
-- **Variadic options**: `string[]`
-
 ## Help System
 
 ### Rendering Help
@@ -169,15 +132,15 @@ interface ParseResult {
 ```ts
 import { Help } from '@bemoje/cli'
 
-// Use default help formatting
-console.log(cmd.renderHelp())
+// Use help formatting (requires Help instance)
+const help = new Help()
+console.log(cmd.renderHelp(help))
 
 // Customize help configuration
 const customHelp = new Help()
 customHelp.helpWidth = 100
 customHelp.sortOptions = true
 customHelp.showGlobalOptions = true
-
 console.log(cmd.renderHelp(customHelp))
 ```
 
@@ -218,68 +181,6 @@ class ColoredHelp extends Help {
 console.log(cmd.renderHelp(new ColoredHelp()))
 ```
 
-## Commander.js Integration
-
-Use the enhanced Help system with existing commander.js commands:
-
-```ts
-import { Command } from 'commander'
-import { CommanderHelpAdapter } from '@bemoje/cli'
-
-// Existing commander.js command
-const commanderCmd = new Command('example')
-  .description('Example commander.js command')
-  .option('-v, --verbose', 'verbose output')
-
-// Use enhanced help system
-const adapter = new CommanderHelpAdapter(commanderCmd)
-console.log(adapter.renderHelp())
-```
-
-## Custom Adapters
-
-You can create your own adapters for any command system by implementing the `ICommandHelp` interface. This allows you to use the enhanced Help system with any CLI library or custom command structure.
-
-### Creating Custom Adapters
-
-**Example**: Adapter for a hypothetical CLI library:
-
-```ts
-import { ICommandHelp, IHelp, Help, renderHelp } from '@bemoje/cli'
-
-class MyAdapter implements ICommandHelp {
-  constructor(private cmd: SomeOtherCliCommand) {}
-
-  // implement ICommandHelp interface methods
-  get name() {
-    return this.cmd.getName()
-  }
-  get commands() {
-    return this.cmd.getSubcommands().map((sub) => {
-      return new MyAdapter(sub)
-    })
-  }
-  get options() {
-    return this.cmd.getOptions().map((opt) => ({
-      flags: opt.flags,
-      //... map props
-    }))
-  }
-  // etc...
-}
-
-const myCommand = new SomeOtherCliCommand('myapp')
-const adapter = new MyAdapter(myCommand)
-console.log(renderHelp(adapter, new Help()))
-```
-
-This pattern allows you to:
-
-- **Bridge Different CLI Libraries**: Use the enhanced Help system with any command framework
-- **Migrate Gradually**: Introduce better help formatting without rewriting existing commands
-- **Standardize Help Output**: Consistent help formatting across different CLI tools in your project
-- **Extend Legacy Systems**: Add modern help features to older CLI codebases
-
 ## Validation
 
 Commands automatically validate:
@@ -287,51 +188,38 @@ Commands automatically validate:
 - Argument ordering (required before optional before variadic)
 
 ```ts
-cmd.argument('[optional]', 'Optional arg').argument('<required>', 'Required arg')
+cmd.addArgument('[optional]', 'Optional arg').addArgument('<required>', 'Required arg')
 //=> ❌ Error!
 ```
 
 - Unique option names and short flags, including globals across parent/child commands
 
 ```ts
-cmd.option('-v, --verbose', 'Verbose output').option('-v, --video', 'Video mode')
+cmd.addOption('-v, --verbose', 'Verbose output').addOption('-v, --video', 'Video mode')
 //=> ❌ Error!
 ```
 
 - Single variadic argument per command
 
 ```ts
-cmd.argument('<files...>', 'First variadic').argument('<more...>', 'Second variadic')
+cmd.addArgument('<files...>', 'First variadic').addArgument('<more...>', 'Second variadic')
 //=> ❌ Error!
 ```
 
-## State Management
-
-Commands can be serialized and restored:
-
-```ts
-// Serialize command configuration
-const state = cmd.toJSON()
-
-// Restore from state
-const restoredCmd = new Command('temp')
-restoredCmd.setState(state)
-```
-
 ## Command Class
 
 **Constructor**:
 
 ```ts
-- new Command(name: string, parent?: Command)
+- new (name: string, parent?: Command): Command
 ```
 
 **Structure Methods**:
 
 ```ts
-- argument(usage, description, options?): this
-- option(usage, description, options?): this
-- subcommand(name: string): Command
+- addArgument(usage, description, options?): this
+- addOption(usage, description, options?): this
+- addSubcommand(name: string): Command
 ```
 
 **Configuration Methods**:
@@ -353,6 +241,6 @@ restoredCmd.setState(state)
 **Parsing & Help**:
 
 ```ts
-- parse(argv?: string[], globalOptions?: OptionDescriptor[]): ParseResult
-- renderHelp(help?: IHelp): string
+- parseArgv(argv?: string[], globalOptions?: OptionDescriptor[]): ParseResult
+- renderHelp(help: IHelp): string
 ```

package/index.d.ts

@@ -1,6 +1,3 @@
 export * from './lib/Command';
-export * from './lib/CommandHelpAdapter';
-export * from './lib/CommanderHelpAdapter';
 export * from './lib/Help';
-export * from './lib/renderHelp';
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,6 +1,3 @@
 export * from "./lib/Command.js";
-export * from "./lib/CommandHelpAdapter.js";
-export * from "./lib/CommanderHelpAdapter.js";
 export * from "./lib/Help.js";
-export * from "./lib/renderHelp.js";
 //# sourceMappingURL=index.js.map