@boneskull/bargs 3.1.0 → 3.3.0

package/README.md

@@ -27,8 +27,7 @@ A CLI with an optional command and a couple options:
 ```typescript
 import { bargs, opt, pos } from '@boneskull/bargs';
 
-await bargs
-  .create('greet', { version: '1.0.0' })
+await bargs('greet', { version: '1.0.0' })
   .globals(
     opt.options({
       name: opt.string({ default: 'world' }),
@@ -112,11 +111,10 @@ const parser = pos.positionals(pos.variadic('string', { name: 'text' }))(
   }),
 );
 
-const { values, positionals } = await bargs
-  .create('echo', {
-    description: 'Echo text to stdout',
-    version: '1.0.0',
-  })
+const { values, positionals } = await bargs('echo', {
+  description: 'Echo text to stdout',
+  version: '1.0.0',
+})
   .globals(parser)
   .parseAsync();
 
@@ -132,11 +130,10 @@ For a CLI with multiple subcommands:
 ```typescript
 import { bargs, merge, opt, pos } from '@boneskull/bargs';
 
-await bargs
-  .create('tasks', {
-    description: 'A task manager',
-    version: '1.0.0',
-  })
+await bargs('tasks', {
+  description: 'A task manager',
+  version: '1.0.0',
+})
   .globals(
     opt.options({
       verbose: opt.boolean({ aliases: ['v'], default: false }),
@@ -181,9 +178,51 @@ $ tasks list --all
 All tasks
 ```
 
+### Nested Commands (Subcommands)
+
+Commands can be nested to arbitrary depth by passing a `CliBuilder` as the second argument to `.command()`:
+
+```typescript
+import { bargs, opt, pos } from '@boneskull/bargs';
+
+// Define subcommands as a separate builder
+const remoteCommands = bargs('remote')
+  .command(
+    'add',
+    pos.positionals(
+      pos.string({ name: 'name', required: true }),
+      pos.string({ name: 'url', required: true }),
+    ),
+    ({ positionals, values }) => {
+      const [name, url] = positionals;
+      // Parent globals (verbose) are available here!
+      if (values.verbose) console.log(`Adding ${name}: ${url}`);
+    },
+    'Add a remote',
+  )
+  .command('remove' /* ... */)
+  .defaultCommand('add');
+
+// Nest under parent CLI
+await bargs('git')
+  .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
+  .command('remote', remoteCommands, 'Manage remotes') // ← CliBuilder
+  .command('commit', commitParser, commitHandler) // ← Regular command
+  .parseAsync();
+```
+
+```shell
+$ git --verbose remote add origin https://github.com/...
+Adding origin: https://github.com/...
+
+$ git remote remove origin
+```
+
+Parent globals automatically flow to nested command handlers. You can nest as deep as you like—just nest `CliBuilder`s inside `CliBuilder`s. See `examples/nested-commands.ts` for a full example.
+
 ## API
 
-### bargs.create(name, options?)
+### bargs(name, options?)
 
 Create a CLI builder.
 
@@ -199,7 +238,7 @@ Create a CLI builder.
 Set global options and transforms that apply to all commands.
 
 ```typescript
-bargs.create('my-cli').globals(opt.options({ verbose: opt.boolean() }));
+bargs('my-cli').globals(opt.options({ verbose: opt.boolean() }));
 // ...
 ```
 
@@ -219,6 +258,21 @@ Register a command. The handler receives merged global + command types.
 )
 ```
 
+### .command(name, cliBuilder, description?)
+
+Register a nested command group. The `cliBuilder` is another `CliBuilder` whose commands become subcommands. Parent globals are passed down to nested handlers.
+
+```typescript
+const subCommands = bargs('sub').command('foo', ...).command('bar', ...);
+
+bargs('main')
+  .command('nested', subCommands, 'Nested commands')  // nested group
+  .parseAsync();
+
+// $ main nested foo
+// $ main nested bar
+```
+
 ### .defaultCommand(name)
 
 > Or `.defaultCommand(parser, handler)`
@@ -245,11 +299,11 @@ Parse arguments and execute handlers.
 
 ```typescript
 // Async (supports async transforms/handlers)
-const result = await bargs.create('my-cli').globals(...).parseAsync();
+const result = await bargs('my-cli').globals(...).parseAsync();
 console.log(result.values, result.positionals, result.command);
 
 // Sync (no async transforms/handlers)
-const result = bargs.create('my-cli').globals(...).parse();
+const result = bargs('my-cli').globals(...).parse();
 ```
 
 ## Option Helpers
@@ -277,6 +331,32 @@ opt.count(); // -vvv → 3
 | `hidden`      | `boolean`  | Hide from `--help` output                        |
 | `required`    | `boolean`  | Mark as required (makes the option non-nullable) |
 
+### Boolean Negation (`--no-<flag>`)
+
+All boolean options automatically support a negated form `--no-<flag>` to explicitly set the option to `false`:
+
+```shell
+$ my-cli --verbose      # verbose: true
+$ my-cli --no-verbose   # verbose: false
+$ my-cli                # verbose: undefined (or default)
+```
+
+If both `--flag` and `--no-flag` are specified, bargs throws an error:
+
+```shell
+$ my-cli --verbose --no-verbose
+Error: Conflicting options: --verbose and --no-verbose cannot both be specified
+```
+
+In help output, booleans with `default: true` display as `--no-<flag>` (since that's how users would turn them off):
+
+```typescript
+opt.options({
+  colors: opt.boolean({ default: true, description: 'Use colors' }),
+});
+// Help output shows: --no-colors  Use colors  [boolean] default: true
+```
+
 ### `opt.options(schema)`
 
 Create a parser from an options schema:
@@ -384,8 +464,7 @@ const globals = map(
   }),
 );
 
-await bargs
-  .create('my-cli')
+await bargs('my-cli')
   .globals(globals)
   .command(
     'info',
@@ -421,18 +500,47 @@ const globals = map(
 );
 ```
 
+### CamelCase Option Keys
+
+If you prefer camelCase property names instead of kebab-case, use the `camelCaseValues` transform:
+
+```typescript
+import { bargs, map, opt, camelCaseValues } from '@boneskull/bargs';
+
+const { values } = await bargs('my-cli')
+  .globals(
+    map(
+      opt.options({
+        'output-dir': opt.string({ default: '/tmp' }),
+        'dry-run': opt.boolean(),
+      }),
+      camelCaseValues,
+    ),
+  )
+  .parseAsync(['--output-dir', './dist', '--dry-run']);
+
+console.log(values.outputDir); // './dist'
+console.log(values.dryRun); // true
+```
+
+The `camelCaseValues` transform:
+
+- Converts all kebab-case keys to camelCase (`output-dir` → `outputDir`)
+- Preserves keys that are already camelCase or have no hyphens
+- Is fully type-safe—TypeScript knows the transformed key names
+
 ## Epilog
 
 By default, **bargs** displays your package's homepage and repository URLs (from `package.json`) at the end of help output. URLs become clickable hyperlinks in supported terminals.
 
 ```typescript
 // Custom epilog
-bargs.create('my-cli', {
+bargs('my-cli', {
   epilog: 'For more info, visit https://example.com',
 });
 
 // Disable epilog entirely
-bargs.create('my-cli', { epilog: false });
+bargs('my-cli', { epilog: false });
 ```
 
 ## Theming
@@ -441,10 +549,10 @@ Customize help output colors with built-in themes or your own:
 
 ```typescript
 // Use a built-in theme: 'default', 'mono', 'ocean', 'warm'
-bargs.create('my-cli', { theme: 'ocean' });
+bargs('my-cli', { theme: 'ocean' });
 
 // Disable colors entirely
-bargs.create('my-cli', { theme: 'mono' });
+bargs('my-cli', { theme: 'mono' });
 ```
 
 The `ansi` export provides common ANSI escape codes for styled terminal output:
@@ -452,7 +560,7 @@ The `ansi` export provides common ANSI escape codes for styled terminal output:
 ```typescript
 import { ansi } from '@boneskull/bargs';
 
-bargs.create('my-cli', {
+bargs('my-cli', {
   theme: {
     command: ansi.bold,
     flag: ansi.brightCyan,
@@ -498,7 +606,7 @@ import {
 } from '@boneskull/bargs';
 
 try {
-  await bargs.create('my-cli').parseAsync();
+  await bargs('my-cli').parseAsync();
 } catch (error) {
   if (error instanceof ValidationError) {
     // Config validation failed (e.g., invalid schema)

package/dist/bargs.cjs

@@ -2,13 +2,13 @@
 /**
  * Core bargs API using parser combinator pattern.
  *
- * Provides `bargs.create()` for building CLIs with a fluent API, plus
- * combinator functions like `pipe()`, `map()`, and `handle()`.
+ * Provides `bargs()` for building CLIs with a fluent API, plus combinator
+ * functions like `pipe()`, `map()`, and `handle()`.
  *
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bargs = void 0;
+exports.bargs = exports.camelCaseValues = void 0;
 exports.handle = handle;
 exports.map = map;
 exports.merge = merge;
@@ -53,27 +53,47 @@ function handle(parserOrFn, maybeFn) {
     };
 }
 function map(parserOrFn, maybeFn) {
+    // Helper to compose transforms (chains existing + new)
+    /**
+     * @function
+     */
+    const composeTransform = (parser, fn) => {
+        const existing = parser.__transform;
+        if (!existing) {
+            return fn;
+        }
+        // Chain: existing transform first, then new transform
+        return (r) => {
+            const r1 = existing(r);
+            if (r1 instanceof Promise) {
+                return r1.then(fn);
+            }
+            return fn(r1);
+        };
+    };
     // Direct form: map(parser, fn) returns Parser
     // Check for Parser first since CallableParser is also a function
     if (isParser(parserOrFn)) {
         const parser = parserOrFn;
         const fn = maybeFn;
+        const composedTransform = composeTransform(parser, fn);
         return {
             ...parser,
             __brand: 'Parser',
             __positionals: [],
-            __transform: fn,
+            __transform: composedTransform,
             __values: {},
         };
     }
     // Curried form: map(fn) returns (parser) => Parser
     const fn = parserOrFn;
     return (parser) => {
+        const composedTransform = composeTransform(parser, fn);
         return {
             ...parser,
             __brand: 'Parser',
             __positionals: [],
-            __transform: fn,
+            __transform: composedTransform,
             __values: {},
         };
     };
@@ -130,6 +150,43 @@ function merge(...parsers) {
     return result;
 }
 // ═══════════════════════════════════════════════════════════════════════════════
+// CAMEL CASE HELPER
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Convert kebab-case string to camelCase.
+ *
+ * @function
+ */
+const kebabToCamel = (s) => s.replace(/-([a-zA-Z])/g, (_, c) => c.toUpperCase());
+/**
+ * Transform for use with `map()` that converts kebab-case option keys to
+ * camelCase.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { bargs, opt, map, camelCaseValues } from '@boneskull/bargs';
+ *
+ * const { values } = await bargs('my-cli')
+ *   .globals(
+ *     map(opt.options({ 'output-dir': opt.string() }), camelCaseValues),
+ *   )
+ *   .parseAsync();
+ *
+ * console.log(values.outputDir); // camelCased!
+ * ```
+ *
+ * @function
+ */
+const camelCaseValues = (result) => ({
+    ...result,
+    values: Object.fromEntries(Object.entries(result.values).map(([k, v]) => [
+        kebabToCamel(k),
+        v,
+    ])),
+});
+exports.camelCaseValues = camelCaseValues;
+// ═══════════════════════════════════════════════════════════════════════════════
 // CLI BUILDER
 // ═══════════════════════════════════════════════════════════════════════════════
 /**
@@ -138,8 +195,7 @@ function merge(...parsers) {
  * @example
  *
  * ```typescript
- * const cli = await bargs
- *   .create('my-app', { version: '1.0.0' })
+ * const cli = await bargs('my-app', { version: '1.0.0' })
  *   .globals(
  *     map(opt.options({ verbose: opt.boolean() }), ({ values }) => ({
  *       values: { ...values, ts: Date.now() },
@@ -153,8 +209,10 @@ function merge(...parsers) {
  *   )
  *   .parseAsync();
  * ```
+ *
+ * @function
  */
-const create = (name, options = {}) => {
+const bargs = (name, options = {}) => {
     const theme = options.theme ? (0, theme_js_1.getTheme)(options.theme) : theme_js_1.defaultTheme;
     return createCliBuilder({
         commands: new Map(),
@@ -163,8 +221,11 @@ const create = (name, options = {}) => {
         theme,
     });
 };
+exports.bargs = bargs;
 /**
  * Check if something is a Command (has __brand: 'Command').
+ *
+ * @function
  */
 const isCommand = (x) => {
     if (x === null || x === undefined) {
@@ -175,21 +236,39 @@ const isCommand = (x) => {
 };
 /**
  * Create a CLI builder.
+ *
+ * @function
  */
 const createCliBuilder = (state) => {
-    return {
-        // Overloaded command(): accepts either (name, Command, desc?) or (name, Parser, handler, desc?)
-        command(name, cmdOrParser, handlerOrDesc, maybeDesc) {
+    const builder = {
+        // Internal method for nested command support - not part of public API
+        __parseWithParentGlobals(args, parentGlobals, allowAsync) {
+            const stateWithGlobals = { ...state, parentGlobals };
+            return parseCore(stateWithGlobals, args, allowAsync);
+        },
+        // Overloaded command(): accepts (name, Command, desc?), (name, Parser, handler, desc?), or (name, CliBuilder, desc?)
+        command(name, cmdOrParserOrBuilder, handlerOrDesc, maybeDesc) {
+            // Form 3: command(name, CliBuilder, description?) - nested commands
+            if (isCliBuilder(cmdOrParserOrBuilder)) {
+                const builder = cmdOrParserOrBuilder;
+                const description = handlerOrDesc;
+                state.commands.set(name, {
+                    builder: builder,
+                    description,
+                    type: 'nested',
+                });
+                return this;
+            }
             let cmd;
             let description;
-            if (isCommand(cmdOrParser)) {
+            if (isCommand(cmdOrParserOrBuilder)) {
                 // Form 1: command(name, Command, description?)
-                cmd = cmdOrParser;
+                cmd = cmdOrParserOrBuilder;
                 description = handlerOrDesc;
             }
-            else if (isParser(cmdOrParser)) {
+            else if (isParser(cmdOrParserOrBuilder)) {
                 // Form 2: command(name, Parser, handler, description?)
-                const parser = cmdOrParser;
+                const parser = cmdOrParserOrBuilder;
                 const handler = handlerOrDesc;
                 description = maybeDesc;
                 // Create Command from Parser + handler
@@ -207,9 +286,9 @@ const createCliBuilder = (state) => {
                 cmd = newCmd;
             }
             else {
-                throw new Error('command() requires a Command or Parser as second argument');
+                throw new Error('command() requires a Command, Parser, or CliBuilder as second argument');
             }
-            state.commands.set(name, { cmd, description });
+            state.commands.set(name, { cmd, description, type: 'command' });
             return this;
         },
         // Overloaded defaultCommand(): accepts name, Command, or (Parser, handler)
@@ -228,6 +307,7 @@ const createCliBuilder = (state) => {
                 state.commands.set(defaultName, {
                     cmd: nameOrCmdOrParser,
                     description: undefined,
+                    type: 'command',
                 });
             }
             else if (isParser(nameOrCmdOrParser)) {
@@ -248,6 +328,7 @@ const createCliBuilder = (state) => {
                 state.commands.set(defaultName, {
                     cmd: newCmd,
                     description: undefined,
+                    type: 'command',
                 });
             }
             else {
@@ -275,9 +356,13 @@ const createCliBuilder = (state) => {
             return parseCore(state, args, true);
         },
     };
+    // Return as public CliBuilder (hiding internal method from type)
+    return builder;
 };
 /**
  * Core parse logic shared between parse() and parseAsync().
+ *
+ * @function
  */
 const parseCore = (state, args, allowAsync) => {
     const { commands, options, theme } = state;
@@ -310,12 +395,19 @@ const parseCore = (state, args, allowAsync) => {
 };
 /**
  * Generate command-specific help.
+ *
+ * @function
  */
 const generateCommandHelpNew = (state, commandName, theme) => {
     const commandEntry = state.commands.get(commandName);
     if (!commandEntry) {
         return `Unknown command: ${commandName}`;
     }
+    // Handle nested commands - show their subcommand list
+    if (commandEntry.type === 'nested') {
+        // TODO: Generate proper help for nested command groups
+        return `${commandName} is a command group. Run '${state.name} ${commandName} --help' for subcommands.`;
+    }
     // TODO: Implement proper command help generation
     const config = {
         commands: {
@@ -331,6 +423,8 @@ const generateCommandHelpNew = (state, commandName, theme) => {
 };
 /**
  * Generate help for the new CLI structure.
+ *
+ * @function
  */
 const generateHelpNew = (state, theme) => {
     // TODO: Implement proper help generation for new structure
@@ -350,6 +444,8 @@ const generateHelpNew = (state, theme) => {
 /**
  * Check if something is a Parser (has __brand: 'Parser'). Parsers can be either
  * objects or functions (CallableParser).
+ *
+ * @function
  */
 const isParser = (x) => {
     if (x === null || x === undefined) {
@@ -359,8 +455,26 @@ const isParser = (x) => {
     const obj = x;
     return '__brand' in obj && obj.__brand === 'Parser';
 };
+/**
+ * Check if something is a CliBuilder (has command, globals, parse, parseAsync
+ * methods).
+ *
+ * @function
+ */
+const isCliBuilder = (x) => {
+    if (x === null || x === undefined || typeof x !== 'object') {
+        return false;
+    }
+    const obj = x;
+    return (typeof obj.command === 'function' &&
+        typeof obj.globals === 'function' &&
+        typeof obj.parse === 'function' &&
+        typeof obj.parseAsync === 'function');
+};
 /**
  * Run a simple CLI (no commands).
+ *
+ * @function
  */
 const runSimple = (state, args, allowAsync) => {
     const { globalParser } = state;
@@ -395,8 +509,20 @@ const runSimple = (state, args, allowAsync) => {
 // ═══════════════════════════════════════════════════════════════════════════════
 // PUBLIC API
 // ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Delegate parsing to a nested CliBuilder, passing down parent globals.
+ *
+ * @function
+ */
+const delegateToNestedBuilder = (builder, remainingArgs, parentGlobals, allowAsync) => {
+    // Access the internal parse function that accepts parent globals
+    const internalBuilder = builder;
+    return internalBuilder.__parseWithParentGlobals(remainingArgs, parentGlobals, allowAsync);
+};
 /**
  * Run a CLI with commands.
+ *
+ * @function
  */
 const runWithCommands = (state, args, allowAsync) => {
     const { commands, defaultCommandName, globalParser } = state;
@@ -431,6 +557,38 @@ const runWithCommands = (state, args, allowAsync) => {
     if (!commandEntry) {
         throw new errors_js_1.HelpError(`Unknown command: ${commandName}`);
     }
+    // Handle nested commands (subcommands)
+    if (commandEntry.type === 'nested') {
+        const { builder } = commandEntry;
+        // Parse global options first (before the command name)
+        const globalOptionsSchema = globalParser?.__optionsSchema ?? {};
+        const globalParsed = (0, parser_js_1.parseSimple)({
+            args: args.slice(0, commandIndex),
+            options: globalOptionsSchema,
+            positionals: [],
+        });
+        // Apply global transforms if any
+        let globalResult = {
+            positionals: globalParsed.positionals,
+            values: globalParsed.values,
+        };
+        const globalTransform = globalParser?.__transform;
+        // Args for nested builder are ONLY those after the command name (not global options)
+        const nestedArgs = args.slice(commandIndex + 1);
+        if (globalTransform) {
+            const transformed = globalTransform(globalResult);
+            if (transformed instanceof Promise) {
+                if (!allowAsync) {
+                    throw new errors_js_1.BargsError('Async global transform detected. Use parseAsync() instead of parse().');
+                }
+                return transformed.then((r) => {
+                    return delegateToNestedBuilder(builder, nestedArgs, r, allowAsync);
+                });
+            }
+            globalResult = transformed;
+        }
+        return delegateToNestedBuilder(builder, nestedArgs, globalResult, allowAsync);
+    }
     const { cmd } = commandEntry;
     // Merge global and command options schemas
     const globalOptionsSchema = globalParser?.__optionsSchema ?? {};
@@ -446,11 +604,16 @@ const runWithCommands = (state, args, allowAsync) => {
         options: mergedOptionsSchema,
         positionals: commandPositionalsSchema,
     });
+    // Merge parent globals (from nested command delegation) with parsed values
+    const parentValues = state.parentGlobals?.values ?? {};
     let result = {
         positionals: parsed.positionals,
-        values: parsed.values,
+        values: { ...parentValues, ...parsed.values },
     };
     // Helper to check for async and throw if not allowed
+    /**
+     * @function
+     */
     const checkAsync = (value, context) => {
         if (value instanceof Promise && !allowAsync) {
             throw new errors_js_1.BargsError(`Async ${context} detected. Use parseAsync() instead of parse().`);
@@ -460,6 +623,9 @@ const runWithCommands = (state, args, allowAsync) => {
     const globalTransform = globalParser?.__transform;
     const commandTransform = cmd?.__transform;
     // Apply transforms and run handler
+    /**
+     * @function
+     */
     const applyTransformsAndHandle = () => {
         // Apply global transforms first
         if (globalTransform) {
@@ -475,6 +641,9 @@ const runWithCommands = (state, args, allowAsync) => {
         }
         return continueWithCommandTransform();
     };
+    /**
+     * @function
+     */
     const continueWithCommandTransform = () => {
         // Apply command transforms
         if (commandTransform) {
@@ -490,6 +659,9 @@ const runWithCommands = (state, args, allowAsync) => {
         }
         return runHandler();
     };
+    /**
+     * @function
+     */
     const runHandler = () => {
         const handlerResult = cmd.handler(result);
         checkAsync(handlerResult, 'handler');
@@ -501,9 +673,8 @@ const runWithCommands = (state, args, allowAsync) => {
     return applyTransformsAndHandle();
 };
 /**
- * Main bargs namespace.
+ * @ignore
+ * @deprecated
  */
-exports.bargs = {
-    create,
-};
+exports.bargs.create = exports.bargs;
 //# sourceMappingURL=bargs.js.map