@probelabs/visor 0.1.127 → 0.1.129

package/dist/defaults/.visor.yaml

@@ -0,0 +1,420 @@
+version: "1.0"
+
+# Default Visor configuration - provides comprehensive code analysis out-of-the-box
+# Uses mock provider for CI compatibility when no AI API keys are configured
+# Users can override this by creating their own .visor.yaml in their project root
+
+# Global AI provider settings - users should configure their preferred provider
+# For CI testing, use --provider mock CLI flag instead
+
+# Run checks sequentially to ensure session reuse works correctly
+max_parallelism: 1
+
+# 🔄 AI Session Reuse Feature:
+# This configuration demonstrates the new 'reuse_ai_session' feature that allows
+# dependent checks to continue conversations with the same AI session, providing
+# context continuity and more intelligent follow-up analysis.
+#
+# Example: security-remediation reuses the session from the security check,
+# allowing the AI to reference the previous security analysis discussion.
+
+# Global fail condition - fail if critical or error severity issues are found
+fail_if: "output.issues && output.issues.some(i => i.severity === 'critical' || i.severity === 'error')"
+
+checks:
+  # AI-powered release notes generation - manual execution only for release workflows
+  release-notes:
+    type: ai
+    group: release
+    schema: plain
+    prompt: |
+      Generate professional release notes for version {{ env.TAG_NAME }} of this project.
+
+      Analyze the git commits since the last release:
+      ```
+      {{ env.GIT_LOG }}
+      ```
+
+      And the file changes summary:
+      ```
+      {{ env.GIT_DIFF_STAT }}
+      ```
+
+      Create release notes with these sections:
+
+      ## 🚀 What's New in {{ env.TAG_NAME }}
+
+      ### ✨ New Features
+      List any new features added (look for feat: commits)
+
+      ### 🐛 Bug Fixes
+      List any bugs fixed (look for fix: commits)
+
+      ### 📈 Improvements
+      List any improvements or refactoring (look for refactor:, perf:, chore:, build: commits)
+
+      ### 🔥 Breaking Changes
+      List any breaking changes if present (look for BREAKING CHANGE or ! in commits)
+
+      ### 📊 Statistics
+      - Number of commits since last release
+      - Number of contributors involved
+      - Number of files changed
+
+      Keep descriptions concise and user-friendly. Focus on what changed from a user perspective, not implementation details.
+      Use present tense and action-oriented language. Group similar changes together.
+    on: [manual]
+
+  # PR overview with intelligent analysis - runs first to establish context
+  overview:
+    type: ai
+    group: overview
+    prompt: |
+        # 📋 Pull Request Overview: {{ pr.title }}
+
+        {% if pr.body %}
+        ## Description
+        {{ pr.body }}
+        {% endif %}
+
+        ## Files Changed Analysis
+
+        Analyze the files listed in the `<files_summary>` section, which provides a structured overview of all changes including filenames, status, additions, and deletions.
+
+        ## Architecture & Impact Assessment
+
+        Please generate a comprehensive overview and analysis of this pull request.
+
+        Follow these instructions to create a thorough assessment:
+
+        1. **Change Impact Analysis**
+           - What this PR accomplishes
+           - Key technical changes introduced
+           - Affected system components
+
+        2. **Architecture Visualization**
+           - Create appropriate mermaid diagram(s) to visualize the changes
+           - Choose the best diagram type for the context
+           - Use multiple diagrams if needed to explain different aspects
+           - Focus on modified components and their relationships
+
+        Provide a balanced technical assessment suitable for both developers and stakeholders.
+    on: [pr_opened, pr_updated]
+
+  # Security analysis - Critical for all projects
+  security:
+    type: ai
+    group: review
+    schema: code-review
+    prompt: |
+        Based on our overview discussion, please perform a comprehensive security analysis of the code changes.
+
+        Analyze the files listed in the `<files_summary>` section and focus on the code changes shown in the diff sections.
+
+        ## Security Analysis Areas
+
+        **Input Validation & Injection:**
+        - SQL injection in database queries
+        - XSS vulnerabilities in user input handling
+        - Command injection in system calls
+        - Path traversal in file operations
+
+        **Authentication & Authorization:**
+        - Weak authentication mechanisms
+        - Session management flaws
+        - Access control bypasses
+        - Privilege escalation opportunities
+
+        **Data Protection:**
+        - Sensitive data exposure in logs/errors
+        - Unencrypted data storage
+        - API key or credential leaks
+        - Privacy regulation compliance
+
+        **Infrastructure Security:**
+        - Insecure configurations
+        - Missing security headers
+        - Vulnerable dependencies
+        - Resource exhaustion vulnerabilities
+
+        Provide specific findings with clear explanations and actionable remediation steps.
+
+        ## Severity Guidelines
+        Use the following severity levels appropriately:
+        - **critical**: Security vulnerabilities that could lead to immediate compromise (RCE, SQL injection, authentication bypass, exposed secrets)
+        - **error**: Security issues that must be fixed before production (XSS, path traversal, weak crypto, missing auth checks)
+        - **warning**: Security concerns that should be addressed (verbose errors, missing rate limiting, insecure defaults)
+        - **info**: Security best practices and hardening suggestions (defense in depth, additional validation)
+    depends_on: [overview]
+    reuse_ai_session: true  # 🔄 Reuses the overview check's AI session for context continuity
+    on: [pr_opened, pr_updated]
+
+  # Performance analysis - Important for all applications
+  performance:
+    type: ai
+    group: review
+    schema: code-review
+    prompt: |
+        Building on our overview and security analysis, now review the code changes for performance issues.
+
+        Focus on the files listed in `<files_summary>` and analyze the code changes shown in the `<full_diff>` or `<commit_diff>` sections.
+
+        ## Performance Analysis Areas
+        **Algorithm & Data Structure Efficiency:**
+        - Time complexity analysis (O(n), O(n²), etc.)
+        - Space complexity and memory usage
+        - Inefficient loops and nested operations
+        - Suboptimal data structure choices
+
+        **Database Performance:**
+        - N+1 query problems
+        - Missing database indexes
+        - Inefficient JOIN operations
+        - Large result set retrievals
+
+        **Resource Management:**
+        - Memory leaks and excessive allocations
+        - File handle management
+        - Connection pooling issues
+        - Resource cleanup patterns
+
+        **Async & Concurrency:**
+        - Blocking operations in async contexts
+        - Race conditions and deadlocks
+        - Inefficient parallel processing
+
+        Building on our overview and security analysis, identify performance issues and provide optimization recommendations that complement our previous findings.
+
+        ## Severity Guidelines
+        Use the following severity levels appropriately:
+        - **critical**: Performance issues causing system failure or severe degradation (infinite loops, memory leaks causing OOM)
+        - **error**: Significant performance problems affecting user experience (O(n²) in critical path, N+1 queries, blocking I/O)
+        - **warning**: Performance concerns that should be optimized (inefficient algorithms, missing indexes, unnecessary operations)
+        - **info**: Performance best practices and optimization opportunities (caching suggestions, async improvements)
+    depends_on: [security]
+    reuse_ai_session: true  # 🔄 Reuses the security check's AI session for context continuity
+    on: [pr_opened, pr_updated]
+
+  # Code quality and maintainability
+  quality:
+    type: ai
+    group: review
+    schema: code-review
+    prompt: |
+        Building on our overview, security, and performance discussions, evaluate the code quality and maintainability.
+
+        Review the code changes shown in the `<full_diff>` or `<commit_diff>` sections, considering the files listed in `<files_summary>`.
+
+        ## Quality Assessment Areas
+        **Code Structure & Design:**
+        - SOLID principles adherence
+        - Design pattern appropriateness
+        - Separation of concerns
+        - Code organization and clarity
+
+        **Error Handling & Reliability:**
+        - Exception handling completeness
+        - Error propagation patterns
+        - Input validation thoroughness
+        - Edge case coverage
+
+        **Testing & Test Coverage:**
+        - Missing tests for critical functionality
+        - Test coverage gaps
+        - Test quality and effectiveness
+        - Edge cases and error scenarios coverage
+
+        **Maintainability:**
+        - Code testability issues
+        - Dependencies and coupling problems
+        - Technical debt introduction
+        - Code duplication (DRY violations)
+
+        **Language-Specific Best Practices:**
+        - Idiomatic code usage
+        - Framework/library best practices
+        - Type safety (if applicable)
+
+        Focus on actionable improvements that enhance code maintainability while considering the overview, security, and performance findings we've already discussed.
+
+        ## Severity Guidelines
+        Use the following severity levels appropriately:
+        - **critical**: Code quality issues that will cause bugs or failures (logic errors, race conditions, null pointer issues)
+        - **error**: Quality problems that significantly impact maintainability (no error handling, high complexity, severe coupling)
+        - **warning**: Quality concerns that should be addressed (missing tests, code duplication, poor naming)
+        - **info**: Best practices and improvement suggestions (refactoring opportunities, documentation improvements)
+    depends_on: [performance]
+    reuse_ai_session: true  # 🔄 Reuses the performance check's AI session for context continuity
+    on: [pr_opened, pr_updated]
+
+  # Code style and formatting analysis
+  style:
+    type: ai
+    group: review
+    schema: code-review
+    prompt: |
+        Building on our overview, security, performance, and quality discussions, analyze the code style and formatting consistency.
+
+        Review the code changes shown in the `<full_diff>` or `<commit_diff>` sections, considering the files listed in `<files_summary>`.
+
+        ## Style Assessment Areas
+        **Code Formatting & Consistency:**
+        - Indentation and spacing consistency
+        - Naming conventions adherence
+        - Code organization and structure
+        - Comment style and documentation
+
+        **Language-Specific Style Guidelines:**
+        - Adherence to language style guides (PEP 8, ESLint, etc.)
+        - Import/require statement organization
+        - Variable and function naming patterns
+        - Code readability and clarity
+
+        **Team Standards:**
+        - Consistency with existing codebase patterns
+        - Formatting tool configuration compliance
+        - Documentation standards adherence
+        - Code comment quality and completeness
+
+        Focus on style improvements that enhance code readability and maintainability while considering our previous analysis.
+
+        ## Severity Guidelines
+        Use the following severity levels appropriately:
+        - **critical**: Never use for style issues (style issues are never critical)
+        - **error**: Major style violations that significantly harm readability (completely inconsistent formatting, misleading names)
+        - **warning**: Style inconsistencies that should be fixed (mixed conventions, unclear naming, formatting issues)
+        - **info**: Style suggestions and minor improvements (spacing, comment formatting, optional conventions)
+    depends_on: [quality]
+    reuse_ai_session: true  # 🔄 Reuses the quality check's AI session for context continuity
+    on: [pr_opened, pr_updated]
+
+  # Command orchestrator - demonstrates noop type for triggering multiple checks
+  review-all:
+    type: noop
+    command: '/review'
+    depends_on: [overview, security, performance, quality, style]
+    on: [issue_comment]
+    if: "event.isPullRequest"  # Only trigger on PR comments, not issues
+    group: orchestrator
+
+  # Intelligent Issue Assistant - provides sophisticated issue triage and assistance
+  issue-assistant:
+    type: ai
+    group: dynamic  # Special group: creates new comment each time instead of updating
+    command: "visor"
+    if: "event.name === 'issues' && event.action === 'opened' || (event.name === 'issue_comment' && event.comment && event.comment.body && event.comment.body.trim().startsWith('/visor'))"
+    prompt: |
+        You are an intelligent GitHub issue assistant for the {{ event.repository.fullName }} repository. Your role is to provide professional, knowledgeable assistance based on the trigger event.
+
+        ## Event Context
+        **Event Type**: {{ event.name }} - {{ event.action }}
+        {% if event.issue -%}
+        **Issue #{{ event.issue.number }}**: {{ event.issue.title }}
+        **Author**: {{ event.issue.author }}
+        **State**: {{ event.issue.state }}
+        **Created**: {{ event.issue.createdAt }}
+        {%- if event.issue.labels.size > 0 %}
+        **Labels**: {% for label in event.issue.labels %}{{ label.name }}{% unless forloop.last %}, {% endunless %}{% endfor %}
+        {%- endif %}
+        {%- if event.issue.assignees.size > 0 %}
+        **Assignees**: {% for assignee in event.issue.assignees %}{{ assignee }}{% unless forloop.last %}, {% endunless %}{% endfor %}
+        {%- endif %}
+        {%- endif %}
+        {%- if event.comment %}
+        **Comment by**: {{ event.comment.author }}
+        {%- endif %}
+
+        ## Repository Analysis Context
+        {%- if event.isPullRequest and pr.title %}
+        **PR Context**: {{ pr.title }}
+        {%- endif %}
+        {%- if event.repository %}
+        **Repository**: {{ event.repository.fullName }}
+        {%- endif %}
+
+        ## Instructions
+
+        {%- if event.name == 'issues' and event.action == 'opened' %}
+
+        **ISSUE TRIAGE MODE**
+
+        Analyze this new issue and provide intelligent triage:
+
+        ### Issue Content
+        {{ event.issue.body }}
+
+        ### Analysis Tasks
+        1. **Categorize** the issue (bug/feature/documentation/question/enhancement/maintenance)
+        2. **Assess priority** (low/medium/high/urgent) based on:
+           - Impact on users/system
+           - Security implications
+           - Blocking nature
+           - Community interest
+        3. **Estimate complexity** (trivial/simple/moderate/complex)
+        4. **Suggest timeline** for resolution
+        5. **Recommend labels** that would help with organization
+        6. **Identify stakeholders** who should be involved or assignees
+        7. **Provide initial response** to the issue author
+
+        ### Response Requirements
+        - Be professional and welcoming
+        - Show you understand the request
+        - Provide clear next steps
+        - Ask clarifying questions if needed
+        - Include technical insights where appropriate
+
+        {%- elsif event.name == 'issue_comment' %}
+
+        **ASSISTANCE MODE**
+
+        A user has asked a question or provided additional information. Provide helpful technical assistance:
+
+        ### Original Issue
+        {%- if event.issue.title %}
+        **Title**: {{ event.issue.title }}
+        {%- endif %}
+        {%- if event.issue.body %}
+        **Description**: {{ event.issue.body }}
+        {%- endif %}
+
+        ### Latest Comment
+        {{ event.comment.body }}
+
+        ### Analysis Tasks
+        1. **Understand the context** of their question/comment
+        2. **Provide technical guidance** based on project knowledge
+        3. **Reference relevant code/files** if applicable
+        4. **Suggest implementation approaches** for feature requests
+        5. **Provide debugging steps** for bug reports
+        6. **Link to documentation** or similar issues if helpful
+        7. **Offer code examples** when appropriate
+
+        ### Response Requirements
+        - Address their specific question directly
+        - Provide actionable guidance
+        - Be encouraging and supportive
+        - Use technical language appropriate to their level
+        - Include code examples where helpful
+        - Reference project conventions and patterns
+
+        {%- endif %}
+
+        ### Special Instructions
+        - Always be professional, helpful, and encouraging
+        - Focus on actionable advice and clear next steps
+        - Use markdown formatting for better readability
+        - Include relevant code examples when helpful
+        - Reference project context and patterns when applicable
+        - If dealing with `/visor` commands in comments, acknowledge and provide assistance
+        - Maintain consistency with project tone and contributor guidelines
+
+        ### Response Format
+        Provide a well-structured markdown response with clear sections and helpful guidance.
+    on: [issue_opened, issue_comment]
+
+# Output configuration
+output:
+  pr_comment:
+    format: markdown
+    group_by: check
+    collapse: true

package/dist/docs/commands.md

@@ -104,7 +104,7 @@ visor mcp-server [options]
 - `--config <path>` - Path to configuration file
 
 #### Execution Control
-- `--timeout <ms>` - Timeout for operations (default: 1200000ms / 20 minutes)
+- `--timeout <ms>` - Timeout for operations (default: 1200000ms / 30 minutes)
 - `--max-parallelism <count>` - Maximum parallel checks (default: 3)
 - `--fail-fast` - Stop execution on first failure
 

package/dist/docs/debugging.md

@@ -3,6 +3,7 @@
 This guide provides comprehensive debugging techniques and tools to help troubleshoot Visor configurations, checks, and transformations.
 
 ## Table of Contents
+- [Running Visor Locally](#running-visor-locally)
 - [Debug Mode](#debug-mode)
 - [Debugging JavaScript Expressions](#debugging-javascript-expressions)
 - [Debugging Liquid Templates](#debugging-liquid-templates)
@@ -13,6 +14,138 @@ This guide provides comprehensive debugging techniques and tools to help trouble
 - [Tracing with OpenTelemetry](#tracing-with-opentelemetry)
 - [Debug Visualizer](#debug-visualizer)
 
+## Running Visor Locally
+
+### Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run the CLI
+./dist/cli-main.js --help
+# or
+./dist/index.js --help
+```
+
+### Basic CLI Usage
+
+```bash
+# Run with a config file
+./dist/index.js --config ./examples/calculator-config.yaml
+
+# Run specific checks only
+./dist/index.js --config .visor.yaml --check security,lint
+
+# Run with debug output
+./dist/index.js --config .visor.yaml --debug
+
+# Output in different formats
+./dist/index.js --config .visor.yaml --output json
+./dist/index.js --config .visor.yaml --output markdown
+./dist/index.js --config .visor.yaml --output sarif
+
+# Pass inline messages for human-input checks
+./dist/index.js --config ./examples/calculator-config.yaml --message "42"
+```
+
+### TUI Mode (Interactive Terminal Interface)
+
+The `--tui` flag enables a persistent terminal interface for any workflow. The workflow runs immediately, and you can re-run it by typing new messages after completion:
+
+```bash
+# Start with TUI mode
+./dist/index.js --tui --config ./examples/calculator-config.yaml
+
+# TUI with debug output (logs go to second tab)
+./dist/index.js --tui --config .visor.yaml --debug
+```
+
+**TUI Features:**
+- **Chat Tab**: Shows workflow prompts and results in a chat-like interface
+- **Logs Tab**: Press `Shift+Tab` or `2` to switch to logs view
+- **Traces Tab**: Real-time OpenTelemetry trace visualization with execution tree
+- **Persistent Input**: Type messages at any time to interact with the workflow
+- **Re-run Workflows**: After completion, type a new message to re-run
+
+**TUI Key Bindings:**
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit input |
+| `Shift+Tab` | Cycle between Chat, Logs, and Traces tabs |
+| `1` / `2` / `3` | Switch to Chat / Logs / Traces tab directly |
+| `e` | Toggle engine state visibility (Traces tab only) |
+| `Escape` | Clear input |
+| `Ctrl+C` | Exit / Abort workflow |
+| `q` | Exit (when workflow is complete) |
+
+**Traces Tab Features:**
+- Real-time execution tree showing check hierarchy
+- forEach iterations grouped under parent check with index
+- IN/OUT/ERR lines showing inputs, outputs, and errors for each span
+- Press `e` to toggle engine state spans (LevelDispatch, WavePlanning, etc.)
+- Engine states hidden by default to focus on your checks
+
+### Debug Server (Visual Debugger)
+
+The debug server provides a web-based UI for stepping through workflow execution:
+
+```bash
+# Start with debug server
+./dist/index.js --config .visor.yaml --debug-server --debug-port 3456
+
+# For headless/CI environments (skip auto-opening browser)
+VISOR_NOBROWSER=true ./dist/index.js --config .visor.yaml --debug-server
+```
+
+Open http://localhost:3456 to view the visual debugger. You can:
+- Click "Start" to begin execution
+- Pause/resume workflow execution
+- View spans and timing information
+- See check outputs and errors
+
+### Combining Debug Options
+
+```bash
+# TUI + Debug mode (verbose logging in logs tab)
+./dist/index.js --tui --config .visor.yaml --debug
+
+# Debug server + Debug mode (full visibility)
+./dist/index.js --config .visor.yaml --debug-server --debug
+
+# Full tracing with Jaeger
+VISOR_TELEMETRY_ENABLED=true \
+VISOR_TELEMETRY_SINK=otlp \
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
+./dist/index.js --config .visor.yaml --debug
+```
+
+### Development Workflow Tips
+
+1. **Use TUI for interactive workflows**: When developing workflows with human-input checks, TUI mode provides the best experience.
+
+2. **Check logs and traces tabs**: In TUI mode, press `Shift+Tab` to cycle tabs. Use the Logs tab for detailed execution logs and the Traces tab for visual execution flow.
+
+3. **Use JSON output for debugging**: `--output json` gives you the full result structure to inspect.
+
+4. **Watch mode for rapid iteration**:
+   ```bash
+   # In one terminal - watch and rebuild
+   npm run build -- --watch
+
+   # In another terminal - run your workflow
+   ./dist/index.js --tui --config ./my-workflow.yaml
+   ```
+
+5. **Run tests for specific features**:
+   ```bash
+   npm test -- --testPathPattern="human-input"
+   npm test -- --testPathPattern="memory"
+   ```
+
 ## Debug Mode
 
 Enable debug mode to see detailed execution information:

package/dist/docs/dev-playbook.md

@@ -66,6 +66,16 @@ npm test
 | `npm run simulate:issue` | Simulate GitHub issue event |
 | `npm run simulate:comment` | Simulate GitHub comment event |
 
+#### Running Locally
+| Command | Description |
+|---------|-------------|
+| `./dist/index.js --config .visor.yaml` | Run with config file |
+| `./dist/index.js --tui --config ./workflow.yaml` | Interactive TUI mode |
+| `./dist/index.js --debug-server --debug-port 3456` | Visual debugger |
+| `./dist/index.js --tui --debug` | TUI with debug logging |
+
+See [Debugging Guide](debugging.md) for complete local development documentation.
+
 ### Using Visor Effectively
 
 - **Start with defaults**: Copy `defaults/visor.yaml` or an example from `examples/`; run `npx -y @probelabs/visor@latest --check all --debug`.

package/dist/docs/index.md

@@ -116,6 +116,7 @@ The test framework allows you to write integration tests for your Visor workflow
 |----------|-------------|
 | [GitHub Checks](./GITHUB_CHECKS.md) | GitHub Checks API integration for PR status reporting |
 | [Slack Integration](./slack-integration.md) | Bidirectional Slack integration via Socket Mode |
+| [Scheduler](./scheduler.md) | Schedule workflows and reminders to run at specified times |
 | [Deployment](./DEPLOYMENT.md) | Cloudflare Pages deployment for landing page |
 
 ---