fix(types): improve type inference for transforms and command handlers

- Add TransformsInput type for contextual typing of inline transform callbacks
- Fix any type leakage in transforms.values and transforms.positionals parameters
- Add bargs.command<TGlobalOptions>() pattern for proper command handler inference
- Update BargsConfig.transforms to use computed types when TTransforms is undefined
- Add any-detection (0 extends 1 & T) to preserve compatibility with type assertions
- Fix stringPos and numberPos to preserve props type for required inference
- Update examples to demonstrate proper type inference patterns
- Add BargsConfigWithCommandsInternal for parser internals
- Export CommandBuilder and additional inference types

BREAKING CHANGE: transforms must appear before handler in config object
for TypeScript to infer transformed types in handler parameters

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

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

Author: boneskull

docs/plans/2026-01-02-command-handler-inference.md

@@ -0,0 +1,98 @@
+# Command Handler Type Inference
+
+## Problem
+
+When defining commands inline without `bargs.command()`, handler parameters (`values`, `positionals`) become `any`:
+
+```typescript
+bargsAsync({
+  commands: {
+    create: {
+      options: { verbose: bargs.boolean() },
+      handler: ({ values }) => {
+        // values is 'any' - no type inference!
+      },
+    },
+  },
+});
+```
+
+**Root cause:** `CommandConfigInput` uses `handler: Handler<any>`, losing type information when TypeScript infers `TCommands extends Record<string, CommandConfigInput>`.
+
+## Solution
+
+Use a mapped type that captures each command's structure and computes the correct handler type, including:
+
+- Global options merged with command options
+- Global transforms applied first, then command transforms
+- Command positionals through command transforms
+
+### New Type: `InferredCommands`
+
+```typescript
+type InferredCommands<
+  TGlobalOptions extends OptionsSchema,
+  TGlobalTransforms extends TransformsConfig<any, any, any, any> | undefined,
+  TCommands extends Record<string, CommandConfigInput>,
+> = {
+  [K in keyof TCommands]: {
+    description: string;
+    options?: TCommands[K]['options'];
+    positionals?: TCommands[K]['positionals'];
+    transforms?: TCommands[K]['transforms'];
+    handler: Handler<
+      BargsResult<
+        InferTransformedValues<
+          InferTransformedValues<
+            InferOptions<TGlobalOptions> &
+              InferOptions<
+                TCommands[K]['options'] extends OptionsSchema
+                  ? TCommands[K]['options']
+                  : Record<string, never>
+              >,
+            TGlobalTransforms
+          >,
+          TCommands[K]['transforms']
+        >,
+        InferTransformedPositionals<
+          InferPositionals<
+            TCommands[K]['positionals'] extends PositionalsSchema
+              ? TCommands[K]['positionals']
+              : readonly []
+          >,
+          TCommands[K]['transforms']
+        >,
+        string
+      >
+    >;
+  };
+};
+```
+
+### Updated `BargsConfigWithCommands`
+
+Use intersection to overlay computed handler types:
+
+```typescript
+type BargsConfigWithCommands<
+  TOptions extends OptionsSchema,
+  TCommands extends Record<string, CommandConfigInput>,
+  TTransforms extends TransformsConfig<...> | undefined,
+> = {
+  // ... other properties
+  commands: TCommands & InferredCommands<TOptions, TTransforms, TCommands>;
+};
+```
+
+## Behavior
+
+Command handlers receive:
+
+- **values**: `InferOptions<GlobalOpts> & InferOptions<CommandOpts>`, transformed by global then command transforms
+- **positionals**: `InferPositionals<CommandPositionals>`, transformed by command transforms
+- **command**: `string` (the command name)
+
+## Files to Modify
+
+1. `src/types.ts` - Add `InferredCommands`, update `BargsConfigWithCommands`
+2. `src/bargs.ts` - Update function overloads to use new types

eslint.config.js

@@ -132,7 +132,6 @@ export default defineConfig(
       '**/*.snapshot',
       '**/.tmp/**/*',
       '.worktrees/**/*',
-      'examples/**/*',
     ],
   },
 );

examples/greeter.ts

@@ -18,27 +18,27 @@ import { bargs, bargsAsync } from '../src/index.js';
 
 const optionsDef = bargs.options({
   greeting: bargs.string({
-    description: 'The greeting to use',
-    default: 'Hello',
     aliases: ['g'],
+    default: 'Hello',
+    description: 'The greeting to use',
   }),
   shout: bargs.boolean({
-    description: 'SHOUT THE GREETING',
-    default: false,
     aliases: ['s'],
+    default: false,
+    description: 'SHOUT THE GREETING',
   }),
   verbose: bargs.boolean({
-    description: 'Show extra output',
-    default: false,
     aliases: ['v'],
+    default: false,
+    description: 'Show extra output',
   }),
 });
 
 const positionalsDef = bargs.positionals(
   bargs.stringPos({
     description: 'Name to greet',
-    required: true,
     name: 'name',
+    required: true,
   }),
 );
 
@@ -48,11 +48,11 @@ const main = async () => {
   // You can also pass a custom Theme object
   const result = await bargsAsync(
     {
-      name: 'greeter',
-      version: '1.0.0',
       description: 'A friendly greeter CLI',
+      name: 'greeter',
       options: optionsDef,
       positionals: positionalsDef,
+      version: '1.0.0',
     },
     { theme: 'ocean' },
   );