refactor: professionalize pass — gates in CI, deep seams, component extractions by 0xSero · Pull Request #181 · sybil-solutions/local-studio

0xSero · 2026-07-12T23:44:21Z

Overnight professionalization loop (~24 commits, ledger with per-iteration rationale in docs/professionalize-loop.md).

Bugs fixed

Chat streams lost their keepalive after the first upstream chunk — long tool-call gaps later in a turn got no heartbeats (Cloudflare-sensitive). Regression test included.
Malformed recipe JSON returned 500 instead of 400 (ctx.req.json() threw outside the try).
SessionStatus union was voided by | string — zero type safety; session-index re-derived "working" from strings incl. a status that doesn't exist.
AggregatedSession client contract omitted four fields the server actually sends, and was defined twice.

Gates & tests

The contracts/structure gates now run in CI (they were local-only — the root cause of three contributors' phantom check:contracts failures).
Frontend unit tests now gate root npm run check; the misnamed "e2e" suites are honestly named regression.
New end-to-end chat proxy tests: upstream forwarding, keepalive-first-byte SSE contract, model_not_running 503 gate.

Deepened seams (controller)

One process-inventory parser behind the ProcessRunner seam replaces three independent ps parsers.
Engine-specific knowledge (vLLM allowlist/Docker-JIT, llama.cpp binary rules) moved out of backend-builder into their EngineSpec files; backend-builder is engine-agnostic (413→279).
Five copy-paste /runtime/{backend}/upgrade routes → one validated /runtime/:backend/upgrade (closes Collapse redundant runtime upgrade routes into /runtime/jobs #145); frontend mirror collapsed too.
The 387-line engines god-router split into recipe/lifecycle/download/runtime registrars.
The 220-line chat-completions handler decomposed into named stages, pinned by the new tests.

Deepened seams (frontend)

session-status.ts: canonical settleTurn/isWorkingStatus replaces five hand-rolled settle copies; SessionStatus and SessionTab.status share the tightened union.
tools/selection-persistence.ts single-owns the ToolSelection wire shape (workspace store delegated; persisted JSON byte-identical).
Component extractions, markup verified byte-identical: chatterbox modal 750→240, left sidebar 548→212, git-diff panel 544→173, recipe modal 526→126.

Docs & config

CONTEXT.md seeds the repo's domain language. README/AGENTS.md corrected (stale pi-runtime paths, removed 3090, Zod→Effect Schema, dead CLI/voice refs).
depcheck config hoisted to .depcheckrc.json, jscpd thresholds aligned at the stricter bar (closes Hoist duplicated per-package cleanup tool configs #146); PROGRESS.md scratch removed.

Deliberate skips (rationale in the ledger — please don't re-request blind)

SSE keepalive unification (chat path is intentionally different: immediate first byte, byte-aligned frames).
GET /runtime/<backend> info-path unification (two discovery mechanisms can disagree; needs design + live verification).
Effect-ifying setActiveRecipe (the machinery keeping models alive; not an autonomous-hours change).
landing-page vs marketing-page near-total duplication — both are routed; consolidation is a pending product decision.

Validation

Full npm run check (contracts, structure, frontend quality incl. build, controller checks) and npm run test:integration (117 controller + 236 frontend regression) green at head. Every push ran the pre-push quality gate.

⚠️ Post-merge: desktop rebuild owed per AGENTS.md (frontend changes shipped).

🤖 Generated with Claude Code

The check:contracts and check:structure gates only ran when someone remembered npm run check locally — three contributors independently hit stale gate failures. Also prunes the validator's reference to the removed shared/contracts/environments.ts and corrects AGENTS.md's test-runner note (tsx --test is long gone). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- frontend depcheck ignore-list moves from a 300-char inline --ignores flag to .depcheckrc.json, the same mechanism controller already uses - controller jscpd minTokens 400 -> 200, matching frontend (0 clones at the stricter threshold, so the alignment is free) - delete PROGRESS.md: a session work-log snapshot duplicating git history; docs/ carries the durable design notes Closes #146. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…n root check tests/frontend/e2e ran node:test module regressions, not end-to-end tests — the name promised browser coverage that doesn't exist. Scripts, CI step, README, and AGENTS.md now say what actually runs. Root check:frontend additionally runs the frontend unit suites; previously the root gate ran controller tests but never frontend's. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The feature-side copy silently omitted cwd/provider/archived/archivedAt fields the /api/agent/sessions/all route actually returns; the route re-declared the shape locally. One definition in shared/agent extends SessionSummary where it lives. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…me/:backend/upgrade Five copy-paste handlers (differing only in a backend literal) become one parameterized route validated against RUNTIME_JOB_BACKENDS. URLs are unchanged for existing callers; sglang/llamacpp/cuda/rocm now honor targetId/version/prefer_bundled and receive runningProcess exactly like the generic /runtime/jobs path, and mlx gains the same endpoint. The frontend mirror collapses five upgrade methods into upgradeRuntime() and drops the RuntimeCommandPayload type whose command/args fields the controller has rejected since the security hardening. Closes #145. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…Runner seam Three independent ps parsers (listProcesses, buildProcessTree, and process-manager's listProcessTable) each ran and parsed their own ps invocation with their own regex — and only one sat behind the injectable ProcessRunner seam, so the other two were untestable. listProcessInventory() returns the superset row (pid/ppid/stat/ command/args) and all three derive from it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>