cli-forge 1.2.3 → 1.3.0

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>>;
+}

package/src/lib/public-api.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/ban-types */
+/* eslint-disable @typescript-eslint/no-empty-object-type */
 import {
   ArrayOptionConfig,
   BooleanOptionConfig,
@@ -18,6 +18,7 @@ import {
 } from '@cli-forge/parser';
 
 import { InternalCLI } from './internal-cli';
+import type { PromptOptionConfig, PromptProvider } from './prompt-types';
 
 /**
  * Extracts the command name from a Command type.
@@ -87,7 +88,7 @@ export type CommandToChildEntry<T, TParentCLI = undefined> = {
 export interface CLI<
   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
 > {
@@ -121,7 +122,7 @@ export interface CLI<
     TCommandArgs extends TArgs,
     TChildHandlerReturn,
     TKey extends string,
-    // eslint-disable-next-line @typescript-eslint/ban-types
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
     TChildChildren = {}
   >(
     key: TKey,
@@ -424,6 +425,17 @@ export interface CLI<
     handler: ErrorHandler
   ): CLI<TArgs, THandlerReturn, TChildren, TParent>;
 
+  /**
+   * Registers a prompt provider for interactive option fulfillment.
+   * Multiple providers can be registered. Filtered providers are checked first
+   * (in registration order), then fallback providers (no filter).
+   *
+   * @param provider The prompt provider to register.
+   */
+  withPromptProvider(
+    provider: PromptProvider
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+
   /**
    * Registers a new option for the CLI command. This option will be accessible
    * within the command handler, as well as any subcommands.
@@ -441,7 +453,7 @@ export interface CLI<
     const TProps extends Record<string, { type: string }>
   >(
     name: TOption,
-    config: ObjectOptionConfig<TCoerce, TProps>
+    config: ObjectOptionConfig<TCoerce, TProps> & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -460,7 +472,7 @@ export interface CLI<
     const TConfig extends StringOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -476,7 +488,7 @@ export interface CLI<
     const TConfig extends NumberOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -492,7 +504,7 @@ export interface CLI<
     const TConfig extends BooleanOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -508,7 +520,7 @@ export interface CLI<
     const TConfig extends ArrayOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -524,7 +536,7 @@ export interface CLI<
     const TOptionConfig extends OptionConfig<any, any, any>
   >(
     name: TOption,
-    config: TOptionConfig
+    config: TOptionConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -551,7 +563,7 @@ export interface CLI<
     const TProps extends Record<string, { type: string }>
   >(
     name: TOption,
-    config: ObjectOptionConfig<TCoerce, TProps>
+    config: ObjectOptionConfig<TCoerce, TProps> & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -570,7 +582,7 @@ export interface CLI<
     const TConfig extends StringOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -586,7 +598,7 @@ export interface CLI<
     const TConfig extends NumberOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -602,7 +614,7 @@ export interface CLI<
     const TConfig extends BooleanOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -618,7 +630,7 @@ export interface CLI<
     const TConfig extends ArrayOptionConfig<any, any>
   >(
     name: TOption,
-    config: TConfig
+    config: TConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -634,7 +646,7 @@ export interface CLI<
     const TOptionConfig extends OptionConfig<any, any, any>
   >(
     name: TOption,
-    config: TOptionConfig
+    config: TOptionConfig & { prompt?: PromptOptionConfig<TArgs> }
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
@@ -928,13 +940,13 @@ export interface CLICommandOptions<
   /**
    * The children commands that exist before the builder runs.
    */
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TInitialChildren = {},
   TParent = any,
   /**
    * The children commands after the builder runs (includes TInitialChildren plus any added by builder).
    */
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TChildren = {}
 > {
   /**
@@ -1080,7 +1092,7 @@ export type SDKChildren<TChildren> = {
  * 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
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   // THandlerReturn extends void | undefined
   // ? SDKChildren<TChildren> // No handler = just children (not callable)
   SDKInvokable<TArgs, THandlerReturn> & SDKChildren<TChildren>;
@@ -1094,7 +1106,7 @@ export type SDKCommand<TArgs, THandlerReturn, TChildren> =
 export function cli<
   TArgs extends ParsedArgs,
   THandlerReturn = void,
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TChildren = {},
   TName extends string = string
 >(

package/src/lib/resolve-prompts.spec.ts

@@ -0,0 +1,311 @@
+import { describe, it, expect, vi } from 'vitest';
+import { resolvePrompts } from './resolve-prompts';
+import type { InternalOptionConfig } from '@cli-forge/parser';
+import type { PromptProvider } from './prompt-types';
+
+function makeConfig(
+  overrides: Partial<InternalOptionConfig> & { key: string }
+): InternalOptionConfig {
+  return {
+    type: 'string',
+    ...overrides,
+  } as InternalOptionConfig;
+}
+
+describe('resolvePrompts', () => {
+  it('should return empty object when no options need prompting', async () => {
+    const result = await resolvePrompts({
+      configuredOptions: {
+        name: makeConfig({ key: 'name' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map(),
+      providers: [],
+      currentArgs: { name: 'Alice' },
+    });
+    expect(result).toEqual({});
+  });
+
+  it('should prompt for required options missing values', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('prompted-value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        name: makeConfig({ key: 'name', required: true }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map(),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(result).toEqual({ name: 'prompted-value' });
+    expect(provider.prompt).toHaveBeenCalledOnce();
+  });
+
+  it('should not prompt for required options that already have values', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('prompted-value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        name: makeConfig({ key: 'name', required: true }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map(),
+      providers: [provider],
+      currentArgs: { name: 'existing' },
+    });
+
+    expect(result).toEqual({});
+    expect(provider.prompt).not.toHaveBeenCalled();
+  });
+
+  it('should call prompt callback with current args', async () => {
+    const promptFn = vi.fn().mockReturnValue('Enter token');
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('token-value'),
+    };
+
+    await resolvePrompts({
+      configuredOptions: {
+        token: makeConfig({ key: 'token' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map([['token', promptFn]]),
+      providers: [provider],
+      currentArgs: { someFlag: true },
+    });
+
+    expect(promptFn).toHaveBeenCalledWith({ someFlag: true });
+  });
+
+  it('should not prompt when callback returns null', async () => {
+    const promptFn = vi.fn().mockReturnValue(null);
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        token: makeConfig({ key: 'token' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map([['token', promptFn]]),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(result).toEqual({});
+    expect(provider.prompt).not.toHaveBeenCalled();
+  });
+
+  it('should prompt for implied options when trigger is set and implied option is missing', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        output: makeConfig({ key: 'output' }),
+        format: makeConfig({ key: 'format' }),
+      },
+      configuredImplies: { output: new Set(['format']) },
+      promptConfigs: new Map(),
+      providers: [provider],
+      currentArgs: { output: '/tmp/out' },
+    });
+
+    expect(result).toEqual({ format: 'value' });
+  });
+
+  it('should not prompt for implied options when trigger is not set', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        output: makeConfig({ key: 'output' }),
+        format: makeConfig({ key: 'format' }),
+      },
+      configuredImplies: { output: new Set(['format']) },
+      promptConfigs: new Map(),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(result).toEqual({});
+    expect(provider.prompt).not.toHaveBeenCalled();
+  });
+
+  it('should group options by matched provider for batch calls', async () => {
+    const batchProvider: PromptProvider = {
+      filter: (name) => name.startsWith('db'),
+      promptBatch: vi
+        .fn()
+        .mockResolvedValue({ dbHost: 'localhost', dbPort: 5432 }),
+    };
+    const fallbackProvider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('fallback'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        dbHost: makeConfig({ key: 'dbHost' }),
+        dbPort: makeConfig({ key: 'dbPort' }),
+        name: makeConfig({ key: 'name' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map([
+        ['dbHost', true],
+        ['dbPort', true],
+        ['name', true],
+      ]),
+      providers: [batchProvider, fallbackProvider],
+      currentArgs: {},
+    });
+
+    expect(batchProvider.promptBatch).toHaveBeenCalledOnce();
+    expect(fallbackProvider.prompt).toHaveBeenCalledOnce();
+    expect(result).toEqual({
+      dbHost: 'localhost',
+      dbPort: 5432,
+      name: 'fallback',
+    });
+  });
+
+  it('should skip options where prompt is false', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        name: makeConfig({ key: 'name', required: true }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map([['name', false]]),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(result).toEqual({});
+    expect(provider.prompt).not.toHaveBeenCalled();
+  });
+
+  it('should throw when options need prompting but no provider matches', async () => {
+    await expect(
+      resolvePrompts({
+        configuredOptions: {
+          name: makeConfig({ key: 'name' }),
+        },
+        configuredImplies: {},
+        promptConfigs: new Map([['name', true]]),
+        providers: [],
+        currentArgs: {},
+      })
+    ).rejects.toThrow(/no prompt provider/i);
+  });
+
+  it('should skip internal options (help, version, unmatched, --)', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        help: makeConfig({ key: 'help', required: true }),
+        version: makeConfig({ key: 'version', required: true }),
+        unmatched: makeConfig({ key: 'unmatched', required: true }),
+        '--': makeConfig({ key: '--', required: true }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map(),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(result).toEqual({});
+    expect(provider.prompt).not.toHaveBeenCalled();
+  });
+
+  it('should prefer promptBatch over prompt when both are available', async () => {
+    let batchCalled = false;
+    const provider: PromptProvider = {
+      promptBatch: vi.fn().mockImplementation(async (options) => {
+        batchCalled = true;
+        const result: Record<string, unknown> = {};
+        for (const opt of options) {
+          result[opt.name] = 'batch-value';
+        }
+        return result;
+      }),
+      prompt: vi.fn().mockImplementation(async () => {
+        throw new Error('Should not be called when promptBatch exists');
+      }),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        a: makeConfig({ key: 'a' }),
+        b: makeConfig({ key: 'b' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map([
+        ['a', true],
+        ['b', true],
+      ]),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(batchCalled).toBe(true);
+    expect(provider.prompt).not.toHaveBeenCalled();
+    expect(result).toEqual({ a: 'batch-value', b: 'batch-value' });
+  });
+
+  it('should prompt with string label when prompt config is a string', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    await resolvePrompts({
+      configuredOptions: {
+        name: makeConfig({ key: 'name' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map([['name', 'What is your name?']]),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(provider.prompt).toHaveBeenCalledOnce();
+    const calledOption = (provider.prompt as ReturnType<typeof vi.fn>).mock
+      .calls[0][0];
+    expect(calledOption.name).toBe('name');
+    expect(calledOption.config.prompt).toBe('What is your name?');
+  });
+
+  it('should not prompt for non-required options without explicit prompt config', async () => {
+    const provider: PromptProvider = {
+      prompt: vi.fn().mockResolvedValue('value'),
+    };
+
+    const result = await resolvePrompts({
+      configuredOptions: {
+        name: makeConfig({ key: 'name' }),
+      },
+      configuredImplies: {},
+      promptConfigs: new Map(),
+      providers: [provider],
+      currentArgs: {},
+    });
+
+    expect(result).toEqual({});
+    expect(provider.prompt).not.toHaveBeenCalled();
+  });
+});

package/src/lib/resolve-prompts.ts

@@ -0,0 +1,156 @@
+import type { InternalOptionConfig } from '@cli-forge/parser';
+import type {
+  PromptConfig,
+  PromptOption,
+  PromptOptionConfig,
+  PromptProvider,
+} from './prompt-types';
+
+/**
+ * Collects options that need prompting, matches them to providers,
+ * executes prompts, and returns the prompted values.
+ */
+export async function resolvePrompts(opts: {
+  configuredOptions: Record<string, InternalOptionConfig>;
+  configuredImplies: Record<string, Set<string>>;
+  promptConfigs: Map<string, PromptOptionConfig<any>>;
+  providers: PromptProvider[];
+  currentArgs: Record<string, unknown>;
+}): Promise<Record<string, unknown>> {
+  const {
+    configuredOptions,
+    configuredImplies,
+    promptConfigs,
+    providers,
+    currentArgs,
+  } = opts;
+
+  // Step 1: Collect promptable options
+  const promptableOptions: PromptOption[] = [];
+
+  for (const [name, config] of Object.entries(configuredOptions)) {
+    // Skip internal options
+    if (
+      name === 'help' ||
+      name === 'version' ||
+      name === 'unmatched' ||
+      name === '--'
+    ) {
+      continue;
+    }
+
+    // Already has a value — skip unless prompt is explicitly true/string
+    const hasValue = currentArgs[name] !== undefined;
+
+    const promptSetting = promptConfigs.get(name);
+    let resolved: PromptConfig | null | undefined;
+
+    if (typeof promptSetting === 'function') {
+      resolved = promptSetting(currentArgs);
+      // Callback: null/undefined treated as false
+      if (resolved === null || resolved === undefined) {
+        continue;
+      }
+    } else if (promptSetting !== undefined) {
+      // Static value
+      resolved = promptSetting;
+    } else {
+      // Not specified: prompt only if required and missing value
+      if (hasValue) continue;
+
+      const isRequired = config.required === true;
+      const isImplied = isOptionImplied(name, configuredImplies, currentArgs);
+
+      if (!isRequired && !isImplied) continue;
+      if (providers.length === 0) continue; // No providers, let validation handle it
+
+      resolved = true; // Will prompt
+    }
+
+    if (resolved === false) continue;
+    if (hasValue && resolved !== true && typeof resolved !== 'string') continue;
+
+    promptableOptions.push({
+      name,
+      config: {
+        ...config,
+        prompt: resolved === true ? true : resolved ?? undefined,
+      },
+    });
+  }
+
+  if (promptableOptions.length === 0) {
+    return {};
+  }
+
+  // Step 2: Match options to providers
+  const filteredProviders = providers.filter((p) => p.filter);
+  const fallbackProviders = providers.filter((p) => !p.filter);
+
+  const providerGroups = new Map<PromptProvider, PromptOption[]>();
+  const unmatchedOptions: PromptOption[] = [];
+
+  for (const option of promptableOptions) {
+    let matched = false;
+    for (const provider of filteredProviders) {
+      if (provider.filter!(option.name, option.config)) {
+        if (!providerGroups.has(provider)) {
+          providerGroups.set(provider, []);
+        }
+        providerGroups.get(provider)!.push(option);
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      unmatchedOptions.push(option);
+    }
+  }
+
+  // Assign unmatched options to first fallback provider
+  if (unmatchedOptions.length > 0) {
+    if (fallbackProviders.length === 0) {
+      const names = unmatchedOptions.map((o) => `'${o.name}'`).join(', ');
+      throw new Error(
+        `Option(s) ${names} require prompting but no prompt provider is available`
+      );
+    }
+    const fallback = fallbackProviders[0];
+    if (!providerGroups.has(fallback)) {
+      providerGroups.set(fallback, []);
+    }
+    providerGroups.get(fallback)!.push(...unmatchedOptions);
+  }
+
+  // Step 3: Execute prompts
+  const results: Record<string, unknown> = {};
+
+  for (const [provider, options] of providerGroups) {
+    if (provider.promptBatch) {
+      const batchResults = await provider.promptBatch(options);
+      Object.assign(results, batchResults);
+    } else if (provider.prompt) {
+      for (const option of options) {
+        results[option.name] = await provider.prompt(option);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Check if an option is implied by another option that has been set.
+ */
+function isOptionImplied(
+  name: string,
+  configuredImplies: Record<string, Set<string>>,
+  currentArgs: Record<string, unknown>
+): boolean {
+  for (const [trigger, implied] of Object.entries(configuredImplies)) {
+    if (implied.has(name) && currentArgs[trigger] !== undefined) {
+      return true;
+    }
+  }
+  return false;
+}