merge: align dev branch with main

2026-06-03 08:51:02 +00:00
parent 51a399c775
commit b39d6ce5f4
319 changed files with 30221 additions and 9221 deletions
@@ -0,0 +1,57 @@
+# Task 3.4 Apply Report: Slim tool_instances Router to HTTP-Only Concerns
+
+**Status:** Success
+
+## Summary
+
+Reduced `apps/api/src/api/tool_instances.py` from **1,412 lines to 284 lines** — an 80% reduction. The router now contains only HTTP routing concerns.
+
+## Files Created
+
+- `apps/api/src/services/instance_lifecycle.py` (420 lines) — High-level orchestration service coordinating Docker compose, container, tunnel, and config staging services for create/start/stop/restart/delete operations.
+
+## Files Modified
+
+- `apps/api/src/services/docker/compose.py` — Added helper functions:
+  - `_sanitize_name()` — Docker name sanitization
+  - `_generate_instance_name()` — Sequential instance naming
+  - `_modify_compose_file()` — Compose file runtime overrides
+  - `_apply_resolved_profile()` — Profile resolution and application
+
+- `apps/api/src/api/tool_instances.py` — Slimmed from 1,412 to 284 lines:
+  - Removed all business logic (Docker calls, compose manipulation, tunnel management)
+  - Removed 8 helper functions (moved to services)
+  - Endpoints are now thin: validation → service call → response
+
+## Quality Gate Results
+
+| Gate | Result |
+|------|--------|
+| `python3 -m py_compile api/tool_instances.py` | ✅ PASS |
+| `python3 -m py_compile services/instance_lifecycle.py` | ✅ PASS |
+| `python3 -m py_compile services/docker/compose.py` | ✅ PASS |
+| `wc -l api/tool_instances.py` | ✅ 284 lines (≤300) |
+| `grep -n "subprocess" api/tool_instances.py` | ✅ 0 results |
+| `grep -n "docker" api/tool_instances.py` | ✅ 5 results (all imports/variable names, no CLI calls) |
+| `npm run typecheck` (frontend) | ✅ PASS |
+| `npm run lint` (frontend) | ✅ PASS |
+
+## Router Structure (After)
+
+```
+284 lines total:
+- 20 lines: imports
+- 22 lines: _get_instance + _get_repo helpers
+- 242 lines: 11 endpoint handlers (avg 22 lines each)
+```
+
+Each endpoint:
+1. Validates input (fetches instance/repo, checks auth)
+2. Calls a single service function
+3. Returns response
+
+## Notes
+
+- `services/instance_lifecycle.py` was actually created and committed by the parallel Task 2.2/3.2 worker run; this commit finalized the router slimming.
+- The `get_user_sessions` endpoint at the bottom of the original router (on `sessions_router`) was already removed in a previous commit.
+- No behavior changes — all endpoint signatures and response shapes preserved.