@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/bot-transports-rfc.md

@@ -1,12 +1,12 @@
 # RFC: Bot Transports for Visor (Slack-first)
 
-Status: Draft
+Status: Implemented
 
 This RFC proposes a Slack integration built on the event-bus/state-machine engine. The first iteration focuses on:
 - A Slack frontend that subscribes to engine events and posts an evolving message per group (e.g., overview, review).
 - Simple configuration via `frontends` in the workflow config, e.g.
 
-```
+```yaml
 frontends:
   - name: slack
     config:
@@ -19,5 +19,15 @@ Design notes:
 - No placeholder/queued messages are posted; only content-producing events produce/modify messages.
 - Messages are updated in-place (using `chat.update`) keyed by group. We do not rely on hidden markers in message text.
 - Debounce/coalescing reduces API churn during bursts; terminal state forces an immediate flush.
-- Future work will add inbound Slack handling (webhooks) to trigger workflows and attach conversation context.
+- Inbound Slack handling is now implemented via Socket Mode (`src/slack/socket-runner.ts`) to trigger workflows and attach conversation context.
+
+## Implementation
+
+The Slack integration is implemented across these key files:
+- `src/frontends/slack-frontend.ts` - Frontend that subscribes to engine events
+- `src/frontends/host.ts` - Frontend host that manages lifecycle
+- `src/slack/client.ts` - Lightweight Slack Web API wrapper
+- `src/slack/socket-runner.ts` - Socket Mode for inbound Slack events
+- `src/slack/adapter.ts` - Slack adapter for message handling
+- `src/slack/markdown.ts` - Markdown to Slack mrkdwn conversion
 

package/dist/docs/ci-cli-mode.md

@@ -1,8 +1,10 @@
 # Run Modes in CI (including GitHub Actions)
 
-Visor now defaults to CLI mode everywhere (no auto-detection). To enable GitHub-specific behavior (comments, checks), pass `--mode github-actions` or set the action input `mode: github-actions`.
+Visor defaults to CLI mode everywhere (no auto-detection). To enable GitHub-specific behavior (comments, checks API), pass `--mode github-actions` or set the action input `mode: github-actions`.
 
-Examples (GitHub Actions – CLI mode):
+## Basic CLI Mode (Default)
+
+In CLI mode, Visor runs standalone without GitHub integration. This is ideal for local development, CI pipelines, or any environment where you want direct output.
 
 ```yaml
 jobs:
@@ -15,20 +17,126 @@ jobs:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 ```
 
-GitHub Actions behavior (comments/checks):
+## GitHub Actions Mode
+
+To enable GitHub-specific features (PR comments, GitHub Checks API):
 
 ```yaml
 jobs:
-  visor-cli:
+  visor-github:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx -y @probelabs/visor@latest --mode github-actions --config .visor.yaml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+## CI-Relevant CLI Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--config <path>` | Path to configuration file | `--config .visor.yaml` |
+| `-o, --output <format>` | Output format: `table`, `json`, `markdown`, `sarif` | `--output sarif` |
+| `--output-file <path>` | Write output to file instead of stdout | `--output-file results.json` |
+| `--timeout <ms>` | Timeout in milliseconds (default: 1200000 / 20 min) | `--timeout 300000` |
+| `--max-parallelism <n>` | Max parallel checks (default: 3) | `--max-parallelism 5` |
+| `--fail-fast` | Stop execution on first failure | `--fail-fast` |
+| `--tags <tags>` | Run only checks with these tags (comma-separated) | `--tags security,fast` |
+| `--exclude-tags <tags>` | Skip checks with these tags | `--exclude-tags slow` |
+| `--event <type>` | Simulate GitHub event type | `--event pr_opened` |
+| `--analyze-branch-diff` | Analyze diff vs base branch | `--analyze-branch-diff` |
+| `--debug` | Enable debug output | `--debug` |
+| `-v, --verbose` | Increase verbosity | `--verbose` |
+| `-q, --quiet` | Reduce output to warnings/errors | `--quiet` |
+| `--mode <mode>` | Run mode: `cli` or `github-actions` | `--mode github-actions` |
+
+## SARIF Output for GitHub Code Scanning
+
+Generate SARIF output for integration with GitHub's code scanning feature:
+
+```yaml
+jobs:
+  visor-security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx -y @probelabs/visor@latest --check security --output sarif --output-file results.sarif
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+```
+
+## Environment Variables
+
+### AI Provider Keys
+
+Set one of the following based on your AI provider:
+
+| Variable | Provider |
+|----------|----------|
+| `OPENAI_API_KEY` | OpenAI GPT models |
+| `ANTHROPIC_API_KEY` | Anthropic Claude models |
+| `GOOGLE_API_KEY` | Google Gemini models |
+| `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` | AWS Bedrock |
+| `AWS_BEDROCK_API_KEY` | AWS Bedrock (API key auth) |
+
+### GitHub Integration
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | Required for `--mode github-actions` |
+
+## Exit Codes
+
+- `0` - Success, no critical issues found
+- `1` - Critical issues found or execution error
+
+## Example: Full CI Pipeline
+
+```yaml
+jobs:
+  visor-review:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npx -y @probelabs/visor@latest --mode github-actions --config .visor.yaml --output json
+        with:
+          fetch-depth: 0  # Full history for branch diff analysis
+
+      - name: Run Visor Code Review
+        run: |
+          npx -y @probelabs/visor@latest \
+            --config .visor.yaml \
+            --output json \
+            --output-file visor-results.json \
+            --analyze-branch-diff \
+            --timeout 600000 \
+            --fail-fast
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+      - name: Upload Results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: visor-results
+          path: visor-results.json
 ```
 
-Notes:
+## Notes
+
+- In CLI mode, GitHub credentials are not required. Provide your AI provider keys as environment variables.
+- If you want PR comments/checks, use `--mode github-actions` with `GITHUB_TOKEN`.
+- Use `--output-file` for reliable file output instead of shell redirection (`> file`).
+- The `--fail-fast` flag is useful in CI to stop early when issues are found.
+- Use `--quiet` to reduce noise in CI logs when only warnings/errors matter.
+
+## Related Documentation
 
-- In CLI mode, GitHub credentials aren’t required. Provide your AI provider keys as env vars (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
-- If you want PR comments/checks, run with `--mode github-actions` or use the published action with `with: mode: github-actions`.
+- [Configuration](./configuration.md) - Full configuration reference
+- [Output Formats](./output-formats.md) - Details on output format options
+- [Event Triggers](./event-triggers.md) - GitHub event filtering
+- [Tag Filtering](./tag-filtering.md) - Selective check execution with tags

package/dist/docs/claude-code.md

@@ -1,34 +1,50 @@
-## 🤖 Claude Code Provider
+## Claude Code Provider
 
-Visor includes advanced integration with Claude Code SDK, providing powerful AI-driven code analysis with MCP (Model Context Protocol) tools and subagent support.
+Visor includes advanced integration with the Claude Code SDK, providing powerful AI-driven code analysis with MCP (Model Context Protocol) tools and subagent support.
 
 ### Features
 
-- Advanced AI Analysis: Leverages Claude Code's sophisticated understanding
-- MCP Tools: Built-in and custom tools for specialized analysis
-- Subagents: Delegate specific tasks to specialized agents
-- Streaming Responses: Real-time feedback during analysis
-- Flexible Permissions: Granular control over tool usage
+- **Advanced AI Analysis**: Leverages Claude Code's sophisticated understanding
+- **MCP Tools**: Custom tools for specialized analysis via MCP servers
+- **Subagents**: Delegate specific tasks to specialized agents
+- **Session Reuse**: Continue conversations across dependent checks
+- **Flexible Permissions**: Granular control over tool usage
 
-### Configuration
+### Configuration Options
+
+The `claude_code` configuration block supports the following options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `allowedTools` | `string[]` | List of tool names Claude can use (e.g., `['Grep', 'Read', 'WebSearch']`) |
+| `maxTurns` | `number` | Maximum conversation turns (default: 5) |
+| `systemPrompt` | `string` | Custom system prompt for the analysis |
+| `mcpServers` | `object` | MCP server configurations (see below) |
+| `subagent` | `string` | Path to a subagent definition file |
+| `hooks` | `object` | Lifecycle hooks (`onStart`, `onEnd`, `onError`) |
+
+### Basic Example
 
 ```yaml
 steps:
-  claude_comprehensive:
+  claude_security_review:
     type: claude-code
-    prompt: "Perform a comprehensive security and performance review"
-    tags: ["comprehensive", "security", "performance", "slow", "remote"]
+    prompt: "Perform a comprehensive security review"
     claude_code:
       allowedTools: ['Grep', 'Read', 'WebSearch']
       maxTurns: 5
       systemPrompt: "You are an expert security auditor"
+```
+
+### Example with MCP Servers
 
+```yaml
+steps:
   claude_with_mcp:
     type: claude-code
     prompt: "Analyze code complexity and architecture"
-    tags: ["architecture", "complexity", "comprehensive", "remote"]
     claude_code:
-      allowedTools: ['analyze_file_structure', 'calculate_complexity']
+      allowedTools: ['Read', 'Grep', 'custom_tool']
       mcpServers:
         custom_analyzer:
           command: "node"
@@ -37,38 +53,92 @@ steps:
             ANALYSIS_MODE: "deep"
 ```
 
-### Built-in MCP Tools
-
-- analyze_file_structure: Analyzes project organization
-- detect_patterns: Identifies code patterns and anti-patterns
-- calculate_complexity: Computes complexity metrics
-- suggest_improvements: Provides improvement recommendations
-
-### Custom MCP Servers
-
-Create `.mcp.json` in your project root:
-
-```json
-{
-  "mcpServers": {
-    "security_scanner": {
-      "command": "python",
-      "args": ["./tools/security_scanner.py"],
-      "env": {
-        "SCAN_DEPTH": "full"
-      }
-    }
-  }
-}
+### MCP Server Configuration
+
+Each MCP server entry supports:
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `command` | `string` | Yes | The command to spawn the MCP server |
+| `args` | `string[]` | No | Command line arguments |
+| `env` | `object` | No | Environment variables for the server process |
+
+### Subagents
+
+Use the `subagent` option to delegate tasks to specialized agents:
+
+```yaml
+steps:
+  claude_comprehensive:
+    type: claude-code
+    prompt: "Perform a comprehensive code review"
+    claude_code:
+      subagent: "./.claude/agents/code-reviewer.md"
+      maxTurns: 10
 ```
 
-### Environment Setup
+### Hooks
 
-```bash
-# Install Claude Code CLI (required)
-npm install -g @anthropic-ai/claude-code
+Lifecycle hooks allow custom processing at different stages:
+
+```yaml
+steps:
+  claude_with_hooks:
+    type: claude-code
+    prompt: "Review the code"
+    claude_code:
+      hooks:
+        onStart: "echo 'Starting review'"
+        onEnd: "echo 'Review complete'"
+        onError: "./scripts/handle-error.sh"
+```
+
+### Session Reuse
+
+Reuse Claude Code sessions across dependent checks for context continuity:
+
+```yaml
+steps:
+  initial_analysis:
+    type: claude-code
+    prompt: "Analyze the code structure"
+    claude_code:
+      maxTurns: 3
+
+  follow_up:
+    type: claude-code
+    prompt: "Based on the previous analysis, suggest improvements"
+    depends_on: [initial_analysis]
+    reuse_ai_session: true
+```
+
+### Environment Variables
 
-# Set API key (optional - uses local Claude Code if available)
+The provider requires an API key via one of these environment variables:
+
+```bash
+# Option 1: Claude Code specific key
 export CLAUDE_CODE_API_KEY=your-api-key
+
+# Option 2: General Anthropic API key
+export ANTHROPIC_API_KEY=your-api-key
+```
+
+### Required Dependencies
+
+Install the Claude Code SDK:
+
+```bash
+npm install @anthropic/claude-code-sdk @modelcontextprotocol/sdk
 ```
 
+### Complete Example
+
+See [examples/claude-code-config.yaml](../examples/claude-code-config.yaml) for a comprehensive configuration example.
+
+### Related Documentation
+
+- [MCP Support for AI Providers](./mcp.md) - General MCP configuration
+- [AI Configuration](./ai-configuration.md) - Standard AI provider configuration
+- [Configuration](./configuration.md) - General configuration reference
+

package/dist/docs/command-provider.md

@@ -29,12 +29,18 @@ steps:
 | `transform` | string | No | Liquid template to transform output |
 | `transform_js` | string | No | JavaScript expression to transform output (evaluated in sandbox) |
 | `env` | object | No | Environment variables to pass to the command |
-| `timeout` | number | No | Command timeout in seconds (default: 60) |
+| `timeout` | number | No | Command timeout in milliseconds (default: 60000, i.e., 60 seconds) |
 | `depends_on` | array | No | Other checks this depends on |
 | `forEach` | object | No | Run command for each item in a collection |
 | `group` | string | No | Group name for organizing results |
 | `on` | array | No | Events that trigger this check |
+| `if` | string | No | Condition expression - check runs only if true |
+| `fail_if` | string | No | Condition expression - check fails if true |
+| `on_fail` | object | No | Failure routing configuration (retry, goto, run) |
+| `on_success` | object | No | Success routing configuration |
+| `continue_on_failure` | boolean | No | Allow dependents to run even if this step fails |
 | `tags` | array | No | Tags for filtering checks |
+| `output_format` | string | No | Output parsing hint: `"json"` or `"text"` |
 
 ## Auto‑JSON Access (no JSON.parse needed)
 
@@ -304,26 +310,26 @@ steps:
 
 ### Timeout Configuration
 
-Configure longer timeouts for commands that take more time:
+Configure longer timeouts for commands that take more time. Timeout is specified in milliseconds:
 
 ```yaml
 steps:
   build-project:
     type: command
     exec: "npm run build"
-    timeout: 300  # 5 minutes
+    timeout: 300000  # 5 minutes (300,000 ms)
     group: build
 
   quick-lint:
     type: command
     exec: "eslint src/"
-    timeout: 30   # 30 seconds
+    timeout: 30000   # 30 seconds (30,000 ms)
     group: quality
 
   long-test-suite:
     type: command
     exec: "npm run test:e2e"
-    timeout: 600  # 10 minutes
+    timeout: 600000  # 10 minutes (600,000 ms)
     group: testing
 ```
 
@@ -337,7 +343,7 @@ steps:
   outdated-deps:
     type: command
     exec: "npm outdated --json || true"
-    timeout: 120  # 2 minutes for npm operations
+    timeout: 120000  # 2 minutes (120,000 ms) for npm operations
     group: dependencies
     tags: [dependencies, maintenance]
 
@@ -351,7 +357,7 @@ steps:
         echo '{"vulnerabilities": {}}'
       fi
     depends_on: [outdated-deps]
-    timeout: 180  # 3 minutes for audit
+    timeout: 180000  # 3 minutes (180,000 ms) for audit
     transform: |
       {
         "critical": {{ output.metadata.vulnerabilities.critical | default: 0 }},
@@ -366,12 +372,12 @@ steps:
 
 The command provider handles errors gracefully:
 
-1. **Command failures** - Non-zero exit codes are captured as errors
-2. **Timeout** - Commands timeout after 60 seconds by default
+1. **Command failures** - Non-zero exit codes are captured as errors (`ruleId: command/execution_error`)
+2. **Timeout** - Commands timeout after 60 seconds (60000ms) by default (`ruleId: command/timeout`)
 3. **Buffer limits** - Output is limited to 10MB
-4. **Transform errors** - Invalid transforms are reported as issues
+4. **Transform errors** - Invalid Liquid or JavaScript transforms are reported as issues (`ruleId: command/transform_error` or `command/transform_js_error`)
 
-Example error output:
+Example error output for execution failure:
 ```json
 {
   "issues": [
@@ -387,6 +393,22 @@ Example error output:
 }
 ```
 
+Example error output for timeout:
+```json
+{
+  "issues": [
+    {
+      "file": "command",
+      "line": 0,
+      "ruleId": "command/timeout",
+      "message": "Command execution timed out after 60000 milliseconds",
+      "severity": "error",
+      "category": "logic"
+    }
+  ]
+}
+```
+
 ## Security Considerations
 
 ### ⚠️ CRITICAL: Command Injection Prevention
@@ -480,7 +502,7 @@ steps:
 
 3. **Secrets Management**:
    ```yaml
-   checks:
+   steps:
      # BAD - Don't echo secrets
      bad-secret:
        type: command
@@ -494,7 +516,7 @@ steps:
 
 4. **File System Access** - Commands run with the same permissions as the visor process:
    ```yaml
-   checks:
+   steps:
      # Be careful with file operations
      file-check:
        type: command
@@ -508,7 +530,7 @@ steps:
          cat "$FILE"
    ```
 
-5. **Timeout Protection** - Commands timeout after 60 seconds by default (configurable via `timeout` field)
+5. **Timeout Protection** - Commands timeout after 60000 milliseconds (60 seconds) by default (configurable via `timeout` field in milliseconds)
 6. **Output Limits** - Command output is limited to 10MB to prevent memory exhaustion
 
 ## Integration with Other Providers
@@ -556,4 +578,4 @@ steps:
 
 ## Comparison with Script Provider
 
-Note: There is no "script" provider. The `command` provider is used for executing shell commands. If you see references to a "script" type in error messages or old documentation, use `type: command` instead.
+The `script` provider executes JavaScript in a secure sandbox, while the `command` provider executes shell commands. Use `command` for running external tools and shell commands; use `script` for JavaScript logic with direct access to PR context, outputs, and memory helpers. See [Script Provider](./script.md) for details.