bob-core 2.0.0-beta.8 → 2.0.0

package/README.md

@@ -1,275 +1,440 @@
-# BOB Core - Bash Operation Buddy Core
+<div align="center">
 
-## Introduction
+```
+  ____   ____  ____
+ | __ ) / __ \| __ )
+ |  _ \| |  | |  _ \
+ | |_) | |  | | |_) |
+ |____/ \____/|____/
+```
+
+# BOB Core
+
+**Your Bash Operation Buddy** 💪
+
+*Build powerful TypeScript CLIs with type-safe commands and beautiful interactive prompts*
+
+[![npm version](https://img.shields.io/npm/v/bob-core.svg)](https://www.npmjs.com/package/bob-core)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
 
-BOB (Bash Operation Buddy) Core is a library that provides a set of functions to create your own CLI in TypeScript easily.
+[Features](#features) • [Installation](#installation) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Examples](#examples)
 
-## Usage
+</div>
+
+---
+
+## Features
+
+✨ **Type-Safe Commands** - Full TypeScript support with type inference for arguments and options  
+🎯 **Declarative API** - Define commands with simple schemas or string signatures  
+💬 **Interactive Prompts** - Built-in support for confirmations, selections, inputs, and more   
+🎨 **Beautiful Help** - Automatically generated, well-formatted help documentation  
+🔍 **Smart Suggestions** - Fuzzy matching suggests similar commands when you make typos  
+📦 **Zero Config** - Works out of the box with sensible defaults  
+🚀 **Dual Module Support** - Both CommonJS and ESM supported  
+⚡️ **Fast & Lightweight** - Minimal dependencies, maximum performance  
+
+---
+
+## Installation
 
 ```bash
 npm install bob-core
 ```
 
-Initialize the CLI:
+```bash
+yarn add bob-core
+```
+
+```bash
+pnpm add bob-core
+```
+
+---
+
+## Quick Start
+
+### Create your CLI
 
 ```typescript
-import { CLI } from 'bob-core';
+// cli.ts
+import { Cli } from 'bob-core';
 
-const cli = new CLI();
+const cli = new Cli({
+  name: 'my-cli',
+  version: '1.0.0'
+});
 
 await cli.withCommands('./commands');
 
-cli.run('commandName', 'arg1', 'arg2', 'arg3');
+const exitCode = await cli.runCommand(process.argv[2], ...process.argv.slice(3));
+process.exit(exitCode);
 ```
 
-Create a command in the `commands` folder:
+### Create a Command
 
-```typescript
-import { LegacyCommand } from 'bob-core';
-
-export default class MyCommand extends LegacyCommand {
-  public name = 'my-command {arg1} {--option1}';
-  public description = 'This is my command';
-  
-  /**
-   * Define the arguments and options help
-   *
-   * Optional
-   */
-  helpDefinition = {
-      arg1: 'This is the first argument',
-      '--option1': 'This is the first option'
-  }
+**Modern Schema-Based (Recommended):**
 
-  /**
-   * Provide examples of how to use the command
-   *
-   * Optional
-   */
-  commandsExamples = [
-      {
-            command: 'my-command value1 --option1',
-            description: 'This is an example'
-      }
-  ]
-
-  public async handle() {
-    console.log('Hello World');
-    console.log('Arguments:', this.argument('arg1'));
-    console.log('Options:', this.option('option1'));
+```typescript
+// commands/greet.ts
+import { Command } from 'bob-core';
+
+export default new Command('greet', {
+  description: 'Greet a user',
+  arguments: {
+    name: 'string'
+  },
+  options: {
+    enthusiastic: {
+      type: 'boolean',
+      alias: ['e'],
+      default: false,
+      description: 'Add enthusiasm!'
+    }
   }
-}
+}).handler((ctx, { arguments: args, options }) => {
+  const greeting = `Hello, ${args.name}${options.enthusiastic ? '!' : '.'}`;
+  console.log(greeting);
+});
 ```
 
-## Cli Help
+**Modern Class-Based:**
 
-The CLI provides a help command that displays all available commands and their descriptions.
+```typescript
+// commands/greet.ts
+import { Command, CommandHandlerOptions, OptionsSchema } from 'bob-core';
+
+const GreetOptions = {
+  enthusiastic: {
+    type: 'boolean',
+    alias: ['e'],
+    default: false,
+    description: 'Add enthusiasm!'
+  }
+} satisfies OptionsSchema;
+type GreetOptions = typeof GreetOptions;
+
+const GreetArguments = {
+  name: 'string'
+} satisfies OptionsSchema;
+type GreetArguments = typeof GreetArguments;
+
+export default class GreetCommand extends Command<any, GreetOptions, GreetArguments> {
+  constructor() {
+    super('greet', {
+      description: 'Greet a user',
+      options: GreetOptions,
+      arguments: GreetArguments
+    });
+  }
 
-```bash
-node cli.js help
+  handle(ctx: any, opts: CommandHandlerOptions<GreetOptions, GreetArguments>) {
+    const greeting = `Hello, ${opts.arguments.name}${opts.options.enthusiastic ? '!' : '.'}`;
+    console.log(greeting);
+  }
+}
 ```
 
-## Commands
-
-```bash
-Bob CLI x.x.x 💪
+**Signature-Based:**
 
-Usage:
-  command [options] [arguments]
+```typescript
+// commands/greet.ts
+import { CommandWithSignature } from 'bob-core';
 
-Available commands:
+export default class GreetCommand extends CommandWithSignature {
+  signature = 'greet {name} {--enthusiastic|-e}';
+  description = 'Greet a user';
 
-help         Show help
-test         test description
-sub:
-  sub        sub command description
-  sub:sub    sub:sub command description
+  protected async handle() {
+    const name = this.argument<string>('name');
+    const enthusiastic = this.option<boolean>('enthusiastic');
 
+    const greeting = `Hello, ${name}${enthusiastic ? '!' : '.'}`;
+    console.log(greeting);
+  }
+}
 ```
 
-## LegacyCommand help
-
-You can also display the help of a specific command.
+### Run It
 
 ```bash
-node cli.js test -h
-```
+$ node cli.js greet John
+Hello, John.
 
-```bash
+$ node cli.js greet Jane --enthusiastic
+Hello, Jane!
+
+$ node cli.js help greet
 Description:
-  test description
+  Greet a user
 
 Usage:
-  test <user> [options]
+  greet <name> [options]
 
 Arguments:
-  user                  user description
-  test                  test description [default: null]
-  test2                 [default: []] (variadic)
+  name                 (string)
 
 Options:
-  --option, -o, -b      option description (boolean) [default: false]
-  --flag                flag description (string) [default: null]
-  --arr                 arr description (array) [default: null]
-  --flag2               flag2 description (string) [default: 2]
-  --help, -h            Display help for the given command. When no command is given display help for the list command (boolean)
+  --enthusiastic, -e   Add enthusiasm! (boolean) [default: false]
+  --help, -h          Display help for the given command
+```
 
-Examples:
-  Example description 1
+---
 
-    node cli.js test yayo --option
+## Interactive Prompts
 
-  Example description 2
+Build beautiful interactive CLIs with built-in prompts:
 
-    node cli.js test anothervalue --flag=2
-```
+```typescript
+import { Command, CommandHandlerOptions, OptionsSchema } from 'bob-core';
+
+export default class SetupCommand extends Command<any, OptionsSchema, OptionsSchema> {
+  constructor() {
+    super('setup', {
+      description: 'Interactive project setup'
+    });
+  }
 
-Depending on the command, the help will display the command signature, description, arguments, options and examples. 
+  async handle(ctx: any, opts: CommandHandlerOptions<OptionsSchema, OptionsSchema>) {
+    // Text input
+    const name = await this.io.askForInput('Project name:');
+
+    // Confirmation
+    const useTypeScript = await this.io.askForConfirmation('Use TypeScript?', true);
+
+    // Selection
+    const framework = await this.io.askForSelect('Framework:', [
+      { title: 'React', value: 'react' },
+      { title: 'Vue', value: 'vue' },
+      { title: 'Svelte', value: 'svelte' }
+    ]);
+
+    // Multi-select
+    const features = await this.io.askForSelect(
+      'Features:',
+      ['ESLint', 'Prettier', 'Testing'],
+      { type: 'multiselect' }
+    );
+
+    // Spinner/loader
+    using loader = this.io.newLoader('Creating project...');
+    await createProject({ name, framework, features });
+    loader.stop();
+
+    this.io.info('✅ Project created!');
+  }
+}
+```
 
+---
 
-## Commands signature
+## Context Injection
 
-The command signature is a string that defines the command name, arguments and options.
+Pass shared dependencies and configuration to your commands:
 
-Example:    
 ```typescript
-    signature = 'my-command {arg1} {arg2} {arg3} {--option1} {--option2}';
-```
+interface AppContext {
+  config: Config;
+  database: Database;
+  logger: Logger;
+}
 
-### Arguments
+const context: AppContext = {
+  config: loadConfig(),
+  database: new Database(),
+  logger: new Logger()
+};
+
+const cli = new Cli<AppContext>({
+  ctx: context,
+  name: 'my-app',
+  version: '1.0.0'
+});
+
+// Access context in commands
+export default new Command<AppContext>('users:list', {
+  description: 'List users'
+}).handler(async (ctx) => {
+  const users = await ctx.database.getUsers();
+  users.forEach(user => console.log(user.name));
+});
+```
 
-All user supplied arguments and options are wrapped in curly braces. 
-In the following example, the command defines three **required** arguments `arg1`, `arg2` and `arg3`.
+---
 
-```typescript
-    signature = 'my-command {arg1} {arg2} {arg3}';
-```
+## Documentation
 
-You may want to make an argument optional by adding a `?` after the argument name or by providing a default value with `=`.
+📚 **[Getting Started](./docs/getting-started.md)** - Installation and first CLI  
+🔨 **[Creating Commands](./docs/creating-commands.md)** - Schema-based and signature-based approaches  
+⚙️ **[Arguments & Options](./docs/arguments-and-options.md)** - Type-safe parameters  
+💬 **[Interactive Prompts](./docs/interactive-prompts.md)** - Build interactive CLIs  
+🚀 **[Advanced Topics](./docs/advanced.md)** - Context, resolvers, error handling  
+❓ **[Help System](./docs/help-system.md)** - Customize help output  
+📖 **[API Reference](./docs/api-reference.md)** - Complete API documentation  
+💡 **[Examples](./docs/examples.md)** - Real-world examples
 
-```typescript
-    signature = 'my-command {arg1} {arg2?} {arg3=defaultValue}';
+---
 
-    handle() {
-        this.argument('arg1'); // 'value' or throw an error if not provided
-        this.argument('arg2'); // 'value' or null if not provided
-        this.argument('arg3'); // 'value' or 'defaultValue' if not provided
-    }
-```
+## Examples
 
-You can also define a variadic argument by adding `*` after the argument name.
-Variadic arguments are stored in an array.
+### Type-Safe Arguments
 
 ```typescript
-    signature = 'my-command {arg1} {arg2*}';
-
-    handle() {
-        this.argument('arg1'); // 'value1'
-        this.argument('arg2'); // ['value2', 'value3']
+export default new Command('deploy', {
+  arguments: {
+    environment: 'string',           // Required
+    region: {                        // Optional with default
+      type: 'string',
+      default: 'us-east-1',
+      required: false
     }
+  }
+}).handler((ctx, { arguments: args }) => {
+  // args.environment is string
+  // args.region is string | null
+});
 ```
 
-Variadic arguments can also be optional.
+### Variadic Arguments
 
 ```typescript
-    signature = 'my-command {arg1} {arg2*?}';
+export default new Command('delete', {
+  arguments: {
+    files: ['string']  // Array of strings
+  }
+}).handler((ctx, { arguments: args }) => {
+  // args.files is string[]
+  args.files.forEach(file => deleteFile(file));
+});
 ```
 
-### Options
-
-Options are defined by `{--optionName}`.
+### Options with Aliases
 
 ```typescript
-    signature = 'my-command {--option1} {--option2} {--option3}';
-```
+export default new Command('serve', {
+  options: {
+    port: {
+      type: 'number',
+      alias: ['p'],
+      default: 3000
+    },
+    verbose: {
+      type: 'boolean',
+      alias: ['v', 'V'],
+      default: false
+    }
+  }
+});
 
-By default options are boolean with a default value of `false`.
-You can also change the option type to string by adding `=` to the option definition.
-You can also provide a default value by adding `=value`.
+// Usage: serve --port=8080 -v
+// Usage: serve -p 8080 --verbose
+```
 
-If the value is 'true' or 'false', the option will be converted to a boolean.
+### Pre-Handlers for Validation
 
 ```typescript
-    signature = 'my-command {--option1} {--option2=true} {--option3=} {--option4=defaultValue} {--option5=}';
-
-    handle() {
-        this.option('option1'); // by default `false` and can be set to `true` by the user 
-        this.option('option2'); // by default `true` and can be set to `false` by the user
-        this.option('option3'); // by default `null` and can be set to "value" by the user
-        this.option('option4'); // by default "defaultValue" and can be set to "value" by the user
+export default new Command('deploy')
+  .preHandler(async (ctx) => {
+    if (!ctx.isAuthenticated) {
+      console.error('Not authenticated');
+      return 1;  // Stop execution
     }
+  })
+  .handler(async (ctx) => {
+    // Only runs if authenticated
+  });
 ```
 
-You can also define a variadic option by adding `*` as option value. (e.g. `{--option2=*}`)
-Variadic options are stored in an array.
+### Command Groups
 
 ```typescript
-    signature = 'my-command {--option1} {--option2=*}';
-
-    handle() {
-        this.option('option1'); // 'value1' 
-        this.option('option2'); // ['value2', 'value3'] // or [] if not provided
-    }
+// commands/db/migrate.ts
+export default new Command('db:migrate', {
+  description: 'Run migrations',
+  group: 'Database'
+});
+
+// commands/db/seed.ts
+export default new Command('db:seed', {
+  description: 'Seed database',
+  group: 'Database'
+});
+
+// Displayed as:
+// Database:
+//   db:migrate    Run migrations
+//   db:seed       Seed database
 ```
 
-## Commands I/O
+---
 
-### Arguments
+## Why BOB Core?
 
-```typescript
-    this.argument('arg1');
-```
+BOB Core makes CLI development in TypeScript a breeze:
 
-You can also provide a default value if the argument is optional.
+- **No Boilerplate** - Define commands declaratively, not imperatively
+- **Type Safety** - Catch errors at compile time, not runtime
+- **Great DX** - Intelligent auto-complete, clear error messages
+- **User Friendly** - Beautiful help, smart suggestions, interactive prompts
+- **Flexible** - Multiple command styles, extend anything
+- **Well Tested** - Comprehensive test suite with Vitest
 
-```typescript
-    this.argument('arg1', 'defaultValue');
-```
+---
 
-If you always need a boolean value, you can use the `argumentBoolean` method.
+## Supported Types
 
-```typescript
-    this.argumentBoolean('arg1');
-```
+| Type | Description | Example |
+|------|-------------|---------|
+| `'string'` | Text value | `'hello'` |
+| `'number'` | Numeric value | `42` |
+| `'boolean'` | True/false | `true` |
+| `['string']` | String array | `['a', 'b']` |
+| `['number']` | Number array | `[1, 2, 3]` |
 
-If you always need a number value, you can use the `argumentNumber` method.
+**Note:** The `secret` flag is not a type but a property of OptionDefinition.
 
-```typescript
-    this.argumentNumber('arg1');
-```
+### Secret/Masked Input
 
-If you always need a array value, you can use the `argumentArray` method.
+For sensitive input like passwords, use the `secret: true` flag in the option definition:
 
 ```typescript
-    this.argumentArray('arg1');
+options: {
+  password: {
+    type: 'string',      // Type is still 'string'
+    secret: true,        // Flag to mask input in interactive prompts
+    required: true,
+    description: 'User password'
+  }
+}
 ```
 
-### Options
+The `secret` flag masks the input when prompting interactively, making it perfect for passwords and API keys.
 
-```typescript
-    this.option('option1');
-```
+---
 
-You can also provide a default value if the option is optional.
+## Contributing
 
-```typescript
-    this.option('option1', 'defaultValue');
-```
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-If you always need a boolean value, you can use the `optionBoolean` method.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-```typescript
-    this.optionBoolean('option1');
-```
+---
 
-If you always need a number value, you can use the `optionNumber` method.
+## License
 
-```typescript
-    this.optionNumber('option1');
-```
+[ISC](LICENSE) © Léo Hubert
 
-If you always need a array value, you can use the `optionArray` method.
+---
 
-```typescript
-    this.optionArray('option1'); 
-```
+<div align="center">
+
+**[⬆ back to top](#bob-core)**
+
+Made with ❤️ by developers, for developers
+
+</div>

package/dist/cjs/package-Blqq-jZJ.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e="bob-core",t="2.0.0",s="BOB Core",i="module",n="./dist/cjs/src/index.js",r="./dist/esm/src/index.js",c="./dist/esm/src/index.d.ts",o=["dist"],d={".":{import:{types:"./dist/esm/src/index.d.ts",default:"./dist/esm/src/index.js"},require:{types:"./dist/cjs/src/index.d.ts",default:"./dist/cjs/src/index.js"}}},p={start:"node -r @swc-node/register debug/main.ts",build:"rimraf ./dist && vite build",typecheck:"tsc --noEmit",prepack:"npm run build",test:"vitest run",lint:"eslint .","lint:fix":"eslint . --fix"},l="Léo Hubert",m="ISC",a={"@eslint/js":"^9.37.0","@faker-js/faker":"^10.0.0","@swc-node/register":"^1.11.1","@trivago/prettier-plugin-sort-imports":"^5.2.2","@types/minimist":"^1.2.5","@types/node":"^20.14.5","@types/prompts":"^2.4.9","@types/string-similarity":"^4.0.2","@vitest/coverage-v8":"^3.2.4",eslint:"^9.37.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4",prettier:"^3.6.2",rimraf:"^6.0.1",tsx:"^4.20.6",typescript:"^5.9.3","typescript-eslint":"^8.46.0",vite:"^7.2.7","vite-plugin-dts":"^4.5.4",vitest:"^3.2.4"},u={chalk:"^4.1.2",minimist:"^1.2.8",prompts:"^2.4.2"},y={name:e,version:t,description:s,type:i,main:n,module:r,types:c,files:o,exports:d,scripts:p,author:l,license:m,devDependencies:a,dependencies:u};exports.author=l;exports.default=y;exports.dependencies=u;exports.description=s;exports.devDependencies=a;exports.exports=d;exports.files=o;exports.license=m;exports.main=n;exports.module=r;exports.name=e;exports.scripts=p;exports.type=i;exports.types=c;exports.version=t;

package/dist/cjs/src/Cli.d.ts

@@ -1,23 +1,22 @@
-import { CommandRegistry, CommandResolver, FileImporter } from './CommandRegistry.js';
-import { default as HelpCommand, HelpCommandOptions } from './commands/HelpCommand.js';
-import { ExceptionHandler } from './ExceptionHandler.js';
 import { Command } from './Command.js';
+import { CommandRegistry, CommandRegistryOptions, CommandResolver, FileImporter } from './CommandRegistry.js';
+import { ExceptionHandler } from './ExceptionHandler.js';
 import { Logger } from './Logger.js';
-export type CliOptions<C = any> = {
+import { default as HelpCommand, HelpCommandOptions } from './commands/HelpCommand.js';
+import { ContextDefinition, OptionsSchema } from './lib/types.js';
+export type CliOptions<C extends ContextDefinition = ContextDefinition> = {
     ctx?: C;
     name?: string;
     version?: string;
     logger?: Logger;
 };
-export declare class Cli<C = any> {
+export declare class Cli<C extends ContextDefinition = ContextDefinition> {
     private readonly ctx?;
     private readonly logger;
     readonly commandRegistry: CommandRegistry;
     private readonly exceptionHandler;
     private readonly helpCommand;
-    protected newCommandRegistry(opts: {
-        logger: Logger;
-    }): CommandRegistry;
+    protected newCommandRegistry(opts: CommandRegistryOptions): CommandRegistry;
     protected newHelpCommand(opts: HelpCommandOptions): HelpCommand;
     protected newExceptionHandler(opts: {
         logger: Logger;
@@ -25,10 +24,10 @@ export declare class Cli<C = any> {
     constructor(opts?: CliOptions<C>);
     withCommandResolver(resolver: CommandResolver): this;
     withFileImporter(importer: FileImporter): this;
-    withCommands(...commands: Array<Command<C, any, any> | {
+    withCommands(...commands: Array<Command<C, OptionsSchema, OptionsSchema> | {
         new (): Command<C>;
     } | string>): Promise<void>;
-    runCommand(command: string | Command | undefined, ...args: any[]): Promise<number>;
+    runCommand(command: string | Command | undefined, ...args: string[]): Promise<number>;
     runHelpCommand(): Promise<number>;
-    protected registerCommand(command: Command<C>): void;
+    protected registerCommand(command: Command<C, OptionsSchema, OptionsSchema>): void;
 }