cli-forge 1.2.3 → 1.3.0

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[]) ?? [];
+}