@probelabs/visor 0.1.106 → 0.1.111

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

@@ -0,0 +1,224 @@
+# Visor Workflow Style Guide
+
+This guide captures pragmatic conventions for writing clear, safe, and maintainable Visor workflows (visor.yaml and friends). It complements the feature guides by focusing on readability, intent, and day‑2 operability.
+
+## Why This Matters
+
+- Readability reduces on‑call cognitive load and speeds reviews.
+- A consistent structure makes behaviors obvious (what, when, how, and why).
+- Guardrails prevent accidental side effects and clarify intent.
+
+## Key Principles
+
+- One step, one responsibility. Prefer small, composable steps over “kitchen‑sink” checks.
+- Declare intent before mechanics. Readers should see what a step is and when it runs before how it runs.
+- Guard and contract every important step. Preconditions (“assume” or “if”) up front, postconditions (“schema” or “guarantee”) after execution.
+- Avoid hidden control flow. Prefer declarative transitions and explicit dependencies over imperative logic.
+- Be idempotent, especially for external effects. Plan for retries and partial failures.
+
+## Recommended Key Order (Per Step)
+
+Use this top‑down order for every step. Omit sections that don’t apply.
+
+1) Identity & Intent
+- `type`
+- `criticality` (external | internal | policy | info)
+- `group`
+- `tags`
+- `description`
+
+2) Triggers & Dependencies
+- `on`
+- `depends_on`
+- `fanout` / `forEach` / `reduce`
+
+3) Preconditions (Guards)
+- `assume`
+- `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`
+- github: `op`, `values`
+- http/http_client/http_input: `url`, `method`, `body`, `headers`
+- log/memory/workflow/noop: minimal fields
+
+5) Contracts (Post‑Exec)
+- `schema` (renderer name or JSON Schema)
+- `guarantee`
+
+6) Failure Policies
+- `fail_if`
+- `continue_on_failure`
+
+7) Routing & Transitions
+- `on_success`
+- `on_fail`
+- `on_finish`
+
+8) Runtime Controls
+- `timeout`, `retries/backoff`, `env`
+- `namespace`, `reuse_ai_session`, `session_mode`
+
+9) Output Formatting
+- `template: { content | file }`
+- `message`, `level` (for `log`)
+
+## Criticality & Contracts (Default Safety)
+
+- `external`: side effects outside the repo/CI boundary (e.g., GitHub ops, webhooks).
+  - Require a precondition: `assume` (preferred) or `if`.
+  - If output‑producing, also require a post‑exec contract: `schema` or `guarantee`.
+  - Logical failures (schema/guarantee/fail_if) are not auto‑retried.
+
+- `internal`: orchestration/state within CI/repo (formerly “control‑plane”).
+  - Same enforcement as `external` (precondition + contract for output steps).
+  - No auto‑retry for logical failures.
+
+- `policy`: evaluative checks (security/perf/quality/docs). Optional guards/contracts.
+
+- `info`: purely informational; never gates dependents. Good for exploratory or advisory steps.
+
+Notes
+- Global `fail_if` is non‑gating by design; it marks the run status but must not block dependents.
+- Check‑level `fail_if` is gating (treated as fatal for routing).
+
+## Declarative Flow > Imperative Glue
+
+- Prefer `transitions` under `on_success` / `on_fail` / `on_finish` over imperative `goto_js`.
+- Keep transition expressions short, pure, and readable; use optional chaining and nullish coalescing for safety.
+
+Example
+
+```yaml
+on_finish:
+  transitions:
+    - when: "any(outputs_history['validate-fact'], v => v?.is_valid === false) && event.name === 'issue_opened'"
+      to: issue-assistant
+    - when: "any(outputs_history['validate-fact'], v => v?.is_valid === false) && event.name === 'issue_comment'"
+      to: comment-assistant
+    - when: "all(outputs_history['validate-fact'], v => v?.is_valid === true)"
+      to: null
+```
+
+## forEach (Fan‑Out) Patterns
+
+- Use `forEach: true` on the parent that produces an array; children with `fanout: map` run per item; with `fanout: reduce` run once (aggregate).
+- Empty arrays should skip dependents with a visible message and not increment stats.
+- Aggregate parents should route (on_success/on_fail) before committing; dependents read per‑scope outputs.
+
+Minimal Map + Aggregate
+
+```yaml
+extract-facts:
+  type: ai
+  on: [issue_opened]
+  forEach: true
+  prompt: |
+    Return JSON array of facts: [{ id, claim, verifiable }]
+  schema:
+    type: array
+    items:
+      type: object
+      required: [id, claim, verifiable]
+
+validate-fact:
+  type: ai
+  on: [issue_opened]
+  depends_on: [extract-facts]
+  fanout: map
+  prompt: "Validate: {{ outputs['extract-facts'].claim }}"
+
+aggregate:
+  type: script
+  on: [issue_opened]
+  depends_on: [validate-fact]
+  content: |
+    const all = (outputs.history['validate-fact']||[]).filter(Boolean);
+    return { all_valid: all.every(v => v?.is_valid === true) };
+  schema:
+    type: object
+    required: [all_valid]
+```
+
+## GitHub Ops (External)
+
+- Normalize values at the provider; still use `assume` to guard empties.
+- Keep idempotency: label adds/sets should tolerate duplicates and ordering.
+
+Example
+
+```yaml
+apply-issue-labels:
+  type: github
+  criticality: external
+  on: [issue_opened]
+  depends_on: [issue-assistant]
+  assume:
+    - "(outputs['issue-assistant']?.labels?.length ?? 0) > 0"
+  op: labels.add
+  values:
+    - "{{ outputs['issue-assistant'].labels | default: [] | json }}"
+```
+
+## Memory & Idempotency
+
+- Use `namespace` to avoid collisions.
+- Treat memory reads in `assume`/`if` as guards only; avoid side effects in expressions.
+- For external calls, design retry‑safe operations (check‑before‑write, idempotency keys).
+
+## YAML Style
+
+- 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.
+- Keep keys in the recommended order across all steps.
+
+## Do’s and Don’ts
+
+Do
+- Declare `criticality` and follow the guard/contract rules for `external`/`internal`.
+- Keep expressions short and defensive: `outputs?.x?.length ?? 0`.
+- Add `schema` whenever output shape matters (AI/script/command/http).
+
+Don’t
+- Hide control flow in templates or long `*_js` snippets.
+- Mix unrelated responsibilities in a single step.
+- Depend on outputs you didn’t guard (always use `assume`).
+
+## Quick Checklist (Per Step)
+
+- Identity: `type`, `criticality`, `group` set?
+- When: `on` clear and minimal?
+- Inputs: `depends_on` accurate? `assume` present for risky reads?
+- How: provider config minimal and readable?
+- Contracts: `schema` or `guarantee` (required for external/internal outputs)?
+- Policies: `fail_if` only for step‑specific gating?
+- Flow: transitions (`on_success`/`on_fail`/`on_finish`) instead of imperative glue?
+- Controls: timeouts and env only when necessary?
+
+## Complete Example (Well‑Structured External Labeling)
+
+```yaml
+apply-overview-labels:
+  type: github
+  criticality: external
+  tags: [github]
+  on: [pr_opened]
+  depends_on: [overview]
+  assume:
+    - "outputs['overview']?.tags?.label"
+    - "outputs['overview']?.tags?.['review-effort'] != null"
+  op: labels.add
+  values:
+    - "{{ outputs.overview.tags.label | default: '' | safe_label }}"
+    - "{{ outputs.overview.tags['review-effort'] | default: '' | prepend: 'review/effort:' | safe_label }}"
+```
+
+## References
+
+- Fault Management & Contracts
+- Criticality Modes
+- Dependencies & Routing
+

package/dist/docs/http.md

@@ -0,0 +1,299 @@
+## 🌐 HTTP Integration & Scheduling
+
+Visor provides comprehensive HTTP integration capabilities including webhook reception, HTTP outputs, scheduled executions via cron, and TLS/HTTPS support.
+
+### HTTP Server for Webhook Reception
+
+Configure an HTTP/HTTPS server to receive webhooks and trigger checks:
+
+```yaml
+version: "1.0"
+
+http_server:
+  enabled: true
+  port: 8080
+  host: "0.0.0.0"
+
+  # Optional TLS/HTTPS configuration
+  tls:
+    enabled: true
+    cert: "${TLS_CERT}"  # From environment variable
+    key: "${TLS_KEY}"
+    ca: "${TLS_CA}"      # Optional CA certificate
+    rejectUnauthorized: true
+
+  # Authentication
+  auth:
+    type: bearer_token
+    secret: "${WEBHOOK_SECRET}"
+
+  # Webhook endpoints
+  endpoints:
+    - path: "/webhook/github"
+      name: "github-events"
+    - path: "/webhook/jenkins"
+      name: "jenkins-builds"
+```
+
+Note: The HTTP server is automatically disabled when running in GitHub Actions to avoid conflicts.
+
+### Check Types for HTTP Integration
+
+#### 1. HTTP Input (Webhook Receiver)
+Receive data from configured webhook endpoints:
+
+```yaml
+steps:
+  github-webhook:
+    type: http_input
+    endpoint: "/webhook/github"
+    on: [webhook_received]
+    transform: |
+      {
+        "event": "{{ webhook.action }}",
+        "repository": "{{ webhook.repository.full_name }}"
+      }
+```
+
+#### 2. HTTP Output (Send Data)
+Send check results to external services:
+
+```yaml
+steps:
+  notify-external:
+    type: http
+    depends_on: [security-check]
+    url: "https://api.example.com/notify"
+    method: POST
+    headers:
+      Content-Type: "application/json"
+      Authorization: "Bearer ${API_TOKEN}"
+    body: |
+      {
+        "results": {{ outputs['security-check'] | json }},
+        "timestamp": "{{ 'now' | date: '%Y-%m-%d %H:%M:%S' }}"
+      }
+```
+
+#### 3. HTTP Client (Fetch Data)
+Fetch data from external APIs:
+
+```yaml
+steps:
+  fetch-config:
+    type: http_client
+    url: "https://api.example.com/config"
+    method: GET
+    headers:
+      Authorization: "Bearer ${API_TOKEN}"
+    transform: |
+      {
+        "settings": {{ response.data | json }},
+        "fetched_at": "{{ 'now' | date: '%Y-%m-%d' }}"
+      }
+```
+
+#### 4. Log Provider (Debugging & Monitoring)
+Output debugging information and monitor workflow execution:
+
+```yaml
+steps:
+  debug-start:
+    type: log
+    group: debugging
+    level: info
+    message: "🚀 Starting code review for PR #{{ pr.number }} by {{ pr.author }}"
+    include_pr_context: true
+    include_dependencies: false
+    include_metadata: true
+
+  debug-dependencies:
+    type: log
+    group: debugging
+    level: debug
+    depends_on: [security-check]
+    message: |
+      📊 Dependency results summary:
+      {% if dependencies %}
+      - Security check found {{ dependencies['security-check'].issueCount }} issues
+      {% else %}
+      - No dependencies processed
+      {% endif %}
+    include_dependencies: true
+
+  performance-monitor:
+    type: log
+    group: monitoring
+    level: warn
+    message: "⚠️ Large PR detected: {{ pr.totalAdditions }} lines added"
+```
+
+### Cron Scheduling
+
+```yaml
+steps:
+  nightly-security-scan:
+    type: ai
+    schedule: "0 3 * * *"  # Every day at 3am
+    prompt: "Run a deep security scan on the default branch"
+```
+
+```yaml
+steps:
+  weekly-health-check:
+    type: http_client
+    url: "https://api.example.com/health"
+    schedule: "0 0 * * 0"  # Every Sunday at midnight
+```
+
+### TLS/HTTPS Configuration
+
+You can configure TLS using environment variables, direct file paths, or Let's Encrypt.
+
+#### Environment Variables
+```yaml
+tls:
+  enabled: true
+  cert: "${TLS_CERT}"
+  key: "${TLS_KEY}"
+```
+
+#### File Paths
+```yaml
+tls:
+  enabled: true
+  cert: "/etc/ssl/certs/server.crt"
+  key: "/etc/ssl/private/server.key"
+```
+
+#### Let's Encrypt
+```yaml
+tls:
+  enabled: true
+  cert: "/etc/letsencrypt/live/example.com/fullchain.pem"
+  key: "/etc/letsencrypt/live/example.com/privkey.pem"
+```
+
+### HTTP Security Features
+
+Visor's HTTP server includes comprehensive security protections:
+
+#### Authentication Methods
+```yaml
+# Bearer Token Authentication
+auth:
+  type: bearer_token
+  secret: "${WEBHOOK_SECRET}"
+
+# HMAC-SHA256 Signature Verification
+auth:
+  type: hmac
+  secret: "${WEBHOOK_SECRET}"
+
+# Basic Authentication
+auth:
+  type: basic
+  username: "${HTTP_USERNAME}"
+  password: "${HTTP_PASSWORD}"
+```
+
+#### HMAC Authentication Details
+For `hmac` authentication, webhooks must include the `x-webhook-signature` header:
+- Signature format: `sha256={hash}`
+- Uses HMAC-SHA256 with the configured secret
+- Implements timing-safe comparison to prevent timing attacks
+- Compatible with GitHub webhook signatures
+
+#### DoS Protection
+- Request size limits: Maximum 1MB request body size
+- Early rejection: Validates `Content-Length` header before processing
+- Graceful error handling: Returns proper HTTP status codes (413 Payload Too Large)
+
+#### Security Best Practices
+- Environment detection: Automatically disables in GitHub Actions
+- TLS support: Full HTTPS configuration with custom certificates
+- Input validation: Validates all webhook payloads before processing
+- Error isolation: Security failures don't affect independent checks
+
+### Complete HTTP Pipeline Example
+
+```yaml
+version: "1.0"
+
+# HTTP server configuration
+http_server:
+  enabled: true
+  port: 8443
+  tls:
+    enabled: true
+    cert: "${TLS_CERT}"
+    key: "${TLS_KEY}"
+  auth:
+    type: bearer_token
+    secret: "${WEBHOOK_SECRET}"
+  endpoints:
+    - path: "/webhook/deployment"
+      name: "deployment-trigger"
+
+steps:
+  # 1. Receive webhook
+  deployment-webhook:
+    type: http_input
+    endpoint: "/webhook/deployment"
+    on: [webhook_received]
+    transform: |
+      {
+        "version": "{{ webhook.version }}",
+        "environment": "{{ webhook.environment }}"
+      }
+
+  # 2. Analyze deployment
+  deployment-analysis:
+    type: ai
+    depends_on: [deployment-webhook]
+    prompt: |
+      Analyze deployment for version {{ outputs['deployment-webhook'].suggestions | first }}
+      Check for potential issues and risks
+
+  # 3. Fetch current status
+  current-status:
+    type: http_client
+    depends_on: [deployment-webhook]
+    url: "https://api.example.com/status"
+    method: GET
+
+  # 4. Send results
+  notify-team:
+    type: http
+    depends_on: [deployment-analysis, current-status]
+    url: "https://slack.example.com/webhook"
+    body: |
+      {
+        "text": "Deployment Analysis Complete",
+        "analysis": {{ outputs['deployment-analysis'] | json }},
+        "current_status": {{ outputs['current-status'] | json }}
+      }
+
+  # 5. Scheduled health check
+  health-check:
+    type: http_client
+    url: "https://api.example.com/health"
+    schedule: "*/5 * * * *"  # Every 5 minutes
+    transform: |
+      {
+        "status": "{{ response.status }}",
+        "checked_at": "{{ 'now' | date: '%Y-%m-%d %H:%M:%S' }}"
+      }
+```
+
+### Liquid Template Support
+
+All HTTP configurations support Liquid templating for dynamic content. See [Liquid Templates Guide](./liquid-templates.md) for complete reference.
+
+Common patterns:
+- Access webhook data: `{{ webhook.field }}`
+- Access headers: `{{ headers['x-custom-header'] }}`
+- Access previous outputs: `{{ outputs['check-name'].suggestions | first }}`
+- Date formatting: `{{ 'now' | date: '%Y-%m-%d' }}`
+- JSON encoding: `{{ data | json }}` (useful for debugging objects)
+