cli-forge 0.12.0 → 1.0.0

package/src/lib/public-api.ts

@@ -13,7 +13,6 @@ import {
   ResolveProperties,
   WithOptional,
   MakeUndefinedPropertiesOptional,
-  WithAdditionalProperties,
 } from '@cli-forge/parser';
 
 import { InternalCLI } from './internal-cli';
@@ -127,7 +126,7 @@ export interface CLI<
       TArgs,
       TCommandArgs,
       TChildHandlerReturn,
-      any,
+      TChildren,
       CLI<TArgs, THandlerReturn, TChildren, TParent>,
       TChildChildren
     >
@@ -436,22 +435,16 @@ export interface CLI<
   option<
     TOption extends string,
     TCoerce,
-    const TProps extends Record<string, { type: string }>,
-    TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false
+    const TProps extends Record<string, { type: string }>
   >(
     name: TOption,
-    config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+    config: ObjectOptionConfig<TCoerce, TProps>
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
         [key in TOption]: WithOptional<
-          unknown extends TCoerce
-            ? WithAdditionalProperties<
-                ResolveProperties<TProps>,
-                TAdditionalProps
-              >
-            : TCoerce,
-          ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+          unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce,
+          ObjectOptionConfig<TCoerce, TProps>
         >;
       }>,
     THandlerReturn,
@@ -525,7 +518,7 @@ export interface CLI<
   // Generic fallback overload
   option<
     TOption extends string,
-    const TOptionConfig extends OptionConfig<any, any, any, any>
+    const TOptionConfig extends OptionConfig<any, any, any>
   >(
     name: TOption,
     config: TOptionConfig
@@ -552,22 +545,16 @@ export interface CLI<
   positional<
     TOption extends string,
     TCoerce,
-    const TProps extends Record<string, { type: string }>,
-    TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false
+    const TProps extends Record<string, { type: string }>
   >(
     name: TOption,
-    config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+    config: ObjectOptionConfig<TCoerce, TProps>
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
         [key in TOption]: WithOptional<
-          unknown extends TCoerce
-            ? WithAdditionalProperties<
-                ResolveProperties<TProps>,
-                TAdditionalProps
-              >
-            : TCoerce,
-          ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+          unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce,
+          ObjectOptionConfig<TCoerce, TProps>
         >;
       }>,
     THandlerReturn,
@@ -641,7 +628,7 @@ export interface CLI<
   // Generic fallback overload
   positional<
     TOption extends string,
-    const TOptionConfig extends OptionConfig<any, any, any, any>
+    const TOptionConfig extends OptionConfig<any, any, any>
   >(
     name: TOption,
     config: TOptionConfig
@@ -778,10 +765,54 @@ export interface CLI<
    */
   getParent(): TParent;
 
-  getBuilder<T extends ParsedArgs = ParsedArgs>(
-    initialCli?: CLI<T, any, any>
-  ):
-    | ((parser: CLI<T, any, any>) => CLI<TArgs, THandlerReturn, TChildren>)
+  /**
+   * Returns a programmatic SDK for invoking this CLI and its subcommands.
+   * The SDK provides typed function calls instead of argv parsing.
+   *
+   * @example
+   * ```ts
+   * const myCLI = cli('my-app')
+   *   .option('verbose', { type: 'boolean' })
+   *   .command('build', {
+   *     builder: (cmd) => cmd.option('watch', { type: 'boolean' }),
+   *     handler: (args) => ({ success: true, files: ['a.js'] })
+   *   });
+   *
+   * const sdk = myCLI.sdk();
+   *
+   * // Invoke root command (if it has a handler)
+   * await sdk({ verbose: true });
+   *
+   * // Invoke subcommand with typed args
+   * const result = await sdk.build({ watch: true });
+   * console.log(result.files);       // ['a.js']
+   * console.log(result.$args.watch); // true
+   *
+   * // Use CLI-style args for -- support
+   * await sdk.build(['--watch', '--', 'extra-arg']);
+   * ```
+   *
+   * @returns An SDK object that is callable (if this command has a handler)
+   *          and has properties for each subcommand.
+   */
+  sdk(): SDKCommand<TArgs, THandlerReturn, TChildren>;
+
+  /**
+   * Returns the builder function for this command as a composable builder.
+   * The returned function can be used with `chain` to compose multiple builders.
+   *
+   * @example
+   * ```ts
+   * const siblings = args.getParent().getChildren();
+   * const withBuildArgs = siblings.build.getBuilder()!;
+   * const withServeArgs = siblings.serve.getBuilder()!;
+   * return chain(args, withBuildArgs, withServeArgs);
+   * ```
+   */
+  getBuilder():
+    | (<TInit extends ParsedArgs, TInitHandlerReturn, TInitChildren, TInitParent>(
+        parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent>
+      ) => CLI<TInit & TArgs, TInitHandlerReturn, TInitChildren & TChildren, TInitParent>)
     | undefined;
   getHandler():
     | ((args: Omit<TArgs, keyof ParsedArgs>) => THandlerReturn)
@@ -910,6 +941,67 @@ export type MiddlewareFunction<TArgs extends ParsedArgs, TArgs2> = (
   args: TArgs
 ) => TArgs2 | Promise<TArgs2>;
 
+// ============================================================================
+// SDK Types
+// ============================================================================
+
+/**
+ * Result type that conditionally includes $args.
+ * Only attaches $args when result is an object type.
+ * Uses Awaited<T> to handle async handlers that return Promise<U>.
+ */
+export type SDKResult<TArgs, THandlerReturn> =
+  Awaited<THandlerReturn> extends object
+    ? Awaited<THandlerReturn> & { $args: TArgs }
+    : Awaited<THandlerReturn>;
+
+/**
+ * The callable signature for a command with a handler.
+ * Supports both object-style args (typed, skips validation) and
+ * string array args (CLI-style, full validation pipeline).
+ */
+export type SDKInvokable<TArgs, THandlerReturn> = {
+  /**
+   * Invoke the command with typed object args.
+   * Skips validation (TypeScript handles it), applies defaults, runs middleware.
+   */
+  (args?: Partial<Omit<TArgs, 'unmatched' | '--'>>): Promise<
+    SDKResult<TArgs, THandlerReturn>
+  >;
+  /**
+   * Invoke the command with CLI-style string args.
+   * Runs full pipeline: parse → validate → middleware → handler.
+   * Use this when you need to pass `--` extra args.
+   */
+  (args: string[]): Promise<SDKResult<TArgs, THandlerReturn>>;
+};
+
+/**
+ * Recursively builds SDK type from TChildren.
+ * Each child command becomes a property on the SDK object.
+ */
+export type SDKChildren<TChildren> = {
+  [K in keyof TChildren]: TChildren[K] extends CLI<
+    infer A,
+    infer R,
+    infer C,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    infer _P
+  >
+    ? SDKCommand<A, R, C>
+    : never;
+};
+
+/**
+ * A single SDK command - callable if it has a handler, with nested children as properties.
+ * Container commands (no handler) are not callable but still provide access to children.
+ */
+export type SDKCommand<TArgs, THandlerReturn, TChildren> =
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  // THandlerReturn extends void | undefined
+  // ? SDKChildren<TChildren> // No handler = just children (not callable)
+  SDKInvokable<TArgs, THandlerReturn> & SDKChildren<TChildren>;
+
 /**
  * Constructs a CLI instance. See {@link CLI} for more information.
  * @param name Name for the top level CLI

package/src/lib/sdk.spec.ts

@@ -0,0 +1,285 @@
+import { cli } from './public-api';
+
+describe('CLI.sdk()', () => {
+  describe('basic invocation', () => {
+    it('should invoke root command with object args', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test', {
+        builder: (cmd) => cmd.option('name', { type: 'string' }),
+        handler: (args) => {
+          receivedArgs = args;
+          return { success: true };
+        },
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk({ name: 'world' });
+
+      expect(result.success).toBe(true);
+      expect(receivedArgs.name).toBe('world');
+    });
+
+    it('should invoke root command with string array args', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test', {
+        builder: (cmd) => cmd.option('name', { type: 'string' }),
+        handler: (args) => {
+          receivedArgs = args;
+          return { success: true };
+        },
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk(['--name', 'world']);
+
+      expect(result.success).toBe(true);
+      expect(receivedArgs.name).toBe('world');
+    });
+
+    it('should attach $args to object results', async () => {
+      const myCLI = cli('test', {
+        builder: (cmd) =>
+          cmd.option('count', { type: 'number', required: true }),
+        handler: (args) => ({ value: args.count * 2 }),
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk({ count: 5 });
+
+      expect(result.value).toBe(10);
+      expect(result.$args.count).toBe(5);
+    });
+
+    it('should return primitives without $args', async () => {
+      const myCLI = cli('test', {
+        handler: () => 42,
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk();
+
+      expect(result).toBe(42);
+    });
+  });
+
+  describe('subcommands', () => {
+    it('should invoke subcommand via property access', async () => {
+      let buildCalled = false;
+      const myCLI = cli('test').command('build', {
+        builder: (cmd) => cmd.option('watch', { type: 'boolean' }),
+        handler: (args) => {
+          buildCalled = true;
+          return { watching: args.watch };
+        },
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk.build({ watch: true });
+
+      expect(buildCalled).toBe(true);
+      expect(result.watching).toBe(true);
+    });
+
+    it('should invoke nested subcommands', async () => {
+      let migrateCalled = false;
+      const myCLI = cli('test').command('db', {
+        builder: (cmd) =>
+          cmd.command('migrate', {
+            builder: (c) => c.option('dry', { type: 'boolean' }),
+            handler: (args) => {
+              migrateCalled = true;
+              return { dryRun: args.dry };
+            },
+          }),
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk.db.migrate({ dry: true });
+
+      expect(migrateCalled).toBe(true);
+      expect(result.dryRun).toBe(true);
+    });
+
+    it('should throw when invoking command without handler', async () => {
+      const myCLI = cli('test').command('db', {
+        // No handler - container command
+        builder: (cmd) =>
+          cmd.command('migrate', {
+            handler: () => 'done',
+          }),
+      });
+
+      const sdk = myCLI.sdk();
+
+      await expect(sdk.db()).rejects.toThrow("Command 'db' has no handler");
+    });
+  });
+
+  describe('defaults', () => {
+    it('should apply default values for object args', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test', {
+        builder: (cmd) =>
+          cmd
+            .option('host', { type: 'string', default: 'localhost' })
+            .option('port', { type: 'number', default: 3000 }),
+        handler: (args) => {
+          receivedArgs = args;
+          return 'ok';
+        },
+      });
+
+      const sdk = myCLI.sdk();
+      await sdk({ port: 8080 });
+
+      expect(receivedArgs.host).toBe('localhost');
+      expect(receivedArgs.port).toBe(8080);
+    });
+
+    it('should allow overriding all defaults', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test', {
+        builder: (cmd) =>
+          cmd.option('verbose', { type: 'boolean', default: false }),
+        handler: (args) => {
+          receivedArgs = args;
+        },
+      });
+
+      const sdk = myCLI.sdk();
+      await sdk({ verbose: true });
+
+      expect(receivedArgs.verbose).toBe(true);
+    });
+  });
+
+  describe('middleware', () => {
+    it('should run middleware for object args', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test', {
+        builder: (cmd) => cmd.option('name', { type: 'string' }),
+        handler: (args) => {
+          receivedArgs = args;
+        },
+      }).middleware((args) => ({ ...args, timestamp: 12345 }));
+
+      const sdk = myCLI.sdk();
+      await sdk({ name: 'test' });
+
+      expect(receivedArgs.timestamp).toBe(12345);
+    });
+
+    it('should run parent middleware for subcommands', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test')
+        .middleware((args) => ({ ...args, fromRoot: true }))
+        .command('child', {
+          handler: (args) => {
+            receivedArgs = args;
+          },
+        });
+
+      const sdk = myCLI.sdk();
+      await sdk.child({});
+
+      expect(receivedArgs.fromRoot).toBe(true);
+    });
+  });
+
+  describe('validation', () => {
+    it('should validate string array args', async () => {
+      const myCLI = cli('test', {
+        builder: (cmd) =>
+          cmd.option('count', { type: 'number', required: true }),
+        handler: () => 'ok',
+      });
+
+      const sdk = myCLI.sdk();
+
+      // String array args go through full validation
+      await expect(sdk([])).rejects.toThrow();
+    });
+
+    it('should skip validation for object args (trust TypeScript)', async () => {
+      let receivedArgs: any;
+      const myCLI = cli('test', {
+        builder: (cmd) =>
+          cmd.option('count', { type: 'number', required: true }),
+        handler: (args) => {
+          receivedArgs = args;
+          return 'ok';
+        },
+      });
+
+      const sdk = myCLI.sdk();
+
+      // Object args skip validation - TypeScript should catch this
+      // but at runtime we allow it through
+      const result = await sdk({});
+      expect(result).toBe('ok');
+      expect(receivedArgs.count).toBeUndefined();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw handler errors directly', async () => {
+      const myCLI = cli('test', {
+        handler: () => {
+          throw new Error('Handler failed');
+        },
+      });
+
+      const sdk = myCLI.sdk();
+
+      await expect(sdk()).rejects.toThrow('Handler failed');
+    });
+
+    it('should throw for non-existent subcommands', async () => {
+      const myCLI = cli('test').command('build', { handler: () => 'ok' });
+
+      const sdk = myCLI.sdk();
+
+      // Access non-existent command returns undefined
+      expect((sdk as any).nonexistent).toBeUndefined();
+    });
+  });
+
+  describe('async handlers', () => {
+    it('should handle async handlers', async () => {
+      const myCLI = cli('test', {
+        handler: async () => {
+          await new Promise((r) => setTimeout(r, 10));
+          return { async: true };
+        },
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk();
+
+      expect(result.async).toBe(true);
+    });
+  });
+
+  describe('type safety', () => {
+    it('should preserve handler return type', async () => {
+      interface BuildResult {
+        files: string[];
+        success: boolean;
+      }
+
+      const myCLI = cli('test', {
+        handler: (): BuildResult => ({
+          files: ['a.js', 'b.js'],
+          success: true,
+        }),
+      });
+
+      const sdk = myCLI.sdk();
+      const result = await sdk();
+
+      // Type should be BuildResult & { $args: ... }
+      expect(result.files).toEqual(['a.js', 'b.js']);
+      expect(result.success).toBe(true);
+    });
+  });
+});

package/src/lib/test-harness.spec.ts

@@ -1,3 +1,4 @@
+import { it, describe, expect } from 'vitest';
 import cli from './public-api';
 import { TestHarness } from './test-harness';
 

package/src/lib/utils.spec.ts

@@ -1,3 +1,4 @@
+import { it, describe, expect } from 'vitest';
 import { stringToArgs } from './utils';
 
 describe('utils', () => {