Initial Commit
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# OpenSpec Change: network-plugin-devtools
|
||||
|
||||
- **Change ID**: network-plugin-devtools
|
||||
- **Package**: `@suaveplan/network-plugin-devtools` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
Debugging a distributed mesh network is notoriously difficult. Peers join and leave, messages are dropped, topology reorganizes, and state diverges. Without specialized developer tools, engineers must rely on console logs and guesswork. The old planning documents envisioned a comprehensive developer experience layer: real-time network visualization, interactive state inspection, simulation configuration, and performance profiling.
|
||||
|
||||
This plugin provides **developer tools** for the network layer: visualization, state inspection, simulation configuration, and performance analysis. It is dev-only and does not run in production.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `DevToolsPlugin` class implementing `NetworkPlugin` (dev-only, no-op in production).
|
||||
- **ADDED**: `NetworkVisualizer` — real-time visualization of the mesh:
|
||||
- Hierarchy view: tier structure, host/sub-host/leaf nodes, parent-child edges
|
||||
- Message flow view: animated message paths, throughput per link, dropped messages
|
||||
- Performance heat map: latency color-coding, bandwidth saturation, error rates
|
||||
- Filtering by tier, latency group, session, transport type
|
||||
- Export to PNG/SVG for documentation
|
||||
- **ADDED**: `StateInspector` — interactive state browser:
|
||||
- Tree view of all synchronized state paths
|
||||
- Historical state viewing with timeline scrubber
|
||||
- Diff visualization between two state versions
|
||||
- Search and filter by path, peer, or session
|
||||
- **ADDED**: `SimulationConfigTool` — scenario builder UI:
|
||||
- Drag-and-drop network topology editor
|
||||
- Network condition editor (latency, loss, bandwidth curves)
|
||||
- Event timeline editor
|
||||
- Simulation recording and playback
|
||||
- Scenario sharing (export/import JSON)
|
||||
- **ADDED**: `PerformanceProfiler` — performance analysis:
|
||||
- Message latency distribution (p50, p95, p99)
|
||||
- Transport throughput per path
|
||||
- Plugin overhead measurement
|
||||
- Memory usage tracking
|
||||
- Regression detection: compares current run against baseline
|
||||
- Optimization suggestions based on bottlenecks
|
||||
- **ADDED**: `NETWORK_DEV_CODES` — frozen error registry.
|
||||
|
||||
## DevTools API
|
||||
|
||||
```typescript
|
||||
// Start visualization
|
||||
visualizer.start({ mode: 'hierarchy', refreshRate: 30 });
|
||||
|
||||
// Focus on a specific peer
|
||||
visualizer.focus(peerId);
|
||||
|
||||
// Inspect state at a path
|
||||
inspector.inspect('game/positions/player1');
|
||||
|
||||
// Run a predefined scenario
|
||||
simulator.runScenario('client-surge', { nodeCount: 100 });
|
||||
|
||||
// Compare performance against baseline
|
||||
profiler.compare(baselineRunId);
|
||||
```
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Production monitoring → `network-plugin-monitor`.
|
||||
- Production alerting → `network-plugin-monitor`.
|
||||
- Simulation engine → `network-plugin-simulation`.
|
||||
- Framework-specific UI components → future React/Vue/Angular wrappers.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This derives from `docs/old-network-planning/ADAPT_5.md` §Developer Tooling and `PHASE_8.md` §Visualization.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| Network visualizer | `ADAPT_5.md` §Network Visualizer Tool | reworded; modes: hierarchy, messages, performance |
|
||||
| State inspector | `ADAPT_5.md` §State Inspector Tool | reworded; diff visualization |
|
||||
| Simulation config | `ADAPT_5.md` §Simulation Configuration Tool | reworded; scenario builder |
|
||||
| Performance profiling | `ADAPT_5.md` §Performance Profiling Tools | reworded; regression detection |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| Export to PNG/SVG | Required for documentation and bug reports |
|
||||
| Regression detection | Required to catch performance degradation in CI |
|
||||
| Scenario sharing | Required for team collaboration on test cases |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/visualizer/visualizer.spec-conformance.test.ts` — pins hierarchy rendering, message flow, heat map.
|
||||
- `src/inspector/inspector.spec-conformance.test.ts` — pins state tree, history, diff.
|
||||
- `src/simulator/simulator.spec-conformance.test.ts` — pins scenario builder, playback, export/import.
|
||||
- `src/profiler/profiler.spec-conformance.test.ts` — pins latency distribution, overhead, regression.
|
||||
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. This package is dev-only and not imported in production builds.
|
||||
81
openspec/archive/2026-05-11-network-plugin-devtools/tasks.md
Normal file
81
openspec/archive/2026-05-11-network-plugin-devtools/tasks.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 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
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-devtools/` with `package.json` (`@suaveplan/network-plugin-devtools@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 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`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
- [x] 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
|
||||
|
||||
- [x] 2.1 `src/types/visualizer.types.ts` — `VisualizerConfig`, `VisualizerMode`, `NodeLayout`, plus `EdgeLayout`, `HeatCell`, `VisualizerFilter`, `TopologyAdapter`, `MessageStreamAdapter`, `Renderer`, `RendererOutput`, `VisualizerScene`.
|
||||
- [x] 2.2 `src/types/inspector.types.ts` — `InspectorConfig`, `StateView`, `DiffView`, plus `StateSnapshot`, `DiffSummary`, `SearchFilter`.
|
||||
- [x] 2.3 `src/types/profiler.types.ts` — `ProfilerConfig`, `PerformanceReport`, `Baseline`, plus `LatencySample`, `ThroughputSample`, `PluginOverheadSample`, `MemorySample`, `LatencyDistribution`, `Regression`, `RegressionSeverity`, `OptimizationSuggestion`.
|
||||
- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_DEV", [...])` registry of 20 codes spanning all four subsystems plus the plugin facade.
|
||||
|
||||
## 3. Network visualizer
|
||||
|
||||
- [x] 3.1 `src/visualizer/network-visualizer.ts` — `NetworkVisualizer`.
|
||||
- [x] 3.2 Hierarchy view: tier structure, edges, labels (via `TopologyAdapter`).
|
||||
- [x] 3.3 Message flow view: animated paths, throughput, drops (via `MessageStreamAdapter`).
|
||||
- [x] 3.4 Performance heat map: latency colour-coding, saturation (via `HeatCell` IR + bundled `SvgRenderer`).
|
||||
- [x] 3.5 Filtering by tier, latency group, session, transport (Zod `VisualizerFilter`).
|
||||
- [x] 3.6 Export to PNG/SVG (`Renderer` injection — bundled `SvgRenderer`; PNG via caller-supplied encoder).
|
||||
|
||||
## 4. State inspector
|
||||
|
||||
- [x] 4.1 `src/inspector/state-inspector.ts` — `StateInspector`.
|
||||
- [x] 4.2 Tree view of synchronised state paths (`list()` + `inspect(path)`).
|
||||
- [x] 4.3 Historical state viewing with timeline scrubber (`scrub(path, atVersion)`).
|
||||
- [x] 4.4 Diff visualisation between two versions (`diff(path, fromVersion, toVersion)` over `@suaveplan/diff`).
|
||||
- [x] 4.5 Search and filter by path, peer, session (`search(SearchFilter)`).
|
||||
|
||||
## 5. Simulation config tool
|
||||
|
||||
- [x] 5.1 `src/simulator/simulation-config-tool.ts` — `SimulationConfigTool` (+ `simulation-config-tool.schemas.ts` Zod boundary split).
|
||||
- [x] 5.2 Topology editor (programmatic API: `addPeer`, `removePeer`, `listPeers`).
|
||||
- [x] 5.3 Network condition editor (latency/loss/bandwidth curves: `setCondition`, `clearCondition`, `listConditions`).
|
||||
- [x] 5.4 Event timeline editor (`addEvent`, `listEvents`).
|
||||
- [x] 5.5 Recording and playback (`startRecording`/`stopRecording`/`loadPlayback`/`playback`).
|
||||
- [x] 5.6 Export/import scenarios as JSON (`exportJson`/`importJson` with full Zod validation).
|
||||
|
||||
## 6. Performance profiler
|
||||
|
||||
- [x] 6.1 `src/profiler/performance-profiler.ts` — `PerformanceProfiler` (+ `performance-profiler.suggestions.ts` heuristic split).
|
||||
- [x] 6.2 Message latency distribution (p50, p95, p99; min/max/mean/count).
|
||||
- [x] 6.3 Transport throughput per path (`recordThroughput`).
|
||||
- [x] 6.4 Plugin overhead measurement (`recordPluginOverhead` with windowed averaging).
|
||||
- [x] 6.5 Memory usage tracking (`recordMemory`).
|
||||
- [x] 6.6 Regression detection against baseline (`captureBaseline` + `compare` with two-window EMA + Z-score severity ladder).
|
||||
- [x] 6.7 Optimization suggestions (`suggestions()` covering tail latency, overhead, heap pressure, zero throughput).
|
||||
|
||||
## 7. Plugin wrapper
|
||||
|
||||
- [x] 7.1 `src/plugin/devtools-plugin.ts` — `DevToolsPlugin implements NetworkPlugin`.
|
||||
- [x] 7.2 No-op in production (tier gate short-circuits `start()`; `requireActive()` raises `PLUGIN_DEV_DISABLED`).
|
||||
- [x] 7.3 Exposes visualizer, inspector, simulator, profiler on plugin API as public fields.
|
||||
|
||||
## 8. Spec
|
||||
|
||||
- [x] 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
|
||||
|
||||
- [x] 9.1 `src/visualizer/visualizer.spec-conformance.test.ts` — hierarchy, flow, heat map, export (26 tests).
|
||||
- [x] 9.2 `src/inspector/inspector.spec-conformance.test.ts` — tree, history, diff, search (14 tests).
|
||||
- [x] 9.3 `src/simulator/simulator.spec-conformance.test.ts` — editor, playback, export/import (25 tests).
|
||||
- [x] 9.4 `src/profiler/profiler.spec-conformance.test.ts` — latency, throughput, regression, suggestions (33 tests).
|
||||
- [x] 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
|
||||
|
||||
- [x] 10.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-devtools` GREEN — 10 tasks successful, 111 tests passed.
|
||||
- [x] 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).
|
||||
- [x] 10.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-devtools` PASS (0 error, 0 warn, 0 info).
|
||||
Reference in New Issue
Block a user