@probelabs/visor 0.1.107 → 0.1.112

package/dist/examples/ai-custom-tools-example.yaml

@@ -0,0 +1,206 @@
+version: "1.0"
+
+# Example: Using Custom Tools with AI Checks
+# This demonstrates how to expose custom shell-based tools to AI via ephemeral SSE MCP servers
+
+# Define custom tools that AI can use
+tools:
+  # Tool 1: Search for patterns in code
+  grep-pattern:
+    name: grep-pattern
+    description: Search for specific patterns in TypeScript files
+    inputSchema:
+      type: object
+      properties:
+        pattern:
+          type: string
+          description: The pattern to search for (regex supported)
+        files:
+          type: string
+          description: File glob pattern (default is *.ts)
+      required: [pattern]
+    exec: |
+      grep -rn "{{ args.pattern }}" {{ args.files | default: "*.ts" }} 2>/dev/null || echo "No matches found"
+    parseJson: false
+    timeout: 5000
+
+  # Tool 2: Count TODO comments
+  count-todos:
+    name: count-todos
+    description: Count TODO, FIXME, and HACK comments in the codebase
+    inputSchema:
+      type: object
+      properties:
+        directory:
+          type: string
+          description: Directory to search (default is src/)
+      required: []
+    exec: |
+      echo "TODO: $(grep -r "TODO" {{ args.directory | default: "src/" }} 2>/dev/null | wc -l | tr -d ' ')"
+      echo "FIXME: $(grep -r "FIXME" {{ args.directory | default: "src/" }} 2>/dev/null | wc -l | tr -d ' ')"
+      echo "HACK: $(grep -r "HACK" {{ args.directory | default: "src/" }} 2>/dev/null | wc -l | tr -d ' ')"
+    parseJson: false
+    timeout: 10000
+
+  # Tool 3: Check for security issues
+  check-secrets:
+    name: check-secrets
+    description: Scan for potential hardcoded secrets and API keys
+    inputSchema:
+      type: object
+      properties:
+        file:
+          type: string
+          description: Specific file to check (optional)
+      required: []
+    exec: |
+      FILES="{{ args.file | default: '.' }}"
+      echo "Scanning for potential secrets in: $FILES"
+      grep -rn -E "(api[_-]?key|secret|password|token)\s*[:=]" $FILES 2>/dev/null | head -20 || echo "No obvious secrets found"
+    parseJson: false
+    timeout: 10000
+
+  # Tool 4: List recent git changes
+  git-recent-changes:
+    name: git-recent-changes
+    description: Get list of recently changed files
+    inputSchema:
+      type: object
+      properties:
+        count:
+          type: number
+          description: Number of commits to look back (default is 5)
+      required: []
+    exec: |
+      git log -{{ args.count | default: 5 }} --name-only --pretty=format:"Commit: %h - %s" 2>/dev/null || echo "Not a git repository"
+    parseJson: false
+    timeout: 5000
+
+  # Tool 5: Get file stats
+  file-stats:
+    name: file-stats
+    description: Get statistics about a specific file
+    inputSchema:
+      type: object
+      properties:
+        filename:
+          type: string
+          description: The file to analyze
+      required: [filename]
+    exec: |
+      if [ -f "{{ args.filename }}" ]; then
+        echo "File: {{ args.filename }}"
+        echo "Lines: $(wc -l < "{{ args.filename }}" | tr -d ' ')"
+        echo "Size: $(wc -c < "{{ args.filename }}" | tr -d ' ') bytes"
+        echo "Last modified: $(stat -f "%Sm" "{{ args.filename }}" 2>/dev/null || stat -c "%y" "{{ args.filename }}" 2>/dev/null)"
+      else
+        echo "Error: File not found - {{ args.filename }}"
+      fi
+    parseJson: false
+    timeout: 3000
+
+# Define AI checks that use these custom tools
+steps:
+  # Check 1: Security review using custom tools
+  security-scan:
+    type: ai
+    prompt: |
+      You are a security-focused code reviewer. You have access to specialized tools.
+
+      Your mission:
+      1. Use the 'check-secrets' tool to scan for hardcoded secrets
+      2. Use the 'grep-pattern' tool to find unsafe function calls like eval(), exec(), or system()
+      3. Report any security issues you find
+
+      Provide a security assessment with severity levels (critical, high, medium, low).
+    ai_custom_tools:
+      - check-secrets
+      - grep-pattern
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+      debug: true
+    on:
+      - manual
+
+  # Check 2: Code quality review using custom tools
+  code-quality:
+    type: ai
+    prompt: |
+      You are a code quality reviewer. You have specialized analysis tools.
+
+      Tasks:
+      1. Use 'count-todos' to get an overview of pending work
+      2. Use 'git-recent-changes' to understand recent activity
+      3. Use 'grep-pattern' to find console.log statements that should be removed
+
+      Provide recommendations for improving code quality.
+    ai_custom_tools:
+      - count-todos
+      - git-recent-changes
+      - grep-pattern
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+    on:
+      - manual
+
+  # Check 3: File-specific analysis
+  analyze-file:
+    type: ai
+    prompt: |
+      You are analyzing a specific file in the codebase.
+
+      Use the 'file-stats' tool to get information about: src/index.ts
+      Then use 'grep-pattern' to find all exported functions in that file.
+
+      Provide a summary of what this file does based on your analysis.
+    ai_custom_tools:
+      - file-stats
+      - grep-pattern
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+    on:
+      - manual
+
+  # Check 4: Comprehensive review combining custom tools and MCP servers
+  comprehensive-review:
+    type: ai
+    prompt: |
+      You are performing a comprehensive code review with access to multiple tools.
+
+      Custom tools available:
+      - check-secrets: Scan for hardcoded secrets
+      - count-todos: Count pending work items
+      - grep-pattern: Search for patterns
+      - git-recent-changes: See recent commits
+      - file-stats: Get file information
+
+      Use these tools strategically to provide a thorough review of the codebase.
+      Focus on security, code quality, and technical debt.
+    ai_custom_tools:
+      - check-secrets
+      - count-todos
+      - grep-pattern
+      - git-recent-changes
+      - file-stats
+    ai_mcp_servers:
+      # You can combine custom tools with external MCP servers
+      filesystem:
+        command: npx
+        args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+      debug: true
+    on:
+      - manual
+
+# Output configuration
+output:
+  pr_comment:
+    enabled: true
+    format: markdown
+    group_by: check
+    collapse: false

package/dist/examples/ai-custom-tools-simple.yaml

@@ -0,0 +1,76 @@
+version: "1.0"
+
+# Example: Using Custom Tools with AI (Reusing ai_mcp_servers)
+# This shows the PREFERRED way to expose custom tools - no new config section needed!
+
+# Define custom tools
+tools:
+  grep-pattern:
+    name: grep-pattern
+    description: Search for specific patterns in TypeScript files
+    inputSchema:
+      type: object
+      properties:
+        pattern:
+          type: string
+          description: The pattern to search for (regex supported)
+      required: [pattern]
+    exec: 'grep -rn "{{ args.pattern }}" *.ts 2>/dev/null || echo "No matches"'
+    parseJson: false
+
+  check-secrets:
+    name: check-secrets
+    description: Scan for hardcoded secrets and API keys
+    inputSchema:
+      type: object
+      properties: {}
+    exec: |
+      grep -rn -E "(api[_-]?key|secret|password|token)\s*[:=]" . 2>/dev/null | head -10 || echo "No secrets found"
+    parseJson: false
+
+  count-todos:
+    name: count-todos
+    description: Count TODO comments in the codebase
+    inputSchema:
+      type: object
+      properties: {}
+    exec: 'grep -r "TODO" src/ 2>/dev/null | wc -l'
+    parseJson: false
+
+steps:
+  # PREFERRED: Use "tools:" in ai_mcp_servers
+  security-review:
+    type: ai
+    prompt: |
+      You have access to custom security scanning tools.
+      Use check-secrets to scan for hardcoded credentials.
+      Use grep-pattern to find dangerous function calls.
+    ai_mcp_servers:
+      # Use "tools:" to reference custom tools - they'll be served via ephemeral SSE!
+      custom-tools:
+        tools: [check-secrets, grep-pattern]  # ← Magic happens here!
+      # You can still combine with external MCP servers
+      filesystem:
+        command: npx
+        args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+      debug: true
+
+  # ALSO WORKS: Legacy ai_custom_tools format (for backward compatibility)
+  code-quality:
+    type: ai
+    prompt: |
+      Use count-todos to analyze pending work items.
+    ai_custom_tools: [count-todos]  # ← Also works, but ai_mcp_servers is preferred
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+
+output:
+  pr_comment:
+    enabled: true
+    format: markdown
+    group_by: check
+    collapse: false

package/dist/examples/git-checkout-basic.yaml

@@ -0,0 +1,32 @@
+# Basic Git Checkout Example
+#
+# This example demonstrates a simple workflow that:
+# 1. Checks out the PR head branch
+# 2. Runs tests
+# 3. Builds the project
+
+version: "1.0"
+
+steps:
+  # Checkout the PR head branch
+  checkout:
+    type: git-checkout
+    ref: "{{ pr.head }}"
+    criticality: internal
+
+  # Run tests on the checked out code
+  test:
+    type: command
+    depends_on: [checkout]
+    exec: npm test
+    working_directory: "{{ outputs.checkout.path }}"
+    assume: "outputs.checkout.success"
+    criticality: internal
+
+  # Build the project
+  build:
+    type: command
+    depends_on: [test]
+    exec: npm run build
+    working_directory: "{{ outputs.checkout.path }}"
+    criticality: internal

package/dist/examples/git-checkout-compare.yaml

@@ -0,0 +1,59 @@
+# Git Checkout Compare Example
+#
+# This example demonstrates checking out multiple branches
+# and comparing them.
+
+version: "1.0"
+
+# Configure worktree cache
+worktree_cache:
+  enabled: true
+  base_path: /tmp/visor-compare
+  cleanup_on_exit: true
+
+steps:
+  # Checkout PR head branch
+  checkout-head:
+    type: git-checkout
+    ref: "{{ pr.head }}"
+    criticality: internal
+
+  # Checkout PR base branch
+  checkout-base:
+    type: git-checkout
+    ref: "{{ pr.base }}"
+    criticality: internal
+
+  # Run tests on head branch
+  test-head:
+    type: command
+    depends_on: [checkout-head]
+    exec: npm test
+    working_directory: "{{ outputs['checkout-head'].path }}"
+    continue_on_failure: true
+    criticality: internal
+
+  # Run tests on base branch
+  test-base:
+    type: command
+    depends_on: [checkout-base]
+    exec: npm test
+    working_directory: "{{ outputs['checkout-base'].path }}"
+    continue_on_failure: true
+    criticality: internal
+
+  # Compare results
+  compare:
+    type: command
+    depends_on: [test-head, test-base]
+    exec: |
+      echo "=== Comparison Results ==="
+      echo "Head branch: {{ pr.head }} ({{ outputs['checkout-head'].commit }})"
+      echo "Base branch: {{ pr.base }} ({{ outputs['checkout-base'].commit }})"
+      echo ""
+      echo "Head tests: {{ outputs['test-head'].exitCode == 0 ? 'PASSED' : 'FAILED' }}"
+      echo "Base tests: {{ outputs['test-base'].exitCode == 0 ? 'PASSED' : 'FAILED' }}"
+      echo ""
+      echo "File differences:"
+      diff -r "{{ outputs['checkout-head'].path }}/src" "{{ outputs['checkout-base'].path }}/src" || true
+    criticality: info

package/dist/examples/git-checkout-cross-repo.yaml

@@ -0,0 +1,76 @@
+# Cross-Repository Checkout Example
+#
+# This example demonstrates checking out multiple repositories
+# and running integration tests.
+
+version: "1.0"
+
+steps:
+  # Checkout main application repository
+  checkout-app:
+    type: git-checkout
+    repository: myorg/main-app
+    ref: "{{ pr.head }}"
+    token: "{{ env.GITHUB_TOKEN }}"
+    criticality: internal
+
+  # Checkout shared library repository
+  checkout-lib:
+    type: git-checkout
+    repository: myorg/shared-lib
+    ref: main
+    token: "{{ env.GITHUB_TOKEN }}"
+    criticality: internal
+
+  # Checkout test utilities repository
+  checkout-test-utils:
+    type: git-checkout
+    repository: myorg/test-utils
+    ref: v2.0.0
+    token: "{{ env.GITHUB_TOKEN }}"
+    criticality: internal
+
+  # Install dependencies in all repositories
+  install-deps:
+    type: command
+    depends_on: [checkout-app, checkout-lib, checkout-test-utils]
+    exec: |
+      echo "Installing dependencies for main app..."
+      cd "{{ outputs['checkout-app'].path }}" && npm install
+
+      echo "Installing dependencies for shared lib..."
+      cd "{{ outputs['checkout-lib'].path }}" && npm install
+
+      echo "Installing dependencies for test utils..."
+      cd "{{ outputs['checkout-test-utils'].path }}" && npm install
+    criticality: internal
+
+  # Run integration tests
+  integration-test:
+    type: command
+    depends_on: [install-deps]
+    exec: |
+      export LIB_PATH="{{ outputs['checkout-lib'].path }}"
+      export TEST_UTILS_PATH="{{ outputs['checkout-test-utils'].path }}"
+      npm run test:integration
+    working_directory: "{{ outputs['checkout-app'].path }}"
+    criticality: internal
+
+  # Generate integration report
+  report:
+    type: command
+    depends_on: [integration-test]
+    exec: |
+      cat << EOF
+      # Integration Test Report
+
+      ## Repositories Tested
+      - **Main App**: {{ outputs['checkout-app'].repository }}@{{ outputs['checkout-app'].commit }}
+      - **Shared Lib**: {{ outputs['checkout-lib'].repository }}@{{ outputs['checkout-lib'].commit }}
+      - **Test Utils**: {{ outputs['checkout-test-utils'].repository }}@{{ outputs['checkout-test-utils'].commit }}
+
+      ## Test Results
+      Exit Code: {{ outputs['integration-test'].exitCode }}
+      Status: {{ outputs['integration-test'].exitCode == 0 ? 'PASSED ✅' : 'FAILED ❌' }}
+      EOF
+    criticality: info

package/dist/examples/on-init-import-demo.yaml

@@ -0,0 +1,179 @@
+version: "1.0"
+
+# Example: Using Imported Reusable Tools and Workflows with on_init
+# This demonstrates how to import tools and workflows from separate files
+# and use them multiple times in on_init hooks.
+#
+# NOTE: In production, you would use extends to import from separate files:
+#
+# extends:
+#   - ./reusable-tools.yaml
+#   - ./reusable-workflows.yaml
+#
+# For test compatibility, tools and workflows are shown inline below (commented out).
+
+# NOTE: Reusable tools would be imported from reusable-tools.yaml
+# In production, those tools would be available after extends.
+# tools:
+#   fetch-jira-issue:
+#     exec: |
+#       echo '{"key":"PROJ-456","summary":"Example issue",...}'
+#     parseJson: true
+#   fetch-external-data:
+#     exec: |
+#       case {{ args.source }} in
+#         user-db) echo '{"source":"user-db","data":{"count":2}}' ;;
+#         metrics-api) echo '{"source":"metrics-api","data":{"cpu":45}}' ;;
+#       esac
+#     parseJson: true
+
+# NOTE: Reusable workflows would be imported from reusable-workflows.yaml
+# workflows:
+#   data-enrichment:
+#     steps:
+#       - id: fetch-primary
+#         exec: echo '{"primary":"data"}'
+#       - id: merge-results
+#         exec: echo '{"enriched":true}'
+#     output_mapping:
+#       enriched_data: "{{ outputs['merge-results'] }}"
+
+steps:
+  # Example 1: Use multiple imported tools in on_init
+  # In production: Uses fetch-jira-issue and fetch-external-data from reusable-tools.yaml
+  multi-tool-preprocessing:
+    type: command
+    on_init:
+      run:
+        - tool: fetch-jira-issue
+          with:
+            issue_key: PROJ-456
+          as: jira-data
+        - tool: fetch-external-data
+          with:
+            source: user-db
+          as: user-data
+        - tool: fetch-external-data
+          with:
+            source: metrics-api
+          as: metrics-data
+    exec: |
+      echo "JIRA: {{ outputs['jira-data'].summary }}"
+      echo "Users: {{ outputs['user-data'].data.count }}"
+      echo "Metrics: {{ outputs['metrics-data'].data.cpu }}%"
+
+  # Example 2: Use imported workflow in on_init
+  # In production: Uses data-enrichment workflow from reusable-workflows.yaml
+  workflow-preprocessing:
+    type: command
+    on_init:
+      run:
+        - workflow: data-enrichment
+          as: enriched
+    exec: |
+      echo "Enriched: {{ outputs.enriched.enriched_data.enriched }}"
+
+  # Example 3: Chain imported tools and workflows
+  # In production: Uses tools and workflows from imported files
+  chain-tools-and-workflows:
+    type: command
+    on_init:
+      run:
+        - tool: fetch-external-data
+          with:
+            source: config-service
+          as: config
+        - workflow: multi-step-validation
+          as: validation
+        - tool: validate-data
+          with:
+            data: "{{ outputs.config.data }}"
+          as: final-check
+    exec: |
+      echo "Config: {{ outputs.config.data.version }}"
+      echo "Validation: {{ outputs.validation.validation_result.status }}"
+      echo "Final: {{ outputs['final-check'].valid }}"
+
+  # Example 4: Use same tool multiple times with different parameters
+  # Demonstrates tool reusability across multiple invocations
+  repeated-tool-usage:
+    type: command
+    on_init:
+      run:
+        - tool: fetch-external-data
+          with:
+            source: user-db
+          as: users
+        - tool: fetch-external-data
+          with:
+            source: config-service
+          as: config
+        - tool: fetch-external-data
+          with:
+            source: metrics-api
+          as: metrics
+    exec: |
+      echo "Fetched from 3 sources:"
+      echo "- {{ outputs.users.source }}: {{ outputs.users.data.count }} users"
+      echo "- {{ outputs.config.source }}: version {{ outputs.config.data.version }}"
+      echo "- {{ outputs.metrics.source }}: {{ outputs.metrics.data.cpu }}% CPU"
+
+tests:
+  defaults:
+    strict: false
+    fail_on_unexpected_calls: false
+  fixtures: []
+  cases:
+    - name: multi-tool-preprocessing-test
+      description: Test using multiple imported tools in on_init
+      event: manual
+      fixture: gh.pr_open.minimal
+      mocks:
+        multi-tool-preprocessing: |
+          JIRA: Example issue
+          Users: 2
+          Metrics: 45%
+      expect:
+        calls:
+          - step: multi-tool-preprocessing
+            exactly: 1
+
+    - name: workflow-preprocessing-test
+      description: Test using imported workflow in on_init
+      event: manual
+      fixture: gh.pr_open.minimal
+      mocks:
+        workflow-preprocessing: "Enriched: true"
+      expect:
+        calls:
+          - step: workflow-preprocessing
+            exactly: 1
+
+    - name: chain-tools-workflows-test
+      description: Test chaining imported tools and workflows
+      event: manual
+      fixture: gh.pr_open.minimal
+      mocks:
+        chain-tools-and-workflows: |
+          Config: 1.2.3
+          Validation: approved
+          Final: true
+      expect:
+        calls:
+          - step: chain-tools-and-workflows
+            exactly: 1
+
+    - name: repeated-tool-test
+      description: Test using same tool multiple times
+      event: manual
+      fixture: gh.pr_open.minimal
+      mocks:
+        repeated-tool-usage: |
+          Fetched from 3 sources:
+          - user-db: 2 users
+          - config-service: version 1.2.3
+          - metrics-api: 45% CPU
+      expect:
+        calls:
+          - step: repeated-tool-usage
+            exactly: 1