@nordsym/apiclaw 1.3.7 → 1.3.9

package/src/ui/prompts.ts

@@ -0,0 +1,390 @@
+/**
+ * APIClaw MCP Auto-Setup - Interactive Prompts
+ * 
+ * Inquirer-based prompts for the --wizard mode.
+ * Provides a guided, interactive setup experience.
+ */
+
+import inquirer from 'inquirer';
+import { colors, icons, header, box, codeBlock, added, bulletList } from './colors.js';
+
+/**
+ * Detected client information
+ */
+export interface DetectedClient {
+  id: string;
+  name: string;
+  detected: boolean;
+  configPath: string;
+  alreadyConfigured: boolean;
+}
+
+/**
+ * Configuration change preview
+ */
+export interface ConfigChange {
+  clientId: string;
+  clientName: string;
+  configPath: string;
+  action: 'create' | 'update' | 'skip';
+  diff?: string;
+}
+
+/**
+ * Wizard result
+ */
+export interface WizardResult {
+  selectedClients: string[];
+  workspace?: string;
+  confirmed: boolean;
+  dryRun: boolean;
+}
+
+/**
+ * Display welcome banner
+ */
+export function showWelcome(): void {
+  console.log(header('APIClaw MCP Auto-Setup'));
+  console.log(colors.secondary('Configure APIClaw as an MCP server across your AI coding assistants.\n'));
+}
+
+/**
+ * Prompt for client selection
+ */
+export async function selectClients(clients: DetectedClient[]): Promise<string[]> {
+  console.log(colors.info(`${icons.search} Detected MCP clients:\n`));
+  
+  // Show detection results
+  for (const client of clients) {
+    if (client.detected) {
+      const status = client.alreadyConfigured 
+        ? colors.warning(`(already configured)`)
+        : colors.success('(detected)');
+      console.log(`  ${icons.success} ${colors.highlight(client.name)} ${status}`);
+      console.log(colors.muted(`    ${client.configPath}`));
+    } else {
+      console.log(`  ${icons.pending} ${colors.muted(client.name)} ${colors.muted('(not found)')}`);
+    }
+  }
+  console.log();
+  
+  const detectedClients = clients.filter(c => c.detected);
+  
+  if (detectedClients.length === 0) {
+    console.log(colors.warning('No MCP clients detected on this system.'));
+    console.log(colors.secondary('\nYou can still configure a custom path.\n'));
+  }
+  
+  const choices = clients.map(client => ({
+    name: `${client.name}${client.detected ? '' : ' (not detected)'}${client.alreadyConfigured ? ' ⚠️ already configured' : ''}`,
+    value: client.id,
+    checked: client.detected && !client.alreadyConfigured,
+    disabled: !client.detected && client.id !== 'custom' ? 'Not installed' : false,
+  }));
+  
+  // Add custom option
+  choices.push({
+    name: 'Custom config path...',
+    value: 'custom',
+    checked: false,
+    disabled: false,
+  });
+  
+  const { selected } = await inquirer.prompt<{ selected: string[] }>([
+    {
+      type: 'checkbox',
+      name: 'selected',
+      message: 'Which clients do you want to configure?',
+      choices,
+      validate: (answer: string[]) => {
+        if (answer.length === 0) {
+          return 'Please select at least one client.';
+        }
+        return true;
+      },
+    },
+  ]);
+  
+  return selected;
+}
+
+/**
+ * Prompt for custom config path
+ */
+export async function promptCustomPath(): Promise<string> {
+  const { customPath } = await inquirer.prompt<{ customPath: string }>([
+    {
+      type: 'input',
+      name: 'customPath',
+      message: 'Enter the path to your MCP config file:',
+      validate: (input: string) => {
+        if (!input.trim()) {
+          return 'Please enter a valid path.';
+        }
+        if (!input.endsWith('.json')) {
+          return 'Config file should be a .json file.';
+        }
+        return true;
+      },
+    },
+  ]);
+  
+  return customPath;
+}
+
+/**
+ * Prompt for workspace ID
+ */
+export async function promptWorkspace(): Promise<string | undefined> {
+  const { hasWorkspace } = await inquirer.prompt<{ hasWorkspace: boolean }>([
+    {
+      type: 'confirm',
+      name: 'hasWorkspace',
+      message: 'Do you have an APIClaw workspace ID to link?',
+      default: false,
+    },
+  ]);
+  
+  if (!hasWorkspace) {
+    return undefined;
+  }
+  
+  const { workspace } = await inquirer.prompt<{ workspace: string }>([
+    {
+      type: 'input',
+      name: 'workspace',
+      message: 'Enter your workspace ID:',
+      validate: (input: string) => {
+        if (!input.trim()) {
+          return 'Please enter a workspace ID.';
+        }
+        if (!input.startsWith('ws_')) {
+          return 'Workspace ID should start with "ws_"';
+        }
+        return true;
+      },
+    },
+  ]);
+  
+  return workspace;
+}
+
+/**
+ * Show preview of changes and confirm
+ */
+export async function confirmChanges(
+  changes: ConfigChange[],
+  options: { dryRun?: boolean } = {}
+): Promise<boolean> {
+  console.log(header('Review Changes'));
+  
+  for (const change of changes) {
+    const actionLabel = {
+      create: colors.success('CREATE'),
+      update: colors.warning('UPDATE'),
+      skip: colors.muted('SKIP'),
+    }[change.action];
+    
+    console.log(`${actionLabel} ${colors.highlight(change.clientName)}`);
+    console.log(colors.muted(`  ${change.configPath}\n`));
+    
+    if (change.diff) {
+      console.log(codeBlock(change.diff));
+      console.log();
+    }
+  }
+  
+  if (options.dryRun) {
+    console.log(box(
+      colors.info('Dry-run mode: No changes will be made.'),
+      { borderColor: colors.info }
+    ));
+    console.log();
+    return true;
+  }
+  
+  const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
+    {
+      type: 'confirm',
+      name: 'confirmed',
+      message: 'Apply these changes?',
+      default: true,
+    },
+  ]);
+  
+  return confirmed;
+}
+
+/**
+ * Prompt for force overwrite
+ */
+export async function confirmForce(clientName: string): Promise<boolean> {
+  const { force } = await inquirer.prompt<{ force: boolean }>([
+    {
+      type: 'confirm',
+      name: 'force',
+      message: `${clientName} already has APIClaw configured. Overwrite?`,
+      default: false,
+    },
+  ]);
+  
+  return force;
+}
+
+/**
+ * Show success message with next steps
+ */
+export function showSuccess(configuredClients: string[]): void {
+  console.log();
+  console.log(box(
+    `${icons.check} APIClaw configured successfully!\n\n` +
+    `Configured: ${configuredClients.join(', ')}`,
+    { title: 'Success', borderColor: colors.success }
+  ));
+  
+  console.log(colors.secondary('\nNext steps:'));
+  console.log(bulletList([
+    `Restart ${configuredClients.join(' / ')}`,
+    'Ask your agent: "List available APIs"',
+  ], 2));
+  
+  console.log(colors.secondary('\nNeed help?'));
+  console.log(`  ${colors.link('https://docs.apiclaw.com/setup')}\n`);
+}
+
+/**
+ * Show dry-run summary
+ */
+export function showDryRunSummary(changes: ConfigChange[]): void {
+  console.log();
+  console.log(box(
+    `${icons.info} Dry-run complete\n\n` +
+    `Would configure: ${changes.filter(c => c.action !== 'skip').length} client(s)\n` +
+    `Would skip: ${changes.filter(c => c.action === 'skip').length} client(s)`,
+    { title: 'Dry Run', borderColor: colors.info }
+  ));
+  
+  console.log(colors.secondary('\nTo apply changes, run:'));
+  console.log(colors.action('  npx @nordsym/apiclaw setup\n'));
+}
+
+/**
+ * Run the full interactive wizard
+ */
+export async function runWizard(
+  clients: DetectedClient[],
+  options: { dryRun?: boolean } = {}
+): Promise<WizardResult> {
+  showWelcome();
+  
+  // Select clients
+  const selectedClients = await selectClients(clients);
+  
+  // Handle custom path if selected
+  const finalClients = [...selectedClients];
+  if (selectedClients.includes('custom')) {
+    const customPath = await promptCustomPath();
+    // Remove 'custom' placeholder and add actual path
+    const idx = finalClients.indexOf('custom');
+    finalClients[idx] = `custom:${customPath}`;
+  }
+  
+  // Optionally link workspace
+  const workspace = await promptWorkspace();
+  
+  // Build preview changes
+  const changes: ConfigChange[] = finalClients.map(clientId => {
+    const isCustom = clientId.startsWith('custom:');
+    const client = isCustom 
+      ? { id: 'custom', name: 'Custom', configPath: clientId.replace('custom:', ''), alreadyConfigured: false }
+      : clients.find(c => c.id === clientId)!;
+    
+    return {
+      clientId: client.id,
+      clientName: client.name,
+      configPath: client.configPath,
+      action: client.alreadyConfigured ? 'skip' : 'update',
+      diff: generateDiff(workspace),
+    };
+  });
+  
+  // Confirm changes
+  const confirmed = await confirmChanges(changes, { dryRun: options.dryRun });
+  
+  return {
+    selectedClients: finalClients,
+    workspace,
+    confirmed,
+    dryRun: options.dryRun || false,
+  };
+}
+
+/**
+ * Generate diff preview for config change
+ */
+function generateDiff(workspace?: string): string {
+  const lines = [
+    added('"apiclaw": {'),
+    added('  "command": "npx",'),
+    added('  "args": ["-y", "@nordsym/apiclaw"]'),
+  ];
+  
+  if (workspace) {
+    lines.splice(2, 0, added(`  "env": { "APICLAW_WORKSPACE": "${workspace}" },`));
+  }
+  
+  lines.push(added('}'));
+  
+  return lines.join('\n');
+}
+
+/**
+ * Prompt for restore backup selection
+ */
+export async function selectBackup(backups: { path: string; date: Date; client: string }[]): Promise<string | null> {
+  if (backups.length === 0) {
+    console.log(colors.warning('No backups found.'));
+    return null;
+  }
+  
+  const choices = backups.map(b => ({
+    name: `${b.client} - ${b.date.toLocaleString()} (${b.path})`,
+    value: b.path,
+  }));
+  
+  choices.push({
+    name: 'Cancel',
+    value: '',
+  });
+  
+  const { backup } = await inquirer.prompt<{ backup: string }>([
+    {
+      type: 'list',
+      name: 'backup',
+      message: 'Select a backup to restore:',
+      choices,
+    },
+  ]);
+  
+  return backup || null;
+}
+
+/**
+ * Confirm uninstall
+ */
+export async function confirmUninstall(clients: string[]): Promise<boolean> {
+  console.log(colors.warning('\n⚠️  This will remove APIClaw from:\n'));
+  console.log(bulletList(clients, 2));
+  console.log();
+  
+  const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
+    {
+      type: 'confirm',
+      name: 'confirmed',
+      message: 'Are you sure you want to uninstall APIClaw?',
+      default: false,
+    },
+  ]);
+  
+  return confirmed;
+}

package/src/ui/spinner.ts

@@ -0,0 +1,325 @@
+/**
+ * APIClaw MCP Auto-Setup - Spinner Utilities
+ * 
+ * Ora-based spinner wrapper with consistent styling and state management.
+ * Provides a fluent API for progress indication during CLI operations.
+ */
+
+import ora, { Ora, Options as OraOptions } from 'ora';
+import { colors, icons } from './colors.js';
+
+export interface SpinnerOptions {
+  /** Spinner text */
+  text?: string;
+  /** Prefix text before spinner */
+  prefix?: string;
+  /** Suffix text after spinner */
+  suffix?: string;
+  /** Whether to show spinner in CI environments */
+  showInCI?: boolean;
+  /** Custom spinner frames */
+  spinner?: OraOptions['spinner'];
+}
+
+export interface TaskSpinner {
+  /** Start the spinner with optional text */
+  start(text?: string): TaskSpinner;
+  /** Update spinner text */
+  text(text: string): TaskSpinner;
+  /** Mark as successful with optional message */
+  succeed(text?: string): TaskSpinner;
+  /** Mark as failed with optional message */
+  fail(text?: string): TaskSpinner;
+  /** Mark as warning with optional message */
+  warn(text?: string): TaskSpinner;
+  /** Show info message without stopping */
+  info(text?: string): TaskSpinner;
+  /** Stop spinner without status */
+  stop(): TaskSpinner;
+  /** Stop and clear spinner */
+  clear(): TaskSpinner;
+  /** Check if spinner is currently spinning */
+  isSpinning(): boolean;
+  /** Access underlying ora instance */
+  readonly ora: Ora;
+}
+
+/**
+ * Create a task spinner with APIClaw styling
+ */
+export function createSpinner(options: SpinnerOptions = {}): TaskSpinner {
+  const {
+    text = '',
+    prefix = '',
+    suffix = '',
+    showInCI = false,
+    spinner = 'dots',
+  } = options;
+
+  const oraInstance = ora({
+    text,
+    prefixText: prefix,
+    suffixText: suffix,
+    spinner,
+    // Disable spinner in CI by default for cleaner logs
+    isEnabled: showInCI || !process.env.CI,
+  });
+
+  const wrapper: TaskSpinner = {
+    start(newText?: string) {
+      if (newText) oraInstance.text = newText;
+      oraInstance.start();
+      return wrapper;
+    },
+
+    text(newText: string) {
+      oraInstance.text = newText;
+      return wrapper;
+    },
+
+    succeed(newText?: string) {
+      oraInstance.succeed(newText);
+      return wrapper;
+    },
+
+    fail(newText?: string) {
+      oraInstance.fail(newText);
+      return wrapper;
+    },
+
+    warn(newText?: string) {
+      oraInstance.warn(newText);
+      return wrapper;
+    },
+
+    info(newText?: string) {
+      oraInstance.info(newText);
+      return wrapper;
+    },
+
+    stop() {
+      oraInstance.stop();
+      return wrapper;
+    },
+
+    clear() {
+      oraInstance.stopAndPersist({ symbol: '' });
+      return wrapper;
+    },
+
+    isSpinning() {
+      return oraInstance.isSpinning;
+    },
+
+    get ora() {
+      return oraInstance;
+    },
+  };
+
+  return wrapper;
+}
+
+/**
+ * Convenience function for common spinner patterns
+ */
+export const spinner = {
+  /**
+   * Create and start a spinner in one call
+   */
+  start(text: string): TaskSpinner {
+    return createSpinner({ text }).start();
+  },
+
+  /**
+   * Run an async task with spinner, auto-succeed/fail
+   */
+  async task<T>(
+    text: string,
+    fn: (spinner: TaskSpinner) => Promise<T>,
+    options: {
+      successText?: string | ((result: T) => string);
+      failText?: string | ((error: Error) => string);
+    } = {}
+  ): Promise<T> {
+    const s = createSpinner({ text }).start();
+    
+    try {
+      const result = await fn(s);
+      const successMsg = typeof options.successText === 'function'
+        ? options.successText(result)
+        : options.successText || text;
+      s.succeed(successMsg);
+      return result;
+    } catch (error) {
+      const failMsg = typeof options.failText === 'function'
+        ? options.failText(error as Error)
+        : options.failText || `${text} - Failed`;
+      s.fail(failMsg);
+      throw error;
+    }
+  },
+
+  /**
+   * Run multiple tasks in sequence with spinners
+   */
+  async sequence<T>(
+    tasks: Array<{
+      text: string;
+      task: () => Promise<T>;
+      successText?: string;
+      failText?: string;
+    }>
+  ): Promise<T[]> {
+    const results: T[] = [];
+    
+    for (const { text, task, successText, failText } of tasks) {
+      const result = await this.task(text, task, { successText, failText });
+      results.push(result);
+    }
+    
+    return results;
+  },
+};
+
+/**
+ * Progress tracker for multi-step operations
+ */
+export class ProgressTracker {
+  private current = 0;
+  private readonly total: number;
+  private readonly items: string[];
+  private readonly taskSpinner: TaskSpinner;
+
+  constructor(items: string[]) {
+    this.items = items;
+    this.total = items.length;
+    this.taskSpinner = createSpinner();
+  }
+
+  /**
+   * Start tracking progress
+   */
+  start(): void {
+    this.current = 0;
+    this.updateText();
+    this.taskSpinner.start();
+  }
+
+  /**
+   * Move to next item
+   */
+  next(): void {
+    this.current++;
+    this.updateText();
+  }
+
+  /**
+   * Mark current item as done and move to next
+   */
+  done(message?: string): void {
+    this.taskSpinner.succeed(message || this.items[this.current - 1]);
+    if (this.current < this.total) {
+      this.taskSpinner.start(this.formatProgress());
+    }
+  }
+
+  /**
+   * Mark as complete
+   */
+  complete(message: string): void {
+    this.taskSpinner.succeed(message);
+  }
+
+  /**
+   * Mark as failed
+   */
+  fail(message: string): void {
+    this.taskSpinner.fail(message);
+  }
+
+  private updateText(): void {
+    this.taskSpinner.text(this.formatProgress());
+  }
+
+  private formatProgress(): string {
+    const item = this.items[this.current] || 'Processing...';
+    return `[${this.current + 1}/${this.total}] ${item}`;
+  }
+}
+
+/**
+ * Silent spinner for non-interactive/CI environments
+ * Logs plain text instead of animated spinners
+ */
+export function createSilentSpinner(options: SpinnerOptions = {}): TaskSpinner {
+  const log = (symbol: string, text?: string) => {
+    if (text) {
+      console.log(`${symbol} ${text}`);
+    }
+  };
+
+  let currentText = options.text || '';
+
+  const wrapper: TaskSpinner = {
+    start(text?: string) {
+      currentText = text || currentText;
+      log(colors.muted('○'), currentText);
+      return wrapper;
+    },
+
+    text(text: string) {
+      currentText = text;
+      return wrapper;
+    },
+
+    succeed(text?: string) {
+      log(icons.success, text || currentText);
+      return wrapper;
+    },
+
+    fail(text?: string) {
+      log(icons.error, text || currentText);
+      return wrapper;
+    },
+
+    warn(text?: string) {
+      log(icons.warning, text || currentText);
+      return wrapper;
+    },
+
+    info(text?: string) {
+      log(icons.info, text || currentText);
+      return wrapper;
+    },
+
+    stop() {
+      return wrapper;
+    },
+
+    clear() {
+      return wrapper;
+    },
+
+    isSpinning() {
+      return false;
+    },
+
+    get ora(): Ora {
+      // Return a mock for compatibility
+      return {} as Ora;
+    },
+  };
+
+  return wrapper;
+}
+
+/**
+ * Get appropriate spinner based on environment
+ */
+export function getSpinner(options: SpinnerOptions = {}): TaskSpinner {
+  // Use silent spinner in CI or when stdout is not a TTY
+  if (process.env.CI || !process.stdout.isTTY) {
+    return createSilentSpinner(options);
+  }
+  return createSpinner(options);
+}