@probelabs/visor 0.1.106 → 0.1.111

package/dist/docs/observability.md

@@ -0,0 +1,12 @@
+## 👀 Observability
+
+- Machine-readable output: `--output json` or `--output sarif`.
+- Prefer the built‑in `--output-file <path>` to save results without touching stdout.
+- Status/progress logs are written to stderr; control verbosity via `-q`, `-v`, or `--debug`.
+
+Examples:
+
+```
+visor --check all --output json --output-file results.json
+visor --check security --output sarif --output-file visor-results.sarif
+```

package/dist/docs/output-formats.md

@@ -0,0 +1,20 @@
+## 📊 Output Formats
+
+- Table: default terminal summary
+- JSON: `--output json` for pipelines
+- Markdown: render comments as markdown
+- SARIF 2.1.0: `--output sarif` for code scanning
+
+### Saving outputs reliably
+
+- Use the built‑in `--output-file <path>` to write the formatted result directly to a file without mixing with logs.
+- All status logs are sent to stderr; stdout contains only the formatted result when not using `--output-file`.
+
+Examples:
+
+```
+visor --check all --output json --output-file results.json
+visor --check security --output sarif --output-file visor-results.sarif
+visor --check architecture --output markdown --output-file report.md
+visor --check style --output table --output-file summary.txt
+```

package/dist/docs/output-formatting.md

@@ -0,0 +1,29 @@
+## Output Formatting and Safety Limits
+
+Visor renders human‑friendly tables in the CLI using `cli-table3`. Extremely large or unbroken strings can make third‑party wrapping/width calculation slow. To keep rendering fast and predictable, Visor pre‑wraps and truncates content before handing it to the table library.
+
+What this means when `--output table` is used:
+
+- Long words are soft‑broken to avoid expensive width calculations.
+- Very large cells are truncated with a clear marker:
+  
+  … [truncated]
+
+- Code replacements are line‑capped and soft‑wrapped so they fit in the table column.
+
+Environment knobs (advanced)
+
+- `VISOR_MAX_TABLE_CELL` (default: `4000`)
+  - Maximum characters allowed per table cell (after wrapping). Content beyond this is truncated and annotated.
+- `VISOR_MAX_TABLE_CODE_LINES` (default: `120`)
+  - Maximum number of code lines included in a single table cell. Extra lines are dropped and the block is annotated.
+
+Notes
+
+- These safety limits affect only the table output. JSON, SARIF, and Markdown formats are unaffected.
+- If you need the complete, untruncated data for automation, prefer `--output json` (optionally with `--output-file`).
+
+Troubleshooting
+
+- If you notice slowdowns at “Formatting results as table”, try reducing `VISOR_MAX_TABLE_CELL` (e.g., `2000`) or use `--output json` for machine‑readable pipelines.
+

package/dist/docs/output-history.md

@@ -0,0 +1,383 @@
+# Output History
+
+The `outputs.history` feature tracks all outputs from check executions, making it easy to access previous iterations in loops, retries, and forEach operations.
+
+## Overview
+
+When checks execute multiple times (through `goto` loops, `retry` attempts, or `forEach` iterations), Visor automatically tracks all output values in `outputs.history`. This is essential for:
+
+- **Loop iteration tracking** - Access all values from previous goto loop iterations
+- **Retry analysis** - See outputs from all retry attempts
+- **forEach processing** - Track all items processed in a forEach loop
+- **Debugging** - Understand the full execution history
+- **Progressive calculations** - Build on previous iteration results
+
+## Structure
+
+The `outputs` variable has two main parts:
+
+```javascript
+outputs['check-name']          // Current/latest value from this check
+outputs.history['check-name']  // Array of ALL previous values from this check
+```
+
+### Current vs History
+
+- **`outputs['check-name']`** - Always contains the **LATEST** value
+  - Updated each time the check executes
+  - Single value (not an array)
+  - What you typically want to use for conditions and decisions
+
+- **`outputs.history['check-name']`** - Contains **ALL PREVIOUS** values
+  - Array of all outputs in chronological order
+  - First element is from first execution, last is most recent
+  - Useful for tracking progress, calculating totals, comparing changes
+
+## Usage Examples
+
+### Basic Loop Tracking
+
+Track a counter through multiple goto iterations:
+
+```yaml
+steps:
+  counter:
+    type: script
+    content: |
+      const count = (memory.get('count') || 0) + 1;
+      memory.set('count', count);
+      return { iteration: count, timestamp: Date.now() };
+
+  process:
+    type: script
+    depends_on: [counter]
+    content: |
+      // Current iteration
+      log('Current iteration:', outputs.counter.iteration);
+
+      // All previous iterations
+      log('All iterations:', outputs.history.counter.map(h => h.iteration));
+
+      // History length equals current iteration
+      log('History length:', outputs.history.counter.length);
+
+      return `Processed iteration ${outputs.counter.iteration}`;
+    on_success:
+      goto: counter
+      goto_js: |
+        // Continue looping until iteration 5
+        return outputs.counter.iteration < 5 ? 'counter' : null;
+```
+
+### Retry Tracking
+
+Track all retry attempts:
+
+```yaml
+steps:
+  attempt-counter:
+    type: script
+    content: |
+      const attempt = (memory.get('attempt') || 0) + 1;
+      memory.set('attempt', attempt);
+      return { attempt, timestamp: Date.now() };
+
+  flaky-operation:
+    type: command
+    depends_on: [attempt-counter]
+    exec: './scripts/flaky-operation.sh'
+    transform_js: |
+      const attempt = outputs['attempt-counter'].attempt;
+      log('Attempt number:', attempt);
+
+      // Simulate success only on 3rd attempt
+      if (attempt < 3) {
+        throw new Error('Simulated failure');
+      }
+
+      return {
+        succeeded: true,
+        attempt,
+        allAttempts: outputs.history['attempt-counter'].map(h => h.attempt)
+      };
+    on_fail:
+      retry:
+        max_attempts: 5
+        delay: 1000
+      goto: attempt-counter
+```
+
+### forEach History
+
+Track all forEach iterations:
+
+```yaml
+steps:
+  generate-items:
+    type: script
+    content: |
+      return [
+        { id: 1, name: 'alpha', value: 10 },
+        { id: 2, name: 'beta', value: 20 },
+        { id: 3, name: 'gamma', value: 30 }
+      ];
+
+  process-item:
+    type: script
+    depends_on: [generate-items]
+    forEach: true
+    content: |
+      // Process current item (use current dependency value)
+      const curr = outputs['generate-items'];
+      const processed = { ...curr, doubled: curr.value * 2, processedAt: Date.now() };
+
+      log('Processing item:', item.id);
+      log('Items processed so far:', outputs.history['process-item'].length);
+
+      return processed;
+
+  summarize:
+    type: script
+    depends_on: [process-item]
+    content: |
+      // Access all forEach results
+      const allProcessed = outputs.history['process-item'];
+
+      return {
+        totalProcessed: allProcessed.length,
+        totalValue: allProcessed.reduce((sum, item) => sum + item.doubled, 0),
+        allIds: allProcessed.map(item => item.id),
+        allNames: allProcessed.map(item => item.name)
+      };
+```
+
+### Comparing with Previous Iteration
+
+Compare current value with previous:
+
+```yaml
+steps:
+  monitor-metric:
+    type: command
+    exec: 'curl -s https://api.example.com/metrics | jq .cpu_usage'
+    transform_js: |
+      const current = parseFloat(output);
+      return { value: current, timestamp: Date.now() };
+
+  check-trend:
+    type: script
+    depends_on: [monitor-metric]
+    content: |
+      const current = outputs['monitor-metric'].value;
+      const history = outputs.history['monitor-metric'];
+
+      if (history.length > 1) {
+        const previous = history[history.length - 1].value;
+        const change = current - previous;
+        const percentChange = (change / previous) * 100;
+
+        log('Current:', current);
+        log('Previous:', previous);
+        log('Change:', percentChange.toFixed(2) + '%');
+
+        if (percentChange > 50) {
+          throw new Error(`CPU usage spiked by ${percentChange.toFixed(2)}%`);
+        }
+      }
+
+      return { current, changeTracked: history.length > 1 };
+    on_success:
+      goto: monitor-metric
+      goto_js: |
+        // Monitor for 5 iterations
+        return outputs.history['monitor-metric'].length < 5 ? 'monitor-metric' : null;
+```
+
+### Progressive Aggregation
+
+Build up results over iterations:
+
+```yaml
+steps:
+  fetch-page:
+    type: script
+    content: |
+      const page = (memory.get('page') || 0) + 1;
+      memory.set('page', page);
+
+      // Simulate fetching a page of data
+      return {
+        page,
+        items: [`item-${page}-1`, `item-${page}-2`, `item-${page}-3`]
+      };
+
+  aggregate-results:
+    type: script
+    depends_on: [fetch-page]
+    content: |
+      // Collect all items from all pages
+      const allPages = outputs.history['fetch-page'];
+      const allItems = allPages.flatMap(page => page.items);
+
+      log('Pages fetched:', allPages.length);
+      log('Total items:', allItems.length);
+
+      return {
+        totalPages: allPages.length,
+        totalItems: allItems.length,
+        items: allItems
+      };
+    on_success:
+      goto: fetch-page
+      goto_js: |
+        // Fetch 3 pages
+        return outputs.history['fetch-page'].length < 3 ? 'fetch-page' : null;
+```
+
+## Access in Different Contexts
+
+### JavaScript Expressions
+
+In script content, `transform_js`, `goto_js`, `fail_if`, etc.:
+
+```javascript
+// Current value
+outputs['check-name']
+outputs.checkName
+
+// History array
+outputs.history['check-name']
+outputs.history.checkName
+
+// Array operations
+outputs.history.counter.length
+outputs.history.counter.map(h => h.value)
+outputs.history.counter.filter(h => h.success)
+outputs.history.counter.every(h => h.valid)
+outputs.history.counter.some(h => h.error)
+```
+
+### Liquid Templates
+
+In templates (logger, http body, etc.):
+
+```liquid
+{# Current value #}
+Current: {{ outputs.counter }}
+
+{# History array #}
+History: {% for val in outputs.history.counter %}{{ val }}{% unless forloop.last %}, {% endunless %}{% endfor %}
+
+{# History length #}
+Total iterations: {{ outputs.history.counter.size }}
+
+{# Access specific iteration #}
+First: {{ outputs.history.counter[0] }}
+Last: {{ outputs.history.counter | last }}
+
+{# Complex iteration #}
+{% for item in outputs.history['process-item'] %}
+  - Item {{ item.id }}: {{ item.name }}
+{% endfor %}
+```
+
+### Command Templates
+
+In shell commands:
+
+```yaml
+steps:
+  show-history:
+    type: command
+    depends_on: [counter]
+    exec: |
+      echo "Current: {{ outputs.counter }}"
+      echo "History: {{ outputs.history.counter | json }}"
+```
+
+## Important Behaviors
+
+### History Contains Current Execution
+
+The history array includes the current execution. So after 3 iterations:
+- `outputs.counter` = value from 3rd iteration
+- `outputs.history.counter` = `[value1, value2, value3]` (length = 3)
+
+### Empty History
+
+If a check hasn't executed yet, or has no output:
+- `outputs.history['check-name']` = `[]` (empty array, not undefined)
+- Always safe to check `.length` or iterate
+
+### Failed Executions
+
+Failed executions that throw errors are NOT added to history. Only successful outputs are tracked.
+
+### forEach Iterations
+
+Each forEach iteration is tracked separately:
+
+```yaml
+steps:
+  process-items:
+    forEach: true
+    type: script
+    content: |
+      const curr = outputs['process-items'];
+      return { itemId: (curr && curr.id) || null, processed: true };
+```
+
+After processing 3 items, `outputs.history['process-items']` will have 3 entries (one per item).
+
+## Debugging with History
+
+### Log All Iterations
+
+```javascript
+log('All counter values:', outputs.history.counter);
+log('Iterations count:', outputs.history.counter.length);
+```
+
+### Verify Sequential Execution
+
+```javascript
+// Check that iterations are sequential
+for (let i = 0; i < outputs.history.counter.length; i++) {
+  if (outputs.history.counter[i].iteration !== i + 1) {
+    throw new Error('Iteration order incorrect');
+  }
+}
+```
+
+### Track Timing
+
+```javascript
+const allTimestamps = outputs.history.counter.map(h => h.timestamp);
+const durations = [];
+for (let i = 1; i < allTimestamps.length; i++) {
+  durations.push(allTimestamps[i] - allTimestamps[i-1]);
+}
+log('Average iteration time:', durations.reduce((a,b) => a+b, 0) / durations.length);
+```
+
+## Performance Considerations
+
+- History stores only the output values, not full check results
+- Memory usage grows linearly with iterations (O(n))
+- For very long-running loops (100+ iterations), consider periodically clearing or summarizing
+- Use `max_loops` configuration to prevent infinite loops
+
+## Related Documentation
+
+- [Liquid Templates](./liquid-templates.md) - Using history in templates
+- [Memory Provider](./memory.md) - Storing and accessing state
+- [Failure Routing](./failure-routing.md) - Using goto and retry with history
+- [forEach Dependency Propagation](./foreach-dependency-propagation.md) - How forEach interacts with history
+- [Debugging](./debugging.md) - Debugging techniques using history
+
+## Examples
+
+See the test files for complete working examples:
+- `tests/unit/output-history.test.ts` - Basic history functionality
+- `tests/integration/output-history-integration.test.ts` - Complex loop scenarios
+- `tests/unit/goto-current-output.test.ts` - Verifying current vs history values

package/dist/docs/performance.md

@@ -0,0 +1,6 @@
+## ⚡ Performance & Cost Controls
+
+- Cache Node in CI: `actions/setup-node@v4` with `cache: npm`.
+- Use tags: run `local,fast` on PRs; `remote,comprehensive` nightly.
+- Increase `max-parallelism` cautiously if not reusing AI sessions.
+

package/dist/docs/pluggable.md

@@ -0,0 +1,124 @@
+## 🔧 Pluggable Architecture
+
+Visor supports multiple provider types (ai, mcp, http, http_client, log, command, github, claude-code). You can also add custom providers.
+
+### Custom Provider Skeleton (TypeScript)
+
+```ts
+class CustomCheckProvider {
+  name = 'custom';
+  async run(input) {
+    // ... implement your logic
+    return { issues: [] };
+  }
+}
+```
+
+### Built-in Providers
+
+#### AI Provider (`type: ai`)
+Execute AI-powered analysis using Google Gemini, Anthropic Claude, OpenAI, or AWS Bedrock.
+
+```yaml
+steps:
+  security:
+    type: ai
+    prompt: "Review for security issues"
+    schema: code-review
+```
+
+[Learn more](./ai-configuration.md)
+
+#### MCP Provider (`type: mcp`)
+Call MCP (Model Context Protocol) tools directly via stdio, SSE, or HTTP transports. Unlike AI provider MCP support, this provider directly invokes MCP tools without an AI model.
+
+```yaml
+steps:
+  probe-search:
+    type: mcp
+    transport: stdio
+    command: npx
+    args: ["-y", "@probelabs/probe@latest", "mcp"]
+    method: search_code
+    methodArgs:
+      query: "TODO"
+```
+
+[Learn more](./mcp-provider.md)
+
+#### Command Provider (`type: command`)
+Execute shell commands with templating and security controls.
+
+```yaml
+steps:
+  lint:
+    type: command
+    exec: npm run lint
+```
+
+[Learn more](./command-provider.md)
+
+#### HTTP Client Provider (`type: http_client`)
+Make HTTP requests to external APIs.
+
+```yaml
+steps:
+  api-check:
+    type: http_client
+    url: https://api.example.com/analyze
+    method: POST
+    body: '{{ pr | json }}'
+```
+
+[Learn more](./http.md)
+
+#### HTTP Provider (`type: http`)
+Send check results to external webhooks.
+
+```yaml
+steps:
+  notify:
+    type: http
+    url: https://webhook.example.com/notify
+    method: POST
+```
+
+[Learn more](./http.md)
+
+#### Logger Provider (`type: logger`)
+Log messages for debugging and workflow visibility.
+
+```yaml
+steps:
+  debug:
+    type: logger
+    message: "PR #{{ pr.number }}: {{ fileCount }} files changed"
+```
+
+[Learn more](./debugging.md)
+
+#### GitHub Provider (`type: github`)
+Interact with GitHub API for labels, comments, and status checks.
+
+```yaml
+steps:
+  label-pr:
+    type: github
+    op: labels.add
+    values: ["security", "needs-review"]
+```
+
+[Learn more](./github-ops.md)
+
+#### Claude Code Provider (`type: claude-code`)
+Use Claude Code SDK with MCP tools and advanced agent capabilities.
+
+```yaml
+steps:
+  claude-analysis:
+    type: claude-code
+    prompt: "Analyze code architecture"
+```
+
+[Learn more](./claude-code.md)
+