Files

Fusion 2c7e575b9f docs(FN-2213): document dev-server module ownership boundaries

- Add a dedicated dev-server module boundary audit covering hyphenated vs non-hyphenated stacks
- Record risk assessment plus FN-2212 priority, size, execution plan, and proposed definition of done
- Update architecture docs to mark the hyphenated dev-server runtime family as canonical and link the audit
- Add the new audit to docs/README and refresh .DONE delivery notes for FN-2213

2026-04-21 07:32:50 -07:00

3.6 KiB

Raw Blame History

Dev Server Module Boundary Audit

Last audited: 2026-04-21 (FN-2213)

Why this exists

packages/dashboard/src currently has two parallel module families with near-identical intent:

dev-server-* (hyphenated)
devserver-* (non-hyphenated)

This overlap was introduced during FN-2183 and creates ambiguity about which stack owns production behavior.

Boundary / Ownership Inventory

Canonical runtime stack (currently in use)

The hyphenated dev-server-* stack is wired into the dashboard API/runtime path and should be treated as the active owner today.

Area	Owner files
API routes and SSE stream (`/api/dev-server/*`)	`dev-server-routes.ts`
Process lifecycle (spawn/stop/restart, URL detection)	`dev-server-process.ts`
Persistent runtime/config state	`dev-server-store.ts` (`.fusion/dev-server.json`)
Script detection for API `detect` endpoint	`dev-server-detect.ts`
Server lifecycle shutdown integration	`routes.ts`, `server.ts` import `dev-server-routes.ts`

Secondary prototype stack (not wired to runtime)

The non-hyphenated devserver-* stack is currently isolated to itself plus direct tests.

Area	Files	Current reachability
Alternate manager/types/persistence/detection model	`devserver-manager.ts`, `devserver-types.ts`, `devserver-persistence.ts`, `devserver-detect.ts`	Not imported by `routes.ts`, `server.ts`, or active API handlers
Persistence format	`.fusion/devserver.json`	Separate from canonical `.fusion/dev-server.json`
Coverage	`__tests__/devserver-*.test.ts`	Unit tests only

Risk Assessment

Import confusion: both families expose similarly named concepts (manager, detect, persistence).
Data divergence risk: two persistence files (dev-server.json vs devserver.json) can drift if both are used.
Onboarding drag: contributors must infer ownership from import graph instead of explicit docs.
Refactor tax: bug fixes can land in the wrong family and miss production paths.

FN-2212 Prioritization Recommendation

Priority: P1 (High)
Size: M
Reasoning: The risk is primarily maintainability/correctness drift (not immediate runtime outage), but ambiguity sits on a core dashboard subsystem and should be resolved before additional dev-server features land.

Recommended FN-2212 Execution Plan

Lock ownership in docs and code comments
- Explicitly mark dev-server-* as canonical runtime owner.
- Explicitly mark devserver-* as experimental/legacy candidate.
Choose consolidation direction (single owner required)
- Preferred: consolidate on dev-server-* (already integrated).
- Alternative: migrate runtime wiring to devserver-* only if there is a clear capability gap worth the migration cost.
Remove or migrate the non-owner stack
- If consolidating on dev-server-*: remove devserver-* modules/tests or relocate them behind an explicit experimental namespace.
- If consolidating on devserver-*: complete route/server integration and delete replaced dev-server-* modules.
Guard against reintroduction
- Add a lightweight lint/test assertion that prevents both naming families from being reintroduced without explicit architecture note/update.

FN-2212 Definition of Done (proposed)

There is one clearly documented canonical dev-server module family.
Runtime/API imports use only the canonical family.
The non-canonical family is either removed or explicitly isolated as experimental with zero ambiguity.
Architecture docs and contributor guidance call out the owner modules and persistence file contract.

3.6 KiB Raw Blame History