@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/probe/npm/bin/.gitignore

@@ -0,0 +1,7 @@
+# Ignore all files in this directory
+*
+# Except these files
+!.gitignore
+!.gitkeep
+!README.md
+!probe

package/data/probe/npm/bin/README.md

@@ -0,0 +1,12 @@
+# Probe Binary Directory
+
+This directory is used to store the downloaded probe binary.
+
+The binary is automatically downloaded during package installation.
+If you encounter any issues with the download, you can manually place the probe binary in this directory.
+
+Binary name should be:
+- `probe` (on Linux/macOS)
+- `probe.exe` (on Windows)
+
+You can download the binary from: https://github.com/probelabs/probe/releases

package/data/probe/npm/bin/probe

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { access, constants } from 'fs';
+import { promisify } from 'util';
+
+const accessAsync = promisify(access);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Check if a file exists and is executable
+ */
+async function isExecutable(filePath) {
+  try {
+    await accessAsync(filePath, constants.F_OK | constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Attempt to download the binary if it's missing
+ */
+async function ensureBinary(binaryPath) {
+  try {
+    // Try to import the downloader and download the binary
+    const { downloadProbeBinary } = await import('../src/downloader.js');
+    console.error('Probe binary not found, downloading...');
+    await downloadProbeBinary();
+    
+    // Check if the binary now exists and is executable
+    if (await isExecutable(binaryPath)) {
+      console.error('Binary downloaded successfully.');
+      
+      // On macOS, try to remove quarantine attributes that might prevent execution
+      if (process.platform === 'darwin') {
+        try {
+          const { exec } = await import('child_process');
+          const { promisify } = await import('util');
+          const execAsync = promisify(exec);
+          await execAsync(`xattr -d com.apple.quarantine "${binaryPath}" 2>/dev/null || true`);
+        } catch {
+          // Ignore errors - this is just a precaution
+        }
+      }
+      
+      return true;
+    } else {
+      console.error('Binary downloaded but is not executable.');
+      return false;
+    }
+  } catch (error) {
+    console.error('Failed to download binary:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Spawn the probe binary with proper error handling
+ */
+async function spawnProbeBinary(binaryPath, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binaryPath, args, { stdio: 'inherit' });
+    
+    child.on('error', async (error) => {
+      // Handle spawn errors, particularly the dreaded "spawn Unknown system error -8"
+      if (error.code === 'ENOENT') {
+        console.error(`Error: Binary not found at ${binaryPath}`);
+        process.exit(1);
+      } else if (error.code === 'EACCES' || error.message.includes('spawn') || error.errno === -8) {
+        console.error(`Error: Cannot execute binary at ${binaryPath}`);
+        console.error('This might be due to:');
+        console.error('1. Missing execute permissions');
+        console.error('2. Architecture mismatch');
+        console.error('3. Corrupted binary file');
+        console.error('');
+        console.error('Attempting to re-download the binary...');
+        
+        const downloadSuccess = await ensureBinary(binaryPath);
+        if (downloadSuccess) {
+          // Retry execution after download
+          try {
+            const retryChild = spawn(binaryPath, args, { stdio: 'inherit' });
+            retryChild.on('exit', (code) => resolve(code || 0));
+            retryChild.on('error', (retryError) => {
+              console.error('Failed to execute binary even after re-download:', retryError.message);
+              reject(retryError);
+            });
+          } catch (retryError) {
+            console.error('Failed to retry execution:', retryError.message);
+            reject(retryError);
+          }
+        } else {
+          reject(error);
+        }
+      } else {
+        console.error('Unexpected error:', error.message);
+        reject(error);
+      }
+    });
+    
+    child.on('exit', (code) => resolve(code || 0));
+  });
+}
+
+// Main execution logic
+async function main() {
+  try {
+    // Check if first argument is 'mcp'
+    if (process.argv[2] === 'mcp') {
+      // Launch MCP server instead of binary
+      const mcpPath = join(__dirname, '..', 'build', 'mcp', 'index.js');
+      const mcpArgs = process.argv.slice(3); // Remove 'node', 'probe', and 'mcp'
+      
+      const child = spawn('node', [mcpPath, ...mcpArgs], { stdio: 'inherit' });
+      child.on('exit', (code) => process.exit(code || 0));
+    } else if (process.argv[2] === 'agent') {
+      // Launch Agent server instead of binary (use bundled version to reduce dependencies)
+      const agentPath = join(__dirname, '..', 'build', 'agent', 'index.js');
+
+      // Verify bundled agent exists
+      try {
+        await accessAsync(agentPath, constants.F_OK);
+      } catch {
+        console.error('Error: Bundled agent not found at', agentPath);
+        console.error('Please run: npm run build:agent');
+        process.exit(1);
+      }
+
+      const agentArgs = process.argv.slice(3); // Remove 'node', 'probe', and 'agent'
+      const child = spawn('node', [agentPath, ...agentArgs], { stdio: 'inherit' });
+      child.on('exit', (code) => process.exit(code || 0));
+    } else {
+      // Normal probe binary execution
+      const isWindows = process.platform === 'win32';
+      const binaryName = isWindows ? 'probe.exe' : 'probe-binary';
+      const binaryPath = join(__dirname, binaryName);
+      
+      // Check if binary exists and is executable
+      if (!(await isExecutable(binaryPath))) {
+        console.error('Probe binary not found or not executable, attempting to download...');
+        const downloadSuccess = await ensureBinary(binaryPath);
+        if (!downloadSuccess) {
+          console.error('Failed to download probe binary. Please try installing again or check your internet connection.');
+          process.exit(1);
+        }
+      }
+      
+      // Execute the binary
+      const exitCode = await spawnProbeBinary(binaryPath, process.argv.slice(2));
+      process.exit(exitCode);
+    }
+  } catch (error) {
+    console.error('Unexpected error in probe wrapper:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run the main function
+main().catch(error => {
+  console.error('Fatal error:', error.message);
+  process.exit(1);
+});

package/data/probe/npm/docs/CLAUDE_CODE_INTEGRATION.md

@@ -0,0 +1,414 @@
+# Claude Code Integration Guide
+
+Complete guide for using ProbeAgent with Claude Code's built-in `claude` command for zero-configuration AI-powered code assistance.
+
+## Table of Contents
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Auto-Fallback Feature](#auto-fallback-feature)
+- [Tool Event Extraction](#tool-event-extraction)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+ProbeAgent now supports Claude Code's `claude` command as a provider, enabling:
+- **Zero-configuration usage** in Claude Code environments
+- **Automatic fallback** when no API keys are present
+- **Black-box operation** - Claude Code handles its own agentic loop
+- **Tool event extraction** - Visibility into internal tool usage
+- **Full MCP integration** - Access to Probe's semantic search tools
+
+## Quick Start
+
+### Automatic (Zero Config)
+
+```javascript
+import { ProbeAgent } from 'probe-agent';
+
+// Works automatically if claude command is installed!
+const agent = new ProbeAgent({
+  allowedFolders: ['/path/to/your/code']
+});
+
+await agent.initialize();
+const response = await agent.answer('Explain how this codebase works');
+```
+
+### Explicit Provider
+
+```javascript
+const agent = new ProbeAgent({
+  provider: 'claude-code',  // Explicit
+  allowedFolders: ['/path/to/your/code']
+});
+```
+
+### Environment Variable
+
+```bash
+USE_CLAUDE_CODE=true node your-script.js
+```
+
+## How It Works
+
+### Architecture
+
+```
+ProbeAgent
+    ↓
+provider: 'claude-code'
+    ↓
+Enhanced Claude Code Engine
+    ↓
+Spawns: claude --output-format json --mcp-config ...
+    ↓
+Claude Code (black box)
+  - Handles its own agentic loop
+  - Uses MCP tools (mcp__probe__*)
+  - Returns final response
+    ↓
+Tool Event Extraction
+    ↓
+Response + Tool Events
+```
+
+### Black Box Mode
+
+Unlike the native engine which controls tool iteration:
+- **Claude Code manages its own loop** - ProbeAgent doesn't see intermediate steps
+- **No XML formatting** - Uses native MCP protocol
+- **Tool events extracted post-hoc** - Emitted as batch after response
+- **Bypass tool loop** - ProbeAgent's iteration logic is skipped
+
+### Key Components
+
+1. **Enhanced Claude Code Engine** (`src/agent/engines/enhanced-claude-code.js`)
+   - Spawns `claude` command with MCP configuration
+   - Manages session persistence
+   - Extracts tool events from response stream
+
+2. **Built-in MCP Server** (`src/agent/mcp/built-in-server.js`)
+   - Provides Probe tools via MCP protocol
+   - Tools: search, extract, query, list_files, search_files
+   - Automatically configured and started
+
+3. **Auto-Detection Logic** (`src/agent/ProbeAgent.js`)
+   - Checks for `claude` command availability
+   - Falls back when no API keys present
+
+## Auto-Fallback Feature
+
+### Detection Flow
+
+```
+Constructor → No API keys found
+    ↓
+Mark apiType='uninitialized'
+    ↓
+initialize() called
+    ↓
+Check: is claude command available?
+    ↓
+Yes → provider='claude-code'
+No  → Throw error with instructions
+```
+
+### Priority Order
+
+1. **Explicit provider** - Use if `options.provider` is set
+2. **API keys** - Use first available (Anthropic, OpenAI, Google, AWS)
+3. **Claude command** - Auto-fallback if installed
+4. **Error** - Neither API keys nor claude available
+
+### Error Messages
+
+**No API keys, no claude command:**
+```
+Error: No API key provided and claude command not found. Please either:
+1. Set an API key: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, or AWS credentials
+2. Install claude command from https://docs.claude.com/en/docs/claude-code
+```
+
+**With debug enabled:**
+```
+[DEBUG] No API keys found - will check for claude command in initialize()
+[DEBUG] No API keys found, but claude command detected
+[DEBUG] Auto-switching to claude-code provider
+```
+
+## Tool Event Extraction
+
+### How It Works
+
+Claude Code emits `assistant` messages containing tool use information:
+
+```javascript
+{
+  type: 'assistant',
+  message: {
+    content: [
+      { type: 'text', text: 'Let me search for that...' },
+      { type: 'tool_use', id: 'toolu_123', name: 'Glob', input: {...} }
+    ]
+  }
+}
+```
+
+The engine extracts these and emits as events:
+
+```javascript
+agent.events.on('toolCall', (event) => {
+  console.log(event.name);      // 'Glob'
+  console.log(event.status);    // 'started'
+  console.log(event.timestamp); // '2025-11-20T10:21:30.935Z'
+  console.log(event.args);      // { pattern: '*.js', path: '...' }
+});
+```
+
+### Event Structure
+
+```javascript
+{
+  timestamp: '2025-11-20T10:21:30.935Z',
+  name: 'Glob',
+  args: { pattern: '*.js', path: '/path/to/code' },
+  id: 'toolu_012JAiRK7bho9vevZyyUYJgu',
+  status: 'started'  // or 'completed'
+}
+```
+
+### Batch Emission
+
+Unlike native engine which emits in real-time:
+- Events collected during response
+- Emitted as batch after completion
+- Maintains compatibility with native engine event listeners
+
+## Configuration
+
+### Options
+
+```javascript
+const agent = new ProbeAgent({
+  // Provider
+  provider: 'claude-code',     // Force claude-code provider
+
+  // Required
+  allowedFolders: ['/path'],   // Allowed code directories
+
+  // Optional
+  debug: true,                 // Enable debug logging
+  sessionId: 'my-session',     // Custom session ID
+  customPrompt: '...',         // Custom system prompt
+  allowedTools: ['mcp__*'],    // Tool filtering
+});
+```
+
+### Environment Variables
+
+```bash
+# Force claude-code provider
+USE_CLAUDE_CODE=true
+
+# Enable debug logging
+DEBUG=probe:*
+```
+
+## Examples
+
+### Basic Usage
+
+```javascript
+import { ProbeAgent } from 'probe-agent';
+
+const agent = new ProbeAgent({
+  allowedFolders: [process.cwd()]
+});
+
+await agent.initialize();
+
+const response = await agent.answer(
+  'Find all async functions that handle errors'
+);
+
+console.log(response);
+```
+
+### With Tool Event Monitoring
+
+```javascript
+const agent = new ProbeAgent({
+  provider: 'claude-code',
+  allowedFolders: [process.cwd()],
+  debug: true
+});
+
+await agent.initialize();
+
+// Track tool usage
+const toolsUsed = [];
+agent.events.on('toolCall', (event) => {
+  if (event.status === 'started') {
+    toolsUsed.push(event.name);
+  }
+});
+
+const response = await agent.answer('Analyze this codebase');
+
+console.log('Tools used:', [...new Set(toolsUsed)]);
+```
+
+### Multi-Step Queries
+
+```javascript
+// Claude Code handles multi-step internally
+const agent = new ProbeAgent({
+  provider: 'claude-code',
+  allowedFolders: ['/my/project']
+});
+
+await agent.initialize();
+
+// This might trigger multiple internal tool uses
+const response = await agent.answer(
+  'Find the authentication logic and explain how it works'
+);
+// Claude Code will search, extract, and analyze automatically
+```
+
+## Testing
+
+### Integration Tests
+
+Located in `tests/integration/`:
+
+1. **claude-code-auto-fallback.spec.js** - Tests automatic provider detection
+2. **claude-code-tool-events.spec.js** - Tests tool event extraction
+3. **claude-code-multi-step.spec.js** - Tests complex multi-step queries
+
+These are standalone integration tests designed to work with the actual `claude` command.
+
+### Manual Testing
+
+```bash
+# Test auto-fallback
+node tests/integration/claude-code-auto-fallback.spec.js
+
+# Test tool events
+node tests/integration/claude-code-tool-events.spec.js
+
+# Test multi-step
+node tests/integration/claude-code-multi-step.spec.js
+```
+
+## Troubleshooting
+
+### Claude command not found
+
+**Problem:** `Error: claude command not found`
+
+**Solution:**
+- Install Claude Code from https://docs.claude.com/en/docs/claude-code
+- Verify: `claude --version`
+
+### Auto-fallback not working
+
+**Problem:** Not detecting claude command
+
+**Solutions:**
+- Ensure `claude` is in PATH
+- Check: `which claude`
+- Verify API keys are not set (auto-fallback only when no keys)
+
+### Tool events not appearing
+
+**Problem:** No tool events emitted
+
+**Possible causes:**
+1. Query didn't trigger tool use
+2. Need to enable event listeners before query
+3. Check that `agent.events` exists
+
+**Solution:**
+```javascript
+// Enable events BEFORE query
+agent.events.on('toolCall', (event) => {
+  console.log('Tool event:', event);
+});
+
+await agent.answer('query here');
+```
+
+### Session persistence issues
+
+**Problem:** Context lost between queries
+
+**Solution:**
+- Use same `sessionId` for related queries
+- Claude Code maintains conversation history automatically
+
+### MCP tools not working
+
+**Problem:** Tools not accessible
+
+**Checks:**
+1. MCP server started: Look for `[MCP] Built-in server started`
+2. Tools registered: Check debug output for tool list
+3. Tool filtering: Verify `allowedTools` configuration
+
+## Best Practices
+
+1. **Use in Claude Code Environment**
+   - Designed for Claude Code's native environment
+   - Leverages built-in authentication
+
+2. **Let Claude Code Handle Complexity**
+   - Don't try to control tool iterations
+   - Trust the black-box approach
+   - Monitor via tool events if needed
+
+3. **Enable Debug for Development**
+   ```javascript
+   const agent = new ProbeAgent({
+     provider: 'claude-code',
+     debug: true  // See what's happening
+   });
+   ```
+
+4. **Handle Errors Gracefully**
+   ```javascript
+   try {
+     await agent.initialize();
+     const response = await agent.answer(query);
+   } catch (error) {
+     if (error.message.includes('claude command not found')) {
+       // Fallback to API key approach
+     }
+   }
+   ```
+
+## Comparison: Native vs Claude Code
+
+| Feature | Native Engine | Claude Code Engine |
+|---------|--------------|-------------------|
+| Tool Loop | ProbeAgent controls (1-30 iterations) | Claude Code handles internally |
+| Tool Events | Real-time (started/completed pairs) | Batch emission at end |
+| Configuration | Requires API keys | Auto-detects claude command |
+| Debug Output | Shows "Tool Loop Iteration X/Y" | Shows "bypassing tool loop" |
+| MCP Protocol | XML-based tool format | Native MCP protocol |
+| Use Case | Custom control, API-based | Claude Code environment |
+
+## Related Documentation
+
+- See `examples/probe-agent-cli.js` for CLI usage
+- See `examples/multi-engine-demo.js` for switching between engines
+- See main README for general ProbeAgent documentation
+
+---
+
+**Last Updated:** November 2025
+**Version:** 0.6.0+