@nwire/studio 0.12.1 → 0.13.1

package/src/lib/topology-view.ts

@@ -0,0 +1,185 @@
+/**
+ * Topology view — pure selectors that shape the deep manifest's runtime
+ * `topology` layer into the rows the specialized Hooks + Plugins pages render,
+ * and tally the live hook-tap from telemetry. Reads `ManifestView` (the
+ * `topology.hooks` registry, the `topology.plugins` list, capabilities,
+ * `ctxByKind`) and `TelemetryRecord`s.
+ *
+ * Kept pure (no DOM, no fetch) so it unit-tests in isolation; the pages bind
+ * `useManifest` + `useTelemetry` to these.
+ */
+import type { ManifestView } from "./manifest";
+import type { TelemetryRecord } from "./telemetry";
+
+/** A `plugin.boot:<n>` / `plugin.shutdown:<n>` lifecycle prefix. */
+const LIFECYCLE_PREFIXES = ["plugin.boot:", "plugin.shutdown:"] as const;
+
+/** One named hook in the registry — the Hooks master row. */
+export interface HookRow {
+  /** Stable id for selection (`hook:<name>` when the topology omits its own). */
+  readonly id: string;
+  readonly name: string;
+  readonly chain: number;
+  readonly listeners: number;
+  /** Where the hook was authored — drives the SourcePill. */
+  readonly source?: { readonly file: string; readonly line?: number; readonly column?: number };
+}
+
+/** One plugin in the registry — the Plugins master row. */
+export interface PluginRow {
+  /** Stable id for selection (`plugin:<name>`). */
+  readonly id: string;
+  readonly name: string;
+}
+
+/** A boot/shutdown hook attributed to a plugin (the lifecycle internals). */
+export interface PluginLifecycleHook {
+  readonly name: string;
+  readonly phase: "boot" | "shutdown";
+  readonly chain: number;
+  readonly listeners: number;
+}
+
+/** The deep internals assembled for a selected plugin. */
+export interface PluginInternals {
+  readonly name: string;
+  /** Boot/shutdown hooks the plugin registered (`plugin.boot:<n>` / `…shutdown:<n>`). */
+  readonly lifecycleHooks: readonly PluginLifecycleHook[];
+  /** Names this plugin contributes via `contributes` / `mounts` graph edges. */
+  readonly contributes: readonly string[];
+  /** A same-named capability's ctx-by-kind, when one exists. */
+  readonly ctxByKind: Readonly<Record<string, readonly string[]>>;
+}
+
+/** A live-fire entry for one hook, tallied from `hook.step` telemetry. */
+export interface HookFire {
+  /** Count of `start`-phase steps seen for this hook (one per fire). */
+  readonly fires: number;
+  /** ISO timestamp of the most recent step, if any. */
+  readonly lastTs?: string;
+}
+
+/** Read a string field off a loosely-typed record, or undefined. */
+function str(rec: TelemetryRecord, key: string): string | undefined {
+  const v = (rec as Record<string, unknown>)[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * The hook registry from native topology, name-sorted. Tolerant of missing
+ * `chain` / `listeners` (older topology) and a missing topology entirely.
+ */
+export function hookRegistry(view: ManifestView | null): HookRow[] {
+  const hooks = view?.manifest.topology?.hooks ?? [];
+  return hooks
+    .filter((h) => typeof h.name === "string" && h.name.length > 0)
+    .map((h) => ({
+      id: h.id ?? `hook:${h.name}`,
+      name: h.name,
+      chain: h.chain ?? 0,
+      listeners: h.listeners ?? 0,
+      source: h.source,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The plugin name that registered a `plugin.boot:<n>` / `plugin.shutdown:<n>`
+ * hook, or `null` for a non-lifecycle hook. Powers the Hooks "Registered by"
+ * cross-link.
+ */
+export function registeringPlugin(hookName: string | undefined | null): string | null {
+  if (!hookName) return null;
+  for (const prefix of LIFECYCLE_PREFIXES) {
+    if (hookName.startsWith(prefix)) return hookName.slice(prefix.length);
+  }
+  return null;
+}
+
+/** The plugin registry from native topology, name-sorted. */
+export function pluginRegistry(view: ManifestView | null): PluginRow[] {
+  const plugins = view?.manifest.topology?.plugins ?? [];
+  return plugins
+    .filter((p) => typeof p.name === "string" && p.name.length > 0)
+    .map((p) => ({ id: `plugin:${p.name}`, name: p.name }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Assemble a plugin's deep internals: its boot/shutdown lifecycle hooks (parsed
+ * back from `topology.hooks`), what it contributes (graph `contributes` /
+ * `mounts` edges out of its node), and a same-named capability's ctx-by-kind.
+ * Pure; tolerant of a missing topology / model.
+ */
+export function pluginInternals(
+  view: ManifestView | null,
+  name: string | null | undefined,
+): PluginInternals | null {
+  if (!view || !name) return null;
+
+  const hooks = view.manifest.topology?.hooks ?? [];
+  const lifecycleHooks: PluginLifecycleHook[] = [];
+  for (const h of hooks) {
+    if (h.name === `plugin.boot:${name}`)
+      lifecycleHooks.push({
+        name: h.name,
+        phase: "boot",
+        chain: h.chain ?? 0,
+        listeners: h.listeners ?? 0,
+      });
+    else if (h.name === `plugin.shutdown:${name}`)
+      lifecycleHooks.push({
+        name: h.name,
+        phase: "shutdown",
+        chain: h.chain ?? 0,
+        listeners: h.listeners ?? 0,
+      });
+  }
+  // Boot before shutdown.
+  lifecycleHooks.sort((a, b) => (a.phase === b.phase ? 0 : a.phase === "boot" ? -1 : 1));
+
+  // `contributes` / `mounts` edges out of this plugin node (emitted by richer
+  // topology captures; absent ones simply yield no rows).
+  const id = `plugin:${name}`;
+  const contributes = view
+    .edgesOf(id, "out")
+    .filter((e) => e.type === "contributes" || e.type === "mounts")
+    .map((e) => {
+      const node = view.node(e.to);
+      return node?.name ?? e.to;
+    })
+    .sort((a, b) => a.localeCompare(b));
+
+  // A capability registered under the same name carries the ctx-by-kind it adds.
+  const capByKind: Record<string, readonly string[]> = {};
+  const capNode = view.node(`capability:${name}`);
+  const capKinds = capNode?.data?.kinds;
+  const capCtxKeys = capNode?.data?.ctxKeys;
+  if (Array.isArray(capCtxKeys)) {
+    const kinds = Array.isArray(capKinds) && capKinds.length ? (capKinds as string[]) : ["*"];
+    for (const k of kinds) capByKind[k] = capCtxKeys as string[];
+  }
+
+  return { name, lifecycleHooks, contributes, ctxByKind: capByKind };
+}
+
+/**
+ * Tally live hook fires from `hook.step` telemetry, keyed by hook name. Counts
+ * one fire per `start`-phase step (a fire's first observation); records the most
+ * recent step's timestamp regardless of phase. Records of other kinds are
+ * ignored, so it degrades to an empty map when no stream/records exist.
+ */
+export function liveFireTally(records: readonly TelemetryRecord[]): Map<string, HookFire> {
+  const out = new Map<string, HookFire>();
+  for (const rec of records) {
+    if (rec.kind !== "hook.step") continue;
+    const name = str(rec, "hookName");
+    if (!name) continue;
+    const prev = out.get(name);
+    const phase = str(rec, "phase");
+    const fires = (prev?.fires ?? 0) + (phase === "start" || phase === undefined ? 1 : 0);
+    const ts = rec.ts ?? prev?.lastTs;
+    out.set(name, { fires, lastTs: ts });
+  }
+  return out;
+}

package/src/lib/waterfall.ts

@@ -0,0 +1,148 @@
+/**
+ * Waterfall layout — pure geometry for the Flow / Trace view.
+ *
+ * Takes a causation forest (`TraceNode[]` from `buildCorrelationTree`) and lays
+ * it out as time-positioned rows: depth-indented, each with an offset + width as
+ * a percentage of the trace span, plus the critical path (the longest-duration
+ * root→leaf chain). No DOM, no Vue — unit-tested in isolation; the component
+ * just renders the rows.
+ */
+import { isFailure, type TelemetryRecord, type TraceNode } from "./telemetry";
+
+/** Smallest bar a row gets so zero-duration spans stay visible as a tick. */
+const MIN_WIDTH_PCT = 1.5;
+
+/** One laid-out row of the waterfall. */
+export interface WaterfallRow {
+  readonly record: TelemetryRecord;
+  /** Tree depth (0 = root) — drives the gutter indent. */
+  readonly depth: number;
+  /** ms from the trace start to this row's start. */
+  readonly offsetMs: number;
+  /** This row's own duration in ms (0 if instantaneous). */
+  readonly durationMs: number;
+  /** Left edge as a percentage [0,100] of the trace span. */
+  readonly offsetPct: number;
+  /** Bar width as a percentage of the trace span (clamped to a visible min). */
+  readonly widthPct: number;
+  /** On the critical (longest-duration) path. */
+  readonly critical: boolean;
+  /** A failure record (drives the red row treatment). */
+  readonly failed: boolean;
+  /** Human label — handler/event name, falling back to the kind. */
+  readonly label: string;
+  /** Stable key for `v-for` + selection. */
+  readonly key: string;
+}
+
+/** The full layout: rows in pre-order plus the resolved time window. */
+export interface WaterfallLayout {
+  readonly rows: WaterfallRow[];
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly spanMs: number;
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return Math.max(lo, Math.min(hi, n));
+}
+
+function parseTs(r: TelemetryRecord): number | undefined {
+  if (!r.ts) return undefined;
+  const t = Date.parse(r.ts);
+  return Number.isNaN(t) ? undefined : t;
+}
+
+/** The display name carried on a record, by convention, else the kind. */
+export function recordLabel(r: TelemetryRecord): string {
+  for (const field of ["name", "action", "event", "query", "actor", "workflow", "handler"]) {
+    const v = r[field];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return r.kind;
+}
+
+interface Flat {
+  readonly node: TraceNode;
+  readonly depth: number;
+}
+
+function flatten(forest: readonly TraceNode[], depth = 0, out: Flat[] = []): Flat[] {
+  for (const node of forest) {
+    out.push({ node, depth });
+    flatten(node.children, depth + 1, out);
+  }
+  return out;
+}
+
+/** The longest downward (root→leaf) path by total duration, with its total. */
+function bestPath(node: TraceNode): { total: number; nodes: TraceNode[] } {
+  const self = node.record.durationMs ?? 0;
+  if (node.children.length === 0) return { total: self, nodes: [node] };
+  let best = { total: -1, nodes: [] as TraceNode[] };
+  for (const child of node.children) {
+    const p = bestPath(child);
+    if (p.total > best.total) best = p;
+  }
+  return { total: self + best.total, nodes: [node, ...best.nodes] };
+}
+
+/**
+ * The critical path across a forest — the single root→leaf chain with the
+ * greatest summed duration. Returns the set of nodes on that chain.
+ */
+export function criticalPath(forest: readonly TraceNode[]): Set<TraceNode> {
+  let best = { total: -1, nodes: [] as TraceNode[] };
+  for (const root of forest) {
+    const p = bestPath(root);
+    if (p.total > best.total) best = p;
+  }
+  return new Set(best.nodes);
+}
+
+/**
+ * Lay a causation forest out as a waterfall. Rows are returned in pre-order
+ * (parents before children). When records carry `ts`, bars are time-positioned
+ * against the trace span; when none do, every bar spans full width so the tree
+ * still reads (depth + kind + duration label) without a timeline.
+ */
+export function buildWaterfall(forest: readonly TraceNode[]): WaterfallLayout {
+  const flat = flatten(forest);
+  const crit = criticalPath(forest);
+
+  const starts = flat
+    .map((f) => parseTs(f.node.record))
+    .filter((t): t is number => t !== undefined);
+  const haveTime = starts.length > 0;
+  const startMs = haveTime ? Math.min(...starts) : 0;
+  const endMs = haveTime
+    ? Math.max(
+        ...flat.map((f) => (parseTs(f.node.record) ?? startMs) + (f.node.record.durationMs ?? 0)),
+      )
+    : 0;
+  const spanMs = Math.max(endMs - startMs, 1);
+
+  const rows: WaterfallRow[] = flat.map((f, i) => {
+    const rec = f.node.record;
+    const start = parseTs(rec) ?? startMs;
+    const offsetMs = haveTime ? start - startMs : 0;
+    const durationMs = rec.durationMs ?? 0;
+    const offsetPct = haveTime ? clamp((offsetMs / spanMs) * 100, 0, 100) : 0;
+    const rawWidth = haveTime ? (durationMs / spanMs) * 100 : 100;
+    const widthPct = clamp(Math.max(rawWidth, MIN_WIDTH_PCT), MIN_WIDTH_PCT, 100 - offsetPct);
+    return {
+      record: rec,
+      depth: f.depth,
+      offsetMs,
+      durationMs,
+      offsetPct,
+      widthPct,
+      critical: crit.has(f.node),
+      failed: isFailure(rec),
+      label: recordLabel(rec),
+      key: rec.envelope?.messageId ?? `${rec.kind}-${i}`,
+    };
+  });
+
+  return { rows, startMs, endMs, spanMs };
+}

package/src/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from "vue";
 import { createRouter, createWebHistory } from "vue-router";
+import { VueQueryPlugin } from "@tanstack/vue-query";
 import App from "./App.vue";
 import "./style.css";
 import { getActiveProjectCwd, loadCatalog } from "./lib/project-catalog";
@@ -47,23 +48,16 @@ class ScopedEventSource extends OriginalEventSource {
 (window as unknown as { EventSource: typeof OriginalEventSource }).EventSource = ScopedEventSource;
 
 import Home from "./pages/Home.vue";
-import Overview from "./pages/Overview.vue";
+import MapView from "./pages/Map.vue";
 import Topology from "./pages/Topology.vue";
 import Trace from "./pages/Trace.vue";
-import Actions from "./pages/Actions.vue";
-import Events from "./pages/Events.vue";
-import Workflows from "./pages/Workflows.vue";
 import Hooks from "./pages/Hooks.vue";
 import Plugins from "./pages/Plugins.vue";
-import Live from "./pages/Live.vue";
-import Dispatch from "./pages/Dispatch.vue";
-import Run from "./pages/Run.vue";
-import Commands from "./pages/Commands.vue";
+import Streams from "./pages/Streams.vue";
+import Operate from "./pages/Operate.vue";
 import Projects from "./pages/Projects.vue";
-import Projections from "./pages/Projections.vue";
-import Queries from "./pages/Queries.vue";
-import Apps from "./pages/Apps.vue";
-import Sinks from "./pages/Sinks.vue";
+import Errors from "./pages/Errors.vue";
+import Inspect from "./pages/Inspect.vue";
 
 /**
  * Routes are namespaced under `/projects/:slug` so every URL is
@@ -78,22 +72,37 @@ import Sinks from "./pages/Sinks.vue";
  */
 const pageRoutes = [
   { path: "", component: Home, name: "home" },
-  { path: "overview", component: Overview, name: "overview" },
+  { path: "map", component: MapView, name: "map" },
+  { path: "inspect", component: Inspect, name: "inspect" },
   { path: "topology", component: Topology, name: "topology" },
   { path: "trace", component: Trace, name: "trace" },
-  { path: "apps", component: Apps, name: "apps" },
-  { path: "actions", component: Actions, name: "actions" },
-  { path: "events", component: Events, name: "events" },
-  { path: "workflows", component: Workflows, name: "workflows" },
+  { path: "errors", component: Errors, name: "errors" },
   { path: "hooks", component: Hooks, name: "hooks" },
   { path: "plugins", component: Plugins, name: "plugins" },
-  { path: "projections", component: Projections, name: "projections" },
-  { path: "queries", component: Queries, name: "queries" },
-  { path: "sinks", component: Sinks, name: "sinks" },
-  { path: "dispatch", component: Dispatch, name: "dispatch" },
-  { path: "live", component: Live, name: "live" },
-  { path: "run", component: Run, name: "run" },
-  { path: "commands", component: Commands, name: "commands" },
+  { path: "streams", component: Streams, name: "streams" },
+  { path: "operate", component: Operate, name: "operate" },
+];
+
+// Per-kind pages collapsed into the unified Inspect view. Old routes (bare +
+// project-pinned) redirect to `/inspect?kind=<kind>` so bookmarks + CI keep
+// working.
+const KIND_REDIRECTS: ReadonlyArray<readonly [string, string]> = [
+  ["apps", "app"],
+  ["actions", "action"],
+  ["events", "event"],
+  ["workflows", "workflow"],
+  ["projections", "projection"],
+  ["queries", "query"],
+  ["sinks", "sinkStage"],
+];
+
+// Dispatch / Run / Commands collapsed into the unified Operate view. Old routes
+// (bare + project-pinned) redirect to `/operate?mode=<mode>` so bookmarks + CI
+// keep working.
+const OPERATE_REDIRECTS: ReadonlyArray<readonly [string, string]> = [
+  ["dispatch", "dispatch"],
+  ["run", "run"],
+  ["commands", "commands"],
 ];
 
 const router = createRouter({
@@ -105,19 +114,44 @@ const router = createRouter({
     // collide with the bare-path variants below.
     {
       path: "/projects/:slug",
-      children: pageRoutes.map((r) => ({ ...r, name: `p-${r.name}` })),
+      children: [
+        ...pageRoutes.map((r) => ({ ...r, name: `p-${r.name}` })),
+        ...KIND_REDIRECTS.map(([path, kind]) => ({
+          path,
+          redirect: (to: { params: Record<string, unknown> }) => ({
+            path: `/projects/${to.params.slug}/inspect`,
+            query: { kind },
+          }),
+        })),
+        ...OPERATE_REDIRECTS.map(([path, mode]) => ({
+          path,
+          redirect: (to: { params: Record<string, unknown> }) => ({
+            path: `/projects/${to.params.slug}/operate`,
+            query: { mode },
+          }),
+        })),
+      ],
     },
     // Bare paths render the same pages. App.vue upgrades the URL to
     // /projects/<slug>/... once the active project slug is known, so a
-    // user who lands on /actions ends up bookmark-friendly without
+    // user who lands on /trace ends up bookmark-friendly without
     // breaking the load. Old bookmarks + CI test suites continue to
     // work unchanged.
     { path: "/", component: Home, name: "home" },
     ...pageRoutes
       .filter((r) => r.path !== "")
       .map((r) => ({ path: `/${r.path}`, component: r.component, name: r.name })),
+    ...KIND_REDIRECTS.map(([path, kind]) => ({
+      path: `/${path}`,
+      redirect: { path: "/inspect", query: { kind } },
+    })),
+    ...OPERATE_REDIRECTS.map(([path, mode]) => ({
+      path: `/${path}`,
+      redirect: { path: "/operate", query: { mode } },
+    })),
     { path: "/eventstorm", redirect: "/trace" },
-    { path: "/modules", redirect: "/apps" },
+    { path: "/live", redirect: "/streams" },
+    { path: "/modules", redirect: { path: "/inspect", query: { kind: "app" } } },
   ],
 });
 
@@ -125,7 +159,7 @@ const router = createRouter({
  * Register every catalog cwd with the running Studio process BEFORE mounting
  * Vue. The fetch shim above appends `?project=<cwd>` to every nwire request,
  * and the server's allowlist only includes `NWIRE_CWD` by default — so the
- * first cache fetch from useCache() would 400 without this hand-shake.
+ * first manifest fetch from useManifest() would 400 without this hand-shake.
  */
 async function bootstrap() {
   const catalog = loadCatalog();
@@ -143,6 +177,6 @@ async function bootstrap() {
       }),
     ),
   );
-  createApp(App).use(router).mount("#app");
+  createApp(App).use(router).use(VueQueryPlugin).mount("#app");
 }
 void bootstrap();