feat(types): add TGlobalTransforms type parameter to CommandConfig

Enable command handlers created via bargs.command<>() to access properties
added by global transforms. The curried form now accepts two type arguments:
bargs.command<typeof globalOptions, typeof globalTransforms>()({ ... })

Changes:
- Add TGlobalTransforms as second type parameter to CommandConfig (5 params now)
- Update CommandBuilder interface and implementation to accept TGlobalTransforms
- Update InferredCommands and CommandsInput to handle 5-parameter CommandConfig
- Update handler type to apply global transforms before command transforms
- Add TransformsInput fallback to CommandConfig.transforms for proper inference
- Remove unused handler property from BargsConfig (non-command context)
- Update examples/transforms.ts to demonstrate the new pattern with commands

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

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

Author: boneskull

examples/transforms.ts

@@ -2,15 +2,15 @@
 /**
  * Transform example
  *
- * Demonstrates how to use transforms to:
+ * Demonstrates how to use transforms with both simple CLIs and commands:
  *
- * - Load and merge config from a JSON file
- * - Add computed/derived values
- * - Transform positionals
+ * - Global transforms that apply to all commands
+ * - Command-specific transforms
+ * - Computed/derived values flowing through handlers
  *
- * Usage: npx tsx examples/transforms.ts --verbose npx tsx
- * examples/transforms.ts --config config.json npx tsx examples/transforms.ts
- * file1.txt file2.txt
+ * Usage: npx tsx examples/transforms.ts process file1.txt file2.txt --verbose
+ * npx tsx examples/transforms.ts info --config config.json npx tsx
+ * examples/transforms.ts --help
  */
 import { existsSync, readFileSync } from 'node:fs';
 
@@ -25,88 +25,137 @@ interface Config {
   verbose?: boolean;
 }
 
-const main = async () => {
-  /* eslint-disable perfectionist/sort-objects -- transforms must come before handler for type inference */
-  const result = await bargsAsync({
-    description: 'Demonstrates transforms feature',
-    name: 'transforms-demo',
-    options: {
-      config: bargsAsync.string({
-        aliases: ['c'],
-        description: 'Path to JSON config file',
-      }),
-      outputDir: bargsAsync.string({
-        aliases: ['o'],
-        description: 'Output directory',
-      }),
-      verbose: bargsAsync.boolean({
-        aliases: ['v'],
-        default: false,
-        description: 'Enable verbose output',
-      }),
-    },
-    positionals: [
-      bargsAsync.variadic('string', {
-        description: 'Input files to process',
-        name: 'files',
-      }),
-    ],
-    transforms: {
-      positionals: (positionals) => {
-        const [files] = positionals;
-        const validFiles = files.filter((f) => {
+// Global options that will be available to all commands
+const globalOptions = {
+  config: bargsAsync.string({
+    aliases: ['c'],
+    description: 'Path to JSON config file',
+  }),
+  outputDir: bargsAsync.string({
+    aliases: ['o'],
+    description: 'Output directory',
+  }),
+  verbose: bargsAsync.boolean({
+    aliases: ['v'],
+    default: false,
+    description: 'Enable verbose output',
+  }),
+} as const;
+
+// Global transforms - these run before command transforms
+const globalTransforms = {
+  values: (values: {
+    config: string | undefined;
+    outputDir: string | undefined;
+    verbose: boolean;
+  }) => {
+    let fileConfig: Config = {};
+
+    if (values.config && existsSync(values.config)) {
+      const content = readFileSync(values.config, 'utf8');
+      fileConfig = JSON.parse(content) as Config;
+    }
+
+    return {
+      ...fileConfig,
+      ...values,
+      configLoaded: !!values.config,
+      timestamp: new Date().toISOString(),
+    };
+  },
+} as const;
+
+// Define commands using the typed command builder with global transforms
+// The second type argument passes global transforms for proper type inference
+const processCommand = bargsAsync.command<
+  typeof globalOptions,
+  typeof globalTransforms
+>()({
+  description: 'Process files',
+  handler: ({ positionals, values }) => {
+    // Global transform properties are now available via TGlobalTransforms type arg
+    const [files] = positionals;
+
+    if (values.verbose) {
+      console.log('Processing configuration:', {
+        configLoaded: values.configLoaded,
+        outputDir: values.outputDir,
+        timestamp: values.timestamp,
+        verbose: values.verbose,
+      });
+    }
+
+    console.log(`Processing ${files.length} file(s):`);
+    for (const file of files) {
+      console.log(`  - ${file.toUpperCase()}`); // Command transform uppercases
+    }
+
+    if (values.outputDir) {
+      console.log(`Output will be written to: ${values.outputDir}`);
+    }
+  },
+  positionals: [
+    bargsAsync.variadic('string', {
+      description: 'Input files to process',
+      name: 'files',
+    }),
+  ],
+  // Command-level transform - processes positionals
+  transforms: {
+    positionals: (positionals) => {
+      const [files] = positionals;
+      // Filter non-existent files and uppercase the rest
+      const validFiles = files
+        .filter((f) => {
           if (!existsSync(f)) {
             console.warn(`Warning: File not found: ${f}`);
             return false;
           }
           return true;
-        });
-        return [validFiles] as const;
-      },
-      values: (values) => {
-        let fileConfig: Config = {};
+        })
+        .map((f) => f.toUpperCase());
+      return [validFiles] as const;
+    },
+  },
+});
 
-        if (values.config && existsSync(values.config)) {
-          const content = readFileSync(values.config, 'utf8');
-          fileConfig = JSON.parse(content) as Config;
-        }
+const infoCommand = bargsAsync.command<
+  typeof globalOptions,
+  typeof globalTransforms
+>()({
+  description: 'Show configuration info',
+  handler: ({ values }) => {
+    // Global transform properties are available via TGlobalTransforms type arg
+    console.log('Current configuration:');
+    console.log(`  Config file: ${values.config ?? '(none)'}`);
+    console.log(`  Output dir: ${values.outputDir ?? '(default)'}`);
+    console.log(`  Verbose: ${values.verbose}`);
+    console.log(`  Config loaded: ${values.configLoaded}`);
+    console.log(`  Timestamp: ${values.timestamp}`);
+  },
+});
 
-        return {
-          ...fileConfig,
-          ...values,
-          configLoaded: !!values.config,
-          timestamp: new Date().toISOString(),
-        };
-      },
+const main = async () => {
+  await bargsAsync({
+    commands: {
+      info: infoCommand,
+      process: processCommand,
     },
-    handler: ({ positionals, values }) => {
-      const [files] = positionals;
-
+    defaultHandler: ({ values }) => {
+      console.log('No command specified. Use --help for usage.');
       if (values.verbose) {
-        console.log('Configuration:', {
-          configLoaded: values.configLoaded,
-          outputDir: values.outputDir,
-          timestamp: values.timestamp,
-          verbose: values.verbose,
-        });
-      }
-
-      console.log(`Processing ${files.length} file(s):`);
-      for (const file of files) {
-        console.log(`  - ${file}`);
-      }
-
-      if (values.outputDir) {
-        console.log(`Output will be written to: ${values.outputDir}`);
+        console.log('(verbose mode enabled)');
       }
+      // Test: Can we access global transform-added properties?
+      console.log(`Config loaded: ${values.configLoaded}`);
+      console.log(`Timestamp: ${values.timestamp}`);
     },
+    description: 'Demonstrates transforms with commands',
+    name: 'transforms-demo',
+    options: globalOptions,
+    transforms: globalTransforms,
     version: '1.0.0',
   });
-  /* eslint-enable perfectionist/sort-objects */
-
-  if (result.values.verbose) {
-    console.log('\nFinal result:', result);
-  }
 };
 
 void main();

src/bargs.ts

@@ -32,8 +32,6 @@ import {
   parseCommandsAsync,
   parseCommandsSync,
   parseSimple,
-  runHandler,
-  runSyncHandler,
   runSyncTransforms,
   runTransforms,
 } from './parser.js';
@@ -242,11 +240,6 @@ export function bargs(
         values: transformed.values,
       } as BargsResult<unknown, readonly unknown[], undefined>;
 
-      // Call handler if provided (sync)
-      if (config.handler) {
-        runSyncHandler(config.handler as (r: typeof result) => void, result);
-      }
-
       return result;
     }
   } catch (error) {
@@ -347,14 +340,6 @@ export async function bargsAsync(
         values: transformed.values,
       } as BargsResult<unknown, readonly unknown[], undefined>;
 
-      // Call handler if provided (async)
-      if (config.handler) {
-        await runHandler(
-          config.handler as (r: typeof result) => Promise<void> | void,
-          result,
-        );
-      }
-
       return result;
     }
   } catch (error) {