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

package/data/probe/site/integrations/docker.md

@@ -0,0 +1,248 @@
+---
+title: Docker Integration
+description: Deploy and run Probe using Docker containers for both CLI and web interface usage.
+---
+
+# Docker Integration
+
+Probe provides Docker images for both the CLI tool and the web interface, making it easy to deploy and use in containerized environments.
+
+## Docker Hub Images
+
+Pre-built images are available on Docker Hub:
+- **Probe CLI**: `probelabs/probe:latest`
+- **Probe Chat**: `probelabs/probe-chat:latest`
+
+### Available Tags
+- `latest` - Latest stable release
+- `X.Y.Z` - Specific version (e.g., `1.0.0`)
+- `X.Y` - Minor version (e.g., `1.0`)
+- `X` - Major version (e.g., `1`)
+
+## Quick Start
+
+### Probe CLI
+
+```bash
+# Pull the image
+docker pull probelabs/probe:latest
+
+# Basic usage
+docker run --rm -v $(pwd):/workspace probelabs/probe search "function" /workspace
+
+# Create an alias for convenience
+alias probe='docker run --rm -v $(pwd):/workspace probelabs/probe'
+probe search "class" .
+```
+
+### Probe Chat Interface
+
+#### CLI Mode
+```bash
+# Interactive chat with your codebase
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY=your_api_key \
+  -v $(pwd):/workspace \
+  probelabs/probe-chat
+```
+
+#### Web Mode
+```bash
+# Run web interface on port 3000
+docker run --rm \
+  -e ANTHROPIC_API_KEY=your_api_key \
+  -v $(pwd):/workspace \
+  -p 3000:3000 \
+  probelabs/probe-chat --web
+```
+
+## Docker Compose
+
+For easier local development and testing, use the included Docker Compose configuration:
+
+### Setup
+
+1. **Create a `.env` file** with your API keys:
+```bash
+ANTHROPIC_API_KEY=your_api_key_here
+# Or use OpenAI:
+# OPENAI_API_KEY=your_api_key_here
+```
+
+2. **Run services**:
+```bash
+# Run Probe CLI
+docker compose run --rm probe search "function" .
+
+# Run Probe Chat CLI
+docker compose run --rm probe-chat-cli
+
+# Run Probe Chat Web (accessible at http://localhost:3000)
+docker compose up probe-chat-web
+```
+
+### Available Services
+
+- **probe**: Probe CLI tool for code search
+- **probe-chat-cli**: Interactive chat interface (CLI mode)
+- **probe-chat-web**: Web interface (port 3000)
+- **probe-dev**: Development build with cargo cache (dev profile)
+
+## Environment Variables
+
+### Probe Chat
+- `ANTHROPIC_API_KEY` - Anthropic API key for Claude models
+- `OPENAI_API_KEY` - OpenAI API key for GPT models
+- `ALLOWED_FOLDERS` - Optional, restricts which folders can be searched
+
+## Use Cases
+
+### CI/CD Integration
+
+```yaml
+# Example GitHub Actions usage
+- name: Analyze Code Structure
+  run: |
+    docker run --rm -v ${{ github.workspace }}:/workspace \
+      probelabs/probe search "TODO|FIXME" /workspace --format json > analysis.json
+```
+
+### Development Teams
+
+```bash
+# Team development environment
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
+  -v $(pwd):/workspace \
+  -p 3000:3000 \
+  probelabs/probe-chat --web
+```
+
+### Code Review Automation
+
+```bash
+# Automated code review
+docker run --rm \
+  -v $(pwd):/workspace \
+  probelabs/probe extract "security|auth" /workspace --format markdown
+```
+
+## Multi-Platform Support
+
+Probe Docker images support multiple architectures:
+- `linux/amd64` - x86_64 Linux systems
+- `linux/arm64` - ARM64 Linux systems (Apple Silicon, ARM servers)
+
+Docker will automatically pull the correct architecture for your system.
+
+## Building Locally
+
+If you prefer to build the images locally:
+
+```bash
+# Build Probe CLI
+docker build -t probe-local .
+
+# Build Probe Chat
+docker build -t probe-chat-local -f examples/chat/Dockerfile examples/chat
+
+# Build with Docker Compose
+docker compose build
+```
+
+## Health Checks
+
+Both images include health checks:
+- **Probe CLI**: Tests `probe --version`
+- **Probe Chat**: Tests application endpoint (web mode) or Node.js version (CLI mode)
+
+## Security Features
+
+- **Non-root execution**: Both containers run as non-root user `probe`
+- **Minimal base images**: Based on `debian:bookworm-slim` and `node:slim`
+- **Security labels**: OCI-compliant labels for metadata
+- **Read-only volumes**: Mount code directories as read-only when possible
+
+## Troubleshooting
+
+### Port Already in Use
+If port 3000 is already in use:
+```bash
+docker run --rm -e ANTHROPIC_API_KEY=your_key -p 8080:3000 probelabs/probe-chat --web
+```
+
+### Permission Issues
+If you need to write to mounted volumes:
+```bash
+# Set ownership for mounted directory
+sudo chown -R 1000:1000 /path/to/mounted/directory
+```
+
+### API Key Issues
+Ensure your API key is properly set:
+```bash
+# Check if key is set
+echo $ANTHROPIC_API_KEY
+
+# Set key if needed
+export ANTHROPIC_API_KEY=your_actual_key
+```
+
+## Advanced Configuration
+
+### Custom Dockerfile
+
+For advanced use cases, you can extend the base images:
+
+```dockerfile
+FROM probelabs/probe-chat:latest
+
+# Add custom configurations
+COPY custom-config.json /app/config/
+ENV CUSTOM_CONFIG_PATH=/app/config/custom-config.json
+
+# Add additional tools
+USER root
+RUN apt-get update && apt-get install -y git
+USER probe
+
+ENTRYPOINT ["node", "index.js"]
+```
+
+### Production Deployment
+
+For production deployments, consider:
+- Using specific version tags instead of `latest`
+- Setting resource limits
+- Implementing proper logging
+- Using secrets management for API keys
+- Setting up monitoring and health checks
+
+```yaml
+# docker-compose.prod.yml
+version: '3.8'
+services:
+  probe-chat:
+    image: probelabs/probe-chat:1.0.0
+    environment:
+      - ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_api_key
+    secrets:
+      - anthropic_api_key
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+          cpus: '0.5'
+    restart: unless-stopped
+
+secrets:
+  anthropic_api_key:
+    external: true
+```
+
+## Related Documentation
+
+- [Installation Guide](../installation.md)
+- [Quick Start](../quick-start.md)
+- [GitHub Actions Integration](./github-actions.md)
+- [Web Interface](../web-interface.md)

package/data/probe/site/integrations/github-actions.md

@@ -0,0 +1,413 @@
+---
+title: GitHub Actions Integration
+description: Automate issue responses, PR reviews, and code modifications using Probe with GitHub Actions.
+---
+
+# GitHub Actions Integration
+
+Probe can be integrated into your GitHub workflow to automate responses to issues and pull requests, and even implement code changes, acting as an AI assistant powered by code context. This allows Probe to help answer questions, review code, or make modifications directly within GitHub.
+
+## Example Workflows
+
+### Example 1: Issue & PR Assistant (Read-Only)
+
+This example workflow demonstrates how to set up Probe to respond to commands in issue comments and newly opened pull requests or issues without modifying code.
+
+**File:** `.github/workflows/probe-assistant.yml`
+
+```yaml
+name: AI Comment Handler
+
+on:
+  pull_request:
+    types: [opened] # Trigger on new PRs
+  issue_comment:
+    types: [created] # Trigger on new issue comments
+  issues:
+    types: [opened] # Trigger on new issues
+
+# Define permissions needed for the workflow
+permissions:
+  issues: write # To post comments on issues
+  pull-requests: write # To post comments on PRs
+  contents: read # To read repository code for context
+
+jobs:
+  trigger_probe_chat:
+    # Use the reusable workflow from the main Probe repository
+    uses: probelabs/probe/.github/workflows/probe.yml@main
+    # Pass required inputs
+    with:
+      # Define the command prefix to trigger the bot
+      command_prefix: "/probe" # Or '/ai', '/ask', etc.
+      # Optionally override the default npx command if the secret isn't set
+      # default_probe_chat_command: 'node path/to/custom/script.js'
+      # Comment management options
+      update_existing_comment: true # Update existing comment instead of creating new ones
+      update_comment_marker: "<!-- probe-assistant -->" # Custom marker for this workflow
+    # Pass necessary secrets to the reusable workflow
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_API_URL: ${{ secrets.ANTHROPIC_API_URL }}
+      # GITHUB_TOKEN is automatically passed
+```
+
+#### How it Works (Read-Only Assistant)
+
+1.  **Triggers**: The workflow runs when a new PR/issue is opened or a comment is made on an issue.
+2.  **Permissions**: It requires `write` permissions for issues/PRs to post comments and `read` permission for `contents` to access repository code for analysis.
+3.  **Reusable Workflow**: It utilizes `probelabs/probe/.github/workflows/probe.yml@main`, which handles parsing the command, invoking the Probe AI agent, searching the codebase, generating a response, and posting it back as a comment.
+4.  **Configuration**:
+    *   `command_prefix`: Defines how users trigger the bot (e.g., `/probe <Your question>`).
+    *   `secrets`: Requires AI provider secrets (e.g., `ANTHROPIC_API_KEY`).
+
+### Example 2: AI Engineer (Code Editing Enabled)
+
+This example demonstrates how to configure Probe to not only respond to comments but also potentially implement code changes using a specific AI persona (`engineer`) and enabling edit capabilities.
+
+**File:** `.github/workflows/probe-engineer.yml`
+
+```yaml
+name: Probe Engineer Handler
+
+on:
+  issue_comment:
+    types: [created] # Trigger only on issue comments
+
+# Define permissions needed for the workflow
+permissions:
+  issues: write # To post comments
+  pull-requests: write # To potentially create/comment on PRs (depending on implement tool behavior)
+  contents: write # REQUIRED to allow code modifications
+
+jobs:
+  trigger_probe_implement:
+    # Use the reusable workflow
+    uses: probelabs/probe/.github/workflows/probe.yml@main
+    with:
+      # Define the command prefix
+      command_prefix: "/engineer" # Specific prefix for this persona
+      # --- Enable Code Modifications ---
+      allow_suggestions: true # Enable suggestions via suggest-changes (recommended for PR contexts)
+      # allow_edit: true # Alternative: enable direct commits
+      # --- Set AI Persona ---
+      prompt: engineer # Use the 'engineer' predefined prompt
+      # --- Comment Management ---
+      update_existing_comment: true # Update existing comment instead of creating new ones
+      update_comment_marker: "<!-- probe-engineer -->" # Custom marker for engineer workflow
+    secrets:
+      # AI Provider Secrets
+      ANTHROPIC_API_KEY: ${{ secrets.PROBE_ANTHROPIC_API_KEY }}
+      ANTHROPIC_API_URL: ${{ secrets.PROBE_ANTHROPIC_URL }}
+      # GitHub App Secrets (Potentially needed for more complex git operations)
+      APP_ID: ${{ secrets.PROBE_APP_ID }}
+      APP_PRIVATE_KEY: ${{ secrets.PROBE_APP_PRIVATE_KEY }}
+      # GITHUB_TOKEN is automatically passed
+```
+
+#### How it Works (AI Engineer)
+
+1.  **Trigger**: This workflow specifically triggers on issue comments.
+2.  **Permissions**: Crucially, it requires `contents: write` permission in addition to `issues: write` and potentially `pull-requests: write`. The `contents: write` permission is essential for allowing the workflow to modify files in the repository.
+3.  **Reusable Workflow**: Still uses `probelabs/probe/.github/workflows/probe.yml@main`.
+4.  **Configuration**:
+    *   `command_prefix`: Uses `/engineer` to invoke this specific workflow.
+    *   `allow_edit: true`: This flag enables Probe's code editing capabilities (likely via the `implement` tool). **Use with caution.**
+    *   `prompt: engineer`: Instructs the AI agent to use the specialized "engineer" persona, focusing on analysis and implementation.
+    *   `secrets`: May require additional secrets like GitHub App credentials (`APP_ID`, `APP_PRIVATE_KEY`) if the implementation involves creating commits or PRs under a specific App identity, depending on the underlying `implement` tool's behavior.
+
+## Code Modification Options
+
+Probe can help you make code changes in two ways:
+
+### Direct Changes (`allow_edit: true`)
+
+When you set `allow_edit: true`, Probe can make changes directly to your code.
+
+*   **What it does**: Probe can modify files in your repository when you ask it to (like "Fix this bug" or "Add error handling").
+*   **Requirements**: Your workflow needs permission to write to your repository (`contents: write`).
+*   **Result**: Changes are saved directly to your code.
+
+### Suggested Changes (`allow_suggestions: true`) - Recommended
+
+When you set `allow_suggestions: true`, Probe creates suggestions instead of making direct changes.
+
+*   **What it does**: Probe analyzes your code and creates suggestions that appear in pull requests, just like when a human reviewer suggests changes.
+*   **Requirements**: Your workflow needs permission to read your code (`contents: read`) and comment on pull requests (`pull-requests: write`).
+*   **Result**: You see suggested changes that you can accept or reject with one click.
+*   **When it works**: Only in pull requests. For other contexts, no changes are made.
+
+### Which Should You Choose?
+
+**We recommend `allow_suggestions: true`** because:
+- You get to review changes before they're applied
+- It's safer than automatic changes
+- You maintain full control over your code
+- It works great with GitHub's built-in review tools
+
+**Important**: Both options let AI modify your code, so always review the changes carefully before accepting them.
+
+## Manual Triggering (`workflow_dispatch`)
+
+You can allow workflows using `probe.yml` to be triggered manually from the GitHub UI. This is useful for testing or running the agent on demand without needing an issue comment or PR event.
+
+1.  **Add `workflow_dispatch` to Triggers**: Modify the `on:` section of your workflow file:
+
+    ```yaml
+    name: Manual Probe Run
+
+    on:
+      workflow_dispatch: # Allows manual triggering
+        # Optional: Define inputs for the manual run
+        inputs:
+          user_request:
+            description: 'The request/question for Probe'
+            required: true
+            default: 'Explain the main function in src/main.rs'
+          # Add other inputs if needed, e.g., target branch
+
+      # Keep other triggers if needed
+      issue_comment:
+        types: [created]
+
+    permissions:
+      # ... your permissions ...
+      contents: read # Or write if allow_edit is true
+
+    jobs:
+      trigger_probe_manual:
+        uses: probelabs/probe/.github/workflows/probe.yml@main
+        with:
+          # Use the input from the manual trigger
+          manual_input: ${{ github.event.inputs.user_request }}
+          # Set other parameters as needed
+          allow_edit: false # Example: disable editing for manual runs
+          # command_prefix is not typically needed for workflow_dispatch
+        secrets:
+          # ... your secrets ...
+    ```
+
+2.  **Trigger from GitHub UI**:
+    *   Go to your repository's "Actions" tab.
+    *   Select the workflow (e.g., "Manual Probe Run") from the list on the left.
+    *   Click the "Run workflow" dropdown button.
+    *   If you defined inputs (like `user_request`), fill them in the form.
+    *   Click the "Run workflow" button.
+
+The reusable `probe.yml` workflow needs to be designed to handle the `manual_input` (or a similarly named input) when triggered via `workflow_dispatch`. Check the `probe.yml` documentation for specifics on how it handles manual inputs.
+
+## Advanced Configuration
+
+### OpenTelemetry Tracing
+
+Probe's GitHub Actions integration supports OpenTelemetry tracing to monitor AI model interactions and performance metrics. This is particularly useful for understanding usage patterns, debugging issues, and optimizing AI interactions.
+
+#### Enable Tracing
+
+Add the `enable_tracing` parameter to your workflow:
+
+```yaml
+jobs:
+  trigger_probe_chat:
+    uses: probelabs/probe/.github/workflows/probe.yml@main
+    with:
+      command_prefix: "/probe"
+      enable_tracing: true # Enable OpenTelemetry tracing
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+#### File Tracing (Default)
+
+When `enable_tracing: true` is set without `TRACING_URL`, traces are saved to a file:
+
+- **Output**: `probe-traces.jsonl` file in JSON Lines format
+- **Artifact**: Automatically uploaded as `probe-traces` artifact
+- **Retention**: 30 days (configurable)
+- **Download**: Available in the Actions run artifacts section
+
+```yaml
+jobs:
+  trigger_probe_chat:
+    uses: probelabs/probe/.github/workflows/probe.yml@main
+    with:
+      command_prefix: "/probe"
+      enable_tracing: true
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      # No TRACING_URL = file tracing
+```
+
+#### Remote Tracing
+
+For remote tracing to an OpenTelemetry collector, add the `TRACING_URL` secret:
+
+```yaml
+jobs:
+  trigger_probe_chat:
+    uses: probelabs/probe/.github/workflows/probe.yml@main
+    with:
+      command_prefix: "/probe"
+      enable_tracing: true
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      TRACING_URL: ${{ secrets.TRACING_URL }} # e.g., http://localhost:4318/v1/traces
+```
+
+#### What Gets Traced
+
+The tracing system captures comprehensive data about AI interactions:
+
+- **AI Model Calls**: Request/response cycles with detailed timing
+- **Token Usage**: Prompt tokens, completion tokens, and total consumption
+- **Performance Metrics**: Response times, request durations, and throughput
+- **GitHub Context**: Issue/PR numbers, repository information, and workflow details
+- **Session Information**: Unique session IDs and conversation flow
+- **Error Tracking**: Failed requests, timeouts, and error details
+
+#### Example Trace Data
+
+```json
+{
+  "traceId": "abc123def456...",
+  "spanId": "789ghi012jkl...",
+  "name": "ai.generateText",
+  "startTimeUnixNano": 1704067200000000000,
+  "endTimeUnixNano": 1704067201000000000,
+  "attributes": {
+    "ai.model.id": "claude-3-7-sonnet-20250219",
+    "ai.model.provider": "anthropic",
+    "ai.telemetry.functionId": "chat-issue-123",
+    "ai.telemetry.metadata.sessionId": "github-issue-123",
+    "ai.telemetry.metadata.iteration": "1",
+    "github.repository": "owner/repo",
+    "github.issue.number": "123",
+    "github.event": "issue_comment"
+  },
+  "events": [
+    {
+      "name": "ai.request.start",
+      "attributes": {
+        "ai.request.messages": "[{\"role\":\"user\",\"content\":\"How does X work?\"}]"
+      }
+    },
+    {
+      "name": "ai.response.complete",
+      "attributes": {
+        "ai.usage.prompt_tokens": "245",
+        "ai.usage.completion_tokens": "156",
+        "ai.usage.total_tokens": "401"
+      }
+    }
+  ]
+}
+```
+
+#### Setting Up Remote Tracing
+
+For remote tracing with Jaeger:
+
+1. **Set up Jaeger**:
+   ```bash
+   docker run -d --name jaeger \
+     -p 16686:16686 \
+     -p 4318:4318 \
+     jaegertracing/all-in-one:latest
+   ```
+
+2. **Add Repository Secret**:
+   - Go to Settings > Secrets and variables > Actions
+   - Add: `TRACING_URL` = `http://localhost:4318/v1/traces`
+
+3. **Configure Workflow**:
+   ```yaml
+   jobs:
+     trigger_probe_chat:
+       uses: probelabs/probe/.github/workflows/probe.yml@main
+       with:
+         enable_tracing: true
+       secrets:
+         TRACING_URL: ${{ secrets.TRACING_URL }}
+   ```
+
+#### Analyzing Traces
+
+Download and analyze trace files:
+
+```bash
+# Download artifact from GitHub Actions
+# Extract probe-traces.jsonl
+
+# View traces
+cat probe-traces.jsonl | jq '.'
+
+# Count interactions by model
+cat probe-traces.jsonl | jq -r '.attributes."ai.model.id"' | sort | uniq -c
+
+# Calculate total token usage
+cat probe-traces.jsonl | jq -r '.events[]? | select(.name == "ai.response.complete") | 
+  .attributes."ai.usage.total_tokens"' | jq -s 'add'
+
+# Find slow responses (>5 seconds)
+cat probe-traces.jsonl | jq -r 'select(((.endTimeUnixNano - .startTimeUnixNano) / 1000000000) > 5) | 
+  {duration: ((.endTimeUnixNano - .startTimeUnixNano) / 1000000000), name: .name}'
+```
+
+#### Use Cases for Tracing
+
+- **Performance Monitoring**: Track AI response times and optimize workflows
+- **Usage Analytics**: Understand token consumption patterns and costs
+- **Debugging**: Identify failed requests and troubleshoot issues
+- **Capacity Planning**: Monitor request volumes and plan scaling
+- **Cost Optimization**: Analyze token usage to optimize AI interactions
+
+### Comment Management
+
+By default, Probe creates a new comment for each invocation. However, you can configure it to update an existing comment instead, which helps reduce comment clutter in issues and pull requests.
+
+#### Parameters
+
+*   **`update_existing_comment`** (boolean, default: `false`): When set to `true`, Probe will search for an existing comment containing the `update_comment_marker` and replace its content instead of creating a new comment.
+*   **`update_comment_marker`** (string, default: `"<!-- probe-bot -->")`): A hidden HTML comment marker inserted into the comment body. This serves as a reliable anchor that allows the workflow to locate and update the correct comment on subsequent runs.
+
+#### Benefits
+
+*   **Reduced Clutter**: Instead of accumulating multiple bot comments, you get a single, continuously updated response.
+*   **Better UX**: Users see the latest response without scrolling through multiple bot comments.
+*   **Cleaner History**: Issue and PR conversations remain focused and readable.
+
+#### Example Usage
+
+```yaml
+jobs:
+  trigger_probe_chat:
+    uses: probelabs/probe/.github/workflows/probe.yml@main
+    with:
+      command_prefix: "/probe"
+      # Enable comment updating
+      update_existing_comment: true
+      # Use a custom marker to distinguish different workflows
+      update_comment_marker: "<!-- my-probe-bot -->"
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+#### How It Works
+
+1.  **First Run**: Probe creates a new comment with the marker embedded as a hidden HTML comment.
+2.  **Subsequent Runs**: Probe searches for existing comments containing the specified marker and updates the first match found.
+3.  **Marker Uniqueness**: Use different markers for different workflows (e.g., `<!-- probe-assistant -->` vs `<!-- probe-engineer -->`) to prevent conflicts.
+
+#### Best Practices
+
+*   Use descriptive markers that identify the specific workflow or purpose (e.g., `<!-- probe-code-review -->`, `<!-- probe-qa-bot -->`).
+*   Enable this feature for workflows that are likely to be invoked multiple times on the same issue or PR.
+*   Consider keeping it disabled for one-off assistance requests where you want to preserve the conversation history.
+
+## Use Cases
+
+*   **Ticket Answering Assistant**: Users ask questions (`/probe How does X work?`), and Probe analyzes code to answer.
+*   **Pull Request Reviewer**: Invoke Probe (`/probe Review this change`) to get AI feedback on PRs.
+*   **AI Code Implementation**: Request code changes (`/engineer Refactor this function`) and have Probe attempt to implement them (requires `allow_edit: true` and `contents: write`).
+
+This integration streamlines development by bringing code-aware AI assistance and automation directly into your GitHub issues and pull requests.