suaveplan/openspec/archive/2026-05-11-network-plugin-devtools/tasks.md

Tasks — network-plugin-devtools

Blocked on: network-core, network-plugin-monitor, network-plugin-simulation.

Status (2026-05-11): SHIPPED. All 4 subsystems implemented at enterprise grade with 100/100/100/100 coverage and full spec-conformance suite. Capability spec openspec/specs/network-plugin-devtools/spec.md published with seven ### Requirement: NET_DEV-NN — clauses, each carrying a **Verified by:** line.

1. Scaffold

• 1.1 packages/network/network-plugin-devtools/ with package.json (@suaveplan/network-plugin-devtools@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/diff (added for inspector RFC-6902 diff), @suaveplan/opentelemetry/@opentelemetry/api, zod.
• 1.3 sideEffects: false.
• 1.4 Marked as devOnly: true in workspace config — implemented via package.json "suaveplan": { "tier": "devtools" } block (no monorepo-wide convention exists yet for this; the dev-only contract is enforced at runtime via the tierGate callback on DevToolsPlugin).

2. Types

• 2.1 src/types/visualizer.types.ts — VisualizerConfig, VisualizerMode, NodeLayout, plus EdgeLayout, HeatCell, VisualizerFilter, TopologyAdapter, MessageStreamAdapter, Renderer, RendererOutput, VisualizerScene.
• 2.2 src/types/inspector.types.ts — InspectorConfig, StateView, DiffView, plus StateSnapshot, DiffSummary, SearchFilter.
• 2.3 src/types/profiler.types.ts — ProfilerConfig, PerformanceReport, Baseline, plus LatencySample, ThroughputSample, PluginOverheadSample, MemorySample, LatencyDistribution, Regression, RegressionSeverity, OptimizationSuggestion.
• 2.4 src/error-codes.ts — defineCodes("NET_DEV", [...]) registry of 20 codes spanning all four subsystems plus the plugin facade.

3. Network visualizer

• 3.1 src/visualizer/network-visualizer.ts — NetworkVisualizer.
• 3.2 Hierarchy view: tier structure, edges, labels (via TopologyAdapter).
• 3.3 Message flow view: animated paths, throughput, drops (via MessageStreamAdapter).
• 3.4 Performance heat map: latency colour-coding, saturation (via HeatCell IR + bundled SvgRenderer).
• 3.5 Filtering by tier, latency group, session, transport (Zod VisualizerFilter).
• 3.6 Export to PNG/SVG (Renderer injection — bundled SvgRenderer; PNG via caller-supplied encoder).

4. State inspector

• 4.1 src/inspector/state-inspector.ts — StateInspector.
• 4.2 Tree view of synchronised state paths (list() + inspect(path)).
• 4.3 Historical state viewing with timeline scrubber (scrub(path, atVersion)).
• 4.4 Diff visualisation between two versions (diff(path, fromVersion, toVersion) over @suaveplan/diff).
• 4.5 Search and filter by path, peer, session (search(SearchFilter)).

5. Simulation config tool

• 5.1 src/simulator/simulation-config-tool.ts — SimulationConfigTool (+ simulation-config-tool.schemas.ts Zod boundary split).
• 5.2 Topology editor (programmatic API: addPeer, removePeer, listPeers).
• 5.3 Network condition editor (latency/loss/bandwidth curves: setCondition, clearCondition, listConditions).
• 5.4 Event timeline editor (addEvent, listEvents).
• 5.5 Recording and playback (startRecording/stopRecording/loadPlayback/playback).
• 5.6 Export/import scenarios as JSON (exportJson/importJson with full Zod validation).

6. Performance profiler

• 6.1 src/profiler/performance-profiler.ts — PerformanceProfiler (+ performance-profiler.suggestions.ts heuristic split).
• 6.2 Message latency distribution (p50, p95, p99; min/max/mean/count).
• 6.3 Transport throughput per path (recordThroughput).
• 6.4 Plugin overhead measurement (recordPluginOverhead with windowed averaging).
• 6.5 Memory usage tracking (recordMemory).
• 6.6 Regression detection against baseline (captureBaseline + compare with two-window EMA + Z-score severity ladder).
• 6.7 Optimization suggestions (suggestions() covering tail latency, overhead, heap pressure, zero throughput).

7. Plugin wrapper

• 7.1 src/plugin/devtools-plugin.ts — DevToolsPlugin implements NetworkPlugin.
• 7.2 No-op in production (tier gate short-circuits start(); requireActive() raises PLUGIN_DEV_DISABLED).
• 7.3 Exposes visualizer, inspector, simulator, profiler on plugin API as public fields.

8. Spec

• 8.1 Capability spec openspec/specs/network-plugin-devtools/spec.md published with seven ### Requirement: NET_DEV-NN — clauses, each carrying a **Verified by:** line referencing the matching *.spec-conformance.test.ts. (Originally scoped out as "no spec required (dev-only tool)"; promoted during the un-deferral sweep so the conformance gate runs against the same contract every other network plugin is held to.)

9. Conformance tests

• 9.1 src/visualizer/visualizer.spec-conformance.test.ts — hierarchy, flow, heat map, export (26 tests).
• 9.2 src/inspector/inspector.spec-conformance.test.ts — tree, history, diff, search (14 tests).
• 9.3 src/simulator/simulator.spec-conformance.test.ts — editor, playback, export/import (25 tests).
• 9.4 src/profiler/profiler.spec-conformance.test.ts — latency, throughput, regression, suggestions (33 tests).
• 9.5 src/error-codes.spec-conformance.test.ts — frozen registry (6 tests).

Plus src/plugin/devtools-plugin.spec-conformance.test.ts (7 tests) covering the facade per NET_DEV-06.

10. Verify

• 10.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-devtools GREEN — 10 tasks successful, 111 tests passed.
• 10.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-devtools 100/100/100/100 (statements 502/502, branches 253/253, functions 108/108, lines 445/445).
• 10.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-devtools PASS (0 error, 0 warn, 0 info).