cli-forge 1.2.3 → 1.4.0

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

package/src/prompt-providers/clack.spec.ts

@@ -0,0 +1,376 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { PromptOption } from '../lib/prompt-types';
+
+// Mock the dynamic import of @clack/prompts
+const mockClack = {
+  text: vi.fn(),
+  confirm: vi.fn(),
+  select: vi.fn(),
+  multiselect: vi.fn(),
+  cancel: vi.fn(),
+  isCancel: vi.fn().mockReturnValue(false),
+};
+
+vi.mock('@clack/prompts', () => mockClack);
+
+// Import after mock is set up
+import { createClackPromptProvider } from './clack';
+
+function makeOption(
+  overrides: Partial<PromptOption['config']> & { name: string }
+): PromptOption {
+  const { name, ...config } = overrides;
+  return {
+    name,
+    config: { type: 'string', key: name, ...config } as PromptOption['config'],
+  };
+}
+
+describe('createClackPromptProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockClack.isCancel.mockReturnValue(false);
+  });
+
+  describe('type mapping', () => {
+    it('should use confirm() for boolean options', async () => {
+      mockClack.confirm.mockResolvedValue(true);
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({ name: 'verbose', type: 'boolean' }),
+      ]);
+
+      expect(mockClack.confirm).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'verbose' })
+      );
+      expect(result).toEqual({ verbose: true });
+    });
+
+    it('should pass initialValue for boolean options with defaults', async () => {
+      mockClack.confirm.mockResolvedValue(false);
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({ name: 'verbose', type: 'boolean', default: true }),
+      ]);
+
+      expect(mockClack.confirm).toHaveBeenCalledWith(
+        expect.objectContaining({ initialValue: true })
+      );
+    });
+
+    it('should use text() for string options without choices', async () => {
+      mockClack.text.mockResolvedValue('hello');
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({ name: 'name', type: 'string' }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'name' })
+      );
+      expect(result).toEqual({ name: 'hello' });
+    });
+
+    it('should use select() for string options with choices', async () => {
+      mockClack.select.mockResolvedValue('b');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({
+          name: 'color',
+          type: 'string',
+          choices: ['a', 'b', 'c'],
+        } as any),
+      ]);
+
+      expect(mockClack.select).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'color',
+          options: [
+            { value: 'a', label: 'a' },
+            { value: 'b', label: 'b' },
+            { value: 'c', label: 'c' },
+          ],
+        })
+      );
+    });
+
+    it('should use multiselect() for array options with choices', async () => {
+      mockClack.multiselect.mockResolvedValue(['x', 'z']);
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({
+          name: 'tags',
+          type: 'array',
+          choices: ['x', 'y', 'z'],
+        } as any),
+      ]);
+
+      expect(mockClack.multiselect).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'tags',
+          options: [
+            { value: 'x', label: 'x' },
+            { value: 'y', label: 'y' },
+            { value: 'z', label: 'z' },
+          ],
+        })
+      );
+      expect(result).toEqual({ tags: ['x', 'z'] });
+    });
+
+    it('should use text() for number options and coerce to Number', async () => {
+      mockClack.text.mockResolvedValue('42');
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({ name: 'port', type: 'number' }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'port' })
+      );
+      expect(result).toEqual({ port: 42 });
+    });
+
+    it('should use default for number options when input is empty', async () => {
+      mockClack.text.mockResolvedValue('');
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({ name: 'port', type: 'number', default: 3000 }),
+      ]);
+
+      expect(result).toEqual({ port: 3000 });
+    });
+
+    it('should validate number input rejects non-numeric values', async () => {
+      mockClack.text.mockResolvedValue('42');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({ name: 'port', type: 'number' }),
+      ]);
+
+      // Extract the validate function that was passed to clack.text
+      const callArgs = mockClack.text.mock.calls[0][0];
+      expect(callArgs.validate('abc')).toBe('Please enter a valid number');
+      expect(callArgs.validate('42')).toBeUndefined();
+      expect(callArgs.validate('')).toBeUndefined();
+    });
+  });
+
+  describe('label resolution', () => {
+    it('should use prompt string as label when available', async () => {
+      mockClack.text.mockResolvedValue('val');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({
+          name: 'token',
+          type: 'string',
+          description: 'API token',
+          prompt: 'Enter your API token',
+        }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'Enter your API token' })
+      );
+    });
+
+    it('should use description as label when prompt is boolean', async () => {
+      mockClack.text.mockResolvedValue('val');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({
+          name: 'token',
+          type: 'string',
+          description: 'API token',
+          prompt: true,
+        }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'API token' })
+      );
+    });
+
+    it('should fall back to option name when no description or prompt string', async () => {
+      mockClack.text.mockResolvedValue('val');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({ name: 'token', type: 'string' }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'token' })
+      );
+    });
+  });
+
+  describe('default value extraction', () => {
+    it('should pass primitive defaults as placeholder and defaultValue', async () => {
+      mockClack.text.mockResolvedValue('override');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({ name: 'host', type: 'string', default: 'localhost' }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({
+          placeholder: 'localhost',
+          defaultValue: 'localhost',
+        })
+      );
+    });
+
+    it('should extract value from { value, description } defaults', async () => {
+      mockClack.text.mockResolvedValue('override');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({
+          name: 'host',
+          type: 'string',
+          default: { value: 'localhost', description: 'The default host' },
+        }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({
+          placeholder: 'localhost',
+          defaultValue: 'localhost',
+        })
+      );
+    });
+
+    it('should call factory from { factory, description } defaults', async () => {
+      const factory = vi.fn().mockReturnValue('from-factory');
+      mockClack.text.mockResolvedValue('override');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({
+          name: 'host',
+          type: 'string',
+          default: { factory, description: 'computed host' },
+        }),
+      ]);
+
+      expect(factory).toHaveBeenCalledOnce();
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({
+          placeholder: 'from-factory',
+          defaultValue: 'from-factory',
+        })
+      );
+    });
+
+    it('should not pass placeholder/defaultValue when no default', async () => {
+      mockClack.text.mockResolvedValue('val');
+      const provider = createClackPromptProvider();
+
+      await provider.promptBatch!([
+        makeOption({ name: 'host', type: 'string' }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledWith(
+        expect.objectContaining({
+          placeholder: undefined,
+          defaultValue: undefined,
+        })
+      );
+    });
+  });
+
+  describe('cancellation handling', () => {
+    it('should throw when user cancels a text prompt', async () => {
+      const cancelSymbol = Symbol('cancel');
+      mockClack.text.mockResolvedValue(cancelSymbol);
+      mockClack.isCancel.mockReturnValue(true);
+      const provider = createClackPromptProvider();
+
+      await expect(
+        provider.promptBatch!([
+          makeOption({ name: 'name', type: 'string' }),
+        ])
+      ).rejects.toThrow('Prompt cancelled by user');
+
+      expect(mockClack.cancel).toHaveBeenCalledWith('Operation cancelled.');
+    });
+
+    it('should throw when user cancels a number prompt (raw cancel)', async () => {
+      const cancelSymbol = Symbol('cancel');
+      mockClack.text.mockResolvedValue(cancelSymbol);
+      mockClack.isCancel.mockReturnValue(true);
+      const provider = createClackPromptProvider();
+
+      await expect(
+        provider.promptBatch!([
+          makeOption({ name: 'port', type: 'number' }),
+        ])
+      ).rejects.toThrow('Prompt cancelled by user');
+    });
+
+    it('should throw when user cancels a confirm prompt', async () => {
+      const cancelSymbol = Symbol('cancel');
+      mockClack.confirm.mockResolvedValue(cancelSymbol);
+      mockClack.isCancel.mockReturnValue(true);
+      const provider = createClackPromptProvider();
+
+      await expect(
+        provider.promptBatch!([
+          makeOption({ name: 'verbose', type: 'boolean' }),
+        ])
+      ).rejects.toThrow('Prompt cancelled by user');
+    });
+  });
+
+  describe('batch behavior', () => {
+    it('should prompt for multiple options in order', async () => {
+      mockClack.text
+        .mockResolvedValueOnce('Alice')
+        .mockResolvedValueOnce('42');
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({ name: 'name', type: 'string' }),
+        makeOption({ name: 'port', type: 'number' }),
+      ]);
+
+      expect(mockClack.text).toHaveBeenCalledTimes(2);
+      expect(result).toEqual({ name: 'Alice', port: 42 });
+    });
+
+    it('should handle mixed option types in a single batch', async () => {
+      mockClack.text.mockResolvedValueOnce('hello');
+      mockClack.confirm.mockResolvedValueOnce(true);
+      mockClack.select.mockResolvedValueOnce('prod');
+      const provider = createClackPromptProvider();
+
+      const result = await provider.promptBatch!([
+        makeOption({ name: 'name', type: 'string' }),
+        makeOption({ name: 'verbose', type: 'boolean' }),
+        makeOption({
+          name: 'env',
+          type: 'string',
+          choices: ['dev', 'prod'],
+        } as any),
+      ]);
+
+      expect(result).toEqual({
+        name: 'hello',
+        verbose: true,
+        env: 'prod',
+      });
+    });
+  });
+});

package/src/prompt-providers/clack.ts

@@ -0,0 +1,169 @@
+import type { Readable, Writable } from 'node:stream';
+import type { PromptOption, PromptProvider } from '../lib/prompt-types';
+
+/**
+ * Options for {@link createClackPromptProvider}.
+ */
+export interface ClackPromptProviderOptions {
+  /**
+   * Custom input stream to read from instead of `process.stdin`.
+   * Useful for testing — pass a `Readable` with `isTTY = true` and
+   * a no-op `setRawMode` to emulate a terminal.
+   */
+  input?: Readable;
+  /**
+   * Custom output stream to write to instead of `process.stdout`.
+   */
+  output?: Writable;
+}
+
+/**
+ * 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.
+ */
+export function createClackPromptProvider(
+  providerOptions?: ClackPromptProviderOptions
+): PromptProvider {
+  // Build the common stream options once; spread into every prompt call.
+  const streamOpts: { input?: Readable; output?: Writable } = {};
+  if (providerOptions?.input) streamOpts.input = providerOptions.input;
+  if (providerOptions?.output) streamOpts.output = providerOptions.output;
+
+  return {
+    async promptBatch(
+      options: PromptOption[]
+    ): Promise<Record<string, unknown>> {
+      const clack = await import('@clack/prompts');
+
+      const results: Record<string, unknown> = {};
+
+      for (const option of options) {
+        const message = getLabel(option);
+        const defaultValue = getDefault(option.config);
+
+        let value: unknown;
+
+        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: string | undefined) => {
+              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
+ */
+export const ClackPromptProvider = createClackPromptProvider();
+
+/**
+ * Determine the label to show for a prompt option.
+ * Priority: prompt string > description > option name.
+ */
+function getLabel(option: PromptOption): string {
+  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: PromptOption['config']): unknown {
+  if (config.default === undefined) return undefined;
+  if (typeof config.default === 'object' && config.default !== null) {
+    if ('factory' in config.default) {
+      return (config.default as { factory: () => unknown }).factory();
+    }
+    if ('value' in config.default) {
+      return (config.default as { value: unknown }).value;
+    }
+  }
+  return config.default;
+}
+
+function hasChoices(config: PromptOption['config']): boolean {
+  return (
+    'choices' in config &&
+    (config as Record<string, unknown>)['choices'] !== undefined
+  );
+}
+
+function getChoices(config: PromptOption['config']): unknown[] {
+  const cfg = config as Record<string, unknown>;
+  const choices = cfg['choices'];
+  if (typeof choices === 'function') {
+    return choices();
+  }
+  return (choices as unknown[]) ?? [];
+}