cli-forge 1.2.3 → 1.3.0

package/dist/prompt-providers/clack.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClackPromptProvider = void 0;
+exports.createClackPromptProvider = createClackPromptProvider;
+/**
+ * Creates a prompt provider backed by @clack/prompts.
+ * Requires `@clack/prompts` as a peer dependency.
+ *
+ * The provider uses dynamic imports so that `@clack/prompts` is only
+ * loaded when prompting actually occurs.
+ */
+function createClackPromptProvider(providerOptions) {
+    // Build the common stream options once; spread into every prompt call.
+    const streamOpts = {};
+    if (providerOptions?.input)
+        streamOpts.input = providerOptions.input;
+    if (providerOptions?.output)
+        streamOpts.output = providerOptions.output;
+    return {
+        async promptBatch(options) {
+            const clack = await import('@clack/prompts');
+            const results = {};
+            for (const option of options) {
+                const message = getLabel(option);
+                const defaultValue = getDefault(option.config);
+                let value;
+                if (option.config.type === 'boolean') {
+                    value = await clack.confirm({
+                        ...streamOpts,
+                        message,
+                        initialValue: typeof defaultValue === 'boolean' ? defaultValue : undefined,
+                    });
+                }
+                else if (hasChoices(option.config)) {
+                    const choices = getChoices(option.config);
+                    if (option.config.type === 'array') {
+                        value = await clack.multiselect({
+                            ...streamOpts,
+                            message,
+                            options: choices.map((c) => ({ value: c, label: String(c) })),
+                        });
+                    }
+                    else {
+                        value = await clack.select({
+                            ...streamOpts,
+                            message,
+                            options: choices.map((c) => ({ value: c, label: String(c) })),
+                        });
+                    }
+                }
+                else if (option.config.type === 'number') {
+                    const raw = await clack.text({
+                        ...streamOpts,
+                        message,
+                        placeholder: defaultValue !== undefined ? String(defaultValue) : undefined,
+                        defaultValue: defaultValue !== undefined ? String(defaultValue) : undefined,
+                        validate: (val) => {
+                            if (val && isNaN(Number(val))) {
+                                return 'Please enter a valid number';
+                            }
+                            return undefined;
+                        },
+                    });
+                    if (clack.isCancel(raw)) {
+                        clack.cancel('Operation cancelled.');
+                        throw new Error('Prompt cancelled by user');
+                    }
+                    value = raw !== undefined && raw !== '' ? Number(raw) : defaultValue;
+                }
+                else {
+                    // string, array without choices
+                    value = await clack.text({
+                        ...streamOpts,
+                        message,
+                        placeholder: defaultValue !== undefined ? String(defaultValue) : undefined,
+                        defaultValue: defaultValue !== undefined ? String(defaultValue) : undefined,
+                    });
+                }
+                // clack returns a Symbol when the user cancels (Ctrl+C)
+                if (clack.isCancel(value)) {
+                    clack.cancel('Operation cancelled.');
+                    throw new Error('Prompt cancelled by user');
+                }
+                results[option.name] = value;
+            }
+            return results;
+        },
+    };
+}
+/**
+ * Default clack prompt provider, uses stdin/stdout
+ */
+exports.ClackPromptProvider = createClackPromptProvider();
+/**
+ * Determine the label to show for a prompt option.
+ * Priority: prompt string > description > option name.
+ */
+function getLabel(option) {
+    if (typeof option.config.prompt === 'string') {
+        return option.config.prompt;
+    }
+    return option.config.description ?? option.name;
+}
+/**
+ * Extract the default value from an option config.
+ * Handles the three forms:
+ * - Primitive value directly
+ * - `{ value: T; description: string }` object
+ * - `{ factory: () => T; description: string }` object
+ */
+function getDefault(config) {
+    if (config.default === undefined)
+        return undefined;
+    if (typeof config.default === 'object' && config.default !== null) {
+        if ('factory' in config.default) {
+            return config.default.factory();
+        }
+        if ('value' in config.default) {
+            return config.default.value;
+        }
+    }
+    return config.default;
+}
+function hasChoices(config) {
+    return ('choices' in config &&
+        config['choices'] !== undefined);
+}
+function getChoices(config) {
+    const cfg = config;
+    const choices = cfg['choices'];
+    if (typeof choices === 'function') {
+        return choices();
+    }
+    return choices ?? [];
+}
+//# sourceMappingURL=clack.js.map

package/dist/prompt-providers/clack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clack.js","sourceRoot":"","sources":["../../src/prompt-providers/clack.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "cli-forge",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "dependencies": {
     "tslib": "^2.3.0",
-    "@cli-forge/parser": "1.2.3"
+    "@cli-forge/parser": "1.3.0"
   },
   "peerDependencies": {
+    "@clack/prompts": "*",
     "markdown-factory": "^0.2.0",
     "tsx": "^4.19.0",
     "zod": "^4.1.13"
   },
   "peerDependenciesMeta": {
+    "@clack/prompts": {
+      "optional": true
+    },
     "markdown-factory": {
       "optional": true,
       "dev": true
@@ -53,6 +57,11 @@
       "require": "./dist/middleware/*.js",
       "types": "./dist/middleware/*.d.ts"
     },
+    "./prompt-providers/clack": {
+      "require": "./dist/prompt-providers/clack.js",
+      "types": "./dist/prompt-providers/clack.d.ts",
+      "import": "./dist/prompt-providers/clack.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/index.ts

@@ -9,5 +9,6 @@ export type {
   ExtractChildren,
 } from './lib/composable-builder';
 export type { ArgumentsOf } from './lib/utils';
+export type { PromptConfig, PromptOptionConfig, PromptOption, PromptProvider } from './lib/prompt-types';
 export { ConfigurationProviders } from './lib/configuration-providers';
 export type { LocalizationDictionary, LocalizationFunction } from '@cli-forge/parser';

package/src/lib/composable-builder.ts

@@ -19,7 +19,7 @@ export type ExtractArgs<T> = T extends CLI<infer A, any, any, any> ? A : never;
  */
 export type ComposableBuilder<
   TArgs2 extends ParsedArgs,
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TAddedChildren = {}
 > = <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
   init: CLI<TInit, THandlerReturn, TChildren, TParent>
@@ -39,11 +39,11 @@ export type ComposableBuilder<
  */
 export function makeComposableBuilder<
   TArgs2 extends ParsedArgs,
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TChildren2 = {}
 >(
   fn: (
-    // eslint-disable-next-line @typescript-eslint/ban-types
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
     init: CLI<ParsedArgs, any, {}, any>
   ) => CLI<TArgs2, any, TChildren2, any>
 ) {

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';
 
 /**
@@ -55,7 +57,7 @@ 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>
@@ -122,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,
@@ -287,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
   > {
@@ -372,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;
   }
@@ -381,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;
   }
@@ -829,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
@@ -1025,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({
@@ -1079,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;
   }
 }