epic: NetScript Dev Dashboard — the Aspire/Scalar satellite that drives the framework (ships as a plugin, beta.6)

[rickylabs]

Summary

A DX-oriented dev dashboard shipping as plugins/dashboard + packages/plugin-dashboard-core on @netscript/fresh-ui. It is a satellite of Aspire's control surface, not a rival — and it is how you drive the framework: it renders only NetScript-domain state Aspire and Scalar cannot see, mirrors the CLI's management verbs through the UI, and deep-links back out to Aspire/Scalar for everything they already own.

Rescoped 2026-07-06 (owner mandate, amended same day). The pass-1 direction duplicated Aspire/Scalar surfaces. The rescope keeps three pillars from the original seed research: Observe (only-NetScript state), Manage (Appwrite-style per-capability console mirroring the CLI), Follow (Encore-model live seam-flow, never re-rendered OTLP).

DX thesis

Answer the questions no existing tool can: "is my NetScript app wired the way I declared it, what is my runtime doing right now at the primitive level, what did this request actually cause, and let me act on it without leaving the browser."

• Aspire owns: resources, console/structured logs, raw traces, metrics, health, process lifecycle.
• Scalar owns: API reference, schemas, try-it, code samples.
• The dashboard owns: primitive run-state (executions/attempts, saga instances incl. compensating, trigger firings, stream deliveries), the runtime override/config layer including gated write-back, plugin-registry wiring + doctor + contribution axes, contract provenance/coverage/duality, route→contract binding, codegen/scaffold state (migrations, drift), the per-capability management loop (create → configure(tabs) → monitor), and the live request journey across framework seams (S13).

Authoritative screen set (supersedes the pass-1 DDX panel list)

• S1 Shell & Wiring Home — [dashboard DDX-5] Fresh build-console shell + app-registration + IA #415 (v2: + quick-action strip mirroring top CLI verbs)
• S2 Config Resolution & Topology Hand-off — [dashboard DDX-6] Stack Map panel #416 (v2: + live-traffic edge overlay, Encore Flow model)
• S3 Runtime-Config Monitor & Control ⚑ flagship — [dashboard DDX-20] S3: Runtime-Config Monitor & Control (flagship) #551 (DDX-20, new; v2: write-back gated on feat(runtime-config): mutation use-cases — set/unset + versioned current pointer bump (S3 write-back co-req) #556, beta.7)
• S4 Service & Contract Catalog — [dashboard DDX-7] Service Catalog + API Explorer panel #417 (provenance/coverage/duality only; no try-it)
• S5 Plugin Control (dogfood centerpiece) — [dashboard DDX-10] Plugin Control host + registry/overview #420 (v2: + install/scaffold entry points, marketplace-lite)
• S6 Run Inspector + NetScript run-overlay — [dashboard DDX-9] Run Inspector panel #419 (run-centric)
• S7–S10 Workers / Sagas / Triggers / Streams consoles — [dashboard DDX-18a] workers per-capability dashboard section #428 [dashboard DDX-18b] sagas per-capability dashboard section #429 [dashboard DDX-18c] triggers per-capability dashboard section #430 [dashboard DDX-18d] streams per-capability dashboard section #431 (v2: each completes the create→configure→monitor→act management loop)
• S11 DB Migrations & Drift — [dashboard DDX-21] S11: DB Migrations & Drift #552 (DDX-21, new; beta.6-if-cheap; migrate/seed actions)
• S12 Dead-Letter Queues — [dashboard DDX-22] S12: Dead-Letter Queues (queue + trigger) #553 (DDX-22, new; wave:defer, gated on thin API slices)
• S13 Live Flow — request journey ⚑ flagship S1: package quality — slow-types + docs (supervisor) — Waves 0–6 ✅ merged  #2 — [dashboard DDX-8] S13: Live Flow — request journey across framework seams #418 (v2 REWRITE, was pass-1 waterfall: now the seam-event causal chain — request → payload → job → saga → fan-out — with per-node Aspire out-links)

Acceptance lines (MANDATORY, gate every slice)

1. Non-duplication. No dashboard screen may render, as an owned surface: an OTLP trace waterfall / span-bar gantt, a structured/console log tail, a metrics chart, a resource start/stop/restart panel, or an OpenAPI operation list / try-it console. Each is Aspire's or Scalar's job and MUST be a deep-link out. Every merged panel must pass "why can't this just deep-link to Aspire/Scalar?" with a NetScript-only answer recorded in its issue — only-NetScript state, only-NetScript action (CLI-mirroring), or framework-seam semantics raw OTLP cannot express.
2. One generator, two callers. Every dashboard mutation invokes the same contract route / CLI scaffolder the terminal does and renders its CLI-equivalent line (netscript … CodeBlock). No dashboard-only write paths, no forked codegen.
3. Flow ≠ waterfall. S13 renders a primitive-grouped causal chain with payloads at seams, assembled from NetScript's own seam events; the moment raw timing/span detail is needed it out-links to Aspire /traces/detail/{id}. No span bars, no time-proportional gantt, no log tails in S13 — ever.

Integration seams (four seams, one URL scheme)

1. Aspire → dashboard: WithUrl("NetScript Dashboard", /resource/{name}) on every scaffolded resource + two framework withCommands — generator emission on [dashboard DDX-14] CLI surface + auto-launch #424, Seam A widening (command/app kinds) on [dashboard DDX-1] @netscript/aspire command + app resource kinds #411, Seam B interim.
2. Dashboard → Aspire: correlation-only TelemetryQueryPort ([dashboard DDX-3] TelemetryQueryPort + aspire-otlp-http adapter #413) resolves a traceId, then out-links to {aspireBase}/traces/detail/{id}, /structuredlogs?resource=, /consolelogs/resource/, /metrics/resource/. Never re-renders OTLP. The S13 flow plane does not widen this port.
3. Dashboard → Scalar: /api/docs (+ operation anchor) deep-links only; externalDocs optional polish.
4. Data plane: owned /_netscript/* introspection ([dashboard DDX-13] Introspection endpoint (/_netscript/*) #423) over already-shipped oRPC contracts, plus /_netscript/flows (SSE): beta.6 joins the shipped per-primitive streams on the stamped traceparent; co-req DDX-23 ([dashboard DDX-23] seam-event flow plane: unified envelope + HTTP boundary events (S13 co-req) #557) adds the unified seam-event envelope + HTTP boundary events.

Killed / folded surfaces (documented so they don't creep back)

• Raw OTLP waterfall renderer (pass-1 [dashboard DDX-8] S13: Live Flow — request journey across framework seams #418 scope → dead; [dashboard DDX-8] S13: Live Flow — request journey across framework seams #418 rescoped to the S13 seam-flow journey, which is not a waterfall — acceptance line 3).
• Logs panel ([dashboard DDX-11] Logs panel #421 → closed; correlated strip in S6 deep-links Aspire logs).
• Resource-control panel ([dashboard DDX-12] Resource Control panel #422 → closed; delivered as withCommand contributions inside Aspire).
• Service /health panel (→ Aspire State column via a proper withHealthCheck() wiring fix).
• Metrics charts + GenAI conversation view (→ Aspire, link only).
• Scalar-style operation list / try-it (→ Scalar /api/docs; the S4 catalog is provenance-only).

Slice map / dependencies

Plumbing: #410 (fresh-ui L3 blocks) → #412 (core scaffold, + FlowRecord) → #414 (thin plugin) · #411 (Seam A) · #413 (+#408 telemetry T7) · #423 (introspection + flows join) · #424 (CLI/deep-links/generator) · #427 (panel seam — the Directus-validated contribution axis).
Screens: #415, #416, #417, #418 (S13), #419, #420, #428–#431, DDX-20/21/22 (#551 #552 #553).
Management wave (beta.7): #432 elevated — "Add resource" scaffold-from-UI keystone; DDX-23 seam-event envelope #557; template-gallery create entries in S5/S7–S10.
Design pre-step: #507 (S1–S13 Claude Design prototype; duplication caught at design review). UI quality: #509.
Gate: #426 (E2E join + panel smoke; v2 adds the S13 flow-chain assertion, still no owned-waterfall assertion).
Co-requisites (wave:defer): TriggerDlqPort contract route #554, queue DeadLetterStore CLI/API #555. Co-requisite (beta.7): runtime-config mutation use-cases #556 (S3 write-back — surface check 2026-07-06: the store is read+watch-only today).
Deferred convergences: in-dashboard AI-on-codegen (with #238), in-app plugin marketplace beyond S5 marketplace-lite.

Refs #301 (road to stable). Co-lands with epic:telemetry-revamp (#399) for T4–T7 correlation fidelity.