@probelabs/visor 0.1.106 → 0.1.107

package/dist/docs/configuration.md

@@ -0,0 +1,303 @@
+## ⚙️ Configuration & Extends
+
+Use `.visor.yaml` to add/override workflow steps in your repo and extend shared configurations. Visor's merge logic makes it flexible for teams and orgs.
+
+> **Note on Terminology**: Visor now uses `steps:` instead of `checks:` in configuration files to better reflect its workflow orchestration capabilities. Both keys work identically for backward compatibility, but `steps:` is recommended for new configurations.
+
+### Validating Configuration
+
+Before running checks, validate your configuration file to catch errors early:
+
+```bash
+# Validate default config location (.visor.yaml)
+visor validate
+
+# Validate specific config file
+visor validate --config .visor.yaml
+
+# Validate example configs
+visor validate --config examples/enhanced-config.yaml
+```
+
+The `validate` command checks for:
+- **Missing required fields** (e.g., `version`)
+- **Invalid check types** (must be: `ai`, `claude-code`, `command`, `http`, `http_input`, `http_client`, `noop`, `log`, `github`)
+- **Invalid event triggers** (e.g., `scheduled` should be `schedule`)
+- **Incorrect field names** and typos
+- **Schema compliance** for all configuration options
+
+Example validation output:
+```
+🔍 Visor Configuration Validator
+
+📂 Validating configuration: .visor.yaml
+
+✅ Configuration is valid!
+
+📋 Summary:
+   Version: 1.0
+   Checks: 5
+
+📝 Configured checks:
+   • security (type: ai)
+   • performance (type: ai)
+   • style (type: command)
+   • notify (type: http)
+   • monitor (type: http_input)
+```
+
+If there are errors, you'll get detailed messages with hints:
+```
+❌ Configuration validation failed!
+
+Error: Invalid check type "webhook". Must be: ai, claude-code, command, http, http_input, http_client, noop, log, github
+
+💡 Hint: The 'webhook' type has been renamed to 'http' for output and 'http_input' for input.
+```
+
+### Check-Level AI Configuration
+
+Override global AI settings at the check level:
+
+```yaml
+# Global AI settings (optional)
+ai_provider: anthropic  # or google, openai, bedrock
+ai_model: claude-3-sonnet
+ai_temperature: 0.2
+
+steps:
+  performance-review:
+    type: ai
+    ai:
+      provider: google
+      model: gemini-1.5-pro
+      temperature: 0.1
+    prompt: "Analyze performance metrics and provide optimization suggestions"
+
+  security-review:
+    type: ai
+    ai_provider: bedrock  # Use AWS Bedrock for this step
+    ai_model: anthropic.claude-sonnet-4-20250514-v1:0
+    prompt: "Analyze code for security vulnerabilities"
+```
+
+### Environment Variables
+
+Inject environment variables globally or per-check via `env`:
+
+```yaml
+# Global environment variables
+env:
+  OPENAI_API_KEY: "${{ env.OPENAI_API_KEY }}"
+  ANTHROPIC_API_KEY: "${{ env.ANTHROPIC_API_KEY }}"
+  GOOGLE_API_KEY: "${{ env.GOOGLE_API_KEY }}"
+  # AWS Bedrock credentials
+  AWS_ACCESS_KEY_ID: "${{ env.AWS_ACCESS_KEY_ID }}"
+  AWS_SECRET_ACCESS_KEY: "${{ env.AWS_SECRET_ACCESS_KEY }}"
+  AWS_REGION: "${{ env.AWS_REGION }}"
+  SLACK_WEBHOOK: "${{ env.SLACK_WEBHOOK }}"
+
+steps:
+  custom-notify:
+    type: http
+    url: "https://hooks.slack.com/services/..."
+    method: POST
+    body: |
+      { "text": "Build complete for {{ pr.title }}" }
+    env:
+      SLACK_WEBHOOK: "${{ env.SLACK_WEBHOOK }}"
+
+  custom-ai-step:
+    type: ai
+    ai_provider: anthropic
+    ai_model: claude-3-opus
+    env:
+      ANTHROPIC_API_KEY: "${{ env.ANTHROPIC_API_KEY }}"
+    prompt: |
+      Analyze with Anthropic using env-provided credentials
+```
+
+#### Environment Variable Syntax
+
+- `${{ env.NAME }}` or `${NAME}` reference process env vars
+- Missing variables resolve to empty strings (validated at runtime)
+- Works in both global and per-check `env` blocks
+
+```yaml
+env:
+  NODE_ENV: "${{ env.NODE_ENV }}"
+  FEATURE_FLAGS: "${FEATURE_FLAGS}"
+
+steps:
+  example:
+    type: ai
+    prompt: |
+      Environment: ${{ env.NODE_ENV }}
+      Features: ${{ env.FEATURE_FLAGS }}
+```
+
+### Configuration Inheritance with `extends`
+
+Build on existing configs and share standards:
+
+```yaml
+# .visor.yaml - project config
+extends: ./base-config.yaml  # Single extend
+
+# OR multiple extends (merged left-to-right)
+extends:
+  - default                   # Built-in defaults
+  - ./team-standards.yaml     # Team standards
+  - ./project-specific.yaml   # Project overrides
+
+steps:
+  my-custom-check:
+    type: ai
+    prompt: "Project-specific analysis..."
+```
+
+#### Example: Team Configuration
+
+team-config.yaml
+```yaml
+version: "1.0"
+ai_provider: openai
+ai_model: gpt-4
+
+steps:
+  security-scan:
+    type: ai
+    prompt: "Perform security analysis following OWASP guidelines"
+    on: [pr_opened, pr_updated]
+
+  code-quality:
+    type: ai
+    prompt: "Check code quality and best practices"
+    on: [pr_opened, pr_updated]
+```
+
+project-config.yaml
+```yaml
+extends: ./team-config.yaml
+
+ai_model: gpt-4-turbo  # Override team default
+
+steps:
+  code-quality:
+    on: []  # Disable a check
+
+  performance-check:
+    type: ai
+    prompt: "Analyze performance implications"
+    on: [pr_opened]
+```
+
+#### Remote Configuration (with Security)
+
+Explicitly allow remote URLs for `extends`:
+
+```bash
+visor --check all \
+  --allowed-remote-patterns "https://github.com/myorg/,https://raw.githubusercontent.com/myorg/"
+```
+
+Then reference in config:
+```yaml
+extends: https://raw.githubusercontent.com/myorg/configs/main/base.yaml
+```
+
+#### Security Features
+1. Path traversal protection for local files
+2. URL allowlist for remote configs (empty by default)
+3. Disable remote extends entirely with `--no-remote-extends`
+
+#### Merge Behavior
+- Simple values: child overrides parent
+- Objects: deep merge
+- Arrays: replaced entirely
+- Checks: disable with `on: []`
+
+### Appending to Prompts with `appendPrompt`
+
+```yaml
+extends: ./base-config.yaml
+
+steps:
+  security-review:
+    appendPrompt: "Also check for SQL injection and hardcoded secrets"
+```
+
+Notes:
+- `appendPrompt` is joined with parent `prompt` via double newline
+- If no parent `prompt`, `appendPrompt` becomes the prompt
+- Use `prompt` to replace entirely
+
+### Priority Order
+
+1. Check-level settings (highest)
+2. Current file configuration
+3. Extended configurations (left → right)
+4. Global configuration
+5. Environment variables
+6. Defaults (lowest)
+
+### Production Environment Setup
+
+```bash
+export OPENAI_API_KEY="sk-your-openai-key"
+export ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"
+export GOOGLE_API_KEY="your-google-api-key"
+export GITHUB_TOKEN="ghp_your-github-token"
+export SECURITY_MODEL="claude-3-opus"
+export PERFORMANCE_MODEL="gpt-4-turbo"
+export PREFERRED_AI_PROVIDER="anthropic"
+export ANALYSIS_TIMEOUT="60000"
+```
+
+Reference from config:
+
+```yaml
+env:
+  OPENAI_KEY: "${{ env.OPENAI_API_KEY }}"
+  ANTHROPIC_KEY: "${{ env.ANTHROPIC_API_KEY }}"
+  GITHUB_ACCESS_TOKEN: "${{ env.GITHUB_TOKEN }}"
+
+steps:
+  production-security:
+    type: ai
+    ai_model: "${{ env.SECURITY_MODEL }}"
+    ai_provider: "${{ env.PREFERRED_AI_PROVIDER }}"
+    env:
+      API_KEY: "${{ env.ANTHROPIC_KEY }}"
+      TIMEOUT: "${{ env.ANALYSIS_TIMEOUT }}"
+    prompt: |
+      Production security analysis with ${{ env.ANALYSIS_TIMEOUT }}ms timeout
+```
+
+### Native GitHub Provider
+
+Use `type: github` to perform labels/comments via GitHub API (Octokit). This avoids shelling out to `gh` and supports safe label sanitization.
+
+Keys:
+- `op`: one of `labels.add`, `labels.remove`, `comment.create`.
+- `values`/`value`: string or array to pass to the op (e.g., label names or comment lines). Empty strings are ignored automatically.
+- `value_js` (optional): JavaScript snippet to compute values dynamically. Not required for filtering empties.
+
+Example:
+```yaml
+steps:
+  apply-overview-labels:
+    type: github
+    tags: [github]
+    depends_on: [overview]
+    on: [pr_opened, pr_updated]
+    op: labels.add
+    values:
+      - "{{ outputs.overview.tags.label | default: '' | safe_label }}"
+      - "{{ outputs.overview.tags['review-effort'] | default: '' | prepend: 'review/effort:' | safe_label }}"
+```
+
+Notes:
+- Requires `GITHUB_TOKEN` (or `github-token` Action input) and `GITHUB_REPOSITORY` in environment.
+- Use Liquid `safe_label` / `safe_label_list` to constrain labels to `[A-Za-z0-9:/\- ]` (alphanumerics, colon, slash, hyphen, and space).
+- Provider errors surface as issues (e.g., `github/missing_token`, `github/op_failed`) and won't abort the whole run.

package/dist/docs/custom-tools.md

@@ -0,0 +1,424 @@
+# Custom Tools in YAML Configuration
+
+## Overview
+
+Custom tools allow you to define reusable command-line tools directly in your YAML configuration. These tools can then be used in MCP (Model Context Protocol) blocks throughout your configuration, making it easy to integrate any command-line tool or script into your workflow.
+
+## Features
+
+- **Define tools in YAML**: No need to create separate scripts or programs
+- **Input validation**: Define JSON Schema for tool parameters
+- **Template support**: Use Liquid templates for dynamic command generation
+- **Transform outputs**: Process tool output with Liquid templates or JavaScript
+- **Reusable**: Define once, use multiple times across your configuration
+- **Importable**: Share tools across projects using the `extends` mechanism
+- **Type-safe**: Full TypeScript support with input/output schemas
+- **MCP-compatible**: Tools follow the Model Context Protocol specification
+
+## Basic Tool Definition
+
+```yaml
+tools:
+  my-tool:
+    name: my-tool
+    description: Description of what the tool does
+    exec: 'echo "Hello World"'
+```
+
+## Complete Tool Schema
+
+```yaml
+tools:
+  tool-name:
+    # MCP-compatible fields (these map directly to MCP tool interface)
+    name: tool-name                    # Required: Tool identifier (MCP: name)
+    description: Tool description       # Recommended: Human-readable description (MCP: description)
+
+    # Input schema (JSON Schema format) - MCP: inputSchema
+    # This follows the JSON Schema specification and is used for:
+    # 1. Validating tool inputs before execution
+    # 2. Providing type information to AI models
+    # 3. Auto-generating documentation
+    inputSchema:
+      type: object
+      properties:
+        param1:
+          type: string
+          description: Parameter description  # Describe each parameter for AI models
+        param2:
+          type: number
+          description: Optional parameter
+      required: [param1]                     # List required parameters
+      additionalProperties: false            # Strict mode: reject unknown parameters
+
+    # Custom tool execution fields
+    exec: 'command {{ args.param1 }}'  # Required: Command to execute (supports Liquid)
+    stdin: '{{ args.param2 }}'         # Optional: Data to pipe to stdin (supports Liquid)
+
+    cwd: /path/to/directory            # Optional: Working directory
+    env:                                # Optional: Environment variables
+      MY_VAR: value
+
+    timeout: 30000                      # Optional: Timeout in milliseconds (default: 30000)
+    parseJson: true                     # Optional: Parse output as JSON
+
+    # Transform output with Liquid template
+    transform: '{ "result": {{ output | json }} }'
+
+    # OR transform with JavaScript
+    transform_js: |
+      return {
+        processed: output.trim().toUpperCase()
+      };
+
+    # Output schema for validation (optional) - MCP: outputSchema
+    # Not currently enforced but useful for documentation
+    outputSchema:
+      type: object
+      properties:
+        result:
+          type: string
+          description: The processed result
+```
+
+## MCP Compatibility
+
+Custom tools are designed to be fully compatible with the Model Context Protocol (MCP) specification. When you define a custom tool, it automatically becomes available as an MCP tool with the following mapping:
+
+| Custom Tool Field | MCP Tool Field | Purpose |
+|------------------|----------------|---------|
+| `name` | `name` | Unique identifier for the tool |
+| `description` | `description` | Human-readable description for AI models and documentation |
+| `inputSchema` | `inputSchema` | JSON Schema defining expected parameters |
+| `outputSchema` | `outputSchema` | JSON Schema for output validation (informational) |
+
+### Why MCP Compatibility Matters
+
+1. **AI Model Integration**: Tools with proper descriptions and schemas can be automatically understood and used by AI models
+2. **Type Safety**: Input schemas provide runtime validation and type checking
+3. **Documentation**: Schemas serve as self-documenting interfaces
+4. **Interoperability**: Tools can potentially be used with other MCP-compatible systems
+
+### Best Practices for MCP Compatibility
+
+1. **Always provide descriptions**: Help AI models understand what your tool does
+   ```yaml
+   tools:
+     analyze-code:
+       name: analyze-code
+       description: "Analyzes source code for complexity metrics and potential issues"
+   ```
+
+2. **Use detailed input schemas**: Include descriptions for each parameter
+   ```yaml
+   inputSchema:
+     type: object
+     properties:
+       file:
+         type: string
+         description: "Path to the source code file to analyze"
+       metrics:
+         type: array
+         description: "List of metrics to calculate"
+         items:
+           type: string
+           enum: ["complexity", "lines", "dependencies"]
+     required: ["file"]
+   ```
+
+3. **Consider output schemas**: While not enforced, they document expected outputs
+   ```yaml
+   outputSchema:
+     type: object
+     properties:
+       complexity:
+         type: number
+         description: "Cyclomatic complexity score"
+       issues:
+         type: array
+         description: "List of detected issues"
+   ```
+
+## Using Custom Tools
+
+Once defined, custom tools can be used in any MCP block by setting `transport: custom`:
+
+```yaml
+steps:
+  my-check:
+    type: mcp
+    transport: custom              # Use custom transport
+    method: my-tool                 # Tool name
+    methodArgs:                     # Tool arguments
+      param1: "value1"
+      param2: 42
+```
+
+## Template Context
+
+Tools have access to a rich template context through Liquid templates:
+
+### In `exec` and `stdin`:
+- `{{ args }}` - The arguments passed to the tool
+- `{{ pr }}` - Pull request information (number, title, author, etc.)
+- `{{ files }}` - List of files in the PR
+- `{{ outputs }}` - Outputs from previous checks
+- `{{ env }}` - Environment variables
+
+### In `transform` and `transform_js`:
+- All of the above, plus:
+- `{{ output }}` - The raw command output
+- `{{ stdout }}` - Standard output
+- `{{ stderr }}` - Standard error
+- `{{ exitCode }}` - Command exit code
+
+## Examples
+
+### 1. Simple Grep Tool
+
+```yaml
+tools:
+  grep-todos:
+    name: grep-todos
+    description: Find TODO comments in code
+    inputSchema:
+      type: object
+      properties:
+        pattern:
+          type: string
+        files:
+          type: array
+          items:
+            type: string
+    exec: 'grep -n "{{ args.pattern }}" {{ args.files | join: " " }}'
+```
+
+### 2. JSON Processing Tool
+
+```yaml
+tools:
+  analyze-package:
+    name: analyze-package
+    description: Analyze package.json dependencies
+    inputSchema:
+      type: object
+      properties:
+        file:
+          type: string
+    exec: 'cat {{ args.file }}'
+    parseJson: true
+    transform_js: |
+      const deps = Object.keys(output.dependencies || {});
+      const devDeps = Object.keys(output.devDependencies || {});
+      return {
+        totalDeps: deps.length + devDeps.length,
+        prodDeps: deps.length,
+        devDeps: devDeps.length
+      };
+```
+
+### 3. Multi-Step Tool with Error Handling
+
+```yaml
+tools:
+  build-and-test:
+    name: build-and-test
+    description: Build project and run tests
+    exec: |
+      npm run build && npm test
+    timeout: 300000  # 5 minutes
+    transform_js: |
+      if (exitCode !== 0) {
+        return {
+          success: false,
+          error: stderr || 'Build or tests failed'
+        };
+      }
+      return {
+        success: true,
+        output: output
+      };
+```
+
+### 4. Tool with Dynamic Command Generation
+
+```yaml
+tools:
+  flexible-linter:
+    name: flexible-linter
+    description: Run appropriate linter based on file type
+    inputSchema:
+      type: object
+      properties:
+        file:
+          type: string
+    exec: |
+      {% assign ext = args.file | split: "." | last %}
+      {% case ext %}
+        {% when "js", "ts" %}
+          eslint {{ args.file }}
+        {% when "py" %}
+          pylint {{ args.file }}
+        {% when "go" %}
+          golint {{ args.file }}
+        {% else %}
+          echo "No linter for .{{ ext }} files"
+      {% endcase %}
+```
+
+## Tool Libraries and Extends
+
+### Creating a Tool Library
+
+Create a file with just tool definitions:
+
+```yaml
+# tools-library.yaml
+version: "1.0"
+
+tools:
+  tool1:
+    name: tool1
+    exec: 'command1'
+
+  tool2:
+    name: tool2
+    exec: 'command2'
+```
+
+### Importing Tools
+
+Use the `extends` mechanism to import tools:
+
+```yaml
+version: "1.0"
+extends: ./tools-library.yaml
+
+# Additional tools can be defined here
+tools:
+  local-tool:
+    name: local-tool
+    exec: 'local-command'
+
+# Use both imported and local tools
+steps:
+  check1:
+    type: mcp
+    transport: custom
+    method: tool1  # From tools-library.yaml
+
+  check2:
+    type: mcp
+    transport: custom
+    method: local-tool  # Defined locally
+```
+
+### Multiple Extends
+
+You can import from multiple sources:
+
+```yaml
+extends:
+  - ./base-tools.yaml
+  - ./security-tools.yaml
+  - https://example.com/shared-tools.yaml
+```
+
+Tools are merged with later sources overriding earlier ones.
+
+## Integration with Other Features
+
+### Using with forEach
+
+```yaml
+steps:
+  lint-all-files:
+    type: mcp
+    transport: custom
+    method: my-linter
+    forEach: "{{ files }}"
+    methodArgs:
+      file: "{{ item.filename }}"
+```
+
+### Conditional Execution
+
+```yaml
+steps:
+  optional-check:
+    type: mcp
+    transport: custom
+    method: my-tool
+    if: "files.some(f => f.filename.endsWith('.js'))"
+    methodArgs:
+      target: "src/"
+```
+
+### Chaining with on_success/on_failure
+
+```yaml
+steps:
+  main-check:
+    type: mcp
+    transport: custom
+    method: build-tool
+    on_success:
+      - type: mcp
+        transport: custom
+        method: test-tool
+    on_failure:
+      - type: mcp
+        transport: custom
+        method: cleanup-tool
+```
+
+## Best Practices
+
+1. **Use Input Schemas**: Always define `inputSchema` to validate tool inputs
+2. **Handle Errors**: Use `transform_js` to check exit codes and handle errors
+3. **Set Timeouts**: Configure appropriate timeouts for long-running commands
+4. **Parse JSON**: Use `parseJson: true` for tools that output JSON
+5. **Document Tools**: Provide clear descriptions for each tool
+6. **Create Libraries**: Group related tools in separate YAML files
+7. **Version Control**: Store tool libraries in version control for sharing
+8. **Test Tools**: Test tools independently before using in complex workflows
+
+## Security Considerations
+
+- Tools execute with the same permissions as the Visor process
+- Be cautious with user input in tool commands
+- Use input validation to prevent command injection
+- Avoid exposing sensitive data in tool outputs
+- Consider using environment variables for secrets
+
+## Troubleshooting
+
+### Tool Not Found
+
+If you get "Tool not found" errors:
+1. Ensure the tool is defined in the `tools` section
+2. Check that the tool name matches exactly
+3. Verify extends paths are correct
+
+### Command Failures
+
+For command execution issues:
+1. Test the command manually first
+2. Check working directory (`cwd`) settings
+3. Verify required binaries are installed
+4. Check timeout settings for long operations
+
+### Template Errors
+
+For Liquid template problems:
+1. Validate template syntax
+2. Check that variables exist in context
+3. Use filters correctly (e.g., `| json`, `| join`)
+
+### Transform Errors
+
+For JavaScript transform issues:
+1. Ensure valid JavaScript syntax
+2. Always return a value
+3. Handle undefined/null cases
+4. Use try-catch for error handling