@probelabs/visor 0.1.106 → 0.1.111

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

@@ -0,0 +1,372 @@
+# Human Input Provider
+
+The human-input provider pauses workflow execution to request input from a human user. This enables interactive workflows, approval gates, and dynamic parameter collection.
+
+## Table of Contents
+- [Overview](#overview)
+- [Configuration](#configuration)
+- [Input Methods](#input-methods)
+- [Examples](#examples)
+- [SDK Usage](#sdk-usage)
+- [Security](#security)
+
+## Overview
+
+The human-input provider supports four input methods, prioritized as follows:
+
+1. **CLI with `--message` argument** - Inline text or file path
+2. **Piped stdin** - Input from pipe or file redirect
+3. **SDK hook** - Custom `onHumanInput` callback
+4. **Interactive prompt** - Beautiful terminal UI (when TTY available)
+
+## Configuration
+
+### Basic Configuration
+
+```yaml
+checks:
+  approval:
+    type: human-input
+    prompt: "Do you approve this deployment? (yes/no)"
+```
+
+### Full Configuration Options
+
+```yaml
+checks:
+  approval:
+    type: human-input
+    prompt: "Enter approval decision"           # Required: prompt text
+    placeholder: "Type yes or no..."            # Optional: placeholder text
+    allow_empty: false                          # Optional: allow empty input (default: false)
+    multiline: false                            # Optional: enable multiline input (default: false)
+    timeout: 300                                # Optional: timeout in seconds
+    default: "no"                               # Optional: default value
+```
+
+### Using Input in Dependent Checks
+
+The user's input is available to dependent checks via the `outputs` variable. By default (no schema), human-input returns an object `{ text: string, ts: number }` where `ts` is the timestamp (milliseconds since epoch):
+
+```yaml
+checks:
+  get-version:
+    type: human-input
+    prompt: "Enter version number"
+
+  tag-release:
+    type: command
+    depends_on: [get-version]
+    exec: |
+      # 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
+
+### 1. CLI with --message
+
+Provide input directly via command line:
+
+```bash
+# Inline message
+visor --check approval --message "yes"
+
+# From file
+visor --check approval --message ./approval.txt
+```
+
+### 2. Piped stdin
+
+Pipe input from another command or file:
+
+```bash
+# From echo
+echo "yes" | visor --check approval
+
+# From file
+visor --check approval < approval.txt
+
+# From command
+curl https://api.example.com/approval | visor --check approval
+```
+
+### 3. SDK Hook
+
+Use a custom hook for programmatic input:
+
+```typescript
+import { runChecks, HumanInputCheckProvider } from '@probelabs/visor';
+
+// Option 1: Using deprecated static method (backward compatible)
+HumanInputCheckProvider.setHooks({
+  onHumanInput: async (request) => {
+    console.log(`Prompt: ${request.prompt}`);
+    return 'yes';
+  }
+});
+
+await runChecks({ config });
+
+// Option 2: Using new ExecutionContext (recommended)
+await runChecks({
+  config,
+  executionContext: {
+    hooks: {
+      onHumanInput: async (request) => {
+        console.log(`Prompt: ${request.prompt}`);
+        return 'yes';
+      }
+    }
+  }
+});
+```
+
+The `HumanInputRequest` interface:
+
+```typescript
+interface HumanInputRequest {
+  checkId: string;        // Check name/ID
+  prompt: string;         // Prompt text
+  placeholder?: string;   // Placeholder text
+  allowEmpty?: boolean;   // Allow empty input
+  multiline?: boolean;    // Multiline mode
+  timeout?: number;       // Timeout in milliseconds
+  default?: string;       // Default value
+}
+```
+
+### 4. Interactive Terminal Prompt
+
+When running in a TTY (interactive terminal), a beautiful prompt appears:
+
+```
+┌─────────────────────────────────────────────┐
+│ Enter approval decision                     │
+├─────────────────────────────────────────────┤
+│ Type yes or no...                           │
+│                                             │
+│ Press Ctrl+D when done (or Ctrl+C to exit) │
+└─────────────────────────────────────────────┘
+```
+
+## Examples
+
+### Simple Approval Gate
+
+```yaml
+checks:
+  manual-approval:
+    type: human-input
+    prompt: "Approve deployment to production? (yes/no)"
+    allow_empty: false
+
+  deploy:
+    type: command
+    depends_on: [manual-approval]
+    fail_if: |
+      outputs['manual-approval'].toLowerCase() !== 'yes'
+    exec: ./deploy.sh production
+```
+
+### Version Input
+
+```yaml
+checks:
+  get-version:
+    type: human-input
+    prompt: "Enter version number (e.g., 1.2.3)"
+
+  validate-version:
+    type: javascript
+    depends_on: [get-version]
+    exec: |
+      const version = outputs['get-version'];
+      const valid = /^\d+\.\d+\.\d+$/.test(version);
+      if (!valid) throw new Error('Invalid version format');
+```
+
+### Multi-step Input
+
+```yaml
+checks:
+  get-feature:
+    type: human-input
+    prompt: "Enter feature name"
+
+  get-description:
+    type: human-input
+    prompt: "Enter feature description"
+    multiline: true
+    depends_on: [get-feature]
+
+  create-issue:
+    type: command
+    depends_on: [get-feature, get-description]
+    exec: |
+      gh issue create \
+        --title "{{ outputs['get-feature'] }}" \
+        --body "{{ outputs['get-description'] }}"
+```
+
+### Calculator Example
+
+See [examples/calculator-sdk-real.ts](../examples/calculator-sdk-real.ts) for a complete working example with:
+- Multiple human-input checks in sequence
+- Output passing between checks
+- JavaScript execution with user input
+- Memory storage
+
+## SDK Usage
+
+### Basic SDK Usage
+
+```typescript
+import { runChecks } from '@probelabs/visor';
+
+const config = {
+  version: '1.0',
+  checks: {
+    approval: {
+      type: 'human-input',
+      prompt: 'Approve? (yes/no)'
+    }
+  }
+};
+
+// Run with execution context (recommended)
+const result = await runChecks({
+  config,
+  executionContext: {
+    hooks: {
+      onHumanInput: async (request) => {
+        // Your custom input logic
+        return await getUserInput(request.prompt);
+      }
+    }
+  }
+});
+```
+
+### With CLI Message
+
+```typescript
+import { CheckExecutionEngine } from '@probelabs/visor';
+
+const engine = new CheckExecutionEngine();
+
+// Set execution context
+engine.setExecutionContext({
+  cliMessage: 'yes'  // Simulates --message flag
+});
+
+const result = await engine.executeChecks({
+  checks: ['approval'],
+  config
+});
+```
+
+### Automated Testing
+
+```typescript
+const testInputs = {
+  'get-number1': '42',
+  'get-number2': '7',
+  'get-operation': '+'
+};
+
+await runChecks({
+  config,
+  executionContext: {
+    hooks: {
+      onHumanInput: async (request) => {
+        return testInputs[request.checkId] || '';
+      }
+    }
+  }
+});
+```
+
+## Security
+
+The human-input provider includes several security features:
+
+### Input Sanitization
+
+All user input is automatically sanitized before being passed to dependent checks:
+
+- **Null bytes removed** - Prevents C-string injection
+- **Control characters removed** - Except newlines and tabs
+- **Size limit** - Maximum 100KB per input
+
+### Path Traversal Protection
+
+When using `--message` with file paths:
+
+- **Path normalization** - Resolves `..` components
+- **Directory restriction** - Only reads files within current working directory
+- **File type validation** - Only reads regular files
+- **Async operations** - Non-blocking file I/O
+
+### DoS Prevention
+
+Stdin input has protection against denial-of-service:
+
+- **Size limit** - Default 1MB maximum
+- **Timeout support** - Configurable timeout
+- **Resource cleanup** - Proper cleanup with `stdin.pause()`
+
+### Execution Context Isolation
+
+The new ExecutionContext pattern eliminates global state:
+
+- **Thread-safe** - No global mutable state
+- **Test isolation** - Each execution has isolated context
+- **Concurrent safe** - Safe for parallel execution
+
+## Migration Guide
+
+### From Static API to ExecutionContext
+
+**Old way (still works but deprecated):**
+
+```typescript
+import { HumanInputCheckProvider, runChecks } from '@probelabs/visor';
+
+HumanInputCheckProvider.setHooks({
+  onHumanInput: async (request) => 'yes'
+});
+
+await runChecks({ config });
+```
+
+**New way (recommended):**
+
+```typescript
+import { runChecks } from '@probelabs/visor';
+
+await runChecks({
+  config,
+  executionContext: {
+    hooks: {
+      onHumanInput: async (request) => 'yes'
+    }
+  }
+});
+```
+
+Benefits of the new approach:
+- Thread-safe (no global state)
+- Better for concurrent executions
+- Easier to test
+- More flexible
+
+## See Also
+
+- [Calculator SDK Example](../examples/calculator-sdk-real.ts) - Complete working example
+- [Debugging Guide](./debugging.md) - Debugging techniques
+- [Command Provider](./command-provider.md) - Executing shell commands
+- [MCP Provider](./mcp-provider.md) - MCP integration

package/dist/docs/lifecycle-hooks.md

@@ -0,0 +1,253 @@
+# Lifecycle Hooks
+
+Lifecycle hooks allow you to execute preprocessing or setup tasks automatically before a step runs. This is particularly useful for enriching context, fetching external data, or preparing the environment.
+
+## `on_init` Hook
+
+The `on_init` hook runs **before** a step executes, allowing you to:
+- Fetch external data (JIRA issues, metrics, configuration)
+- Enrich AI prompts with additional context
+- Execute setup tasks or validation
+- Invoke custom tools, steps, or workflows
+
+### Basic Usage
+
+```yaml
+steps:
+  my-check:
+    type: ai
+    on_init:
+      run:
+        - tool: fetch-jira-issue
+          with:
+            issue_key: "PROJ-123"
+          as: jira-data
+    prompt: |
+      Review this PR considering JIRA issue: {{ outputs['jira-data'] | json }}
+```
+
+### Features
+
+#### 1. Multiple Invocations
+
+Execute multiple tools, steps, or workflows in sequence:
+
+```yaml
+on_init:
+  run:
+    - tool: fetch-user-data
+      as: users
+    - tool: fetch-config
+      as: config
+    - workflow: validate-environment
+      as: validation
+```
+
+#### 2. Custom Arguments
+
+Pass arguments to tools and workflows using `with`:
+
+```yaml
+on_init:
+  run:
+    - tool: fetch-external-data
+      with:
+        source: metrics-api
+        format: json
+      as: metrics
+```
+
+#### 3. Custom Output Names
+
+Store outputs with custom names using `as`:
+
+```yaml
+on_init:
+  run:
+    - tool: fetch-jira-issue
+      with:
+        issue_key: "PROJ-456"
+      as: jira-context  # Access via {{ outputs['jira-context'] }}
+```
+
+#### 4. Dynamic Preprocessing
+
+Use `run_js` for conditional preprocessing based on PR context:
+
+```yaml
+on_init:
+  run_js: |
+    const items = [];
+
+    // Fetch JIRA only if PR title contains issue key
+    const jiraMatch = pr.title.match(/PROJ-\d+/);
+    if (jiraMatch) {
+      items.push({
+        tool: 'fetch-jira-issue',
+        with: { issue_key: jiraMatch[0] },
+        as: 'jira-data'
+      });
+    }
+
+    // Fetch metrics if backend files changed
+    if (files.some(f => f.filename.includes('backend/'))) {
+      items.push({
+        tool: 'fetch-metrics',
+        as: 'backend-metrics'
+      });
+    }
+
+    return items;
+```
+
+### Invocation Types
+
+#### Tool Invocation
+
+Execute a custom MCP tool:
+
+```yaml
+on_init:
+  run:
+    - tool: my-custom-tool
+      with:
+        param1: value1
+      as: tool-output
+```
+
+#### Step Invocation
+
+Execute another step:
+
+```yaml
+on_init:
+  run:
+    - step: preprocessing-step
+      with:
+        input: "{{ pr.title }}"
+      as: preprocessed
+```
+
+#### Workflow Invocation
+
+Execute a workflow:
+
+```yaml
+on_init:
+  run:
+    - workflow: data-enrichment
+      with:
+        source: production
+      as: enriched-data
+```
+
+### Accessing Outputs
+
+Outputs from `on_init` items are available in the step's execution context:
+
+```yaml
+steps:
+  my-check:
+    type: command
+    on_init:
+      run:
+        - tool: fetch-data
+          as: external-data
+    exec: |
+      echo "Fetched data: {{ outputs['external-data'] | json }}"
+```
+
+### Reusable Tools and Workflows
+
+Define tools and workflows in separate files and import them:
+
+**reusable-tools.yaml:**
+```yaml
+version: "1.0"
+tools:
+  fetch-jira-issue:
+    name: fetch-jira-issue
+    exec: |
+      # Fetch JIRA issue...
+    parseJson: true
+steps: {}
+```
+
+**Main configuration:**
+```yaml
+version: "1.0"
+extends:
+  - ./reusable-tools.yaml
+
+steps:
+  ai-review:
+    type: ai
+    on_init:
+      run:
+        - tool: fetch-jira-issue
+          with:
+            issue_key: "{{ pr.title | regex_search: '[A-Z]+-[0-9]+' }}"
+          as: jira
+    prompt: "Review considering: {{ outputs.jira | json }}"
+```
+
+### Loop Protection
+
+To prevent infinite loops and excessive preprocessing:
+
+- **Maximum 50 items**: `on_init` can execute at most 50 items (configurable via `MAX_ON_INIT_ITEMS`)
+- **No nested execution**: `on_init` hooks within `on_init` items are skipped
+- **Separate from routing loops**: `on_init` loop protection is independent of `on_success`/`on_fail` routing
+
+### forEach Integration
+
+**How on_init works with forEach**: When a check uses `forEach`, the `on_init` hook runs **once before the forEach loop starts**, not once per item:
+
+```yaml
+steps:
+  analyze-files:
+    type: ai
+    forEach: file-list
+    on_init:  # Runs ONCE before processing all files
+      run:
+        - tool: fetch-project-config
+          as: config
+    prompt: |
+      Analyze {{ item }} using config: {{ outputs.config }}
+      # outputs.config is available to ALL forEach iterations
+```
+
+This design allows you to:
+- Fetch shared data once that all iterations can use
+- Avoid redundant preprocessing for each item
+- Keep forEach loops efficient
+
+If you need per-item preprocessing, add `on_init` to child steps that depend on the forEach check.
+
+### Examples
+
+See the `examples/` directory for comprehensive examples:
+
+- **examples/reusable-tools.yaml** - Reusable tool library with 3 custom tools (fetch-jira-issue, fetch-external-data, validate-data)
+- **examples/reusable-workflows.yaml** - Reusable workflow library with 3 workflows (data-enrichment, issue-triage, multi-step-validation)
+- **examples/on-init-import-demo.yaml** - Complete demonstration showing:
+  - Using multiple imported tools in on_init
+  - Invoking imported workflows
+  - Chaining tools and workflows together
+  - Reusing the same tool multiple times with different parameters
+  - Includes 4 passing test cases
+
+### Best Practices
+
+1. **Keep preprocessing lightweight**: `on_init` runs before every step execution
+2. **Use custom output names**: Make outputs easy to identify with descriptive `as` names
+3. **Leverage reusability**: Define common tools/workflows once and import them
+4. **Use `run_js` for conditionals**: Avoid fetching unnecessary data
+5. **Handle failures gracefully**: Consider what happens if preprocessing fails
+
+### See Also
+
+- [Custom Tools](./custom-tools.md) - Define reusable MCP tools
+- [Workflows](./workflows.md) - Create reusable workflows
+- [Liquid Templates](./liquid-templates.md) - Template syntax for dynamic values
+- [RFC: on_init Hook](./rfc/on_init-hook.md) - Design proposal and rationale

package/dist/docs/limits.md

@@ -0,0 +1,64 @@
+## 🚦 Execution Limits (Run Caps)
+
+This feature protects workflows from accidental infinite loops by capping how many times a step may execute in a single engine run. It complements (but is different from) routing loop budgets.
+
+### Why this exists
+
+- Complex `on_fail`/`on_success` routing can create feedback loops when a remediation step immediately routes back to its source.
+- The cap provides a hard stop with a clear error if a step keeps re-running without converging.
+
+### Configuration
+
+Global (default is 50 if omitted):
+
+```yaml
+version: "1.0"
+
+limits:
+  max_runs_per_check: 50  # Applies to every step unless overridden
+```
+
+Per-step override:
+
+```yaml
+steps:
+  refine:
+    type: ai
+    max_runs: 10  # Hard cap for this step within one engine run
+```
+
+Disable cap for a specific step (not recommended unless you know it converges quickly):
+
+```yaml
+steps:
+  extract:
+    type: command
+    max_runs: 0   # or any negative value
+```
+
+### Behavior
+
+- The engine counts executions per step. For `forEach` children, the counter is tracked per item scope (each item has its own budget).
+- When the cap is exceeded, the step fails immediately with a single error issue:
+  - `ruleId`: `<step-id>/limits/max_runs_exceeded`
+  - `severity`: `error`
+  - `message` includes the scope and attempt number
+- Dependents are gated as with any error unless the dependency declares `continue_on_failure: true`.
+
+### How this differs from `routing.max_loops`
+
+- `routing.max_loops` caps routing transitions (e.g., goto/retry waves) per scope.
+- `limits.max_runs_per_check` caps actual step executions per step (also per scope for `forEach`).
+- Both guard rails can be used together: set a modest routing budget (e.g., 5–10) and leave the execution cap at the default (50) or tailor per step.
+
+### Recommendations
+
+- Keep `routing.max_loops` small for fast feedback (5–10).
+- Use per-step `max_runs` on chat-like loops or known retryers if you need tighter control.
+- Prefer fixing the loop logic (conditions/routing) over raising the caps.
+
+### Troubleshooting
+
+- If you hit `.../limits/max_runs_exceeded` immediately, check if a step is routed back without changing state.
+- For `forEach` flows, confirm whether the error is tied to a specific item scope; fix that item’s remediation path.
+