cli-forge 1.2.2 → 1.3.0

package/src/lib/internal-cli.spec.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it } from 'vitest';
 import { InternalCLI } from './internal-cli';
 import { cli } from './public-api';
+import type { PromptProvider } from './prompt-types';
 
 const ORIGINAL_CONSOLE_LOG = console.log;
 
@@ -1250,4 +1251,303 @@ describe('cliForge', () => {
       expect(result.watch).toBe(true);
     });
   });
+
+  describe('prompt providers', () => {
+    it('should register a prompt provider via withPromptProvider', () => {
+      const provider: PromptProvider = {
+        prompt: async () => 'test-value',
+      };
+      const app = cli('test').withPromptProvider(provider);
+      // Should return CLI for chaining
+      expect(app).toBeDefined();
+    });
+
+    it('should throw if provider has neither prompt nor promptBatch', () => {
+      expect(() => {
+        cli('test').withPromptProvider({} as any);
+      }).toThrow(/must implement at least one of/);
+    });
+
+    it('should store prompt config from option registration', () => {
+      const app = cli('test')
+        .option('name', { type: 'string', prompt: true })
+        .option('age', { type: 'number', prompt: 'How old are you?' })
+        .option('debug', { type: 'boolean' });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.get('name')).toBe(true);
+      expect(internal.promptConfigs.get('age')).toBe('How old are you?');
+      expect(internal.promptConfigs.has('debug')).toBe(false);
+    });
+
+    it('should store prompt config from positional registration', () => {
+      const app = cli('test')
+        .positional('file', { type: 'string', prompt: 'Which file?' });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.get('file')).toBe('Which file?');
+    });
+
+    it('should not store prompt config when prompt is not provided', () => {
+      const app = cli('test')
+        .option('name', { type: 'string' });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.size).toBe(0);
+    });
+
+    it('should store prompt callback config', () => {
+      const promptFn = () => 'Enter value';
+      const app = cli('test')
+        .option('token', { type: 'string', prompt: promptFn });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.get('token')).toBe(promptFn);
+    });
+
+    it('should propagate prompt providers to subcommands', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test')
+        .withPromptProvider(provider)
+        .command('sub', {
+          builder: (cmd) =>
+            cmd.option('name', { type: 'string', required: true }),
+          handler: () => {},
+        });
+
+      await app.forge(['sub']);
+      expect(prompted).toContain('name');
+    });
+  });
+
+  describe('prompt resolution in forge', () => {
+    it('should prompt for required options with no value when provider exists', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return option.name === 'name' ? 'Alice' : 42;
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', required: true })
+        .option('age', { type: 'number', required: true })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(prompted).toContain('name');
+      expect(prompted).toContain('age');
+    });
+
+    it('should not prompt for options with values already provided', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', required: true })
+        .withPromptProvider(provider);
+
+      await app.forge(['--name', 'Bob']);
+      expect(prompted).not.toContain('name');
+    });
+
+    it('should prompt when prompt is true even if not required', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', prompt: true })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(prompted).toContain('name');
+    });
+
+    it('should still prompt when prompt is true even if value already provided', async () => {
+      const prompted: string[] = [];
+      let handlerArgs: any;
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'prompted-value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: (args) => {
+          handlerArgs = args;
+        },
+      })
+        .option('name', { type: 'string', prompt: true })
+        .withPromptProvider(provider);
+
+      await app.forge(['--name', 'cli-value']);
+      expect(prompted).toContain('name');
+      expect(handlerArgs.name).toBe('prompted-value');
+    });
+
+    it('should not prompt when prompt is false even if required', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', required: true, prompt: false })
+        .withPromptProvider(provider);
+
+      // This will throw due to required validation, but should not prompt
+      await expect(app.forge([])).rejects.toThrow();
+      expect(prompted).not.toContain('name');
+    });
+
+    it('should use prompt callback to resolve config', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('token', {
+          type: 'string',
+          prompt: (args: any) => (args.authFile ? false : 'Enter token'),
+        })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(prompted).toContain('token');
+    });
+
+    it('should throw when prompting needed but no provider registered', async () => {
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', prompt: true });
+
+      await expect(app.forge([])).rejects.toThrow(/no prompt provider/i);
+    });
+
+    it('should use filtered providers before fallback providers', async () => {
+      const calls: Array<{ provider: string; option: string }> = [];
+      const filteredProvider: PromptProvider = {
+        filter: (name) => name === 'secret',
+        prompt: async (option) => {
+          calls.push({ provider: 'filtered', option: option.name });
+          return 'secret-value';
+        },
+      };
+      const fallbackProvider: PromptProvider = {
+        prompt: async (option) => {
+          calls.push({ provider: 'fallback', option: option.name });
+          return 'fallback-value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', prompt: true })
+        .option('secret', { type: 'string', prompt: true })
+        .withPromptProvider(filteredProvider)
+        .withPromptProvider(fallbackProvider);
+
+      await app.forge([]);
+      expect(calls).toContainEqual({ provider: 'filtered', option: 'secret' });
+      expect(calls).toContainEqual({ provider: 'fallback', option: 'name' });
+    });
+
+    it('should prefer promptBatch over prompt when available', async () => {
+      let batchCalled = false;
+      const provider: PromptProvider = {
+        promptBatch: async (options) => {
+          batchCalled = true;
+          const result: Record<string, unknown> = {};
+          for (const opt of options) {
+            result[opt.name] = 'batch-value';
+          }
+          return result;
+        },
+        prompt: async () => {
+          throw new Error('Should not be called when promptBatch exists');
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('a', { type: 'string', prompt: true })
+        .option('b', { type: 'string', prompt: true })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(batchCalled).toBe(true);
+    });
+
+    it('should prompt, inject values, and pass validation', async () => {
+      let handlerArgs: any;
+      const provider: PromptProvider = {
+        promptBatch: async (options) => {
+          const results: Record<string, unknown> = {};
+          for (const opt of options) {
+            if (opt.config.type === 'number') {
+              results[opt.name] = 42;
+            } else {
+              results[opt.name] = 'prompted-' + opt.name;
+            }
+          }
+          return results;
+        },
+      };
+
+      const app = cli('test', {
+        handler: (args) => {
+          handlerArgs = args;
+        },
+      })
+        .option('name', { type: 'string', required: true })
+        .option('port', { type: 'number', prompt: 'Which port?' })
+        .option('verbose', { type: 'boolean', default: false })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+
+      expect(handlerArgs.name).toBe('prompted-name');
+      expect(handlerArgs.port).toBe(42);
+      expect(handlerArgs.verbose).toBe(false); // default, not prompted
+    });
+  });
 });

package/src/lib/internal-cli.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/ban-types */
+/* eslint-disable @typescript-eslint/no-empty-object-type */
 import {
   ArgvParser,
   EnvOptionConfig,
@@ -22,6 +22,8 @@ import {
   ErrorHandler,
   SDKCommand,
 } from './public-api';
+import type { PromptProvider, PromptOptionConfig } from './prompt-types';
+import { resolvePrompts } from './resolve-prompts';
 import { getCallingFile, getParentPackageJson } from './utils';
 
 /**
@@ -43,14 +45,43 @@ import { getCallingFile, getParentPackageJson } from './utils';
  *   }).forge();
  * ```
  */
+/**
+ * Cross-realm brand symbol used to identify InternalCLI instances across
+ * different copies of the cli-forge package (e.g. when pnpm resolves
+ * multiple copies due to differing peer dependencies). `Symbol.for()`
+ * returns the same symbol globally, so the brand check works even when
+ * `instanceof` would fail.
+ */
+const CLI_FORGE_BRAND = Symbol.for('cli-forge:InternalCLI');
+
 export class InternalCLI<
   TArgs extends ParsedArgs = ParsedArgs,
   THandlerReturn = void,
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TChildren = {},
   TParent = undefined
 > implements CLI<TArgs, THandlerReturn, TChildren, TParent>
 {
+  /**
+   * Cross-realm brand for identifying InternalCLI instances across
+   * different package copies. See {@link CLI_FORGE_BRAND}.
+   */
+  readonly [CLI_FORGE_BRAND] = true;
+
+  /**
+   * Check whether `obj` is an InternalCLI instance, even when it was
+   * created by a different copy of the cli-forge package.
+   */
+  static isInternalCLI(
+    obj: unknown
+  ): obj is InternalCLI<any, any, any, any> {
+    return (
+      obj != null &&
+      typeof obj === 'object' &&
+      CLI_FORGE_BRAND in obj
+    );
+  }
+
   /**
    * For internal use only. Stick to properties available on {@link CLI}.
    */
@@ -93,6 +124,14 @@ export class InternalCLI<
     (cli: any, args: TArgs) => Promise<void> | void
   > = [];
 
+  registeredPromptProviders: PromptProvider[] = [];
+
+  /**
+   * Stores prompt config for each option, keyed by option name.
+   * Set when .option() is called with a `prompt` property.
+   */
+  promptConfigs: Map<string, PromptOptionConfig<any>> = new Map();
+
   /**
    * Set when a `$0` alias replaces the root builder via `.command()`.
    * The $0 builder should only run if no explicit subcommand is given,
@@ -258,7 +297,7 @@ export class InternalCLI<
               CLI<TArgs, THandlerReturn, TChildren, TParent>
             >;
           }
-        : // eslint-disable-next-line @typescript-eslint/ban-types
+        : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
           {}),
     TParent
   > {
@@ -304,10 +343,16 @@ export class InternalCLI<
           this.registeredCommands[alias] = cmd;
         }
       }
-    } else if (keyOrCommand instanceof InternalCLI) {
-      const cmd = keyOrCommand;
+    } else if (InternalCLI.isInternalCLI(keyOrCommand)) {
+      const cmd = keyOrCommand as InternalCLI<any, any, any, any>;
       if (cmd.name === '$0') {
         this.withRootCommandConfiguration(cmd.configuration as any);
+        // Copy any commands registered on the $0 instance (e.g. subcommands
+        // added via `.commands()` after the $0 CLI was created).
+        for (const [key, subcmd] of Object.entries(cmd.registeredCommands)) {
+          subcmd._parent = this;
+          this.registeredCommands[key] = subcmd;
+        }
         return this as any;
       }
       cmd._parent = this;
@@ -337,8 +382,12 @@ export class InternalCLI<
   option<
     TOption extends string,
     const TOptionConfig extends OptionConfig<any, any, any>
-  >(name: TOption, config: TOptionConfig) {
-    this.parser.option(name, config);
+  >(name: TOption, config: TOptionConfig & { prompt?: PromptOptionConfig<TArgs> }) {
+    const { prompt, ...parserConfig } = config;
+    if (prompt !== undefined) {
+      this.promptConfigs.set(name, prompt);
+    }
+    this.parser.option(name, parserConfig as TOptionConfig);
     // Interface modifies the return type to reflect new params, cast is necessay.... I think 🤔
     return this as any;
   }
@@ -346,8 +395,12 @@ export class InternalCLI<
   positional<
     TOption extends string,
     const TOptionConfig extends OptionConfig<any, any, any>
-  >(name: TOption, config: TOptionConfig) {
-    this.parser.positional(name, config);
+  >(name: TOption, config: TOptionConfig & { prompt?: PromptOptionConfig<TArgs> }) {
+    const { prompt, ...parserConfig } = config;
+    if (prompt !== undefined) {
+      this.promptConfigs.set(name, prompt);
+    }
+    this.parser.positional(name, parserConfig as TOptionConfig);
     // Interface modifies the return type to reflect new params, cast is necessay.... I think 🤔
     return this as any;
   }
@@ -794,6 +847,18 @@ export class InternalCLI<
     return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
+  withPromptProvider(
+    provider: PromptProvider
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
+    if (!provider.prompt && !provider.promptBatch) {
+      throw new Error(
+        "Prompt provider must implement at least one of 'prompt' or 'promptBatch'"
+      );
+    }
+    this.registeredPromptProviders.push(provider);
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
+  }
+
   group(
     labelOrConfigObject:
       | string
@@ -990,6 +1055,47 @@ export class InternalCLI<
       // seeded with the accumulated values from the discovery loop.
       // The alreadyParsed values ensure proper required-option
       // validation and prevent positional re-consumption.
+
+      // Prompt for missing option values before final validation.
+      // Collect prompt providers from the full command chain.
+      const allPromptProviders: PromptProvider[] = [
+        ...this.registeredPromptProviders,
+      ];
+      const allPromptConfigs = new Map(this.promptConfigs);
+      {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let walkCmd: InternalCLI<any, any, any, any> = this;
+        for (const command of this.commandChain) {
+          walkCmd = walkCmd.registeredCommands[command];
+          for (const p of walkCmd.registeredPromptProviders) {
+            allPromptProviders.push(p);
+          }
+          for (const [k, v] of walkCmd.promptConfigs) {
+            allPromptConfigs.set(k, v);
+          }
+        }
+      }
+
+      if (allPromptProviders.length > 0 || allPromptConfigs.size > 0) {
+        const promptedValues = await resolvePrompts({
+          configuredOptions: this.parser.configuredOptions as Record<
+            string,
+            any
+          >,
+          configuredImplies: this.parser.configuredImplies,
+          promptConfigs: allPromptConfigs,
+          providers: allPromptProviders,
+          currentArgs: mergedArgs,
+        });
+
+        // Inject prompted values into accumulated args
+        for (const [key, value] of Object.entries(promptedValues)) {
+          if (value !== undefined) {
+            mergedArgs[key] = value;
+          }
+        }
+      }
+
       try {
         argv = this.parser
           .clone({
@@ -1044,6 +1150,8 @@ export class InternalCLI<
     }
     clone.commandChain = [...this.commandChain];
     clone.requiresCommand = this.requiresCommand;
+    clone.registeredPromptProviders = [...this.registeredPromptProviders];
+    clone.promptConfigs = new Map(this.promptConfigs);
     return clone;
   }
 }

package/src/lib/prompt-types.ts

@@ -0,0 +1,48 @@
+import type { InternalOptionConfig } from '@cli-forge/parser';
+
+/**
+ * Static prompt configuration for an option.
+ * - `true` — always prompt
+ * - `string` — always prompt with this label
+ * - `false` — never prompt
+ */
+export type PromptConfig = boolean | string;
+
+/**
+ * Full prompt configuration, including dynamic resolution.
+ * When a function is provided, it receives accumulated args and returns
+ * a static PromptConfig. Returning null/undefined from the callback
+ * is treated as falsy (don't prompt).
+ */
+export type PromptOptionConfig<TArgs = unknown> =
+  | PromptConfig
+  | ((args: Partial<TArgs>) => PromptConfig | null | undefined);
+
+/**
+ * An option that needs prompting, passed to prompt providers.
+ */
+export interface PromptOption {
+  /** The option name (key) */
+  name: string;
+  /** The full option config from the parser, with resolved prompt value */
+  config: InternalOptionConfig & { prompt?: PromptConfig };
+}
+
+/**
+ * A prompt provider that can fulfill missing option values interactively.
+ */
+export interface PromptProvider {
+  /**
+   * If provided, this provider only handles options where filter returns true.
+   * Providers without filters act as fallbacks.
+   */
+  filter?: (name: string, config: InternalOptionConfig) => boolean;
+  /**
+   * Prompt for a single option. Called per-option if promptBatch is not defined.
+   */
+  prompt?: (option: PromptOption) => Promise<unknown>;
+  /**
+   * Prompt for multiple options at once. Preferred over prompt when available.
+   */
+  promptBatch?: (options: PromptOption[]) => Promise<Record<string, unknown>>;
+}