bmad-elsabro 1.0.0

package/tools/cli/lib/prompts.ts

@@ -0,0 +1,541 @@
+/**
+ * @clack/prompts wrapper for BMAD CLI
+ *
+ * This module provides a unified interface for CLI prompts using @clack/prompts.
+ * It replaces Inquirer.js to fix Windows arrow key navigation issues (libuv #852).
+ *
+ * @module prompts
+ */
+
+// Use dynamic import for ESM module
+let _clack: any = null;
+
+/**
+ * Lazy-load @clack/prompts (ESM module)
+ * @returns The clack prompts module
+ */
+async function getClack(): Promise<any> {
+  if (!_clack) {
+    _clack = await import('@clack/prompts');
+  }
+  return _clack;
+}
+
+/**
+ * Handle user cancellation gracefully
+ * @param value - The value to check
+ * @param message - Message to display
+ * @returns True if cancelled
+ */
+async function handleCancel(value: unknown, message = 'Operation cancelled'): Promise<boolean> {
+  const clack = await getClack();
+  if (clack.isCancel(value)) {
+    clack.cancel(message);
+    process.exit(0);
+  }
+  return false;
+}
+
+/**
+ * Display intro message
+ * @param message - The intro message
+ */
+async function intro(message: string): Promise<void> {
+  const clack = await getClack();
+  clack.intro(message);
+}
+
+/**
+ * Display outro message
+ * @param message - The outro message
+ */
+async function outro(message: string): Promise<void> {
+  const clack = await getClack();
+  clack.outro(message);
+}
+
+/**
+ * Display a note/info box
+ * @param message - The note content
+ * @param title - Optional title
+ */
+async function note(message: string, title?: string): Promise<void> {
+  const clack = await getClack();
+  clack.note(message, title);
+}
+
+/**
+ * Spinner controller interface
+ */
+export interface SpinnerController {
+  start(msg?: string): void;
+  stop(msg?: string, code?: number): void;
+  message(msg?: string): void;
+}
+
+/**
+ * Display a spinner for async operations
+ * @returns Spinner controller with start, stop, message methods
+ */
+async function spinner(): Promise<SpinnerController> {
+  const clack = await getClack();
+  return clack.spinner() as SpinnerController;
+}
+
+/**
+ * Choice object for select/multiselect prompts
+ */
+export interface Choice<T = unknown> {
+  name?: string;
+  value?: T;
+  label?: string;
+  hint?: string;
+  description?: string;
+  checked?: boolean;
+  type?: string;
+}
+
+/**
+ * Clack-native option format
+ */
+export interface ClackOption<T = unknown> {
+  value: T;
+  label: string;
+  hint?: string;
+}
+
+/**
+ * Options for select prompt
+ */
+export interface SelectOptions<T = unknown> {
+  message: string;
+  choices: Array<Choice<T> | string | number>;
+  default?: T;
+}
+
+/**
+ * Single-select prompt (replaces Inquirer 'list' type)
+ * @param options - Prompt options
+ * @returns Selected value
+ */
+async function select<T = unknown>(options: SelectOptions<T>): Promise<T> {
+  const clack = await getClack();
+
+  // Convert Inquirer-style choices to clack format
+  // Handle both object choices {name, value, hint} and primitive choices (string/number)
+  const clackOptions: Array<ClackOption<T>> = options.choices
+    .filter((c) => typeof c === 'object' && c !== null ? c.type !== 'separator' : true)
+    .map((choice): ClackOption<T> => {
+      if (typeof choice === 'string' || typeof choice === 'number') {
+        return { value: choice as T, label: String(choice) };
+      }
+      return {
+        value: (choice.value === undefined ? choice.name : choice.value) as T,
+        label: choice.name || choice.label || String(choice.value),
+        hint: choice.hint || choice.description,
+      };
+    });
+
+  // Find initial value
+  let initialValue: T | undefined;
+  if (options.default !== undefined) {
+    initialValue = options.default;
+  }
+
+  const result = await clack.select({
+    message: options.message,
+    options: clackOptions,
+    initialValue,
+  });
+
+  await handleCancel(result);
+  return result as T;
+}
+
+/**
+ * Options for multiselect prompt (Inquirer-style)
+ */
+export interface MultiselectOptions<T = unknown> {
+  message: string;
+  choices?: Array<Choice<T> | string | number>;
+  options?: Array<ClackOption<T>>;
+  initialValues?: T[];
+  required?: boolean;
+}
+
+/**
+ * Multi-select prompt (replaces Inquirer 'checkbox' type)
+ * @param options - Prompt options
+ * @returns Array of selected values
+ */
+async function multiselect<T = unknown>(options: MultiselectOptions<T>): Promise<T[]> {
+  const clack = await getClack();
+
+  // Support both clack-native (options) and Inquirer-style (choices) APIs
+  let clackOptions: Array<ClackOption<T>>;
+  let initialValues: T[];
+
+  if (options.options) {
+    // Native clack format: options with label/value
+    clackOptions = options.options;
+    initialValues = options.initialValues || [];
+  } else {
+    // Convert Inquirer-style choices to clack format
+    // Handle both object choices {name, value, hint} and primitive choices (string/number)
+    clackOptions = (options.choices || [])
+      .filter((c) => typeof c === 'object' && c !== null ? c.type !== 'separator' : true)
+      .map((choice): ClackOption<T> => {
+        if (typeof choice === 'string' || typeof choice === 'number') {
+          return { value: choice as T, label: String(choice) };
+        }
+        return {
+          value: (choice.value === undefined ? choice.name : choice.value) as T,
+          label: choice.name || choice.label || String(choice.value),
+          hint: choice.hint || choice.description,
+        };
+      });
+
+    // Find initial values (pre-checked items)
+    initialValues = (options.choices || [])
+      .filter((c) => typeof c === 'object' && c !== null && c.checked && c.type !== 'separator')
+      .map((c) => ((c as Choice<T>).value === undefined ? (c as Choice<T>).name : (c as Choice<T>).value) as T);
+  }
+
+  const result = await clack.multiselect({
+    message: options.message,
+    options: clackOptions,
+    initialValues: initialValues.length > 0 ? initialValues : undefined,
+    required: options.required || false,
+  });
+
+  await handleCancel(result);
+  return result as T[];
+}
+
+/**
+ * Options for grouped multiselect prompt
+ */
+export interface GroupMultiselectOptions<T = unknown> {
+  message: string;
+  options: Record<string, Array<ClackOption<T>>>;
+  initialValues?: T[];
+  required?: boolean;
+  selectableGroups?: boolean;
+}
+
+/**
+ * Grouped multi-select prompt for categorized options
+ * @param options - Prompt options
+ * @returns Array of selected values
+ */
+async function groupMultiselect<T = unknown>(options: GroupMultiselectOptions<T>): Promise<T[]> {
+  const clack = await getClack();
+
+  const result = await clack.groupMultiselect({
+    message: options.message,
+    options: options.options,
+    initialValues: options.initialValues,
+    required: options.required || false,
+    selectableGroups: options.selectableGroups || false,
+  });
+
+  await handleCancel(result);
+  return result as T[];
+}
+
+/**
+ * Options for confirm prompt
+ */
+export interface ConfirmOptions {
+  message: string;
+  default?: boolean;
+}
+
+/**
+ * Confirm prompt (replaces Inquirer 'confirm' type)
+ * @param options - Prompt options
+ * @returns User's answer
+ */
+async function confirm(options: ConfirmOptions): Promise<boolean> {
+  const clack = await getClack();
+
+  const result = await clack.confirm({
+    message: options.message,
+    initialValue: options.default === undefined ? true : options.default,
+  });
+
+  await handleCancel(result);
+  return result as boolean;
+}
+
+/**
+ * Validation function type
+ */
+export type ValidateFn = (value: string) => string | undefined;
+
+/**
+ * Options for text input prompt
+ */
+export interface TextOptions {
+  message: string;
+  default?: string;
+  placeholder?: string;
+  validate?: ValidateFn;
+}
+
+/**
+ * Text input prompt (replaces Inquirer 'input' type)
+ * @param options - Prompt options
+ * @returns User's input
+ */
+async function text(options: TextOptions): Promise<string> {
+  const clack = await getClack();
+
+  // Use default as placeholder if placeholder not explicitly provided
+  // This shows the default value as grayed-out hint text
+  const placeholder = options.placeholder === undefined ? options.default : options.placeholder;
+
+  const result = await clack.text({
+    message: options.message,
+    defaultValue: options.default,
+    placeholder: typeof placeholder === 'string' ? placeholder : undefined,
+    validate: options.validate,
+  });
+
+  await handleCancel(result);
+  return result as string;
+}
+
+/**
+ * Options for password input prompt
+ */
+export interface PasswordOptions {
+  message: string;
+  validate?: ValidateFn;
+}
+
+/**
+ * Password input prompt (replaces Inquirer 'password' type)
+ * @param options - Prompt options
+ * @returns User's input
+ */
+async function password(options: PasswordOptions): Promise<string> {
+  const clack = await getClack();
+
+  const result = await clack.password({
+    message: options.message,
+    validate: options.validate,
+  });
+
+  await handleCancel(result);
+  return result as string;
+}
+
+/**
+ * Prompt functions for group
+ */
+export type PromptFunctions = Record<string, (opts?: { results: any }) => Promise<unknown> | undefined>;
+
+/**
+ * Group options
+ */
+export interface GroupOptions {
+  onCancel?: (opts: { results: any }) => void;
+}
+
+/**
+ * Group multiple prompts together
+ * @param prompts - Object of prompt functions
+ * @param options - Group options
+ * @returns Object with all answers
+ */
+async function group<T extends PromptFunctions>(prompts: T, options: GroupOptions = {}): Promise<any> {
+  const clack = await getClack();
+
+  const result = await clack.group(prompts, {
+    onCancel: () => {
+      clack.cancel('Operation cancelled');
+      process.exit(0);
+    },
+    ...options,
+  });
+
+  return result;
+}
+
+/**
+ * Task object for tasks prompt
+ */
+export interface Task {
+  title: string;
+  task: (message: (msg: string) => void) => string | Promise<string> | void | Promise<void>;
+  enabled?: boolean;
+}
+
+/**
+ * Run tasks with spinner feedback
+ * @param taskList - Array of task objects
+ */
+async function tasks(taskList: Task[]): Promise<void> {
+  const clack = await getClack();
+  await clack.tasks(taskList);
+}
+
+/**
+ * Log object with styling methods
+ */
+const log = {
+  async info(message: string): Promise<void> {
+    const clack = await getClack();
+    clack.log.info(message);
+  },
+  async success(message: string): Promise<void> {
+    const clack = await getClack();
+    clack.log.success(message);
+  },
+  async warn(message: string): Promise<void> {
+    const clack = await getClack();
+    clack.log.warn(message);
+  },
+  async error(message: string): Promise<void> {
+    const clack = await getClack();
+    clack.log.error(message);
+  },
+  async message(message: string): Promise<void> {
+    const clack = await getClack();
+    clack.log.message(message);
+  },
+  async step(message: string): Promise<void> {
+    const clack = await getClack();
+    clack.log.step(message);
+  },
+};
+
+/**
+ * Inquirer-style question object
+ */
+export interface Question {
+  type: 'input' | 'confirm' | 'list' | 'checkbox' | 'password';
+  name: string;
+  message: string;
+  choices?: Array<Choice<unknown> | string | number>;
+  default?: unknown | ((answers: Record<string, unknown>) => unknown);
+  validate?: (value: string, answers: Record<string, unknown>) => string | boolean;
+  when?: boolean | ((answers: Record<string, unknown>) => boolean | Promise<boolean>);
+}
+
+/**
+ * Execute an array of Inquirer-style questions using @clack/prompts
+ * This provides compatibility with dynamic question arrays
+ * @param questions - Array of Inquirer-style question objects
+ * @returns Object with answers keyed by question name
+ */
+async function prompt(questions: Question[]): Promise<Record<string, unknown>> {
+  const answers: Record<string, unknown> = {};
+
+  for (const question of questions) {
+    const { type, name, message, choices, default: defaultValue, validate, when } = question;
+
+    // Handle conditional questions via 'when' property
+    if (when !== undefined) {
+      const shouldAsk = typeof when === 'function' ? await when(answers) : when;
+      if (!shouldAsk) continue;
+    }
+
+    let answer: unknown;
+
+    switch (type) {
+      case 'input': {
+        // Note: @clack/prompts doesn't support async validation, so validate must be sync
+        answer = await text({
+          message,
+          default: typeof defaultValue === 'function' ? String(defaultValue(answers)) : String(defaultValue || ''),
+          validate: validate
+            ? (val: string): string | undefined => {
+                const result = validate(val, answers);
+                if (result instanceof Promise) {
+                  throw new TypeError('Async validation is not supported by @clack/prompts. Please use synchronous validation.');
+                }
+                return result === true ? undefined : String(result);
+              }
+            : undefined,
+        });
+        break;
+      }
+
+      case 'confirm': {
+        answer = await confirm({
+          message,
+          default: typeof defaultValue === 'function' ? Boolean(defaultValue(answers)) : Boolean(defaultValue),
+        });
+        break;
+      }
+
+      case 'list': {
+        answer = await select({
+          message,
+          choices: choices || [],
+          default: typeof defaultValue === 'function' ? defaultValue(answers) : defaultValue,
+        });
+        break;
+      }
+
+      case 'checkbox': {
+        answer = await multiselect({
+          message,
+          choices: choices || [],
+          required: false,
+        });
+        break;
+      }
+
+      case 'password': {
+        // Note: @clack/prompts doesn't support async validation, so validate must be sync
+        answer = await password({
+          message,
+          validate: validate
+            ? (val: string): string | undefined => {
+                const result = validate(val, answers);
+                if (result instanceof Promise) {
+                  throw new TypeError('Async validation is not supported by @clack/prompts. Please use synchronous validation.');
+                }
+                return result === true ? undefined : String(result);
+              }
+            : undefined,
+        });
+        break;
+      }
+
+      default: {
+        // Default to text input for unknown types
+        answer = await text({
+          message,
+          default: typeof defaultValue === 'function' ? String(defaultValue(answers)) : String(defaultValue || ''),
+        });
+      }
+    }
+
+    answers[name] = answer;
+  }
+
+  return answers;
+}
+
+export {
+  getClack,
+  handleCancel,
+  intro,
+  outro,
+  note,
+  spinner,
+  select,
+  multiselect,
+  groupMultiselect,
+  confirm,
+  text,
+  password,
+  group,
+  tasks,
+  log,
+  prompt,
+};

package/tools/cli/lib/types/config.types.ts

@@ -0,0 +1,43 @@
+/**
+ * Configuration type definitions
+ */
+
+/**
+ * Replacement values for config processing
+ */
+export interface ConfigReplacements {
+  root?: string;
+  module?: string;
+  version?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Property specification in validation schema
+ */
+export interface PropertySpec {
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  enum?: unknown[];
+}
+
+/**
+ * Validation schema for configuration
+ */
+export interface ValidationSchema {
+  required?: string[];
+  properties?: Record<string, PropertySpec>;
+}
+
+/**
+ * Result of configuration validation
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Generic configuration object
+ */
+export type ConfigObject = Record<string, unknown>;

package/tools/cli/lib/types/xml-handler.types.ts

@@ -0,0 +1,50 @@
+/**
+ * Type definitions for XML Handler
+ */
+
+/**
+ * Metadata for agent injection
+ */
+export interface AgentMetadata {
+  module?: string;
+  name?: string;
+  includeMetadata?: boolean;
+  forWebBundle?: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * Build metadata for YAML to XML conversion
+ */
+export interface BuildMetadata {
+  sourceFile: string;
+  sourceHash: string | null;
+  customizeFile: string | null;
+  customizeHash: string | null;
+  builderVersion: string;
+  includeMetadata: boolean;
+  forWebBundle: boolean;
+}
+
+/**
+ * XML node structure (xml2js format)
+ */
+export interface XmlNode {
+  '#name'?: string;
+  $?: Record<string, string>;
+  $$?: XmlNode[];
+  _?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Parsed XML agent structure
+ */
+export interface ParsedAgent {
+  agent?: {
+    $$?: XmlNode[];
+    activation?: unknown;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}