supavision 0.1.0__tar.gz

supavision-0.1.0/.dockerignore

@@ -0,0 +1,11 @@
+.venv
+.git
+.pytest_cache
+.ruff_cache
+.supavision
+__pycache__
+*.pyc
+tests/
+.env
+.coverage
+.review-loop

supavision-0.1.0/.env.example

@@ -0,0 +1,21 @@
+# Backend: claude_cli (default, free with subscription) or openrouter (API key)
+# SUPAVISION_BACKEND=claude_cli
+
+# Required ONLY if using openrouter backend
+# OPENROUTER_API_KEY=sk-or-your-key-here
+
+# Optional — Slack webhook for alerts (can also be set per-resource)
+# SLACK_WEBHOOK=https://hooks.slack.com/services/xxx/yyy/zzz
+
+# Optional — override defaults
+# SUPAVISION_MODEL=anthropic/claude-sonnet-4
+# SUPAVISION_CHECK_INTERVAL=60
+# SUPAVISION_CLI_TIMEOUT=900
+
+# Dashboard authentication (recommended for production)
+# Set a password to require login. Leave unset for open access.
+# SUPAVISION_PASSWORD=your-secure-password
+# SUPAVISION_USER=admin
+
+# Webhook security — restrict allowed webhook domains
+# WEBHOOK_ALLOWED_DOMAINS=hooks.slack.com,discord.com

supavision-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+labels: bug
+---
+
+**What happened?**
+A clear description of the bug.
+
+**Steps to reproduce**
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- OS: [e.g. Ubuntu 24.04]
+- Python: [e.g. 3.12]
+- Backend: [claude_cli / openrouter]
+- Version: [e.g. 0.1.0]
+
+**Logs** (if applicable)
+```
+Paste relevant logs here
+```

supavision-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+**What problem does this solve?**
+Describe the use case.
+
+**Proposed solution**
+How you'd like it to work.
+
+**Alternatives considered**
+Other approaches you've thought about.

supavision-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## What does this PR do?
+
+Brief description of the change.
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/`)
+- [ ] Lint passes (`ruff check src/ tests/`)
+- [ ] Updated README if adding user-facing features
+- [ ] No new dependencies unless discussed in an issue first

supavision-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest tests/ -v --tb=short

supavision-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Build artifacts
+*.egg-info/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Supervisor runtime
+.env
+.supavision/
+
+# Internal planning
+.review-loop/
+SUPERVISOR_NEXT_DIRECTION.md
+
+# Logs
+*.log

supavision-0.1.0/.supervisor/locks/1d8a4060-d88b-4b94-ad1f-9791dccd14fa.lock

@@ -0,0 +1 @@
+445889

supavision-0.1.0/.supervisor/locks/5953f122-9413-403c-b10a-93b033ceef8c.lock

@@ -0,0 +1 @@
+274693

supavision-0.1.0/.supervisor/locks/d575d0fb-b566-4b34-8844-12204d0fa1bd.lock

@@ -0,0 +1 @@
+616038

supavision-0.1.0/.supervisor/scheduler.lock

@@ -0,0 +1 @@
+630635

supavision-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# Architecture: Two-Lane Design
+
+Supavision monitors two kinds of resources: **infrastructure** (servers, AWS, databases) and **codebases** (local projects). These produce fundamentally different outputs and follow different lifecycles, so the data model splits into two parallel lanes.
+
+## The Two Lanes
+
+```
+                          Resource
+                         /        \
+              ┌─────────┘          └──────────┐
+              │                               │
+         LANE 1: Health                  LANE 2: Work
+    (resource-level pulse)          (per-issue lifecycle)
+              │                               │
+         Run → Report → Evaluation       WorkItem (Finding | ManualTask)
+              │                               │
+    "Is this resource healthy?"      "Is this specific issue real?
+     Severity: healthy/warning/       Should we fix it? Track it
+     critical. One per run.           through eval → approve →
+     Aggregate narrative."            implement → complete."
+```
+
+## Rules
+
+### Lane 1 (Health)
+- **Report** = aggregate narrative about a resource's overall state. One per Run. Used for health dashboards and alerting. Never contains per-issue lifecycle state.
+- **Evaluation** = severity assessment of a Report. Answers "how healthy is this resource?" Uses `Severity` (healthy/warning/critical). Stored in the `evaluations` table.
+
+### Lane 2 (Work)
+- **WorkItem** = a single actionable issue with its own lifecycle. Has a stage (scanned/evaluated/approved/implementing/completed/rejected/dismissed), its own agent jobs, feedback, and transitions.
+- **Finding-level evaluation** is stored as fields ON the WorkItem (`evaluation_verdict`, `evaluation_reasoning`, `fix_approach`), NOT as a row in the `evaluations` table.
+
+### The Boundary
+- Code that touches Lane 1 must never import WorkItem models.
+- Code that touches Lane 2 must never write to the `evaluations` table.
+- The only place both lanes appear together is the resource detail page in the UI.
+
+## Import Rules
+
+```
+models/
+├── core.py    ← Shared: Resource, Run, Credential, Schedule (both lanes)
+├── health.py  ← Lane 1: Report, Evaluation, Severity, SystemContext, Checklist
+└── work.py    ← Lane 2: Finding, ManualTask, AgentJob, Transition, BlocklistEntry
+```
+
+| Domain | Imports from |
+|--------|-------------|
+| Infrastructure (engine.py, evaluator.py, tools.py, executor.py, discovery_diff.py) | `models.core` + `models.health` only |
+| Codebase (scanner.py, blocklist.py, agent_runner.py, code_evaluator.py) | `models.core` + `models.work` only |
+| Shared (db.py, web/, cli.py, scheduler.py, mcp.py) | All models (via `models.__init__`) |
+
+Enforced by `tests/test_lane_boundary.py` (AST-based import verification).
+
+## Anti-Patterns (Do Not)
+
+1. **Do not add lifecycle stages to Reports.** Reports are snapshots, not workflows.
+2. **Do not use WorkItems for infrastructure health.** "High CPU" is a Report with severity=warning, not a WorkItem.
+3. **Do not nest WorkItems inside Reports.** They share a parent Resource and a Run ID, but are siblings, not parent-child.
+4. **Do not write finding verdicts to the evaluations table.** Finding-level judgments live on the WorkItem model.

supavision-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 (2026-03-31)
+
+Initial release.
+
+### Features
+- AI-powered server discovery and health checks via Claude Code CLI
+- Web dashboard with dark theme, resource management, real-time updates
+- 5 resource types: Server, AWS Account, Database, GitHub Organization
+- REST API with API key authentication and OpenAPI docs
+- Slack webhook notifications with smart dedup (24h TTL)
+- Rule-based severity evaluation (zero additional LLM cost)
+- Type-aware resource creation wizard
+- Resource pause/resume, search/filter, pagination
+- Responsive design (desktop + mobile)
+- Custom CSS design system (zero framework dependencies)
+- 340 tests, CI with GitHub Actions
+- Docker support with healthcheck
+
+### Resource Types
+- **Server** — SSH-based monitoring of Linux servers
+- **AWS Account** — CloudWatch, Lambda, EC2, IAM, cost monitoring
+- **Database** — PostgreSQL/MySQL health, schema, replication
+- **GitHub Organization** — branch protection, security alerts, PRs
+
+### Backends
+- **claude_cli** (default) — uses Claude Code CLI, covered by Claude subscription
+- **openrouter** — uses OpenRouter API, pay-per-token

supavision-0.1.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+## Commands
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests/ -v
+.venv/bin/ruff check src/ tests/
+.venv/bin/uvicorn supervisor.web.app:create_app --factory --port 8080
+```
+
+## Architecture
+
+Two-lane design. See `ARCHITECTURE.md` for the full rationale.
+
+**Lane 1 (Health):** Resource → Run → Report → Evaluation → Alert
+  Infrastructure monitoring. CLI: `engine.py` → Claude CLI subprocess.
+
+**Lane 2 (Work):** Resource → WorkItem (Finding | ManualTask) → AgentJob
+  Codebase improvement. CLI: `codebase_engine.py` → scanner + agent_runner.
+
+Both lanes share: Resource, Run, Store (SQLite WAL), Scheduler, Notifications, MCP.
+
+### Models package
+```
+models/
+├── core.py    — Shared: Resource, Run, Credential, Schedule
+├── health.py  — Lane 1: Report, Evaluation, Severity, SystemContext, Checklist
+└── work.py    — Lane 2: Finding, ManualTask, AgentJob, FindingStage, BlocklistEntry
+```
+
+Import rules enforced by `tests/test_lane_boundary.py` (AST-based).
+
+## Key files
+
+### Infrastructure domain (Lane 1)
+- `engine.py` — Core run logic, Claude CLI integration, SSE output streaming
+- `evaluator.py` — Rule-based severity assessment (zero LLM cost)
+- `executor.py` — SSH command execution with multiplexing
+- `tools.py` — Scoped read-only tools for infrastructure investigation
+- `discovery_diff.py` — Drift detection between baselines
+
+### Codebase domain (Lane 2)
+- `codebase_engine.py` — Orchestrates scan, evaluate, implement, scout
+- `scanner.py` — 81 regex security patterns across 9 languages (zero cost)
+- `blocklist.py` — False-positive learning from rejection feedback
+- `agent_runner.py` — Background thread job executor (Claude Code subprocess)
+- `code_evaluator.py` — Evaluation prompt generation
+- `prompt_builder.py` — Implementation prompt generation
+
+### Shared
+- `mcp.py` — MCP server (9 tools: 4 health + 5 work), JSON-RPC over stdio
+- `scheduler.py` — Cron-based job scheduling with `asyncio.Semaphore(3)`
+- `notifications.py` — Slack + webhook alerts with SSRF protection and dedup
+- `db.py` — SQLite store with WAL mode, thread-safe via RLock
+- `web/dashboard.py` — All dashboard routes (resources, findings, settings, SSE)
+- `web/routes.py` — REST API (resources CRUD + codebase scan endpoint)
+
+## Adding resource types
+
+1. Create `templates/{type_name}/discovery.md` and `templates/{type_name}/health_check.md`
+2. Add entry to `resource_types.py`
+3. Templates use `{{resource_name}}`, `{{ssh_host}}`, etc. as placeholders
+
+## Codebase CLI commands
+
+```bash
+supavision scan <resource_id>          # Run regex scan
+supavision findings <resource_id>      # List findings
+supavision evaluate <work_item_id>     # Create evaluation job
+supavision implement <work_item_id>    # Create implementation job
+supavision scout <resource_id>         # Launch scout agent
+supavision approve <work_item_id>      # Approve for implementation
+supervisor reject <work_item_id>       # Reject work item
+supervisor blocklist                   # List blocklist entries
+```
+
+## Testing
+
+Tests use real SQLite databases in tmp_path. No mocking of the store layer.
+Engine and CLI tests mock the Claude CLI subprocess.
+Lane boundary tests (`test_lane_boundary.py`) verify import isolation via AST parsing.
+Run a single test: `.venv/bin/pytest tests/test_evaluator.py -v`
+
+## Code Style
+
+- Use ruff for linting
+- Pydantic models for all data structures
+- Type hints on all public functions
+- Infrastructure domain imports from `models.core` + `models.health` only
+- Codebase domain imports from `models.core` + `models.work` only

supavision-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0.

supavision-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to Supavision
+
+## Development Setup
+
+```bash
+git clone https://github.com/devsquall/supavision.git
+cd supavision
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The default backend (`claude_cli`) requires [Claude Code](https://claude.ai/code) installed. No API keys needed.
+
+To use OpenRouter instead, copy `.env.example` to `.env` and set `OPENROUTER_API_KEY`.
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Code Style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting:
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Adding a Resource Type
+
+1. Create a directory under `templates/` (e.g., `templates/my_type/`)
+2. Add `discovery.md` — instructions for initial exploration
+3. Add `health_check.md` — instructions for recurring health checks
+4. If your type needs new tools, add them to `src/supavision/tools.py`:
+   - Define the tool in `TOOL_DEFINITIONS`
+   - Add a `_tool_<name>` method to `ToolDispatcher`
+   - Include input validation (never trust LLM-generated arguments)
+5. Add tests for any new tools in `tests/`
+
+## Adding Tools
+
+Tools must be **read-only and safe**. Guidelines:
+
+- Validate all inputs (paths, service names, commands)
+- Use allowlists, not blocklists
+- Never allow arbitrary command execution
+- Return errors as strings, never raise exceptions
+- Keep tool output under 10KB (truncate if needed)
+
+## Pull Requests
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update README if adding user-facing features
+- Run `ruff check` and `pytest` before submitting

supavision-0.1.0/Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install system deps (SSH client for remote monitoring)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends openssh-client curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install Node.js + Claude Code CLI
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
+    apt-get install -y nodejs && \
+    npm install -g @anthropic-ai/claude-code@latest && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY pyproject.toml README.md ./
+COPY src/ src/
+RUN pip install --no-cache-dir -e .
+
+# Copy templates
+COPY templates/ templates/
+
+# Data directory
+VOLUME /app/.supavision
+
+ENV SUPAVISION_BACKEND=claude_cli
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8080/api/v1/health || exit 1
+
+ENTRYPOINT ["supavision"]
+CMD ["serve", "--port", "8080"]

supavision-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Supervisor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.