feat!: remove direct CliBuilder pattern for nested commands

Remove the inferior `.command(name, CliBuilder)` overload that lacked type
inference for parent globals. The factory pattern `.command(name, factory)`
is now the only way to create nested command groups.

BREAKING CHANGE: The `.command(name, cliBuilder, options?)` overload has been
removed. Users must migrate to the factory pattern:

Before:
  const sub = bargs('sub').command('foo', ...);
  bargs('main').command('nested', sub, 'desc');

After:
  bargs('main').command('nested', (nested) =>
    nested.command('foo', ...), 'desc');

The factory pattern provides full type inference for parent globals in nested
command handlers, which the direct CliBuilder pattern could not.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: boneskull

README.md

@@ -220,9 +220,7 @@ Adding origin: https://github.com/...
 $ git remote remove origin
 ```
 
-The factory function receives a `CliBuilder` that already has parent globals typed, so all nested command handlers get full type inference for merged `global + command` options.
-
-You can also pass a pre-built `CliBuilder` directly (see [.command(name, cliBuilder)](#commandname-clibuilder-description)), but handlers won't have parent globals typed at compile time. See `examples/nested-commands.ts` for a full example.
+The factory function receives a `CliBuilder` that already has parent globals typed, so all nested command handlers get full type inference for merged `global + command` options. See `examples/nested-commands.ts` for a full example.
 
 ## API
 
@@ -262,24 +260,9 @@ 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 at runtime, but **handlers won't have parent globals typed** at compile time.
-
-```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
-```
-
 ### .command(name, factory, description?)
 
-Register a nested command group using a factory function. **This is the recommended form** because the factory receives a builder that already has parent globals typed, giving full type inference in nested handlers.
+Register a nested command group using a factory function. The factory receives a builder that already has parent globals typed, giving full type inference in nested handlers.
 
 ```typescript
 bargs('main')

src/bargs.ts

@@ -550,27 +550,25 @@ const createCliBuilder = <V, P extends readonly unknown[]>(
         | Promise<ParseResult<V, P> & { command?: string }>;
     },
 
-    // Overloaded command(): accepts (name, factory, options?), (name, CliBuilder, options?),
+    // Overloaded command(): accepts (name, factory, options?),
     // (name, Command, options?), or (name, Parser, handler, options?)
     command<CV, CP extends readonly unknown[]>(
       name: string,
-      cmdOrParserOrBuilderOrFactory:
+      cmdOrParserOrFactory:
         | ((builder: CliBuilder<V, P>) => CliBuilder<CV, CP>)
-        | CliBuilder<CV, CP>
         | Command<CV, CP>
         | Parser<CV, CP>,
       handlerOrDescOrOpts?: CommandOptions | HandlerFn<CV & V, CP> | string,
       maybeDescOrOpts?: CommandOptions | string,
     ): CliBuilder<V, P> {
-      // Form 4: command(name, factory, options?) - factory for nested commands with parent globals
-      // Check this FIRST before isCliBuilder/isParser since those check for __brand which a plain function won't have
+      // Form 3: command(name, factory, options?) - factory for nested commands with parent globals
+      // Check this FIRST before isParser since that checks for __brand which a plain function won't have
       if (
-        typeof cmdOrParserOrBuilderOrFactory === 'function' &&
-        !isParser(cmdOrParserOrBuilderOrFactory) &&
-        !isCommand(cmdOrParserOrBuilderOrFactory) &&
-        !isCliBuilder(cmdOrParserOrBuilderOrFactory)
+        typeof cmdOrParserOrFactory === 'function' &&
+        !isParser(cmdOrParserOrFactory) &&
+        !isCommand(cmdOrParserOrFactory)
       ) {
-        const factory = cmdOrParserOrBuilderOrFactory as (
+        const factory = cmdOrParserOrFactory as (
           b: CliBuilder<V, P>,
         ) => CliBuilder<CV, CP>;
         const { aliases, description } = parseCommandOptions(
@@ -602,37 +600,21 @@ const createCliBuilder = <V, P extends readonly unknown[]>(
         return this;
       }
 
-      // Form 3: command(name, CliBuilder, options?) - nested commands
-      if (isCliBuilder(cmdOrParserOrBuilderOrFactory)) {
-        const builder = cmdOrParserOrBuilderOrFactory;
-        const { aliases, description } = parseCommandOptions(
-          handlerOrDescOrOpts as CommandOptions | string | undefined,
-        );
-        state.commands.set(name, {
-          aliases,
-          builder: builder as CliBuilder<unknown, readonly unknown[]>,
-          description,
-          type: 'nested',
-        });
-        registerAliases(state.aliasMap, state.commands, name, aliases);
-        return this;
-      }
-
       let cmd: Command<unknown, readonly unknown[]>;
       let aliases: string[] | undefined;
       let description: string | undefined;
 
-      if (isCommand(cmdOrParserOrBuilderOrFactory)) {
+      if (isCommand(cmdOrParserOrFactory)) {
         // Form 1: command(name, Command, options?)
-        cmd = cmdOrParserOrBuilderOrFactory;
+        cmd = cmdOrParserOrFactory;
         const opts = parseCommandOptions(
           handlerOrDescOrOpts as CommandOptions | string | undefined,
         );
         aliases = opts.aliases;
         description = opts.description;
-      } else if (isParser(cmdOrParserOrBuilderOrFactory)) {
+      } else if (isParser(cmdOrParserOrFactory)) {
         // Form 2: command(name, Parser, handler, options?)
-        const parser = cmdOrParserOrBuilderOrFactory;
+        const parser = cmdOrParserOrFactory;
         const handler = handlerOrDescOrOpts as HandlerFn<CV & V, CP>;
         const opts = parseCommandOptions(maybeDescOrOpts);
         aliases = opts.aliases;
@@ -980,27 +962,6 @@ const isParser = (x: unknown): x is Parser<unknown, readonly unknown[]> => {
   return '__brand' in obj && obj.__brand === 'Parser';
 };
 
-/**
- * Check if something is a CliBuilder (has command, globals, parse, parseAsync
- * methods).
- *
- * @function
- */
-const isCliBuilder = (
-  x: unknown,
-): x is CliBuilder<unknown, readonly unknown[]> => {
-  if (x === null || x === undefined || typeof x !== 'object') {
-    return false;
-  }
-  const obj = x as Record<string, unknown>;
-  return (
-    typeof obj.command === 'function' &&
-    typeof obj.globals === 'function' &&
-    typeof obj.parse === 'function' &&
-    typeof obj.parseAsync === 'function'
-  );
-};
-
 /**
  * Run a simple CLI (no commands).
  *

src/types.ts

@@ -84,18 +84,6 @@ export interface CliBuilder<
     options?: CommandOptions | string,
   ): CliBuilder<TGlobalValues, TGlobalPositionals>;
 
-  /**
-   * Register a nested command group (subcommands).
-   *
-   * The nested CliBuilder's commands become subcommands of this command. Parent
-   * globals are passed down to nested command handlers.
-   */
-  command<CV, CP extends readonly unknown[]>(
-    name: string,
-    nestedBuilder: CliBuilder<CV, CP>,
-    options?: CommandOptions | string,
-  ): CliBuilder<TGlobalValues, TGlobalPositionals>;
-
   /**
    * Register a nested command group using a factory function.
    *

test/bargs.test.ts

@@ -406,137 +406,6 @@ describe('positionals', () => {
   });
 });
 
-describe('nested commands (subcommands)', () => {
-  it('supports nested commands via CliBuilder', async () => {
-    let result: unknown;
-
-    const remoteCommands = bargs('remote').command(
-      'add',
-      pos.positionals(
-        pos.string({ name: 'name', required: true }),
-        pos.string({ name: 'url', required: true }),
-      ),
-      ({ positionals }) => {
-        result = { command: 'remote add', positionals };
-      },
-      'Add a remote',
-    );
-
-    const cli = bargs('git').command(
-      'remote',
-      remoteCommands,
-      'Manage remotes',
-    );
-
-    await cli.parseAsync(['remote', 'add', 'origin', 'https://github.com/...']);
-
-    expect(result, 'to satisfy', {
-      command: 'remote add',
-      positionals: ['origin', 'https://github.com/...'],
-    });
-  });
-
-  it('supports deeply nested commands', async () => {
-    let result: unknown;
-
-    const setCommands = bargs('set').command(
-      'url',
-      pos.positionals(pos.string({ name: 'url', required: true })),
-      ({ positionals }) => {
-        result = { command: 'remote origin set url', positionals };
-      },
-    );
-
-    const originCommands = bargs('origin').command(
-      'set',
-      setCommands,
-      'Set properties',
-    );
-
-    const remoteCommands = bargs('remote').command(
-      'origin',
-      originCommands,
-      'Manage origin',
-    );
-
-    const cli = bargs('git').command('remote', remoteCommands);
-
-    await cli.parseAsync(['remote', 'origin', 'set', 'url', 'https://new.url']);
-
-    expect(result, 'to satisfy', {
-      command: 'remote origin set url',
-      positionals: ['https://new.url'],
-    });
-  });
-
-  it('passes parent globals to nested command handlers', async () => {
-    let result: unknown;
-
-    const remoteCommands = bargs('remote').command(
-      'add',
-      pos.positionals(pos.string({ name: 'name', required: true })),
-      ({ positionals, values }) => {
-        result = { positionals, values };
-      },
-    );
-
-    const cli = bargs('git')
-      .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
-      .command('remote', remoteCommands);
-
-    await cli.parseAsync(['--verbose', 'remote', 'add', 'origin']);
-
-    expect(result, 'to satisfy', {
-      positionals: ['origin'],
-      values: { verbose: true },
-    });
-  });
-
-  it('runs default subcommand when no subcommand specified', async () => {
-    let result: unknown;
-
-    const remoteCommands = bargs('remote')
-      .command(
-        'list',
-        opt.options({}),
-        () => {
-          result = 'list called';
-        },
-        'List remotes',
-      )
-      .command('add', opt.options({}), () => {
-        result = 'add called';
-      })
-      .defaultCommand('list');
-
-    const cli = bargs('git').command('remote', remoteCommands);
-
-    await cli.parseAsync(['remote']);
-
-    expect(result, 'to be', 'list called');
-  });
-
-  it('generates help listing nested command', () => {
-    const remoteCommands = bargs('remote')
-      .command('add', opt.options({}), () => {}, 'Add a remote')
-      .command('remove', opt.options({}), () => {}, 'Remove a remote');
-
-    const cli = bargs('git').command(
-      'remote',
-      remoteCommands,
-      'Manage remotes',
-    );
-
-    // The parent CLI should list 'remote' as a command with its description
-    // Note: The actual help generation for nested commands is handled by the
-    // nested builder when --help is passed to it. Here we just verify
-    // the parent CLI shows the nested command group.
-    // This is a bit tricky to test since --help calls process.exit(0).
-    // For now, we verify the nested command is properly registered.
-    expect(cli, 'to be defined');
-  });
-});
-
 describe('nested commands via factory pattern', () => {
   it('supports nested commands via factory function', async () => {
     let result: unknown;