@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/guides/workflow-style-guide.md

@@ -37,12 +37,17 @@ Use this top‑down order for every step. Omit sections that don’t apply.
 - `if`
 
 4) Provider Configuration (Only fields for the given type)
-- ai: `prompt`, `ai.{model,provider,tools,…}`
-- command: `exec`, `args`, `cwd`, `shell`
-- script: `content` or `file`
+- ai: `prompt`, `ai.{model,provider,tools,…}`, `ai_custom_tools`
+- command: `exec`, `stdin`, `cwd`, `timeout`
+- script: `content`
 - github: `op`, `values`
-- http/http_client/http_input: `url`, `method`, `body`, `headers`
-- log/memory/workflow/noop: minimal fields
+- http/http_client/http_input: `url`, `method`, `body`, `headers`, `endpoint`, `transform`
+- mcp: `transport`, `url`, `command`, `command_args`, `methodArgs`
+- log: `message`, `level`
+- memory: `operation`, `key`, `value`, `namespace`
+- workflow: `workflow`, `args`, `overrides`, `output_mapping`
+- git-checkout: `ref`, `repository`, `working_directory`
+- noop/human-input/claude-code: minimal fields
 
 5) Contracts (Post‑Exec)
 - `schema` (renderer name or JSON Schema)
@@ -53,6 +58,7 @@ Use this top‑down order for every step. Omit sections that don’t apply.
 - `continue_on_failure`
 
 7) Routing & Transitions
+- `on_init`
 - `on_success`
 - `on_fail`
 - `on_finish`
@@ -170,6 +176,7 @@ apply-issue-labels:
 
 ## YAML Style
 
+- Use `steps:` (preferred) or `checks:` as the top‑level key for step definitions.
 - Prefer block arrays/lists over inline `[]` unless trivially short.
 - Quote JS expressions in `assume`/`if` using double quotes.
 - Use `|` for multiline `prompt`/`content`; avoid trailing whitespace.
@@ -218,7 +225,9 @@ apply-overview-labels:
 
 ## References
 
-- Fault Management & Contracts
-- Criticality Modes
-- Dependencies & Routing
+- [Fault Management & Contracts](./fault-management-and-contracts.md) — safety checklist, behavior matrix, examples
+- [Criticality Modes](./criticality-modes.md) — external, internal, policy, info definitions and defaults
+- [Dependencies & Routing](../dependencies.md) — dependency patterns, fanout, session reuse
+- [Failure Routing](../failure-routing.md) — on_fail, on_success, on_finish hooks
+- [Output History](../output-history.md) — accessing historical outputs in expressions
 

package/dist/docs/http.md

@@ -39,6 +39,8 @@ Note: The HTTP server is automatically disabled when running in GitHub Actions t
 
 ### Check Types for HTTP Integration
 
+> **Important:** HTTP steps that interact with external services should declare `criticality: external` and include `assume`/`guarantee` contracts for safety. See [Criticality Modes](./guides/criticality-modes.md) for details.
+
 #### 1. HTTP Input (Webhook Receiver)
 Receive data from configured webhook endpoints:
 
@@ -46,6 +48,9 @@ Receive data from configured webhook endpoints:
 steps:
   github-webhook:
     type: http_input
+    criticality: external  # Receives from external system
+    assume: "true"         # Precondition guard (required for critical steps)
+    schema: plain          # Output contract
     endpoint: "/webhook/github"
     on: [webhook_received]
     transform: |
@@ -55,6 +60,15 @@ steps:
       }
 ```
 
+**HTTP Input Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `endpoint` | Webhook endpoint path (must match http_server endpoints) | Required |
+| `on` | Event triggers (typically `[webhook_received]`) | - |
+| `transform` | Liquid template to transform received webhook data | - |
+| `group` | Grouping category for the step | - |
+
 #### 2. HTTP Output (Send Data)
 Send check results to external services:
 
@@ -62,12 +76,16 @@ Send check results to external services:
 steps:
   notify-external:
     type: http
+    criticality: external  # Sends to external system
+    assume: "outputs['security-check']"  # Only run if dependency succeeded
+    schema: plain
     depends_on: [security-check]
     url: "https://api.example.com/notify"
     method: POST
     headers:
       Content-Type: "application/json"
       Authorization: "Bearer ${API_TOKEN}"
+    timeout: 30000  # Optional timeout in milliseconds (default: 30000)
     body: |
       {
         "results": {{ outputs['security-check'] | json }},
@@ -75,6 +93,17 @@ steps:
       }
 ```
 
+**HTTP Output Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `url` | Target URL | Required |
+| `body` | Request body template (Liquid) | Required |
+| `method` | HTTP method | POST |
+| `headers` | Request headers (supports env var substitution) | {} |
+| `timeout` | Request timeout in milliseconds | 30000 |
+| `metadata` | Additional metadata available in templates | {} |
+
 #### 3. HTTP Client (Fetch Data)
 Fetch data from external APIs:
 
@@ -82,10 +111,14 @@ Fetch data from external APIs:
 steps:
   fetch-config:
     type: http_client
+    criticality: external  # Fetches from external system
+    assume: "env.API_TOKEN"  # Require API token to be set
+    schema: plain
     url: "https://api.example.com/config"
     method: GET
     headers:
       Authorization: "Bearer ${API_TOKEN}"
+    timeout: 30000  # Optional timeout in milliseconds (default: 30000)
     transform: |
       {
         "settings": {{ response.data | json }},
@@ -93,6 +126,44 @@ steps:
       }
 ```
 
+**HTTP Client Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `url` | Target URL (supports Liquid templates and env vars) | Required |
+| `method` | HTTP method (GET, POST, PUT, DELETE, etc.) | GET |
+| `headers` | Request headers (supports env var substitution) | {} |
+| `body` | Request body for POST/PUT (supports Liquid templates) | - |
+| `timeout` | Request timeout in milliseconds | 30000 |
+| `transform` | Liquid template to transform response | - |
+| `transform_js` | JavaScript expression to transform response | - |
+| `output_file` | Download response to file instead of returning data | - |
+| `skip_if_exists` | Skip download if file exists (caching) | true |
+
+**File Download Example:**
+
+```yaml
+steps:
+  download-artifact:
+    type: http_client
+    url: "https://example.com/artifacts/{{ pr.number }}.zip"
+    output_file: "./downloads/artifact.zip"
+    skip_if_exists: true  # Use cached file if exists
+```
+
+**JavaScript Transform Example:**
+
+```yaml
+steps:
+  fetch-and-transform:
+    type: http_client
+    url: "https://api.example.com/data"
+    transform_js: |
+      // Access response via 'output' variable
+      const items = output.items || [];
+      return items.filter(i => i.status === 'active');
+```
+
 #### 4. Log Provider (Debugging & Monitoring)
 Output debugging information and monitor workflow execution:
 
@@ -102,7 +173,7 @@ steps:
     type: log
     group: debugging
     level: info
-    message: "🚀 Starting code review for PR #{{ pr.number }} by {{ pr.author }}"
+    message: "Starting code review for PR #{{ pr.number }} by {{ pr.author }}"
     include_pr_context: true
     include_dependencies: false
     include_metadata: true
@@ -113,7 +184,7 @@ steps:
     level: debug
     depends_on: [security-check]
     message: |
-      📊 Dependency results summary:
+      Dependency results summary:
       {% if dependencies %}
       - Security check found {{ dependencies['security-check'].issueCount }} issues
       {% else %}
@@ -125,7 +196,31 @@ steps:
     type: log
     group: monitoring
     level: warn
-    message: "⚠️ Large PR detected: {{ pr.totalAdditions }} lines added"
+    message: "Large PR detected: {{ pr.totalAdditions }} lines added"
+```
+
+**Log Provider Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `message` | Log message template (Liquid) | Required |
+| `level` | Log level: `debug`, `info`, `warn`, `error` | info |
+| `group` | Grouping category (e.g., `debugging`, `monitoring`, `chat`) | - |
+| `include_pr_context` | Include PR details in output | true |
+| `include_dependencies` | Include dependency results in output | true |
+| `include_metadata` | Include execution metadata in output | true |
+
+**Chat Group Example:**
+
+When `group: chat` is set, the log provider exposes a structured `output.text` field for chat-style integrations:
+
+```yaml
+steps:
+  chat-response:
+    type: log
+    group: chat
+    level: info
+    message: "Analysis complete for PR #{{ pr.number }}"
 ```
 
 ### Cron Scheduling
@@ -195,6 +290,10 @@ auth:
   type: basic
   username: "${HTTP_USERNAME}"
   password: "${HTTP_PASSWORD}"
+
+# No Authentication (not recommended for production)
+auth:
+  type: none
 ```
 
 #### HMAC Authentication Details

package/dist/docs/human-input-provider.md

@@ -61,9 +61,9 @@ checks:
       # Prefer .text to read the string payload
       git tag v{{ outputs['get-version'].text | default: outputs['get-version'] }}
       git push origin v{{ outputs['get-version'].text | default: outputs['get-version'] }}
+```
 
 > See also: [Default Output Schema](./default-output-schema.md)
-```
 
 ## Input Methods
 
@@ -99,19 +99,13 @@ curl https://api.example.com/approval | visor --check approval
 Use a custom hook for programmatic input:
 
 ```typescript
-import { runChecks, HumanInputCheckProvider } from '@probelabs/visor';
+import { runChecks } from '@probelabs/visor/sdk';
 
 // Option 1: Using deprecated static method (backward compatible)
-HumanInputCheckProvider.setHooks({
-  onHumanInput: async (request) => {
-    console.log(`Prompt: ${request.prompt}`);
-    return 'yes';
-  }
-});
-
-await runChecks({ config });
+// Note: HumanInputCheckProvider is not exported from the SDK;
+// use executionContext instead (recommended)
 
-// Option 2: Using new ExecutionContext (recommended)
+// Option 2: Using ExecutionContext (recommended)
 await runChecks({
   config,
   executionContext: {
@@ -132,8 +126,8 @@ interface HumanInputRequest {
   checkId: string;        // Check name/ID
   prompt: string;         // Prompt text
   placeholder?: string;   // Placeholder text
-  allowEmpty?: boolean;   // Allow empty input
-  multiline?: boolean;    // Multiline mode
+  allowEmpty: boolean;    // Allow empty input
+  multiline: boolean;     // Multiline mode
   timeout?: number;       // Timeout in milliseconds
   default?: string;       // Default value
 }
@@ -225,7 +219,7 @@ See [examples/calculator-sdk-real.ts](../examples/calculator-sdk-real.ts) for a
 ### Basic SDK Usage
 
 ```typescript
-import { runChecks } from '@probelabs/visor';
+import { runChecks } from '@probelabs/visor/sdk';
 
 const config = {
   version: '1.0',
@@ -254,25 +248,23 @@ const result = await runChecks({
 ### With CLI Message
 
 ```typescript
-import { CheckExecutionEngine } from '@probelabs/visor';
+import { runChecks } from '@probelabs/visor/sdk';
 
-const engine = new CheckExecutionEngine();
-
-// Set execution context
-engine.setExecutionContext({
-  cliMessage: 'yes'  // Simulates --message flag
-});
-
-const result = await engine.executeChecks({
+const result = await runChecks({
+  config,
   checks: ['approval'],
-  config
+  executionContext: {
+    cliMessage: 'yes'  // Simulates --message flag
+  }
 });
 ```
 
 ### Automated Testing
 
 ```typescript
-const testInputs = {
+import { runChecks } from '@probelabs/visor/sdk';
+
+const testInputs: Record<string, string> = {
   'get-number1': '42',
   'get-number2': '7',
   'get-operation': '+'
@@ -331,22 +323,14 @@ The new ExecutionContext pattern eliminates global state:
 
 ### From Static API to ExecutionContext
 
-**Old way (still works but deprecated):**
+**Old way (deprecated, internal use only):**
 
-```typescript
-import { HumanInputCheckProvider, runChecks } from '@probelabs/visor';
-
-HumanInputCheckProvider.setHooks({
-  onHumanInput: async (request) => 'yes'
-});
-
-await runChecks({ config });
-```
+The static `HumanInputCheckProvider.setHooks()` method is deprecated and not exported from the public SDK. If you were using it directly by importing from internal paths, migrate to the new pattern.
 
 **New way (recommended):**
 
 ```typescript
-import { runChecks } from '@probelabs/visor';
+import { runChecks } from '@probelabs/visor/sdk';
 
 await runChecks({
   config,

package/dist/docs/index.md

@@ -0,0 +1,206 @@
+# Visor Documentation
+
+Visor is an AI-powered workflow orchestration tool for code review, automation, and CI/CD pipelines. It supports multiple AI providers, pluggable check providers, and integrates with GitHub Actions and Slack.
+
+---
+
+## Getting Started
+
+| Document | Description |
+|----------|-------------|
+| [NPM Usage](./NPM_USAGE.md) | Quick start guide for installing and running Visor via npm/npx |
+| [Configuration](./configuration.md) | Core configuration reference for `.visor.yaml` files |
+| [Commands](./commands.md) | CLI commands and PR comment commands reference |
+| [Action Reference](./action-reference.md) | GitHub Action inputs, outputs, and usage examples |
+| [CI/CLI Mode](./ci-cli-mode.md) | Running Visor in CI pipelines and CLI mode |
+
+---
+
+## Configuration
+
+| Document | Description |
+|----------|-------------|
+| [Configuration](./configuration.md) | Main configuration guide including check types and validation |
+| [Tag Filtering](./tag-filtering.md) | Filter check execution using tags for different environments |
+| [Event Triggers](./event-triggers.md) | GitHub events and how to trigger checks based on PR/issue actions |
+| [Timeouts](./timeouts.md) | Per-provider timeout configuration and behavior |
+| [Execution Limits](./limits.md) | Run caps and loop protection for workflow safety |
+| [Liquid Templates](./liquid-templates.md) | Template syntax for dynamic content in prompts and commands |
+| [Schema Templates](./schema-templates.md) | JSON Schema validation and output rendering system |
+| [Default Output Schema](./default-output-schema.md) | Automatic timestamp injection and output normalization |
+| [Suppressions](./suppressions.md) | Suppressing warnings using code comments |
+
+---
+
+## Providers
+
+Visor supports 15 provider types for different check and workflow operations.
+
+### AI Providers
+
+| Document | Description |
+|----------|-------------|
+| [AI Configuration](./ai-configuration.md) | Configure AI providers (Gemini, Claude, OpenAI, Bedrock) |
+| [Claude Code](./claude-code.md) | Claude Code SDK integration with MCP tools and subagents |
+| [Advanced AI](./advanced-ai.md) | Session reuse, multi-turn conversations, and advanced AI features |
+| [AI Custom Tools](./ai-custom-tools.md) | Define custom shell-based tools for AI via ephemeral MCP servers |
+| [AI Custom Tools Usage](./ai-custom-tools-usage.md) | Practical examples of using custom tools with AI providers |
+| [MCP Support for AI](./mcp.md) | MCP server configuration for AI provider enhancement |
+
+### Execution Providers
+
+| Document | Description |
+|----------|-------------|
+| [MCP Provider](./mcp-provider.md) | Direct MCP tool execution via stdio, SSE, or HTTP transports |
+| [Command Provider](./command-provider.md) | Execute shell commands with output parsing and templating |
+| [Script Provider](./script.md) | Run JavaScript in a secure sandbox with PR context access |
+| [Custom Tools](./custom-tools.md) | Define reusable command-line tools in YAML configuration |
+
+### Integration Providers
+
+| Document | Description |
+|----------|-------------|
+| [HTTP Integration](./http.md) | HTTP server, webhooks, scheduling, and TLS configuration |
+| [GitHub Provider](./github-ops.md) | Native GitHub operations (labels, comments) via Octokit |
+| [Git Checkout](./providers/git-checkout.md) | Checkout code from repositories using git worktrees |
+| [Memory Provider](./memory.md) | Persistent key-value storage for stateful workflows |
+| [Human Input](./human-input-provider.md) | Pause workflows to collect user input via CLI, stdin, or SDK |
+
+### Utility Providers
+
+| Document | Description |
+|----------|-------------|
+| [Pluggable Architecture](./pluggable.md) | Overview of all providers and custom provider development |
+
+---
+
+## Workflows and Routing
+
+| Document | Description |
+|----------|-------------|
+| [Reusable Workflows](./workflows.md) | Define modular, parameterized workflow components |
+| [Dependencies](./dependencies.md) | Step dependencies, parallel execution, and DAG scheduling |
+| [Failure Routing](./failure-routing.md) | Auto-fix loops, retries, goto routing, and remediation |
+| [Router Patterns](./router-patterns.md) | Best practices for router steps and control flow |
+| [Lifecycle Hooks](./lifecycle-hooks.md) | on_init, on_success, on_fail, on_finish hooks |
+| [ForEach Propagation](./foreach-dependency-propagation.md) | ForEach output validation and dependent propagation |
+| [Output History](./output-history.md) | Track outputs across loops, retries, and forEach iterations |
+| [Fail If](./fail-if.md) | Conditional failure expressions for any provider |
+| [Author Permissions](./author-permissions.md) | Permission checking functions based on PR author association |
+| [Workflow Creation Guide](./workflow-creation-guide.md) | Comprehensive guide to creating Visor workflows |
+| [Recipes](./recipes.md) | Copy-pasteable examples for common workflow patterns |
+
+---
+
+## Testing
+
+The test framework allows you to write integration tests for your Visor workflows in YAML.
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](./testing/getting-started.md) | Quick start guide for writing and running tests |
+| [CLI Reference](./testing/cli.md) | Test runner commands, flags, and parallelism options |
+| [DSL Reference](./testing/dsl-reference.md) | Complete schema reference for `.visor.tests.yaml` files |
+| [Assertions](./testing/assertions.md) | Writing expectations for calls, prompts, outputs, and failures |
+| [Flow Tests](./testing/flows.md) | Multi-stage flow tests across multiple events |
+| [Fixtures and Mocks](./testing/fixtures-and-mocks.md) | Built-in fixtures and mocking AI/provider responses |
+| [CI Integration](./testing/ci.md) | Running tests in CI pipelines with reporting |
+| [Troubleshooting](./testing/troubleshooting.md) | Common test issues and solutions |
+| [Cookbook](./testing/cookbook.md) | Copy-pasteable test recipes for common scenarios |
+
+---
+
+## Integrations
+
+| Document | Description |
+|----------|-------------|
+| [GitHub Checks](./GITHUB_CHECKS.md) | GitHub Checks API integration for PR status reporting |
+| [Slack Integration](./slack-integration.md) | Bidirectional Slack integration via Socket Mode |
+| [Deployment](./DEPLOYMENT.md) | Cloudflare Pages deployment for landing page |
+
+---
+
+## Observability
+
+| Document | Description |
+|----------|-------------|
+| [Observability Overview](./observability.md) | Output formats, logging, telemetry, and execution statistics |
+| [Output Formats](./output-formats.md) | Table, JSON, markdown, and SARIF output format details |
+| [Debugging](./debugging.md) | Debug mode, logging, expression debugging, and visualizer |
+| [Telemetry Setup](./telemetry-setup.md) | OpenTelemetry configuration for traces and metrics |
+| [Dashboards](./dashboards/README.md) | Grafana dashboards for Visor telemetry visualization |
+| [Troubleshooting](./troubleshooting.md) | Common issues and diagnostic techniques |
+| [Performance](./performance.md) | Parallelism, cost controls, and optimization strategies |
+
+---
+
+## Guides
+
+Best practices and style guides for writing maintainable workflows.
+
+| Document | Description |
+|----------|-------------|
+| [Workflow Style Guide](./guides/workflow-style-guide.md) | Conventions for clear, safe, and maintainable workflows |
+| [Criticality Modes](./guides/criticality-modes.md) | external, internal, policy, info classification and defaults |
+| [Fault Management](./guides/fault-management-and-contracts.md) | NASA-style fault handling with assume/guarantee contracts |
+| [Security](./security.md) | Authentication, permissions, and security best practices |
+| [Development Playbook](./dev-playbook.md) | Internal development guide and conventions |
+
+---
+
+## Reference
+
+| Document | Description |
+|----------|-------------|
+| [SDK](./sdk.md) | Programmatic usage of Visor from Node.js |
+| [Output Formatting](./output-formatting.md) | Output format specification and customization |
+
+---
+
+## RFCs and Design Documents
+
+Internal design documents, proposals, and implementation tracking.
+
+### Implemented RFCs
+
+| Document | Description |
+|----------|-------------|
+| [Git Checkout Step](./rfc/git-checkout-step.md) | Design for git worktree-based checkout provider |
+| [Workspace Isolation](./rfc/workspace-isolation.md) | Isolated workspace implementation using /tmp |
+| [on_init Hook](./rfc/on_init-hook.md) | Lifecycle hook for context preprocessing |
+| [Telemetry Tracing](./telemetry-tracing-rfc.md) | OpenTelemetry tracing architecture |
+| [Test Framework](./test-framework-rfc.md) | In-YAML integration test framework design |
+
+### Design Documents
+
+| Document | Description |
+|----------|-------------|
+| [Failure Routing RFC](./failure-routing-rfc.md) | Auto-fix loops and routing design |
+| [Failure Conditions Schema](./failure-conditions-schema.md) | Schema for failure condition configuration |
+| [Failure Conditions Implementation](./failure-conditions-implementation.md) | Implementation details for failure handling |
+| [Engine State Machine Plan](./engine-state-machine-plan.md) | State machine execution engine design |
+| [Loop Routing Refactor](./loop-routing-refactor.md) | Refactoring plan for routing loops |
+| [Goto Forward Run Plan](./goto-forward-run-plan.md) | Forward-run implementation for goto routing |
+| [Debug Visualizer](./debug-visualizer.md) | Interactive debugging visualizer design |
+| [Debug Visualizer RFC](./debug-visualizer-rfc.md) | Debug visualizer architecture RFC |
+| [Debug Visualizer Progress](./debug-visualizer-progress.md) | Implementation progress tracker |
+| [Execution Statistics RFC](./execution-statistics-rfc.md) | Execution metrics and statistics design |
+| [Event-Driven GitHub](./event-driven-github-integration-rfc.md) | Event-driven GitHub integration design |
+| [Bot Transports RFC](./bot-transports-rfc.md) | Transport layer design for bot integrations |
+| [Engine Pause/Resume RFC](./engine-pause-resume-rfc.md) | Pause and resume functionality design |
+| [Visor SDK RFC](./visor-sdk-rfc.md) | SDK architecture and API design |
+| [Schema Next PR](./schema-next-pr.md) | Schema evolution planning |
+
+### Proposals
+
+| Document | Description |
+|----------|-------------|
+| [Snapshot Scope Execution](./proposals/snapshot-scope-execution.md) | MVCC-style snapshot isolation execution model |
+
+### Roadmap
+
+| Document | Description |
+|----------|-------------|
+| [Criticality Implementation](./roadmap/criticality-implementation-tasks.md) | Implementation tasks for criticality model |
+| [Fact Validator Implementation](./fact-validator-implementation-plan.md) | Fact validation feature implementation plan |
+| [Fact Validator Gap Analysis](./fact-validator-gap-analysis.md) | Gap analysis for fact validation system |