P10-T1 Web UI

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
           fetch-depth: 0  # Need full history for branch comparison
 
       - name: Check DocC sync
-        run: python scripts/check_doc_sync.py --branch
+        run: make doccheck-branch
   lint:
     name: Lint & Type Check
     runs-on: ubuntu-latest
@@ -37,16 +37,16 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install ruff mypy
+          pip install -e ".[dev]"
 
       - name: Run ruff linter
-        run: ruff check src/
+        run: make lint
 
       - name: Run ruff formatter check
-        run: ruff format --check src/ tests/
+        run: make format-check
 
       - name: Run mypy type checker
-        run: mypy src/
+        run: make typecheck
 
   test:
     name: Test (Python ${{ matrix.python-version }})
@@ -71,8 +71,7 @@ jobs:
           pip install -e ".[dev]"
 
       - name: Run tests with coverage
-        run: |
-          pytest tests/ -v --cov=src --cov-report=xml --cov-report=term
+        run: make test
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.11'

.gitignore

@@ -53,3 +53,9 @@ Package.resolved
 # Task tracker state files
 .task_state.json
 .current_task
+
+# Specifications
+/SPECS/tmp/*
+
+# Web UI
+/logs/*

AGENTS.md

@@ -35,7 +35,8 @@ A Python wrapper (`xcodemcpwrapper`) that intercepts responses from `xcrun mcpbr
 | Phase 6: Packaging & Distribution | 8/8 | ✅ Complete |
 | Phase 7: Documentation | 11/11 | ✅ Complete |
 | Phase 8: Documentation Publishing | 2/2 | ✅ Complete |
-| **Total** | **67/67** | **✅ 100%** |
+| Phase 10: Web UI Dashboard | 1/1 | ✅ Complete |
+| **Total** | **68/68** | **✅ 100%** |
 
 ### Metrics
 
@@ -62,7 +63,13 @@ A Python wrapper (`xcodemcpwrapper`) that intercepts responses from `xcrun mcpbr
 │   ├── __main__.py        # Main entry point
 │   ├── bridge.py          # Subprocess bridge management
 │   ├── transform.py       # Response transformation engine
-│   └── cli.py             # CLI entry point
+│   ├── cli.py             # CLI entry point
+│   └── webui/             # Optional Web UI dashboard
+│       ├── server.py      # FastAPI server
+│       ├── metrics.py     # Metrics collection
+│       ├── audit.py       # Audit logging
+│       ├── config.py      # Web UI configuration
+│       └── static/        # Dashboard frontend
 ├── tests/
 │   ├── unit/              # Unit tests (181+ tests)
 │   │   ├── test_bridge.py
@@ -78,6 +85,7 @@ A Python wrapper (`xcodemcpwrapper`) that intercepts responses from `xcrun mcpbr
 │   └── codex-cli.txt
 ├── docs/                  # Documentation
 │   ├── installation.md
+│   ├── webui-setup.md     # Web UI dashboard guide
 │   ├── cursor-setup.md
 │   ├── claude-setup.md
 │   ├── codex-setup.md
@@ -182,6 +190,28 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 codex mcp add xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper
 ```
 
+### Web UI Dashboard (Optional)
+
+Enable the Web UI for real-time monitoring and audit logging:
+
+```bash
+# Start with Web UI
+xcodemcpwrapper --web-ui --web-ui-port 8080
+
+# Or use make
+make webui
+```
+
+Access the dashboard at http://localhost:8080
+
+Features:
+- Real-time metrics (RPS, latency, error rates)
+- Tool usage analytics with charts
+- Audit logging with export (JSON/CSV)
+- Request/response inspector
+
+See [docs/webui-setup.md](docs/webui-setup.md) for detailed configuration.
+
 ## Available Xcode MCP Tools
 
 When properly configured, the following 20 tools become available to AI agents:
@@ -263,13 +293,29 @@ pytest --cov
 pytest tests/unit/test_transform.py
 pytest tests/integration/test_performance.py
 
+# Run Web UI tests
+pytest tests/unit/webui/ tests/integration/webui/ -v
+
 # Run linting
 ruff check src/
 
 # Run type checking
 mypy src/
 ```
 
+### Makefile Commands
+
+```bash
+make test        # Run all tests with coverage
+make test-webui  # Run Web UI specific tests
+make lint        # Run linter
+make format      # Format code
+make typecheck   # Run type checker
+make check       # Run all quality gates
+make webui       # Start wrapper with Web UI
+make webui-health # Check Web UI status
+```
+
 ### Verified with Real Xcode
 
 Tested successfully with real `xcrun mcpbridge`:

CONTRIBUTING.md

@@ -9,8 +9,13 @@ Thank you for your interest in contributing! This document outlines the developm
 git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
 cd XcodeMCPWrapper
 
+# Create and activate a virtual environment (recommended on macOS/Homebrew Python)
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+
 # Install in editable mode with dev dependencies
-pip install -e ".[dev]"
+python3 -m pip install -e ".[dev]"
 ```
 
 ## Quality Gates
@@ -128,6 +133,38 @@ chmod +x check.sh
 ./check.sh
 ```
 
+## Adding New Features
+
+When adding new features that require specific commands or dependencies:
+
+### Update the Makefile
+
+Add relevant `make` targets for the new feature. For example:
+
+```makefile
+# For optional features with extra dependencies
+install-feature:
+	python3 -m pip install -e ".[feature]"
+
+# For feature-specific tests
+test-feature:
+	pytest tests/unit/feature/ tests/integration/feature/ -v
+```
+
+Then update the `.PHONY` line and `help` target to include the new commands.
+
+### Update pyproject.toml
+
+If the feature has optional dependencies, add them to `[project.optional-dependencies]`:
+
+```toml
+[project.optional-dependencies]
+feature = [
+    "dependency1>=1.0",
+    "dependency2>=2.0",
+]
+```
+
 ## Workflow
 
 We follow the [FLOW.md](SPECS/COMMANDS/FLOW.md) workflow:

FEATURE_REBUILD/Architecture.md

@@ -0,0 +1,107 @@
+# Web UI Dashboard Rebuild Architecture
+
+## Current Pain Points (with evidence)
+
+1. P-001: Weak abstraction between metrics implementations.
+   - Evidence: `create_app()` is typed for `MetricsCollector`, but runtime passes `SharedMetricsStore` with `# type: ignore[arg-type]` in `src/mcpbridge_wrapper/__main__.py`.
+   - Impact: Hidden interface drift risk and reduced static safety.
+
+2. P-002: Shared metrics summary semantics are lossy.
+   - Evidence: `SharedMetricsStore.get_summary()` computes per-tool latency percentiles with simplified approximations and derives `uptime_seconds` from the query window, not process/service lifetime in `src/mcpbridge_wrapper/webui/shared_metrics.py`.
+   - Impact: Dashboard metrics can be misleading under non-trivial traffic.
+
+3. P-003: Auth flow inconsistency for WebSocket path.
+   - Evidence: server expects query token for websocket auth while dashboard websocket connection is opened without token in `src/mcpbridge_wrapper/webui/server.py` and `src/mcpbridge_wrapper/webui/static/dashboard.js`.
+   - Impact: Auth-enabled deployments can lose real-time updates.
+
+4. P-004: CLI parsing lacks resilient validation.
+   - Evidence: direct `int()` casts on `--web-ui-port` values in `src/mcpbridge_wrapper/__main__.py`.
+   - Impact: invalid input can terminate process with uncaught `ValueError`.
+
+5. P-005: Operator documentation mismatch.
+   - Evidence: `docs/webui-setup.md` references `MCP_WRAPPER_WEB_UI*` while code consumes `WEBUI_*` and `--web-ui`.
+   - Impact: misconfiguration and support churn.
+
+## Target Principles
+
+- Contract-first: define shared protocols for metrics/audit/config interfaces used by server and runtime.
+- Deterministic behavior: explicit validation and error boundaries at CLI/API edges.
+- Compatibility-first: preserve externally visible API routes and payload schema.
+- Replace type-ignore coupling with static interface compliance.
+- Keep observability consistent across single-process and multi-process modes.
+
+## Layering & Dependency Rules
+
+- Domain Layer
+  - Contains data contracts and invariants (`MetricsSummary`, `TimeseriesPoint`, `AuditEntry`).
+  - No filesystem, network, or subprocess dependencies.
+
+- Application Layer
+  - Orchestrates request tracking, metrics updates, and audit recording.
+  - Depends on Domain contracts and storage/transport protocols.
+
+- Adapters Layer
+  - Implements storage and transport: SQLite metrics store, in-memory metrics store, JSONL audit store, FastAPI endpoints, WebSocket stream.
+  - Depends on Application and Domain.
+
+- Interface Layer
+  - CLI argument handling and entrypoint wiring.
+  - Depends on Application and Adapters.
+
+Dependency rule: higher layers must not import lower-layer concrete implementations directly; dependency inversion via protocols.
+
+## Module Breakdown
+
+- `webui/contracts.py`
+  - Shared Protocol/TypedDict/Pydantic contracts for metrics, audit, and config snapshots.
+- `webui/application/telemetry_service.py`
+  - Request/response lifecycle orchestration and normalized summary/timeseries generation.
+- `webui/adapters/metrics_sqlite.py`
+  - Process-safe metrics persistence and query implementation.
+- `webui/adapters/metrics_memory.py`
+  - In-memory metrics implementation for tests and single-process tooling.
+- `webui/adapters/audit_jsonl.py`
+  - Rotated audit logging and exports.
+- `webui/http/server.py`
+  - Route definitions, auth checks, serialization.
+- `__main__.py`
+  - CLI parsing, bridge wiring, and service bootstrap.
+
+## Key Data Flows (sequence bullets)
+
+- Flow A: Startup
+  - CLI parses flags -> loads config -> creates telemetry service -> starts server adapter.
+- Flow B: MCP request/response tracking
+  - stdin request callback -> track request id/tool/start time -> stdout response match -> record latency/error -> append audit entry.
+- Flow C: Dashboard read path
+  - HTTP/WS request -> auth guard -> telemetry service snapshot -> serialize stable response contract.
+- Flow D: Reset path
+  - POST reset -> telemetry service clear -> storage adapter reset -> acknowledgment response.
+
+## State Management Approach
+
+- Canonical telemetry state resides in metrics store adapter.
+- Pending in-flight map remains in application layer and is bounded by active request IDs.
+- Audit history uses append-only persistence plus bounded in-memory recent cache.
+
+## Error Handling Strategy
+
+- CLI validation errors return explicit user-facing messages and non-zero exit codes.
+- Adapter failures map to bounded API errors without exposing sensitive internals.
+- WebSocket auth failures return deterministic unauthorized close codes.
+- Non-fatal telemetry capture failures must not break MCP forwarding path.
+
+## Testing Strategy
+
+- Domain/contracts: unit tests for schema stability and invariant checks.
+- Application: deterministic lifecycle tests (tracked, matched, unmatched, error paths).
+- Adapters: integration tests for SQLite bucketing, audit rotation, export format.
+- HTTP/WS: endpoint contract tests and auth-mode tests (including websocket auth path).
+- End-to-end: wrapper + web UI behavior in multi-process simulation.
+
+## Risks
+
+- Refactor can accidentally change payload formats if contracts are not centralized.
+- Multi-process timing variability can make timeseries tests flaky if too strict.
+- Auth flow changes can break existing local setups if rollout is not backward-compatible.
+- Performance regressions are possible if telemetry queries become heavier without indexes.

FEATURE_REBUILD/CompatibilityHarness.md

@@ -0,0 +1,66 @@
+# Web UI Rebuild Compatibility Harness
+
+## What Must Match (MUST list)
+
+1. `/api/metrics` key set and value types used by dashboard remain unchanged.
+2. `/api/metrics/timeseries` returns `{requests, errors, latencies}` arrays of `{t, v}`.
+3. `/api/audit` pagination/filter behavior remains stable.
+4. `/api/audit/export/json` and `/api/audit/export/csv` remain downloadable with valid payloads.
+5. Non-auth mode dashboard continues to show live metrics via websocket or polling fallback.
+6. Wrapper behavior without `--web-ui` remains unchanged.
+
+## What May Change (MAY list)
+
+1. Internal module boundaries and abstractions.
+2. Internal storage query implementation details.
+3. Error message wording, provided status codes and actionable guidance remain equivalent.
+
+## Golden Sources (tests/fixtures/snapshots/logs)
+
+- Test suites:
+  - `tests/unit/webui/test_server.py`
+  - `tests/unit/webui/test_shared_metrics.py`
+  - `tests/integration/webui/test_e2e.py`
+  - `tests/unit/test_main.py`
+- Planned fixtures:
+  - `tests/fixtures/webui/metrics_summary.json`
+  - `tests/fixtures/webui/metrics_timeseries.json`
+  - `tests/fixtures/webui/audit_page.json`
+- Historical evidence:
+  - `SPECS/INPROGRESS/Web_UI_Debugging_Summary.md`
+  - `SPECS/ARCHIVE/P10-T2_Fix_Web_UI_Timeseries_Charts/P10-T2_Validation_Report.md`
+
+## Parity Check Plan (how we compare)
+
+1. API schema parity
+   - Compare runtime responses against fixture schemas for required keys/types.
+2. Behavior parity
+   - Replay request/response tracking scenario; assert summary counters and in-flight transitions.
+3. Timeseries parity
+   - Assert chart payload format and bounded `t` range.
+4. Audit parity
+   - Assert filter/pagination/export output shape and ordering.
+5. Auth parity
+   - Assert protected endpoints return `401` without credentials and success with valid credentials.
+6. Non-WebUI parity
+   - Run core wrapper tests without `--web-ui`; assert no behavior deltas.
+
+## CI Integration
+
+- Add compatibility harness to CI quality gate for Web UI touching changes:
+  - `pytest tests/integration/webui/test_compat_harness.py -v`
+  - `pytest tests/unit/webui/ tests/integration/webui/ -v`
+- Keep existing global checks:
+  - `pytest`
+  - `ruff check src/ tests/`
+  - `mypy src/`
+
+## Rollback Strategy
+
+- Deployment model: single PR rollout with immediate revert path.
+- Rollback trigger:
+  - API contract mismatch, auth regression, or chart data regression in harness.
+- Rollback action:
+  1. Revert rebuild commit set.
+  2. Re-run baseline Web UI test suites.
+  3. Restore last known good release notes and docs references.