WUP (What's Up)

AI Cost Tracking

🤖 LLM usage: $6.7514 (123 commits)
👤 Human dev: ~$6506 (65.1h @ $100/h, 30min dedup)

Generated on 2026-09-11 using openrouter/qwen/qwen3-coder-next

WUP (What's Up) - Intelligent file watcher for regression testing in large projects.

WUP monitors file changes and runs intelligent regression tests using a 3-layer approach:

Detection Layer: File watching with heuristics
Priority Layer: Quick tests of related services (3 endpoints max)
Detail Layer: Full tests with blame reports (only on failure)

Features

🎯 Intelligent Testing: Only tests related services when files change
⚡ CPU Throttling: Respects system resources with configurable CPU limits
🔄 3-Layer Architecture: Quick smoke tests first, detailed tests only on failure
📊 Live Dashboard: Real-time status monitoring with Rich CLI
🔍 Dependency Mapping: Automatic detection of files → endpoints → services
🚀 Framework Support: FastAPI, Flask, Django, Express.js, and more
📝 Blame Reports: Detailed regression reports with file/line/commit info
⚙️ Configuration System: Declarative configuration via wup.yaml file
🎛️ Per-Service Settings: Custom test strategies per service
🧪 TestQL Integration: Native support for TestQL scenarios
🔧 CLI/Shell Automation: Auto-detection and configuration of CLI tools and shell scripts

Installation

# Install from source
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Quick Start

# 1. Interactive configuration (recommended)
wup assistant

# 2. Or quick auto-setup
wup assistant --quick --template fastapi

# 3. Build dependency map (one-time setup)
wup map-deps ./my-project

# 4. Start watching (TestQL + live probes every 60s by default)
wup watch ./my-project

# 5. Start with live dashboard


wup watch ./my-project --dashboard

Usage

Build Dependency Map

# Auto-detect framework
wup map-deps ./my-project

# Specify framework
wup map-deps ./my-project --framework fastapi

# Custom output file
wup map-deps ./my-project --output my-deps.json

Watch Project

# Basic watching: TestQL mode + live HTTP probes every 60s (uses wup.yaml if present)
wup watch ./my-project

# Legacy HTTP-only watcher (no TestQL, no periodic probes unless configured)
wup watch ./my-project --mode default --probe-interval 0

# With custom settings
wup watch ./my-project \
  --cpu-throttle 0.5 \
  --debounce 3 \
  --cooldown 600 \
  --probe-interval 120

# Detailed startup and service diagnostics
wup watch ./my-project --verbose

# Detailed TestQL watch with live probes every 60 seconds
wup dive ./my-project

# With live dashboard
wup watch ./my-project --dashboard

# Use specific config file
wup watch ./my-project --config custom-config.yaml

# Discover endpoints from TestQL scenarios
wup testql-endpoints /path/to/scenarios --output testql-deps.json

Watch Multiple Projects Simultaneously

Pass several project roots to watch them all at once in a single process. Each project keeps its own wup.yaml, dependency map, file observer and test queue.

When the current directory is a workspace containing projects in immediate subfolders, plain wup watch . auto-detects their common source directories, for example api/src, worker/services and frontend/app. This also repairs the runtime behaviour of older auto-generated configs that still point only to missing root-level app, src and routes directories. The config file is not rewritten by this fallback.

# Watch several projects at the same time
wup watch ./service-a ./service-b ./service-c

# Discover: expand a monorepo root into every sub-project that has a wup.yaml
wup watch --discover ./my-monorepo

# Discover from the current directory
wup watch -D .

--discover walks the immediate sub-directories of each given path and watches those that already contain a wup.yaml (hidden and vendor folders such as node_modules, .venv, dist and build are skipped). A relative --deps path is resolved per project, so each project uses its own deps.json.

The live --dashboard and single --config options apply to single-project runs only; when watching multiple projects each uses its own wup.yaml.

Continuous Intent Monitoring with todo2code

WUP can run todo2code on startup, periodically and after debounced source-file changes. Diagnostics are projected into the regular service-health stream as <project>:intent: blocking findings produce down, review-required findings produce degraded, and a clean audit produces up.

The integration is opt-in and deterministic by default, so merely installing WUP never starts paid LLM requests:

intent_monitoring:
  enabled: true
  runner: cli
  command:
    - node
    - /path/to/todo2code/dist/src/cli.js
  interval_s: 300
  debounce_s: 10
  run_on_start: true
  run_on_change: true
  mode: deterministic
  task_file: TASK.md
  todo_file: TODO.md
  changelog_file: CHANGELOG.md
  docs:
    - README.md
    - docs/**/*.md
  output_dir: .wup/intent
  fail_severities:
    - blocking
    - review_required

Set runner: python to use the dependency-free todo2code-sdk bridge. Install it from todo2code's sdk/python directory and set cli_path to the built dist/src/cli.js. The Python package still delegates semantic processing to the canonical Node/TypeScript runtime.

mode: prefer-llm or mode: require-llm enables LLM enrichment for NL and TODO/CHANGELOG. Documentation and final-summary LLM calls remain separately controlled by docs_llm and summary_llm. Use these modes deliberately: an audit may run after every debounce interval and therefore incur provider cost.

Initialize Configuration

# Generate default wup.yaml configuration
wup init

# Generate with custom output path
wup init --output .wup.yaml

# Auto-detect and configure CLI/shell services
wup init-cli ./my-project

# Merge CLI configuration with existing wup.yaml
wup init-cli ./my-project --merge

Check Status

# View dependency map status
wup status

# Custom deps file
wup status --deps my-deps.json

CLI/Shell Automation

WUP can automatically detect and configure CLI tools and shell scripts for testing:

# Auto-detect CLI commands and generate configuration
wup init-cli ./my-project

# Merge with existing wup.yaml
wup init-cli ./my-project --merge

# Custom output paths
wup init-cli ./my-project --output-config custom.yaml --output-scenarios custom-scenarios

# Skip argument inference (faster)
wup init-cli ./my-project --no-infer-args

The init-cli command:

Scans pyproject.toml, setup.py, setup.cfg for entry points
Detects packages with __main__.py modules
Generates shell service configuration in wup.yaml
Creates TestQL scenarios for CLI commands in testql-scenarios/
Supports merging with existing configurations

Generated files:

cli-smoke.testql.toon.yaml - Smoke tests for all CLI commands
cli-{command}.testql.toon.yaml - Detailed tests for each command

Architecture

3-Layer Testing Approach

┌─────────────────────────────────────────────────────────────┐
│                    DETECTION LAYER                          │
│  File watching with watchdog + heuristics                   │
│  Skips: .git, __pycache__, node_modules, .venv              │
└──────────────────────┬──────────────────────────────────────┘
                       │ File change
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   PRIORITY LAYER                            │
│  Quick test: 3 endpoints max per service                    │
│  Duration: ~1-2 seconds                                     │
│  Result: Pass → Done, Fail → Escalate                       │
└──────────────────────┬──────────────────────────────────────┘
                       │ Failure
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    DETAIL LAYER                             │
│  Full test: All endpoints with blame report                 │
│  Duration: ~3-5 seconds                                     │
│  Result: Regression report with file/line/commit            │
└─────────────────────────────────────────────────────────────┘

Performance Characteristics

Idle:           0.1% CPU, 10MB RAM
File change:    5s test → 2% CPU spike
Full regression: 15s test → 15% CPU spike
200+ files/min: 100 req/s → OK (throttled)

Configuration

Service Types

WUP supports three service types for coincidence detection and intelligent testing:

web - HTTP/API services (FastAPI, Flask, Django, Express.js, etc.)
shell - CLI tools, scripts, and command-line services
auto - Automatic detection (default)

Coincidence detection allows WUP to identify related services. For example, if you have users-web and users-shell, WUP will detect they share the same domain and test both when relevant files change.

wup.yaml Configuration File

WUP supports declarative configuration via wup.yaml (or .wup.yaml) in your project root. This allows you to define watch paths, service-specific settings, and test strategies.

Generate a default configuration:

wup init

The generated wup.yaml includes:

Metadata header: Version, generation date, documentation links
Dependencies info: WUP version and optional wupbro dashboard
Quick start guide: Common commands to get started
Detected watch paths: Existing common source directories at the project root and one level below it

Example wup.yaml:

project:
  name: "my-project"
  description: "My awesome project"

watch:
  # Folders to watch (supports glob patterns)
  paths:
    - "app/**"
    - "src/**"
    - "routes/**"
    - "!tests/**"         # exclusion
    - "!node_modules/**"

  # Global exclude patterns
  exclude_patterns:
    - "*.md"
    - "*.txt"
    - "migrations/**"

  # File types to watch (empty = watch all files)
  # Only changes to these file extensions will trigger tests
  file_types:
    - ".py"
    - ".ts"
    - ".jsx"

services:
  # Service configurations - simplified with auto-detection
  # If paths are empty, WUP auto-detects files by service name
  
  - name: "users-shell"
    type: "shell"
    # Auto-detects files containing "users-shell"
  
  - name: "users-web"
    type: "web"
    # Auto-detects files containing "users-web"
    # Will detect coincidence with users-shell
  
  # Or use explicit paths (old style still works)
  - name: "payments"
    paths:
      - "app/payments/**"
    type: "auto"

test_strategy:
  quick:
    debounce_s: 2
    max_queue: 5
    timeout_s: 10
  detail:
    debounce_s: 10
    max_queue: 1
    timeout_s: 30

testql:
  # TestQL-specific configuration
  scenario_dir: "scenarios/tests"
  smoke_scenario: "smoke.testql.toon.yaml"
  output_format: "json"
  extra_args:
    - "--timeout 10s"

CLI Options

Option	Default	Description
`--config`	auto	Path to wup.yaml config file
`--cpu-throttle`	0.8	CPU usage threshold (0.0-1.0)
`--debounce`	2	Debounce time in seconds
`--cooldown`	300	Test cooldown in seconds
`--dashboard`	false	Enable live dashboard
`--deps`	deps.json	Dependency map file path
`--mode`	default	Watcher mode: default or testql

Environment Variables

# Set default CPU throttle
export WUP_CPU_THROTTLE=0.5

# Set default debounce time
export WUP_DEBOUNCE=3

Full list of supported variables (see .env.example):

Variable	Default	Description
`WUP_CPU_THROTTLE`	—	CPU usage threshold (0.0-1.0)
`WUP_DEBOUNCE`	—	Debounce time in seconds
`WUPBRO_ENDPOINT`	—	wupbro backend URL
`WUP_BASE_URL`	—	Base URL for visual diff page scanning
`OPENROUTER_API_KEY`	(not set)	Required for LLM features (https://openrouter.ai/keys)
`LLM_MODEL`	`openrouter/qwen/qwen3-coder-next`	LLM model for assistant
`PFIX_AUTO_APPLY`	`true`	Apply fixes without asking
`PFIX_AUTO_INSTALL_DEPS`	`true`	Auto pip/uv install missing deps
`PFIX_AUTO_RESTART`	`false`	Restart process after fix
`PFIX_MAX_RETRIES`	`3`	Max fix retries
`PFIX_DRY_RUN`	`false`	Dry-run mode (no changes written)
`PFIX_ENABLED`	`true`	Enable/disable pfix
`PFIX_GIT_COMMIT`	`false`	Auto-commit fixes
`PFIX_GIT_PREFIX`	`pfix:`	Commit message prefix
`PFIX_CREATE_BACKUPS`	`false`	Create .pfix_backups/ directory

Visual DOM Diff

WUP optionally scans configured pages with Playwright after each successful quick test, compares the DOM structure to the previous snapshot, and reports significant changes.

Setup

pip install playwright
playwright install chromium

Configuration

visual_diff:
  enabled: true
  base_url: "http://localhost:8100"   # or leave empty and set WUP_BASE_URL env var
  base_url_env: "WUP_BASE_URL"
  delay_seconds: 5.0      # wait after file change before scanning
  max_depth: 10            # DOM snapshot depth
  pages:
    - "/health"
    - "/dashboard"
  pages_from_endpoints: true   # also scan endpoints from testql config
  threshold_added: 3           # min node additions to report as "changed"
  threshold_removed: 3
  threshold_changed: 5
  headless: true

Or set the base URL in .wup.env in the project root (not committed to git):

# .wup.env
WUP_BASE_URL=http://localhost:8100

Output

Snapshots — .wup/visual-snapshots/<service>/<page>.json
Diff events — .wup/visual-diffs/<service>/<page>.jsonl (appended on each change)

Visible in wup status as a "Visual DOM diffs" section.

Graceful degradation

If Playwright is not installed, the visual diff module logs a warning and skips scanning — it does not break the watcher.

Web Dashboard (wupbro)

Optional FastAPI backend that receives events from WUP agents and renders a live dashboard.

Run

pip install -e wupbro/
wupbro --reload --port 8000

Open http://localhost:8000/ to see regressions, passes, anomalies, visual diffs, and health transitions in real time.

Configure agent → backend

# wup.yaml
web:
  enabled: true
  endpoint: "http://localhost:8000"
  timeout_s: 2.0

Or via env:

export WUPBRO_ENDPOINT=http://localhost:8000

The agent fire-and-forgets REGRESSION, PASS, ANOMALY, VISUAL_DIFF, and HEALTH_TRANSITION events. Network errors never break the watcher (soft-fail).

See wupbro/README.md for full API reference and driver endpoints (DOM diff, browserless, anomaly).

Project Structure

wup/
├── wup/
│   ├── __init__.py            # Package exports
│   ├── anomaly_detector.py    # AnomalyDetector: hash, YAML structure, AST diff
│   ├── assistant.py           # WupAssistant: interactive configuration wizard
│   ├── cli.py                 # CLI: watch, map-deps, status, init, testql-endpoints, assistant, version, init-cli
│   ├── cli_scanner.py         # CLIScanner: detects CLI commands from pyproject.toml, setup.py, etc.
│   ├── cli_config_generator.py # CLIConfigGenerator: generates wup.yaml for shell services
│   ├── testql_cli_generator.py # TestQLCliGenerator: generates TestQL scenarios for CLI commands
│   ├── config.py              # Config loading/saving + .wup.env support
│   ├── core.py                # WupWatcher: detection, inference, scheduling
│   ├── dependency_mapper.py   # DependencyMapper: codebase → deps.json
│   ├── testql_discovery.py    # TestQLEndpointDiscovery: scenario parsing
│   ├── testql_monitor.py      # TestQLMonitor: extracts live HTTP probes and Docker services
│   ├── testql_watcher.py      # TestQLWatcher: scenario runner + health tracking
│   ├── visual_diff.py         # VisualDiffer: Playwright DOM snapshot + diff engine
│   ├── web_client.py          # WebClient: async HTTP event sink → wupbro
│   ├── monitoring_manifest.py # Builds and patches the wup.yaml monitoring block
│   ├── planfile_reporter.py   # PlanfileReporter: creates and deduplicates Planfile tickets
│   └── models/
│       ├── __init__.py
│       └── config.py          # Dataclasses: WupConfig, ServiceConfig, WatchConfig, TestStrategyConfig, TestQLConfig, VisualDiffConfig, WebConfig, AnomalyDetectionConfig...
├── wupbro/                   # Optional FastAPI dashboard (separate package)
│   ├── wupbro/
│   │   ├── main.py            # FastAPI app
│   │   ├── routers/           # events, drivers, dashboard
│   │   ├── storage.py         # EventStore (in-memory + JSONL)
│   │   └── templates/         # index.html dashboard
│   └── tests/                 # FastAPI endpoint tests (pytest + TestClient)
├── tests/
│   ├── test_wup.py            # unit/integration tests (incl. VisualDiffer, config)
│   ├── test_testql_watcher.py # TestQLWatcher + VisualDiffer integration tests
│   ├── test_web_client.py     # WebClient + WebConfig tests
│   └── test_e2e.py            # end-to-end CLI tests
├── examples/
│   ├── fastapi-app/           # FastAPI example project
│   ├── flask-app/             # Flask example project
│   ├── multi-service/         # Multi-service example
│   ├── testql_demo.py         # TestQL simulation demo
│   ├── testql_integration.py  # Custom TestQLWatcher + visual diff example
│   └── visual_diff_demo.py    # Visual DOM diff demo (no Playwright required)
├── docs/
│   └── TESTQL_INTEGRATION.md  # TestQL integration guide
├── testql-scenarios/          # Auto-generated TestQL scenarios
├── pyproject.toml             # Package config (setuptools)
└── README.md

Development

Running Tests

The locked test group runs the complete WUP plus workspace suite on Python 3.10+. It deliberately excludes Goal, Koru and costs, which are optional automation tools and would otherwise make a networkless test image unnecessarily large. Use test-root for the smaller WUP-only suite.

# Prepare and run the complete test lane
uv sync --locked --no-default-groups --group test
uv run --no-default-groups --group test pytest -q
uv run --no-default-groups --group test ruff check .

# Run the Python 3.10-compatible WUP root lane
uv sync --locked --no-default-groups --group test-root
uv run --no-default-groups --group test-root pytest tests \
  --ignore=tests/test_status_data.py --ignore=tests/test_endpoints_init_cli.py

# Run a specific suite or coverage
uv run --no-default-groups --group test pytest tests/test_wup.py -v
uv run --no-default-groups --group test pytest tests/ --cov=wup

# Opt into ticket/LLM/cost automation when it is needed
uv sync --locked --no-default-groups --group automation

For pip users, pip install -e '.[dev]' installs the Python 3.10-compatible test tooling; pip install -e '.[dev-workspace]' adds the local workspace packages. pip install -e '.[automation]' adds the optional automation tools.

The Wellmanifest adoption scope and the current protected-CI evidence are recorded in docs/WELLMANIFEST_ADOPTION.md.

Goal wrapper (local `.venv`)

When goal is installed globally, it may inherit another project's VIRTUAL_ENV. Use the local wrapper to force wup/.venv before running goal commands:

# Default: runs goal -a
bash scripts/goal-local

# Explicit arguments
bash scripts/goal-local -a
bash scripts/goal-local --dry-run

If needed, point to a specific goal binary:

GOAL_BIN=/home/tom/.local/bin/goal bash scripts/goal-local -a

Examples

# Visual diff demo (no Playwright required)
python3 examples/visual_diff_demo.py

# With live page scan (requires playwright)
python3 examples/visual_diff_demo.py http://localhost:8100/health

# TestQL + visual diff integration
python3 examples/testql_integration.py /path/to/project

# Monorepo analysis (c2004-style large projects)
python3 examples/c2004_monorepo_demo.py /path/to/monorepo

# CI/CD integration patterns
python3 examples/ci_cd_integration.py

# Generate GitHub Actions workflow
python3 examples/ci_cd_integration.py --generate-github-actions

# Webhook notifications (Slack, Teams, Discord)
python3 examples/webhook_notifications.py

Building & Publishing

python -m build

Real-World Testing

WUP has been tested on production-scale projects:

c2004 Project (maskservice/c2004): Large IoT platform with 21+ connect-* modules
- 29 services auto-detected by assistant
- 100+ YAML configuration files monitored
- Anomaly detection: 0.06s for 5 config files (~1ms/file)
- Framework: Custom Python/FastAPI hybrid

Documentation

Comprehensive documentation is available in the docs/ directory:

Configuration Assistant - Interactive setup guide for wup.yaml
- wup assistant - Interactive configuration wizard
- Auto-detects framework and services
- Intelligent suggestions and validation
- wup init-cli - Automated CLI/shell project setup
Anomaly Detection - Fast alternatives to Playwright
- Hash-based change detection (~1ms per file)
- YAML structure analysis
- Python AST diff for API changes
- Configure with anomaly_detection: in wup.yaml
Browser Notifications - Real-time alerts in wupbro
- 7 notification types (regressions, status changes, recoveries)
- Configurable per-type with cooldown
- Server-Sent Events for instant delivery
- Browser Notifications API integration
TestQL Integration - TestQL scenario support
- wup init-cli - Automated CLI command detection and TestQL scenario generation
- Shell service configuration for CLI tools
- TestQL scenarios for CLI commands

License

Licensed under Apache-2.0.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

TestQL → Planfile → GitHub incidents

The repository watcher is configured in wup.yaml and runs the existing cli-wup.testql.toon.yaml and cli-smoke.testql.toon.yaml scenarios. A failed health transition creates one deduplicated Planfile ticket with the github integration. Planfile immediately publishes only tickets tagged for that integration; historical tickets without that tag remain local. When the same service and stage recover, WUP completes the incident ticket and publishes the resolved state.

Install the persistent watcher for the current user with:

./scripts/install-wup-watcher-service.sh
systemctl --user status wup-watcher.service
journalctl --user -u wup-watcher.service -f

Agents take the next runnable item with planfile ticket next --format json. The GitHub target is configured as semcod/wup in .planfile/integrations.oql.planfile.yaml; credentials are read from the existing gh auth session and are never written to the repository.

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

WUP (What's Up)

AI Cost Tracking

Features

Installation

Quick Start

Usage

Build Dependency Map

Watch Project

Watch Multiple Projects Simultaneously

Continuous Intent Monitoring with todo2code

Initialize Configuration

Check Status

CLI/Shell Automation

Architecture

3-Layer Testing Approach

Performance Characteristics

Configuration

Service Types

wup.yaml Configuration File

CLI Options

Environment Variables

Visual DOM Diff

Setup

Configuration

Output

Graceful degradation

Web Dashboard (wupbro)

Run

Configure agent → backend

Project Structure

Development

Running Tests

Goal wrapper (local .venv)

Examples

Building & Publishing

Real-World Testing

Documentation

License

Contributing

TestQL → Planfile → GitHub incidents

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Goal wrapper (local `.venv`)