@claude-flow/cli 3.0.0-alpha.1

package/src/init/types.ts

@@ -0,0 +1,447 @@
+/**
+ * V3 Init System Types
+ * Configuration options for initializing Claude Code integration
+ */
+
+/**
+ * Components that can be initialized
+ */
+export interface InitComponents {
+  /** Create .claude/settings.json with hooks */
+  settings: boolean;
+  /** Copy skills to .claude/skills/ */
+  skills: boolean;
+  /** Copy commands to .claude/commands/ */
+  commands: boolean;
+  /** Copy agents to .claude/agents/ */
+  agents: boolean;
+  /** Create helper scripts in .claude/helpers/ */
+  helpers: boolean;
+  /** Configure statusline */
+  statusline: boolean;
+  /** Create MCP configuration */
+  mcp: boolean;
+  /** Create .claude-flow/ directory (V3 runtime) */
+  runtime: boolean;
+  /** Create CLAUDE.md with swarm guidance */
+  claudeMd: boolean;
+}
+
+/**
+ * Hook configuration options
+ */
+export interface HooksConfig {
+  /** Enable PreToolUse hooks */
+  preToolUse: boolean;
+  /** Enable PostToolUse hooks */
+  postToolUse: boolean;
+  /** Enable UserPromptSubmit for routing */
+  userPromptSubmit: boolean;
+  /** Enable SessionStart hooks */
+  sessionStart: boolean;
+  /** Enable Stop hooks */
+  stop: boolean;
+  /** Enable Notification hooks */
+  notification: boolean;
+  /** Enable PermissionRequest auto-allow for claude-flow */
+  permissionRequest: boolean;
+  /** Hook timeout in milliseconds */
+  timeout: number;
+  /** Continue on hook error */
+  continueOnError: boolean;
+}
+
+/**
+ * Skills configuration
+ */
+export interface SkillsConfig {
+  /** Include core skills (swarm, memory, sparc) */
+  core: boolean;
+  /** Include AgentDB skills */
+  agentdb: boolean;
+  /** Include GitHub integration skills */
+  github: boolean;
+  /** Include Flow Nexus skills */
+  flowNexus: boolean;
+  /** Include V3 implementation skills */
+  v3: boolean;
+  /** Include all available skills */
+  all: boolean;
+}
+
+/**
+ * Commands configuration
+ */
+export interface CommandsConfig {
+  /** Include core commands */
+  core: boolean;
+  /** Include analysis commands */
+  analysis: boolean;
+  /** Include automation commands */
+  automation: boolean;
+  /** Include github commands */
+  github: boolean;
+  /** Include hooks commands */
+  hooks: boolean;
+  /** Include monitoring commands */
+  monitoring: boolean;
+  /** Include optimization commands */
+  optimization: boolean;
+  /** Include SPARC commands */
+  sparc: boolean;
+  /** Include all commands */
+  all: boolean;
+}
+
+/**
+ * Agents configuration
+ */
+export interface AgentsConfig {
+  /** Include core agents (coder, tester, reviewer) */
+  core: boolean;
+  /** Include consensus agents */
+  consensus: boolean;
+  /** Include GitHub agents */
+  github: boolean;
+  /** Include hive-mind agents */
+  hiveMind: boolean;
+  /** Include SPARC agents */
+  sparc: boolean;
+  /** Include swarm coordinators */
+  swarm: boolean;
+  /** Include all agents */
+  all: boolean;
+}
+
+/**
+ * Statusline configuration
+ */
+export interface StatuslineConfig {
+  /** Enable statusline */
+  enabled: boolean;
+  /** Show V3 progress */
+  showProgress: boolean;
+  /** Show security status */
+  showSecurity: boolean;
+  /** Show swarm activity */
+  showSwarm: boolean;
+  /** Show hooks metrics */
+  showHooks: boolean;
+  /** Show performance targets */
+  showPerformance: boolean;
+  /** Refresh interval in milliseconds */
+  refreshInterval: number;
+}
+
+/**
+ * MCP configuration
+ */
+export interface MCPConfig {
+  /** Include claude-flow MCP server */
+  claudeFlow: boolean;
+  /** Include ruv-swarm MCP server */
+  ruvSwarm: boolean;
+  /** Include flow-nexus MCP server */
+  flowNexus: boolean;
+  /** Auto-start MCP server */
+  autoStart: boolean;
+  /** Server port */
+  port: number;
+}
+
+/**
+ * Runtime configuration (.claude-flow/)
+ */
+export interface RuntimeConfig {
+  /** Swarm topology */
+  topology: 'mesh' | 'hierarchical' | 'hierarchical-mesh' | 'adaptive';
+  /** Maximum agents */
+  maxAgents: number;
+  /** Memory backend */
+  memoryBackend: 'memory' | 'sqlite' | 'agentdb' | 'hybrid';
+  /** Enable HNSW indexing */
+  enableHNSW: boolean;
+  /** Enable neural learning */
+  enableNeural: boolean;
+}
+
+/**
+ * Detected platform information
+ */
+export interface PlatformInfo {
+  /** Operating system */
+  os: 'windows' | 'darwin' | 'linux';
+  /** Architecture */
+  arch: 'x64' | 'arm64' | 'arm' | 'ia32';
+  /** Node.js version */
+  nodeVersion: string;
+  /** Shell type */
+  shell: 'powershell' | 'cmd' | 'bash' | 'zsh' | 'sh';
+  /** Home directory */
+  homeDir: string;
+  /** Config directory (platform-specific) */
+  configDir: string;
+}
+
+/**
+ * Detect current platform
+ */
+export function detectPlatform(): PlatformInfo {
+  const os = require('os');
+  const path = require('path');
+
+  const platform = os.platform();
+  const arch = os.arch();
+  const homeDir = os.homedir();
+
+  let osType: 'windows' | 'darwin' | 'linux';
+  let shell: 'powershell' | 'cmd' | 'bash' | 'zsh' | 'sh';
+  let configDir: string;
+
+  switch (platform) {
+    case 'win32':
+      osType = 'windows';
+      shell = process.env.PSModulePath ? 'powershell' : 'cmd';
+      configDir = process.env.APPDATA || path.join(homeDir, 'AppData', 'Roaming');
+      break;
+    case 'darwin':
+      osType = 'darwin';
+      shell = process.env.SHELL?.includes('zsh') ? 'zsh' : 'bash';
+      configDir = path.join(homeDir, 'Library', 'Application Support');
+      break;
+    default:
+      osType = 'linux';
+      shell = process.env.SHELL?.includes('zsh') ? 'zsh' : (process.env.SHELL?.includes('bash') ? 'bash' : 'sh');
+      configDir = process.env.XDG_CONFIG_HOME || path.join(homeDir, '.config');
+  }
+
+  return {
+    os: osType,
+    arch: arch as PlatformInfo['arch'],
+    nodeVersion: process.version,
+    shell,
+    homeDir,
+    configDir,
+  };
+}
+
+/**
+ * Complete init options
+ */
+export interface InitOptions {
+  /** Target directory */
+  targetDir: string;
+  /** Source base directory for skills/commands/agents (optional) */
+  sourceBaseDir?: string;
+  /** Force overwrite existing files */
+  force: boolean;
+  /** Run in interactive mode */
+  interactive: boolean;
+  /** Components to initialize */
+  components: InitComponents;
+  /** Hooks configuration */
+  hooks: HooksConfig;
+  /** Skills configuration */
+  skills: SkillsConfig;
+  /** Commands configuration */
+  commands: CommandsConfig;
+  /** Agents configuration */
+  agents: AgentsConfig;
+  /** Statusline configuration */
+  statusline: StatuslineConfig;
+  /** MCP configuration */
+  mcp: MCPConfig;
+  /** Runtime configuration */
+  runtime: RuntimeConfig;
+}
+
+/**
+ * Default init options - full V3 setup
+ */
+export const DEFAULT_INIT_OPTIONS: InitOptions = {
+  targetDir: process.cwd(),
+  force: false,
+  interactive: true,
+  components: {
+    settings: true,
+    skills: true,
+    commands: true,
+    agents: true,
+    helpers: true,
+    statusline: true,
+    mcp: true,
+    runtime: true,
+    claudeMd: true,
+  },
+  hooks: {
+    preToolUse: true,
+    postToolUse: true,
+    userPromptSubmit: true,
+    sessionStart: true,
+    stop: true,
+    notification: true,
+    permissionRequest: true,
+    timeout: 5000,
+    continueOnError: true,
+  },
+  skills: {
+    core: true,
+    agentdb: true,
+    github: true,
+    flowNexus: false,
+    v3: true,
+    all: false,
+  },
+  commands: {
+    core: true,
+    analysis: true,
+    automation: true,
+    github: true,
+    hooks: true,
+    monitoring: true,
+    optimization: true,
+    sparc: true,
+    all: false,
+  },
+  agents: {
+    core: true,
+    consensus: false,
+    github: true,
+    hiveMind: true,
+    sparc: true,
+    swarm: true,
+    all: false,
+  },
+  statusline: {
+    enabled: true,
+    showProgress: true,
+    showSecurity: true,
+    showSwarm: true,
+    showHooks: true,
+    showPerformance: true,
+    refreshInterval: 5000,
+  },
+  mcp: {
+    claudeFlow: true,
+    ruvSwarm: false,
+    flowNexus: false,
+    autoStart: false,
+    port: 3000,
+  },
+  runtime: {
+    topology: 'hierarchical-mesh',
+    maxAgents: 15,
+    memoryBackend: 'hybrid',
+    enableHNSW: true,
+    enableNeural: true,
+  },
+};
+
+/**
+ * Minimal init options
+ */
+export const MINIMAL_INIT_OPTIONS: InitOptions = {
+  ...DEFAULT_INIT_OPTIONS,
+  components: {
+    settings: true,
+    skills: true,
+    commands: false,
+    agents: false,
+    helpers: false,
+    statusline: false,
+    mcp: true,
+    runtime: true,
+    claudeMd: true,
+  },
+  hooks: {
+    ...DEFAULT_INIT_OPTIONS.hooks,
+    userPromptSubmit: false,
+    stop: false,
+    notification: false,
+  },
+  skills: {
+    core: true,
+    agentdb: false,
+    github: false,
+    flowNexus: false,
+    v3: false,
+    all: false,
+  },
+  agents: {
+    core: true,
+    consensus: false,
+    github: false,
+    hiveMind: false,
+    sparc: false,
+    swarm: false,
+    all: false,
+  },
+  runtime: {
+    topology: 'mesh',
+    maxAgents: 5,
+    memoryBackend: 'memory',
+    enableHNSW: false,
+    enableNeural: false,
+  },
+};
+
+/**
+ * Full init options (everything enabled)
+ */
+export const FULL_INIT_OPTIONS: InitOptions = {
+  ...DEFAULT_INIT_OPTIONS,
+  components: {
+    settings: true,
+    skills: true,
+    commands: true,
+    agents: true,
+    helpers: true,
+    statusline: true,
+    mcp: true,
+    runtime: true,
+    claudeMd: true,
+  },
+  skills: {
+    core: true,
+    agentdb: true,
+    github: true,
+    flowNexus: true,
+    v3: true,
+    all: true,
+  },
+  commands: {
+    ...DEFAULT_INIT_OPTIONS.commands,
+    all: true,
+  },
+  agents: {
+    ...DEFAULT_INIT_OPTIONS.agents,
+    all: true,
+  },
+  mcp: {
+    claudeFlow: true,
+    ruvSwarm: true,
+    flowNexus: true,
+    autoStart: false,
+    port: 3000,
+  },
+};
+
+/**
+ * Init result
+ */
+export interface InitResult {
+  success: boolean;
+  platform: PlatformInfo;
+  created: {
+    directories: string[];
+    files: string[];
+  };
+  skipped: string[];
+  errors: string[];
+  summary: {
+    skillsCount: number;
+    commandsCount: number;
+    agentsCount: number;
+    hooksEnabled: number;
+  };
+}

package/src/mcp-client.ts

@@ -0,0 +1,227 @@
+/**
+ * V3 CLI MCP Client
+ *
+ * Thin wrapper for calling MCP tools from CLI commands.
+ * Implements ADR-005: MCP-First API Design - CLI as thin wrapper around MCP tools
+ *
+ * This provides a simple interface for CLI commands to call MCP tools without
+ * containing hardcoded business logic. All business logic lives in MCP tool handlers.
+ */
+
+import type { MCPTool } from './mcp-tools/types.js';
+
+// Import MCP tool handlers from local package
+import { agentTools } from './mcp-tools/agent-tools.js';
+import { swarmTools } from './mcp-tools/swarm-tools.js';
+import { memoryTools } from './mcp-tools/memory-tools.js';
+import { configTools } from './mcp-tools/config-tools.js';
+import { hooksTools } from './mcp-tools/hooks-tools.js';
+
+/**
+ * MCP Tool Registry
+ * Maps tool names to their handler functions
+ */
+const TOOL_REGISTRY = new Map<string, MCPTool>();
+
+// Register all tools
+function registerTools(tools: MCPTool[]): void {
+  tools.forEach(tool => {
+    TOOL_REGISTRY.set(tool.name, tool);
+  });
+}
+
+// Initialize registry with all available tools
+registerTools([...agentTools, ...swarmTools, ...memoryTools, ...configTools, ...hooksTools]);
+
+/**
+ * MCP Client Error
+ */
+export class MCPClientError extends Error {
+  constructor(
+    message: string,
+    public toolName: string,
+    public cause?: Error
+  ) {
+    super(message);
+    this.name = 'MCPClientError';
+  }
+}
+
+/**
+ * Call an MCP tool by name with input parameters
+ *
+ * @param toolName - Name of the MCP tool (e.g., 'agent/spawn', 'swarm/init')
+ * @param input - Input parameters for the tool
+ * @param context - Optional tool context
+ * @returns Promise resolving to tool result
+ * @throws {MCPClientError} If tool not found or execution fails
+ *
+ * @example
+ * ```typescript
+ * // Spawn an agent
+ * const result = await callMCPTool('agent/spawn', {
+ *   agentType: 'coder',
+ *   priority: 'normal'
+ * });
+ *
+ * // Initialize swarm
+ * const swarm = await callMCPTool('swarm/init', {
+ *   topology: 'hierarchical-mesh',
+ *   maxAgents: 15
+ * });
+ * ```
+ */
+export async function callMCPTool<T = unknown>(
+  toolName: string,
+  input: Record<string, unknown> = {},
+  context?: Record<string, unknown>
+): Promise<T> {
+  // Look up tool in registry
+  const tool = TOOL_REGISTRY.get(toolName);
+
+  if (!tool) {
+    throw new MCPClientError(
+      `MCP tool not found: ${toolName}`,
+      toolName
+    );
+  }
+
+  try {
+    // Call the tool handler
+    const result = await tool.handler(input, context);
+    return result as T;
+  } catch (error) {
+    // Wrap and re-throw with context
+    throw new MCPClientError(
+      `Failed to execute MCP tool '${toolName}': ${error instanceof Error ? error.message : String(error)}`,
+      toolName,
+      error instanceof Error ? error : undefined
+    );
+  }
+}
+
+/**
+ * Get tool metadata by name
+ *
+ * @param toolName - Name of the MCP tool
+ * @returns Tool metadata or undefined if not found
+ */
+export function getToolMetadata(toolName: string): Omit<MCPTool, 'handler'> | undefined {
+  const tool = TOOL_REGISTRY.get(toolName);
+
+  if (!tool) {
+    return undefined;
+  }
+
+  // Return everything except the handler function
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    category: tool.category,
+    tags: tool.tags,
+    version: tool.version,
+    cacheable: tool.cacheable,
+    cacheTTL: tool.cacheTTL,
+  };
+}
+
+/**
+ * List all available MCP tools
+ *
+ * @param category - Optional category filter
+ * @returns Array of tool metadata
+ */
+export function listMCPTools(category?: string): Array<Omit<MCPTool, 'handler'>> {
+  const tools = Array.from(TOOL_REGISTRY.values());
+
+  const filtered = category
+    ? tools.filter(t => t.category === category)
+    : tools;
+
+  return filtered.map(tool => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    category: tool.category,
+    tags: tool.tags,
+    version: tool.version,
+    cacheable: tool.cacheable,
+    cacheTTL: tool.cacheTTL,
+  }));
+}
+
+/**
+ * Check if an MCP tool exists
+ *
+ * @param toolName - Name of the MCP tool
+ * @returns True if tool exists
+ */
+export function hasTool(toolName: string): boolean {
+  return TOOL_REGISTRY.has(toolName);
+}
+
+/**
+ * Get all tool categories
+ *
+ * @returns Array of unique categories
+ */
+export function getToolCategories(): string[] {
+  const categories = new Set<string>();
+
+  TOOL_REGISTRY.forEach(tool => {
+    if (tool.category) {
+      categories.add(tool.category);
+    }
+  });
+
+  return Array.from(categories).sort();
+}
+
+/**
+ * Validate tool input against schema
+ *
+ * @param toolName - Name of the MCP tool
+ * @param input - Input to validate
+ * @returns Validation result with errors if any
+ */
+export function validateToolInput(
+  toolName: string,
+  input: Record<string, unknown>
+): { valid: boolean; errors?: string[] } {
+  const tool = TOOL_REGISTRY.get(toolName);
+
+  if (!tool) {
+    return {
+      valid: false,
+      errors: [`Tool '${toolName}' not found`],
+    };
+  }
+
+  // Basic validation - check required fields
+  const schema = tool.inputSchema;
+  const errors: string[] = [];
+
+  if (schema.required && Array.isArray(schema.required)) {
+    for (const requiredField of schema.required) {
+      if (!(requiredField in input)) {
+        errors.push(`Missing required field: ${requiredField}`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+export default {
+  callMCPTool,
+  getToolMetadata,
+  listMCPTools,
+  hasTool,
+  getToolCategories,
+  validateToolInput,
+  MCPClientError,
+};