@claude-flow/cli 3.0.0-alpha.6 → 3.0.0-alpha.61

package/README.md

@@ -5,19 +5,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
-[![Commands](https://img.shields.io/badge/Commands-14+-orange.svg)](https://github.com/ruvnet/claude-flow)
-[![Subcommands](https://img.shields.io/badge/Subcommands-92+-purple.svg)](https://github.com/ruvnet/claude-flow)
+[![Commands](https://img.shields.io/badge/Commands-29-orange.svg)](https://github.com/ruvnet/claude-flow)
+[![Subcommands](https://img.shields.io/badge/Subcommands-170+-purple.svg)](https://github.com/ruvnet/claude-flow)
 
-> Modern CLI module for Claude Flow V3 - comprehensive command-line interface with 14 commands, 92+ subcommands, interactive prompts, self-learning hooks, background workers, hive-mind coordination, and beautiful output formatting.
+> Modern CLI module for Claude Flow V3 - comprehensive command-line interface with 29 commands, 170+ subcommands, interactive prompts, self-learning hooks, background workers, hive-mind coordination, Q-Learning agent routing, code analysis, collaborative issue claims, smart error suggestions, and beautiful output formatting.
 
 ## Features
 
 ### Core Capabilities
-- **14 Main Commands** - Complete CLI coverage for all Claude Flow operations
-- **92+ Subcommands** - Fine-grained control over every aspect of the system
+- **29 Main Commands** - Complete CLI coverage for all Claude Flow operations
+- **170+ Subcommands** - Fine-grained control over every aspect of the system
 - **Advanced Argument Parsing** - Full support for flags, options, subcommands, and positional arguments
 - **Interactive Prompts** - Rich interactive mode with confirmations, selections, and input validation
 - **Beautiful Output** - Colored output, tables, progress bars, spinners, and multiple formats (text, JSON, table)
+- **Smart Error Suggestions** - Levenshtein distance-based typo detection with helpful corrections
 
 ### V3-Specific Features
 - **Self-Learning Hooks** - 17 hook subcommands + 12 background workers with pattern learning and neural integration
@@ -25,11 +26,15 @@
 - **15-Agent Swarm** - V3 hierarchical mesh coordination with domain specialization
 - **AgentDB Integration** - 150x-12,500x faster vector search with HNSW indexing
 - **SONA Learning** - Sub-0.05ms adaptation with Mixture of Experts routing
+- **Q-Learning Routing** - Intelligent task-to-agent routing with reinforcement learning
+- **Code Analysis** - AST analysis, diff classification, complexity metrics, boundary detection
+- **Issue Claims (ADR-016)** - Collaborative human-agent issue management with work stealing
 
 ### Developer Experience
 - **Type-Safe** - Full TypeScript support with comprehensive type definitions
 - **Global Options** - Built-in `--help`, `--version`, `--verbose`, `--quiet`, `--format`
-- **Auto-Completion** - Shell completion support for commands and options
+- **Shell Completions** - Full tab completion for bash, zsh, fish, and PowerShell
+- **Doctor Command** - System diagnostics with health checks and suggested fixes
 - **Migration Tools** - Built-in V2 to V3 migration with rollback support
 
 ## Installation
@@ -63,6 +68,15 @@ claude-flow swarm init --v3-mode
 # Search memory
 claude-flow memory search -q "authentication patterns"
 
+# Route task to optimal agent (Q-Learning)
+claude-flow route task "Implement OAuth2 authentication"
+
+# Analyze code complexity
+claude-flow analyze complexity ./src
+
+# Claim an issue
+claude-flow issues claim ISSUE-123
+
 # Check system status
 claude-flow status --watch
 ```
@@ -87,6 +101,21 @@ claude-flow status --watch
 | `hooks` | 17 | Self-learning hooks with neural pattern recognition + 12 background workers |
 | `hive-mind` | 6 | Queen-led consensus-based multi-agent coordination |
 | `migrate` | 5 | V2 to V3 migration with rollback support |
+| `process` | 4 | Background process management and monitoring |
+| `daemon` | 5 | Node.js worker daemon (start, stop, status, trigger, enable) |
+| `neural` | 5 | Neural pattern training (train, status, patterns, predict, optimize) |
+| `security` | 6 | Security scanning (scan, audit, cve, threats, validate, report) |
+| `performance` | 5 | Performance profiling (benchmark, profile, metrics, optimize, report) |
+| `providers` | 5 | AI providers (list, add, remove, test, configure) |
+| `plugins` | 5 | Plugin management (list, install, uninstall, enable, disable) |
+| `deployment` | 5 | Deployment management (deploy, rollback, status, environments, release) |
+| `embeddings` | 4 | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
+| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) |
+| `issues` | 10 | Collaborative issue claims with work stealing (ADR-016) |
+| `route` | 7 | Q-Learning agent routing with reinforcement learning |
+| `analyze` | 11 | Code analysis (AST, diff, complexity, boundaries, dependencies) |
+| `doctor` | 1 | System diagnostics with health checks and suggested fixes |
+| `completions` | 4 | Shell completions for bash, zsh, fish, and PowerShell |
 
 ---
 
@@ -954,6 +983,396 @@ claude-flow migrate rollback --backup-id backup-1704369600
 
 ---
 
+### `doctor` - System Diagnostics
+
+System health checks with automatic fix suggestions.
+
+```bash
+claude-flow doctor [options]
+```
+
+#### Health Checks
+
+| Check | Description | Auto-Fix |
+|-------|-------------|----------|
+| Node.js Version | Verify Node.js 20+ | nvm install 20 |
+| npm Version | Verify npm 9+ | npm install -g npm@latest |
+| Git | Check git installation | Install git |
+| Git Repository | Check if in git repo | git init |
+| Config File | Validate configuration | claude-flow config init |
+| Daemon Status | Check daemon running | claude-flow daemon start |
+| Memory Database | Check memory DB | claude-flow memory configure |
+| API Keys | Check for API keys | export ANTHROPIC_API_KEY=... |
+| MCP Servers | Check MCP configuration | claude mcp add claude-flow ... |
+| Disk Space | Check available space | Free up disk |
+| TypeScript | Check TypeScript install | npm install -D typescript |
+
+#### Options
+
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--fix` | `-f` | Show fix commands for issues | `false` |
+| `--component` | `-c` | Check specific component | all |
+| `--verbose` | `-v` | Verbose output | `false` |
+
+#### Examples
+
+```bash
+# Run full health check
+claude-flow doctor
+
+# Show fixes for issues
+claude-flow doctor --fix
+
+# Check specific component
+claude-flow doctor -c daemon
+claude-flow doctor -c mcp
+claude-flow doctor -c memory
+```
+
+#### Output Example
+
+```
+Claude Flow Doctor
+System diagnostics and health check
+──────────────────────────────────────────────────
+
+✓ Node.js Version: v22.21.1 (>= 20 required)
+✓ npm Version: v10.9.4
+✓ Git: v2.52.0
+✓ Git Repository: In a git repository
+⚠ Config File: No config file (using defaults)
+⚠ Daemon Status: Not running
+⚠ Memory Database: Not initialized
+⚠ API Keys: No API keys found
+⚠ MCP Servers: No MCP config found
+✓ Disk Space: 73G available
+✓ TypeScript: v5.9.3
+
+──────────────────────────────────────────────────
+
+Summary: 6 passed, 5 warnings
+
+All checks passed with some warnings.
+```
+
+---
+
+### `route` - Q-Learning Agent Router
+
+Intelligent task-to-agent routing using reinforcement learning.
+
+```bash
+claude-flow route <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `task` | Route a task to optimal agent using Q-Learning |
+| `list-agents` | List available agent types with capabilities |
+| `stats` | Show router statistics and learning metrics |
+| `feedback` | Provide routing feedback for continuous learning |
+| `reset` | Reset Q-Learning router state |
+| `export` | Export Q-table for persistence |
+| `import` | Import Q-table from file |
+
+#### Agent Types
+
+| Type | Description |
+|------|-------------|
+| `coder` | Code implementation and debugging |
+| `tester` | Testing and quality assurance |
+| `reviewer` | Code review and quality checks |
+| `architect` | System design and architecture |
+| `researcher` | Research and information gathering |
+| `optimizer` | Performance optimization |
+| `debugger` | Bug fixing and troubleshooting |
+| `documenter` | Documentation and comments |
+
+#### How It Works
+
+1. **State Encoding** - Analyzes task description using hash-based feature extraction
+2. **Q-Learning** - Uses Q-table to map (state, action) pairs to expected rewards
+3. **Epsilon-Greedy** - Balances exploration (try new agents) vs exploitation (use best known)
+4. **Feedback Loop** - Learns from success/failure outcomes to improve routing
+
+#### Examples
+
+```bash
+# Route a task to optimal agent
+claude-flow route task "Implement user authentication with JWT"
+
+# Route with verbose output showing decision process
+claude-flow route task "Fix memory leak in API handler" --verbose
+
+# List available agent types
+claude-flow route list-agents
+
+# View router statistics
+claude-flow route stats
+
+# Provide feedback (reward: -1 to 1)
+claude-flow route feedback --agent coder --reward 0.8 --task "auth implementation"
+
+# Export Q-table for backup
+claude-flow route export -o ./q-table.json
+
+# Import Q-table
+claude-flow route import -i ./q-table.json
+
+# Reset router (start fresh)
+claude-flow route reset --confirm
+```
+
+---
+
+### `analyze` - Code Analysis
+
+Comprehensive code analysis with AST parsing, diff classification, complexity metrics, and dependency analysis.
+
+```bash
+claude-flow analyze <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description | Algorithm |
+|------------|-------------|-----------|
+| `ast` | AST analysis with symbol extraction | tree-sitter (regex fallback) |
+| `complexity` | Cyclomatic and cognitive complexity | McCabe + cognitive metrics |
+| `symbols` | Extract functions, classes, types | AST parsing |
+| `imports` | Import dependency analysis | Static analysis |
+| `diff` | Diff classification and risk assessment | Pattern matching |
+| `boundaries` | Code boundaries detection | MinCut algorithm |
+| `modules` | Module community detection | Louvain algorithm |
+| `dependencies` | Full dependency graph | Graph building |
+| `circular` | Circular dependency detection | Tarjan's SCC |
+| `deps` | Project dependency analysis | npm/yarn |
+| `code` | Static code quality analysis | Multi-metric |
+
+#### Diff Risk Levels
+
+| Risk | Color | Description |
+|------|-------|-------------|
+| `critical` | Red | Breaking changes, security-sensitive |
+| `high` | Orange | Core logic, API changes |
+| `medium` | Yellow | Feature additions, significant refactoring |
+| `low` | Green | Documentation, tests, formatting |
+
+#### Examples
+
+```bash
+# Analyze AST of a file
+claude-flow analyze ast ./src/auth/login.ts
+
+# Analyze with symbol extraction
+claude-flow analyze symbols ./src/services/ --recursive
+
+# Check cyclomatic complexity
+claude-flow analyze complexity ./src --threshold 10
+
+# Classify a git diff
+claude-flow analyze diff HEAD~1
+
+# Classify staged changes
+claude-flow analyze diff --staged
+
+# Find code boundaries (module splits)
+claude-flow analyze boundaries ./src --min-cut
+
+# Detect module communities
+claude-flow analyze modules ./src --algorithm louvain
+
+# Find circular dependencies
+claude-flow analyze circular ./src
+
+# Full dependency graph
+claude-flow analyze dependencies ./src -o ./deps.dot --format dot
+
+# Project dependency analysis
+claude-flow analyze deps --outdated
+```
+
+---
+
+### `issues` - Collaborative Issue Claims (ADR-016)
+
+Human-agent collaborative issue management with work stealing, load balancing, and handoffs.
+
+```bash
+claude-flow issues <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List all active claims |
+| `claim` | Claim an issue for yourself or an agent |
+| `release` | Release a claim |
+| `handoff` | Request handoff to another agent/user |
+| `status` | Update claim status and progress |
+| `stealable` | List issues available for work stealing |
+| `steal` | Steal an issue from overloaded/stale claimant |
+| `load` | View agent load distribution |
+| `rebalance` | Rebalance claims across swarm |
+| `board` | Visual Kanban-style claim board |
+
+#### Claim Status
+
+| Status | Description |
+|--------|-------------|
+| `active` | Actively being worked on |
+| `paused` | Temporarily paused |
+| `blocked` | Blocked by dependency |
+| `stealable` | Available for work stealing |
+| `completed` | Work completed |
+| `handoff-pending` | Awaiting handoff acceptance |
+| `review-requested` | Needs review |
+
+#### Work Stealing
+
+Issues can be marked stealable when:
+- **Overloaded** - Claimant has too many active claims
+- **Stale** - No progress for extended period
+- **Blocked** - Blocked beyond timeout threshold
+- **Voluntary** - Claimant voluntarily releases
+
+#### Examples
+
+```bash
+# List all claims
+claude-flow issues list
+
+# List with status filter
+claude-flow issues list --status active
+
+# Claim an issue
+claude-flow issues claim ISSUE-123
+
+# Claim as agent
+claude-flow issues claim ISSUE-123 --as-agent --type coder
+
+# Update progress
+claude-flow issues status ISSUE-123 --progress 50
+
+# Mark as blocked
+claude-flow issues status ISSUE-123 --set blocked --note "Waiting for API"
+
+# Request handoff to another user
+claude-flow issues handoff ISSUE-123 --to user:alice:Alice
+
+# Request handoff to agent
+claude-flow issues handoff ISSUE-123 --to agent:coder:coder-001
+
+# View stealable issues
+claude-flow issues stealable
+
+# Steal an issue
+claude-flow issues steal ISSUE-123 --reason overloaded
+
+# View agent load
+claude-flow issues load
+
+# Rebalance swarm
+claude-flow issues rebalance --strategy even
+
+# Visual board view
+claude-flow issues board
+```
+
+#### Board View
+
+```
+📋 Issue Claims Board
+────────────────────────────────────────────────────────────────
+
+ACTIVE (3)          PAUSED (1)          BLOCKED (1)
+────────────────    ────────────────    ────────────────
+│ ISSUE-123    │    │ ISSUE-456    │    │ ISSUE-789    │
+│ 🤖 coder     │    │ 👤 alice     │    │ 🤖 tester    │
+│ 75% ████░░░  │    │ 30% ██░░░░░  │    │ 50% ███░░░░  │
+└──────────────┘    └──────────────┘    └──────────────┘
+```
+
+---
+
+### `completions` - Shell Completions
+
+Generate shell completion scripts for tab completion of commands.
+
+```bash
+claude-flow completions <shell>
+```
+
+#### Supported Shells
+
+| Shell | Installation | File Location |
+|-------|-------------|---------------|
+| `bash` | `claude-flow completions bash >> ~/.bashrc` | `~/.bash_completion.d/claude-flow` |
+| `zsh` | `claude-flow completions zsh > ~/.zfunc/_claude-flow` | `~/.zfunc/_claude-flow` |
+| `fish` | `claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish` | `~/.config/fish/completions/` |
+| `powershell` | `claude-flow completions powershell >> $PROFILE` | PowerShell profile |
+
+#### Examples
+
+```bash
+# Install bash completions
+claude-flow completions bash > ~/.bash_completion.d/claude-flow
+source ~/.bash_completion.d/claude-flow
+
+# Install zsh completions
+mkdir -p ~/.zfunc
+claude-flow completions zsh > ~/.zfunc/_claude-flow
+# Add to .zshrc: fpath=(~/.zfunc $fpath); autoload -Uz compinit; compinit
+
+# Install fish completions
+claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish
+
+# Install PowerShell completions
+claude-flow completions powershell >> $PROFILE
+```
+
+#### Completion Features
+
+- All 29 top-level commands
+- Full subcommand completion for each command
+- Flag and option completion
+- Dynamic suggestions based on context
+
+---
+
+### Smart Error Suggestions
+
+When you mistype a command, the CLI provides helpful suggestions using Levenshtein distance matching.
+
+```bash
+$ claude-flow swram
+[ERROR] Unknown command: swram
+  Did you mean one of these?
+  - swarm
+  - neural
+  - start
+
+$ claude-flow memroy
+[ERROR] Unknown command: memroy
+  Did you mean "memory"?
+
+$ claude-flow agnet
+[ERROR] Unknown command: agnet
+  Did you mean "agent"?
+```
+
+The suggestion system:
+- Uses Levenshtein distance to find similar commands
+- Recognizes 40+ common typos (e.g., `memroy` → `memory`, `swram` → `swarm`)
+- Suggests up to 3 alternatives sorted by similarity
+- Boosts prefix matches for better suggestions
+
+---
+
 ## Global Options
 
 All commands support these global options:
@@ -1180,6 +1599,9 @@ The CLI is optimized for V3 performance targets:
 - [@claude-flow/mcp](../mcp) - MCP server implementation
 - [@claude-flow/hooks](../hooks) - Self-learning hooks system
 - [@claude-flow/neural](../neural) - SONA neural learning
+- [@claude-flow/embeddings](../embeddings) - Vector embeddings (75x faster with agentic-flow)
+- [@claude-flow/security](../security) - CVE remediation & security patterns
+- [@claude-flow/providers](../providers) - Multi-LLM provider system
 
 ## License
 

package/bin/cli.js

@@ -3,12 +3,148 @@
  * @claude-flow/cli - CLI Entry Point
  *
  * Claude Flow V3 Command Line Interface
+ *
+ * Auto-detects MCP mode when stdin is piped and no args provided.
+ * This allows: echo '{"jsonrpc":"2.0",...}' | npx @claude-flow/cli
  */
 
-import { CLI } from '../dist/src/index.js';
+// Check if we should run in MCP server mode
+// Conditions: stdin is being piped AND no CLI arguments provided
+const isMCPMode = !process.stdin.isTTY && process.argv.length === 2;
+
+if (isMCPMode) {
+  // Run MCP server mode
+  const { listMCPTools, callMCPTool, hasTool } = await import('../dist/src/mcp-client.js');
+
+  const VERSION = '3.0.0';
+  const sessionId = `mcp-${Date.now()}-${Math.random().toString(36).substr(2, 4)}`;
+
+  console.error(
+    `[${new Date().toISOString()}] INFO [claude-flow-mcp] (${sessionId}) Starting in stdio mode`
+  );
+
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', async (chunk) => {
+    buffer += chunk;
+    let lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (line.trim()) {
+        try {
+          const message = JSON.parse(line);
+          const response = await handleMessage(message);
+          if (response) {
+            console.log(JSON.stringify(response));
+          }
+        } catch (error) {
+          console.log(JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32700, message: 'Parse error' },
+          }));
+        }
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    process.exit(0);
+  });
+
+  async function handleMessage(message) {
+    if (!message.method) {
+      return {
+        jsonrpc: '2.0',
+        id: message.id,
+        error: { code: -32600, message: 'Invalid Request: missing method' },
+      };
+    }
+
+    const params = message.params || {};
+
+    switch (message.method) {
+      case 'initialize':
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            protocolVersion: '2024-11-05',
+            serverInfo: { name: 'claude-flow', version: VERSION },
+            capabilities: {
+              tools: { listChanged: true },
+              resources: { subscribe: true, listChanged: true },
+            },
+          },
+        };
+
+      case 'tools/list': {
+        const tools = listMCPTools();
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            tools: tools.map(tool => ({
+              name: tool.name,
+              description: tool.description,
+              inputSchema: tool.inputSchema,
+            })),
+          },
+        };
+      }
+
+      case 'tools/call': {
+        const toolName = params.name;
+        const toolParams = params.arguments || {};
+
+        if (!hasTool(toolName)) {
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: { code: -32601, message: `Tool not found: ${toolName}` },
+          };
+        }
+
+        try {
+          const result = await callMCPTool(toolName, toolParams, { sessionId });
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] },
+          };
+        } catch (error) {
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: {
+              code: -32603,
+              message: error instanceof Error ? error.message : 'Tool execution failed',
+            },
+          };
+        }
+      }
+
+      case 'notifications/initialized':
+        return null;
+
+      case 'ping':
+        return { jsonrpc: '2.0', id: message.id, result: {} };
 
-const cli = new CLI();
-cli.run().catch((error) => {
-  console.error('Fatal error:', error.message);
-  process.exit(1);
-});
+      default:
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          error: { code: -32601, message: `Method not found: ${message.method}` },
+        };
+    }
+  }
+} else {
+  // Run normal CLI mode
+  const { CLI } = await import('../dist/src/index.js');
+  const cli = new CLI();
+  cli.run().catch((error) => {
+    console.error('Fatal error:', error.message);
+    process.exit(1);
+  });
+}