@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/workflows.md

@@ -229,6 +229,19 @@ steps:
     on: [pr_opened, pr_updated]
 ```
 
+### Using Config Path
+
+Alternatively, reference a config file directly instead of a pre-registered workflow:
+
+```yaml
+steps:
+  external_workflow:
+    type: workflow
+    config: ./other-workflow.yaml  # Path to workflow config file
+    args:
+      param1: value1
+```
+
 ### With Output Mapping
 
 Map workflow outputs to check outputs:
@@ -264,6 +277,18 @@ steps:
         ai_model: claude-3-opus-20240229
 ```
 
+### Workflow Step Configuration Reference
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `workflow` | string | Workflow ID from imported workflow (required if not using `config`) |
+| `config` | string | Path to workflow config file (alternative to `workflow`) |
+| `args` | object | Input parameter values to pass to the workflow |
+| `overrides` | object | Override specific step configurations within the workflow |
+| `output_mapping` | object | Map workflow output names to check output names |
+| `timeout` | number | Maximum execution time in milliseconds |
+| `env` | object | Environment variables to set for workflow execution |
+
 ## Advanced Features
 
 ### Conditional Steps
@@ -300,32 +325,45 @@ steps:
 
 ### Workflow Composition
 
-Workflows can use other workflows:
+Workflows can use other workflows. Create a parent workflow file that imports and uses child workflows:
 
 ```yaml
-workflows:
-  comprehensive-check:
-    steps:
-      security:
-        type: workflow
-        workflow: security-scan
-        workflow_inputs:
-          severity_threshold: "{{ inputs.security_level }}"
-
-      quality:
-        type: workflow
-        workflow: code-quality
-        workflow_inputs:
-          language: "{{ inputs.language }}"
-
-      aggregate:
-        type: script
-        content: |
-          return {
-            passed: steps.security.output.passed && steps.quality.output.passed,
-            score: (steps.security.output.score + steps.quality.output.score) / 2
-          };
-        depends_on: [security, quality]
+# comprehensive-check.yaml
+id: comprehensive-check
+name: Comprehensive Check
+version: "1.0"
+
+inputs:
+  - name: security_level
+    schema:
+      type: string
+    default: medium
+  - name: language
+    schema:
+      type: string
+    required: true
+
+steps:
+  security:
+    type: workflow
+    workflow: security-scan
+    args:
+      severity_threshold: "{{ inputs.security_level }}"
+
+  quality:
+    type: workflow
+    workflow: code-quality
+    args:
+      language: "{{ inputs.language }}"
+
+  aggregate:
+    type: script
+    content: |
+      return {
+        passed: outputs['security'].passed && outputs['quality'].passed,
+        score: (outputs['security'].score + outputs['quality'].score) / 2
+      };
+    depends_on: [security, quality]
 ```
 
 ## Examples
@@ -470,7 +508,38 @@ examples:
 
 ### 6. Test Your Workflows
 
-Create test configurations to validate workflows:
+You can include inline tests in workflow files that are automatically stripped when the workflow is imported:
+
+```yaml
+# my-workflow.yaml
+id: my-workflow
+name: My Workflow
+version: "1.0"
+
+inputs:
+  - name: test_param
+    schema:
+      type: string
+
+steps:
+  process:
+    type: script
+    content: |
+      return { result: inputs.test_param, score: 85 };
+
+# Inline tests - NOT imported when used as component
+tests:
+  basic-test:
+    type: script
+    content: |
+      const output = outputs['process'];
+      if (output.result !== "test_value") throw new Error("Result mismatch");
+      if (output.score < 0 || output.score > 100) throw new Error("Score out of range");
+      return { passed: true };
+    depends_on: [process]
+```
+
+Alternatively, create a separate test config:
 
 ```yaml
 # test-workflow.yaml
@@ -478,15 +547,16 @@ steps:
   test_workflow:
     type: workflow
     workflow: my-workflow
-    workflow_inputs:
+    args:
       test_param: "test_value"
 
   validate_output:
     type: script
     content: |
-      const output = outputs.test_workflow;
-      assert(output.result !== undefined, "Result is required");
-      assert(output.score >= 0 && output.score <= 100, "Score out of range");
+      const output = outputs['test_workflow'];
+      if (output.result === undefined) throw new Error("Result is required");
+      if (output.score < 0 || output.score > 100) throw new Error("Score out of range");
+      return { valid: true };
     depends_on: [test_workflow]
 ```
 
@@ -496,22 +566,22 @@ Complete workflow schema:
 
 ```typescript
 interface WorkflowDefinition {
-  id: string;                    // Unique identifier
-  name: string;                   // Display name
-  description?: string;           // Description
+  id: string;                    // Unique identifier (required)
+  name: string;                  // Display name (required)
+  description?: string;          // Description
   version?: string;              // Semantic version
   tags?: string[];               // Categorization tags
   category?: string;             // Category (security, quality, etc.)
 
   inputs?: WorkflowInputParam[]; // Input parameters
   outputs?: WorkflowOutputParam[]; // Output parameters
-  steps: Record<string, WorkflowStep>; // Workflow steps
+  steps: Record<string, WorkflowStep>; // Workflow steps (required)
 
-  on?: EventTrigger[];          // Events that can trigger this workflow
+  on?: EventTrigger[];           // Events that can trigger this workflow
   defaults?: Partial<CheckConfig>; // Default config for steps
-  reusable?: boolean;            // Can be used as component
+  tests?: Record<string, CheckConfig>; // Inline tests (NOT imported when used as component)
 
-  author?: {                    // Author information
+  author?: {                     // Author information
     name?: string;
     email?: string;
     url?: string;
@@ -522,6 +592,8 @@ interface WorkflowDefinition {
 }
 ```
 
+**Note:** The `tests` field allows you to include inline test cases in a workflow file. When the workflow is imported via `imports`, the tests are stripped out and NOT executed. Tests only run when the workflow file is executed directly or via `visor test`.
+
 ## Integration with CI/CD
 
 Workflows integrate seamlessly with GitHub Actions:
@@ -540,19 +612,36 @@ jobs:
         uses: your-org/visor-action@v1
         with:
           config: .visor.yaml
-          workflow_imports: |
-            ./workflows/*.yaml
-            https://workflows.example.com/shared/*.yaml
+```
+
+In your `.visor.yaml`, use the `imports` field to include workflow files:
+
+```yaml
+# .visor.yaml
+version: "1.0"
+
+# Import workflow definitions
+imports:
+  - ./workflows/*.yaml
+  - https://workflows.example.com/shared/security.yaml
+
+steps:
+  run-security:
+    type: workflow
+    workflow: security-scan
+    args:
+      level: high
 ```
 
 ## Troubleshooting
 
 ### Common Issues
 
-1. **Workflow not found**: Ensure the workflow is registered via `workflows` or `workflow_imports`
+1. **Workflow not found**: Ensure the workflow is imported via the `imports` field in your config, or use the `config` property to reference the file path directly
 2. **Input validation failed**: Check that inputs match the defined schema
 3. **Circular dependencies**: Ensure workflow steps don't have circular `depends_on`
 4. **Output computation error**: Verify JavaScript expressions and Liquid templates are valid
+5. **Tests running unexpectedly**: When importing workflows, `tests` blocks are automatically stripped; if tests are running, check if you're executing the workflow file directly
 
 ### Debug Mode
 
@@ -566,4 +655,12 @@ This will show:
 - Workflow registration details
 - Input validation results
 - Step execution order
-- Output computation values
+- Output computation values
+
+## See Also
+
+- [Workflow Creation Guide](workflow-creation-guide.md) - Comprehensive guide with all check types and patterns
+- [Configuration](configuration.md) - Main configuration reference
+- [Event Triggers](event-triggers.md) - Configuring when workflows run
+- [Liquid Templates](liquid-templates.md) - Template syntax for dynamic values
+- [Debugging](debugging.md) - Debugging techniques for workflows

package/dist/examples/README.md

@@ -63,10 +63,83 @@ Example configurations demonstrating various Visor features and use cases.
 ### Basic Examples
 - **`quick-start-tags.yaml`** - Simple configuration showing basic tag usage
 - **`visor-with-tags.yaml`** - Comprehensive configuration with all tag features
- - **`routing-basic.yaml`** - Failure routing with retry + goto ancestor
- - **`routing-on-success.yaml`** - on_success post-steps + single jump-back
- - **`routing-foreach.yaml`** - forEach remediation with run + retry
- - **`routing-dynamic-js.yaml`** - Dynamic routing via goto_js/run_js
+- **`enhanced-config.yaml`** - Enhanced configuration with advanced features
+
+### Routing Examples
+- **`routing-basic.yaml`** - Failure routing with retry + goto ancestor
+- **`routing-on-success.yaml`** - on_success post-steps + single jump-back
+- **`routing-foreach.yaml`** - forEach remediation with run + retry
+- **`routing-dynamic-js.yaml`** - Dynamic routing via goto_js/run_js
+- **`routing-goto-event.yaml`** - Goto routing with event handling
+
+### Control Flow Examples
+- **`if-conditions.yaml`** - Conditional execution with if statements
+- **`for-loop-example.yaml`** - Loop iteration patterns
+- **`forEach-example.yaml`** - ForEach iteration over collections
+- **`transform-example.yaml`** - Data transformation between steps
+
+### AI Provider Examples
+- **`ai-custom-tools-example.yaml`** - AI with custom shell-based tools via ephemeral MCP servers
+- **`ai-custom-tools-simple.yaml`** - Simplified AI custom tools example
+- **`ai-retry-fallback-config.yaml`** - AI with retry and fallback providers
+- **`ai-with-bash.yaml`** - AI check combined with bash command execution
+- **`ai-with-mcp.yaml`** - AI check with MCP tool integration
+- **`bedrock-config.yaml`** - AWS Bedrock AI provider configuration
+- **`claude-code-config.yaml`** - Claude Code SDK integration with MCP tools
+- **`fact-validator.yaml`** - AI-based fact validation workflow
+
+### MCP & Tools Examples
+- **`mcp-provider-example.yaml`** - MCP provider with stdio/SSE/HTTP transports
+- **`custom-tools-example.yaml`** - Custom tool definitions
+- **`tools-library.yaml`** - Reusable tool library (git, docker, npm, testing, code quality tools)
+- **`reusable-tools.yaml`** - Patterns for reusable tool definitions
+- **`project-with-tools.yaml`** - Project configuration with integrated tools
+
+### Memory & State Examples
+- **`memory-counter.yaml`** - Basic memory counter implementation
+- **`memory-error-collection.yaml`** - Collecting errors in memory across steps
+- **`memory-exec-js.yaml`** - JavaScript execution within memory provider
+- **`memory-namespace-isolation.yaml`** - Memory namespace isolation between workflows
+- **`memory-retry-counter.yaml`** - Retry logic with memory-based counter tracking
+- **`memory-state-machine.yaml`** - State machine implementation using memory
+
+### Human Input Examples
+- **`human-input-example.yaml`** - Interactive human-in-the-loop patterns
+- **`basic-human-input.yaml`** - Basic human input workflow
+- **`calculator-config.yaml`** - Interactive calculator with memory and validation
+
+### HTTP & Webhooks Examples
+- **`http-integration-config.yaml`** - HTTP API integration patterns
+- **`https-server-config.yaml`** - HTTPS server configuration
+- **`webhook-pipeline-config.yaml`** - Multi-pipeline webhook system (GitHub, JIRA integration)
+- **`cron-webhook-config.yaml`** - Scheduled cron triggers with webhooks
+
+### Git Operations Examples
+- **`git-checkout-basic.yaml`** - Basic git checkout operations
+- **`git-checkout-compare.yaml`** - Git checkout with comparison workflows
+- **`git-checkout-cross-repo.yaml`** - Cross-repository git operations
+
+### Failure Handling Examples
+- **`fail-if-simple.yaml`** - Simple fail_if conditions
+- **`failure-conditions-basic.yaml`** - Basic failure condition patterns
+- **`failure-conditions-advanced.yaml`** - Advanced failure handling with complex conditions
+- **`failure-conditions-github-style.yaml`** - GitHub-style failure conditions
+- **`failure-conditions-migration.yaml`** - Migration patterns for failure conditions
+
+### Integration Examples
+- **`jira-simple-example.yaml`** - Simple JIRA integration
+- **`jira-single-issue-workflow.yaml`** - Single JIRA issue workflow
+- **`jira-workflow-mcp.yaml`** - JIRA workflow with MCP tools
+- **`slack-simple-chat.yaml`** - Slack bot simple chat integration
+
+### Session & Import Examples
+- **`session-reuse-config.yaml`** - Session reuse configuration
+- **`session-reuse-self.yaml`** - Self-referencing session reuse patterns
+- **`on-init-import-demo.yaml`** - On-init hooks with imports
+- **`reusable-workflows.yaml`** - Reusable workflow patterns
+
+### Output Examples
+- **`outputs-raw-basic.yaml`** - Raw output formatting
 
 ### GitHub Actions Workflows
 - **`github-workflow-with-tags.yml`** - Progressive code review workflow using tags
@@ -77,6 +150,12 @@ Example configurations demonstrating various Visor features and use cases.
 - **`environments/visor.staging.yaml`** - Staging environment (balanced checks)
 - **`environments/visor.prod.yaml`** - Production environment (comprehensive validation)
 
+### Reusable Workflows (`workflows/` directory)
+- **`workflows/calculator-workflow.yaml`** - Reusable calculator workflow with inputs/outputs
+- **`workflows/code-quality.yaml`** - Code quality workflow (linting, complexity, formatting)
+- **`workflows/quick-pr-check.yaml`** - Quick PR validation workflow
+- **`workflows/workflow-composition-example.yaml`** - Workflow composition and state isolation demo
+
 ## 🚀 Quick Start
 
 ### 1. Basic Tag Usage
@@ -269,6 +348,92 @@ steps:
 - Use environment-specific configs with `extends` for DRY principles
 - Test tag filters with `--debug` to see which checks run
 
+## 🔌 Integration Examples
+
+### Slack Integration
+
+```bash
+# Run Slack bot (requires SLACK_BOT_TOKEN, SLACK_APP_TOKEN env vars)
+visor --config examples/slack-simple-chat.yaml
+```
+
+### JIRA Integration
+
+```bash
+# Simple JIRA workflow
+visor --config examples/jira-simple-example.yaml
+
+# JIRA with MCP tools
+visor --config examples/jira-workflow-mcp.yaml
+```
+
+### Webhook Pipelines
+
+```bash
+# Multi-pipeline webhook server
+visor --config examples/webhook-pipeline-config.yaml
+
+# Cron-triggered webhooks
+visor --config examples/cron-webhook-config.yaml
+```
+
+## 🧠 Memory & State Examples
+
+```bash
+# Basic memory counter
+visor --config examples/memory-counter.yaml
+
+# State machine with memory
+visor --config examples/memory-state-machine.yaml
+
+# Retry logic with counter
+visor --config examples/memory-retry-counter.yaml
+```
+
+## 🤖 AI Provider Examples
+
+```bash
+# AI with custom tools (ephemeral MCP servers)
+visor --config examples/ai-custom-tools-example.yaml
+
+# AI with bash execution
+visor --config examples/ai-with-bash.yaml
+
+# AWS Bedrock provider
+visor --config examples/bedrock-config.yaml --provider bedrock
+
+# Claude Code SDK integration
+visor --config examples/claude-code-config.yaml
+```
+
+## 🔧 MCP & Tools Examples
+
+```bash
+# MCP provider with different transports
+visor --config examples/mcp-provider-example.yaml
+
+# Custom tools
+visor --config examples/custom-tools-example.yaml
+```
+
+## 🔄 Reusable Workflows
+
+Import and compose workflows:
+
+```bash
+# Use the calculator workflow
+visor --config examples/workflows/calculator-workflow.yaml --input "num1=10" --input "num2=5" --input "operation=add"
+
+# Code quality workflow
+visor --config examples/workflows/code-quality.yaml --input "language=typescript"
+
+# Quick PR check
+visor --config examples/workflows/quick-pr-check.yaml --input "pr_type=feature"
+
+# Workflow composition example (imports calculator-workflow)
+visor --config examples/workflows/workflow-composition-example.yaml
+```
+
 ## 📚 Further Reading
 
 - [Main README](../README.md) - Complete Visor documentation

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

@@ -45,10 +45,9 @@ steps:
       You have access to custom security scanning tools.
       Use check-secrets to scan for hardcoded credentials.
       Use grep-pattern to find dangerous function calls.
+    # Use ai_custom_tools to reference custom tools defined in this file
+    ai_custom_tools: [check-secrets, grep-pattern]
     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

package/dist/examples/cron-webhook-config.yaml

@@ -42,6 +42,9 @@ steps:
   # Send security scan results to Slack
   security-to-slack:
     type: http
+    criticality: external
+    assume: "outputs['nightly-security-scan']"
+    schema: plain
     depends_on: [nightly-security-scan]
     url: "${SLACK_WEBHOOK_URL}"  # Read from SLACK_WEBHOOK_URL environment variable
     method: POST
@@ -103,6 +106,9 @@ steps:
   # Webhook input for deployment notifications
   deployment-webhook:
     type: http_input
+    criticality: external
+    assume: "true"
+    schema: plain
     endpoint: "/deploy"
     on: [webhook_received]
 
@@ -129,6 +135,9 @@ steps:
   # Send deployment analysis to ops team
   notify-ops-team:
     type: http
+    criticality: external
+    assume: "outputs['post-deploy-validation']"
+    schema: plain
     depends_on: [post-deploy-validation]
     url: "${OPS_WEBHOOK_URL}"  # Read from OPS_WEBHOOK_URL environment variable
     method: POST
@@ -154,6 +163,9 @@ steps:
   # CI completion webhook input
   ci-completion:
     type: http_input
+    criticality: external
+    assume: "true"
+    schema: plain
     endpoint: "/ci-complete"
     transform: |
       {
@@ -196,6 +208,9 @@ steps:
   # Send monitoring alerts
   monitoring-alert:
     type: http
+    criticality: external
+    assume: "outputs['business-hours-monitor']"
+    schema: plain
     depends_on: [business-hours-monitor]
     url: "${ALERT_WEBHOOK_URL}"  # Read from ALERT_WEBHOOK_URL environment variable
     body: |

package/dist/examples/forEach-example.yaml

@@ -85,6 +85,9 @@ steps:
   # Complex example: Process webhook data
   get-jira-tickets:
     type: http_client
+    criticality: external
+    assume: "pr.number"
+    schema: plain
     url: "https://api.example.com/jira/tickets?pr={{ pr.number }}"
     transform: |
       {{ data.issues | json }}
@@ -93,6 +96,9 @@ steps:
 
   update-each-ticket:
     type: http
+    criticality: external
+    assume: "outputs['get-jira-tickets']"
+    schema: plain
     url: "https://api.example.com/jira/ticket/{{ outputs.get-jira-tickets.id }}"
     body: |
       {

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

@@ -13,6 +13,7 @@ steps:
     type: git-checkout
     ref: "{{ pr.head }}"
     criticality: internal
+    assume: "pr.head"  # Ensure PR head ref exists before checkout
 
   # Run tests on the checked out code
   test:
@@ -21,6 +22,7 @@ steps:
     exec: npm test
     working_directory: "{{ outputs.checkout.path }}"
     assume: "outputs.checkout.success"
+    schema: plain
     criticality: internal
 
   # Build the project
@@ -29,4 +31,6 @@ steps:
     depends_on: [test]
     exec: npm run build
     working_directory: "{{ outputs.checkout.path }}"
+    assume: "outputs.test"
+    schema: plain
     criticality: internal

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

@@ -17,12 +17,14 @@ steps:
     type: git-checkout
     ref: "{{ pr.head }}"
     criticality: internal
+    assume: "pr.head"  # Ensure PR head ref exists
 
   # Checkout PR base branch
   checkout-base:
     type: git-checkout
     ref: "{{ pr.base }}"
     criticality: internal
+    assume: "pr.base"  # Ensure PR base ref exists
 
   # Run tests on head branch
   test-head:
@@ -31,6 +33,8 @@ steps:
     exec: npm test
     working_directory: "{{ outputs['checkout-head'].path }}"
     continue_on_failure: true
+    assume: "outputs['checkout-head']"
+    schema: plain
     criticality: internal
 
   # Run tests on base branch
@@ -40,6 +44,8 @@ steps:
     exec: npm test
     working_directory: "{{ outputs['checkout-base'].path }}"
     continue_on_failure: true
+    assume: "outputs['checkout-base']"
+    schema: plain
     criticality: internal
 
   # Compare results

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

@@ -13,6 +13,7 @@ steps:
     ref: "{{ pr.head }}"
     token: "{{ env.GITHUB_TOKEN }}"
     criticality: internal
+    assume: "env.GITHUB_TOKEN"  # Ensure token is available
 
   # Checkout shared library repository
   checkout-lib:
@@ -21,6 +22,7 @@ steps:
     ref: main
     token: "{{ env.GITHUB_TOKEN }}"
     criticality: internal
+    assume: "env.GITHUB_TOKEN"  # Ensure token is available
 
   # Checkout test utilities repository
   checkout-test-utils:
@@ -29,6 +31,7 @@ steps:
     ref: v2.0.0
     token: "{{ env.GITHUB_TOKEN }}"
     criticality: internal
+    assume: "env.GITHUB_TOKEN"  # Ensure token is available
 
   # Install dependencies in all repositories
   install-deps:
@@ -43,6 +46,8 @@ steps:
 
       echo "Installing dependencies for test utils..."
       cd "{{ outputs['checkout-test-utils'].path }}" && npm install
+    assume: "outputs['checkout-app'] && outputs['checkout-lib'] && outputs['checkout-test-utils']"
+    schema: plain
     criticality: internal
 
   # Run integration tests
@@ -54,6 +59,8 @@ steps:
       export TEST_UTILS_PATH="{{ outputs['checkout-test-utils'].path }}"
       npm run test:integration
     working_directory: "{{ outputs['checkout-app'].path }}"
+    assume: "outputs['install-deps']"
+    schema: plain
     criticality: internal
 
   # Generate integration report