feat(nested): add factory pattern for nested commands with typed parent globals

[boneskull]

Adds a new .command(name, factory, description?) overload that accepts a
factory function. The factory receives a CliBuilder pre-typed with parent
globals, enabling full type inference in nested command handlers.

Example:

  bargs('main')
    .globals(opt.options({ verbose: opt.boolean() }))
    .command('remote', (remote) =>
      remote.command('add', parser, ({ values }) => {
        values.verbose; // Fully typed!
      }),
    );

• Add factory overload to CliBuilder.command() in types.ts
• Implement factory detection in bargs.ts command() method
• Update nested-commands.ts example to use factory pattern
• Document factory pattern in README.md - Add 5 tests for factory form of nested commands

The existing .command(name, cliBuilder, desc) form remains for backwards
compatibility.

[boneskull]

• feat(nested): add factory pattern for nested commands with typed parent globals #18 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull request overview

This PR adds a factory pattern for defining nested commands that provides full type inference of parent global options. The factory function receives a CliBuilder pre-typed with parent globals, enabling handlers in nested commands to access parent global types at compile time. This improves the developer experience compared to the existing pattern of passing pre-built CliBuilder instances, where parent globals are only available at runtime.

Key changes:

• New .command(name, factory, description?) overload that accepts a factory function for creating nested command groups
• Factory receives a builder with parent global types, enabling full type inference in nested command handlers
• Maintains backward compatibility with existing .command(name, cliBuilder, desc) form

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/types.ts	Adds new command overload signature for factory pattern with documentation and example
src/bargs.ts	Implements factory detection and child builder creation logic; updates error message to include factory function
test/bargs.test.ts	Adds 5 comprehensive tests covering basic usage, parent globals, deep nesting, default commands, and merged options
examples/nested-commands.ts	Refactors example to use factory pattern instead of pre-built builders, demonstrating typed parent globals
README.md	Updates documentation to explain factory pattern as recommended approach; clarifies difference from pre-built CliBuilder form

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.