@telorun/debug-ui 0.2.1 → 0.4.0

package/src/graph.ts

@@ -0,0 +1,360 @@
+import { type DebugEvent, type DebugFrame, eventSuffix, isLogFrame } from "./wire.js";
+
+/**
+ * Pure, framework-agnostic derivation of a resource graph from a debug event
+ * stream — the model behind the Graph view. No React, no layout: it folds the
+ * frame buffer into nodes (one per resource) and edges (dependency wiring), and
+ * tracks each node's lifecycle status and most-recent invocation. The component
+ * layer adds positions (dagre) and rendering.
+ *
+ * Two event families drive it:
+ *  - Lifecycle events `<Kind>.<Name>.{Created,Initialized,Teardown}` — a node
+ *    appears (its payload carries the resolved `{kind,name}` and `dependencies`),
+ *    then flips to `initialized` / `torndown`.
+ *  - Dispatch (trace) events — every capability call emits a structured payload
+ *    `{ spanId, parentSpanId, capability, phase, outcome, ref:{kind,name}, … }`.
+ *    The consumer reads the *payload*, never the dotted name: `ref` locates the
+ *    node, `outcome` records the result. Terminal events carry an `outcome`;
+ *    `phase:"start"` events carry none and are skipped here.
+ *
+ * When the producer has tracing on, dispatch events also carry `spanId` /
+ * `parentSpanId`; {@link deriveInvocations} folds those into the call tree behind
+ * the invocation list + scoped trace graph.
+ */
+
+export type NodeStatus = "created" | "initialized" | "torndown";
+
+export type InvokeOutcome = "ok" | "failed" | "rejected" | "cancelled";
+
+/** The most recent invocation observed for a node. */
+export interface InvokeRecord {
+  outcome: InvokeOutcome;
+  /** The terminal event's suffix (`Invoked`, `InvokeFailed`, …) — for display only. */
+  suffix: string;
+  timestamp: string;
+  /** The dispatched inputs (present on every invocation event the kernel emits). */
+  inputs?: unknown;
+  /** The returned outputs — only on an `ok` outcome. */
+  outputs?: unknown;
+  /** The full raw event payload (error / cancellation detail for non-`ok`). */
+  payload: unknown;
+}
+
+export interface GraphNode {
+  /** Stable id — the resource name (dot-free, unique within its module scope). */
+  id: string;
+  kind: string;
+  name: string;
+  module?: string;
+  status: NodeStatus;
+  /** Total invocations seen across the stream. */
+  invokeCount: number;
+  lastInvoke?: InvokeRecord;
+  /** Buffer index of the last frame that touched this node — drives the pulse:
+   *  the renderer flashes a node whose activity index advanced since last paint. */
+  lastActivitySeq: number;
+}
+
+export interface GraphEdge {
+  id: string;
+  /** Source resource name (the dependant). */
+  source: string;
+  /** Target resource name (the dependency). */
+  target: string;
+}
+
+export interface GraphState {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+interface WireResourceRef {
+  kind: string;
+  name: string;
+  module?: string;
+  alias?: string;
+}
+
+function asResource(payload: unknown): WireResourceRef | undefined {
+  const res = (payload as { resource?: unknown } | undefined)?.resource;
+  if (res && typeof res === "object") {
+    const { kind, name } = res as Record<string, unknown>;
+    if (typeof kind === "string" && typeof name === "string") {
+      return { kind, name, ...res } as WireResourceRef;
+    }
+  }
+  return undefined;
+}
+
+/** The resolved `{kind,name}` a dispatch event's payload carries under `ref`. */
+function readRef(payload: Record<string, unknown> | undefined): { kind: string; name: string } | undefined {
+  const ref = payload?.ref;
+  if (ref && typeof ref === "object") {
+    const { kind, name } = ref as Record<string, unknown>;
+    if (typeof kind === "string" && typeof name === "string") return { kind, name };
+  }
+  return undefined;
+}
+
+/** Narrow a payload `outcome` to a known {@link InvokeOutcome}. Absent on
+ *  `phase:"start"` events, so they are naturally skipped by callers. */
+function asOutcome(value: unknown): InvokeOutcome | undefined {
+  return value === "ok" || value === "failed" || value === "rejected" || value === "cancelled"
+    ? value
+    : undefined;
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}
+
+function asCapability(value: unknown): SpanCapability | undefined {
+  return value === "invoke" || value === "run" || value === "provide" || value === "request"
+    ? value
+    : undefined;
+}
+
+/**
+ * Fold a frame buffer into the resource graph. Logs are ignored; events are
+ * applied in arrival order so the returned status / `lastInvoke` reflect the
+ * latest state. Edges are deduped by `source→target` and retained even when the
+ * target node hasn't been seen (an imported dependency may live in another scope);
+ * the renderer drops dangling edges.
+ */
+export function deriveGraph(frames: readonly DebugFrame[]): GraphState {
+  const nodes = new Map<string, GraphNode>();
+  const edges = new Map<string, GraphEdge>();
+
+  frames.forEach((frame, seq) => {
+    if (isLogFrame(frame)) return;
+    const event = frame as DebugEvent;
+    const suffix = eventSuffix(event.event);
+
+    if (suffix === "Created") {
+      const res = asResource(event.payload);
+      if (!res) return;
+      const existing = nodes.get(res.name);
+      if (existing) {
+        existing.lastActivitySeq = seq;
+      } else {
+        nodes.set(res.name, {
+          id: res.name,
+          kind: res.kind,
+          name: res.name,
+          module: res.module,
+          status: "created",
+          invokeCount: 0,
+          lastActivitySeq: seq,
+        });
+      }
+      const deps = (event.payload as { dependencies?: WireResourceRef[] }).dependencies ?? [];
+      for (const dep of deps) {
+        if (!dep?.name || dep.name === res.name) continue;
+        const id = `${res.name}->${dep.name}`;
+        if (!edges.has(id)) edges.set(id, { id, source: res.name, target: dep.name });
+      }
+      return;
+    }
+
+    if (suffix === "Initialized" || suffix === "Teardown") {
+      const res = asResource(event.payload);
+      const node = res ? nodes.get(res.name) : undefined;
+      if (node) {
+        node.status = suffix === "Teardown" ? "torndown" : "initialized";
+        node.lastActivitySeq = seq;
+      }
+      return;
+    }
+
+    // Dispatch (trace) events: the payload's `ref.name` resolves the target node
+    // directly (nodes are name-keyed). `phase:"start"` events carry no `outcome`
+    // and are skipped — only terminal events record a result.
+    const p = (event.payload ?? undefined) as Record<string, unknown> | undefined;
+    const ref = readRef(p);
+    const outcome = asOutcome(p?.outcome);
+    const node = ref ? nodes.get(ref.name) : undefined;
+    if (!node || !outcome) return;
+    node.invokeCount += 1;
+    node.lastActivitySeq = seq;
+    node.lastInvoke = {
+      outcome,
+      suffix: eventSuffix(event.event),
+      timestamp: event.timestamp,
+      inputs: p && "inputs" in p ? p.inputs : undefined,
+      outputs: p && "outputs" in p ? p.outputs : undefined,
+      payload: event.payload,
+    };
+  });
+
+  return { nodes: [...nodes.values()], edges: [...edges.values()] };
+}
+
+// ── Invocation traces ──────────────────────────────────────────────────────
+
+/** Which capability the span represents. `"request"` is an inbound-boundary span. */
+export type SpanCapability = "invoke" | "run" | "provide" | "request";
+
+/** One invocation — a single dispatched call, identified by its `spanId`. */
+export interface Invocation {
+  id: number;
+  parentId?: number;
+  /** Trace this span belongs to — present while tracing; groups the call tree. */
+  traceId?: string;
+  kind: string;
+  name: string;
+  capability?: SpanCapability;
+  outcome: InvokeOutcome;
+  /** The terminal event's suffix (`Invoked`, `InvokeFailed`, …) — for display only. */
+  suffix: string;
+  /** Human label (e.g. a route `"POST /feedback"`), for `request` spans. */
+  label?: string;
+  /** Structured span attributes (e.g. `{ method, path }`). */
+  attributes?: Record<string, unknown>;
+  /** On a trace root: the redacted CEL root scope (variables / secrets / resources
+   *  / ports) the trace could reference. */
+  context?: Record<string, unknown>;
+  timestamp: string;
+  inputs?: unknown;
+  outputs?: unknown;
+  /** Full raw event payload (error / cancellation detail for non-`ok`). */
+  payload: unknown;
+}
+
+export interface TraceState {
+  /** Every invocation, keyed by id. */
+  byId: Map<number, Invocation>;
+  /** Child invocation ids per parent id. */
+  childrenOf: Map<number, number[]>;
+  /** Root invocations (no parent), in arrival order. */
+  roots: Invocation[];
+}
+
+/**
+ * Fold the dispatch events that carry a `spanId` into a call tree. Each
+ * invocation appears once — keyed by `spanId`, the first terminal event wins, so
+ * the `InvokeRejected.Undeclared` echo (same id, emitted after `InvokeRejected`)
+ * is deduped. `phase:"start"` events carry no `outcome` and are skipped. Empty
+ * when the producer isn't tracing (no `spanId`).
+ */
+export function deriveInvocations(frames: readonly DebugFrame[]): TraceState {
+  const byId = new Map<number, Invocation>();
+  const childrenOf = new Map<number, number[]>();
+  const roots: Invocation[] = [];
+
+  for (const frame of frames) {
+    if (isLogFrame(frame)) continue;
+    const event = frame as DebugEvent;
+    const p = (event.payload ?? undefined) as Record<string, unknown> | undefined;
+    const id = num(p?.spanId);
+    if (id === undefined || byId.has(id)) continue;
+    const outcome = asOutcome(p?.outcome);
+    if (!outcome) continue;
+    const ref = readRef(p);
+    if (!ref) continue;
+
+    const parentId = num(p?.parentSpanId);
+    const invocation: Invocation = {
+      id,
+      parentId,
+      traceId: typeof p?.traceId === "string" ? p.traceId : undefined,
+      kind: ref.kind,
+      name: ref.name,
+      capability: asCapability(p?.capability),
+      outcome,
+      suffix: eventSuffix(event.event),
+      label: typeof p?.label === "string" ? p.label : undefined,
+      attributes:
+        p?.attributes && typeof p.attributes === "object"
+          ? (p.attributes as Record<string, unknown>)
+          : undefined,
+      context:
+        p?.context && typeof p.context === "object"
+          ? (p.context as Record<string, unknown>)
+          : undefined,
+      timestamp: event.timestamp,
+      inputs: p && "inputs" in p ? p.inputs : undefined,
+      outputs: p && "outputs" in p ? p.outputs : undefined,
+      payload: event.payload,
+    };
+    byId.set(id, invocation);
+    if (parentId === undefined) {
+      roots.push(invocation);
+    } else {
+      const list = childrenOf.get(parentId);
+      if (list) list.push(id);
+      else childrenOf.set(parentId, [id]);
+    }
+  }
+
+  return { byId, childrenOf, roots };
+}
+
+/** One resource in a scoped trace graph — collapses repeated calls to the same
+ *  resource into a single node carrying all its invocations within that trace. */
+export interface TraceNode {
+  /** Resource key `kind.name`. */
+  id: string;
+  kind: string;
+  name: string;
+  /** Human label from the span (e.g. a route `"POST /feedback"`), if any. */
+  label?: string;
+  isRoot: boolean;
+  invocations: Invocation[];
+}
+
+export interface TraceEdge {
+  id: string;
+  source: string;
+  target: string;
+}
+
+export interface TraceSubgraph {
+  nodes: TraceNode[];
+  edges: TraceEdge[];
+}
+
+/**
+ * The call graph of a single trace: the resources that participated in `rootId`'s
+ * subtree, wired by the actual parent→child call edges. A resource invoked more
+ * than once in the trace is one node holding all its calls; edges are deduped by
+ * `source→target`.
+ */
+export function traceSubgraph(trace: TraceState, rootId: number): TraceSubgraph {
+  const root = trace.byId.get(rootId);
+  if (!root) return { nodes: [], edges: [] };
+
+  const resourceKey = (inv: Invocation) => `${inv.kind}.${inv.name}`;
+  const nodes = new Map<string, TraceNode>();
+  const edges = new Map<string, TraceEdge>();
+
+  const visit = (id: number): void => {
+    const inv = trace.byId.get(id);
+    if (!inv) return;
+    const key = resourceKey(inv);
+    const node = nodes.get(key);
+    if (node) node.invocations.push(inv);
+    else
+      nodes.set(key, {
+        id: key,
+        kind: inv.kind,
+        name: inv.name,
+        label: inv.label,
+        isRoot: id === rootId,
+        invocations: [inv],
+      });
+
+    for (const childId of trace.childrenOf.get(id) ?? []) {
+      const child = trace.byId.get(childId);
+      if (!child) continue;
+      const target = resourceKey(child);
+      if (key !== target) {
+        const edgeId = `${key}->${target}`;
+        if (!edges.has(edgeId)) edges.set(edgeId, { id: edgeId, source: key, target });
+      }
+      visit(childId);
+    }
+  };
+  visit(rootId);
+
+  return { nodes: [...nodes.values()], edges: [...edges.values()] };
+}

package/src/index.ts

@@ -19,3 +19,19 @@ export { type EventFilter, matchesFilter, distinctSuffixes } from "./filter.js";
 export type { DebugTheme } from "./theme.js";
 export { type DebugStreamHandlers, connectDebugStream } from "./sse-client.js";
 export { type FoundBlob, collectBlobs, blobDimensions, formatBytes } from "./media.js";
+export {
+  type GraphState,
+  type GraphNode,
+  type GraphEdge,
+  type NodeStatus,
+  type InvokeOutcome,
+  type InvokeRecord,
+  type Invocation,
+  type TraceState,
+  type TraceNode,
+  type TraceEdge,
+  type TraceSubgraph,
+  deriveGraph,
+  deriveInvocations,
+  traceSubgraph,
+} from "./graph.js";

package/app-dist/assets/index-CK8ArLzP.css

@@ -1 +0,0 @@
-.tdbg-root{--tdbg-bg: #0f1115;--tdbg-panel: #161a21;--tdbg-line: #232a34;--tdbg-text: #d7dce3;--tdbg-muted: #7a8493;--tdbg-accent: #4f9cf0;--tdbg-bad: #ff8079;--tdbg-bad-bg: rgba(248, 81, 73, .2);--tdbg-good: #5fd673;--tdbg-good-bg: rgba(63, 185, 80, .18);display:flex;flex-direction:column;height:100%;min-height:0;font:13px/1.5 ui-monospace,SF Mono,Menlo,Consolas,monospace;color:var(--tdbg-text);background:var(--tdbg-bg)}.tdbg-root[data-theme=light]{--tdbg-bg: #ffffff;--tdbg-panel: #f6f7f9;--tdbg-line: #e2e5e9;--tdbg-text: #1f2328;--tdbg-muted: #656d76;--tdbg-accent: #2f6feb;--tdbg-bad: #cf222e;--tdbg-bad-bg: rgba(207, 34, 46, .1);--tdbg-good: #1a7f37;--tdbg-good-bg: rgba(26, 127, 55, .1)}.tdbg-tabs{display:flex;align-items:center;gap:8px;padding:6px 10px;background:var(--tdbg-panel);border-bottom:1px solid var(--tdbg-line)}.tdbg-tab{padding:4px 10px;color:var(--tdbg-muted);background:none;border:1px solid transparent;border-radius:6px;cursor:pointer;font:inherit}.tdbg-tab:hover{color:var(--tdbg-text)}.tdbg-tab-on{color:var(--tdbg-text);background:var(--tdbg-bg);border-color:var(--tdbg-line)}.tdbg-tabcount{margin-left:4px;color:var(--tdbg-muted);font-size:11px}.tdbg-tabs-spacer{flex:1}.tdbg-endpoints{display:flex;align-items:center;gap:6px}.tdbg-endpoint{display:inline-flex;align-items:center;gap:4px;padding:2px 8px;color:var(--tdbg-muted);background:var(--tdbg-bg);border:1px solid var(--tdbg-line);border-radius:999px;font-size:11px;white-space:nowrap}.tdbg-endpoint-link{color:var(--tdbg-accent);text-decoration:none}.tdbg-endpoint-link:hover{border-color:var(--tdbg-accent)}.tdbg-bar{position:sticky;top:0;z-index:1;padding:8px 10px;background:var(--tdbg-panel);border-bottom:1px solid var(--tdbg-line)}.tdbg-bar-row{display:flex;align-items:center;gap:8px}.tdbg-search{flex:1}.tdbg-search,.tdbg-kind{padding:5px 8px;color:var(--tdbg-text);background:var(--tdbg-bg);border:1px solid var(--tdbg-line);border-radius:5px;font:inherit}.tdbg-kind{width:140px}.tdbg-btn{padding:5px 10px;color:var(--tdbg-text);background:var(--tdbg-bg);border:1px solid var(--tdbg-line);border-radius:5px;cursor:pointer;font:inherit}.tdbg-btn:hover{border-color:var(--tdbg-accent)}.tdbg-icon-btn{display:inline-flex;align-items:center;justify-content:center;padding:5px 7px}.tdbg-counts{color:var(--tdbg-muted);white-space:nowrap}.tdbg-status{width:9px;height:9px;border-radius:50%;background:var(--tdbg-muted);flex:0 0 auto}.tdbg-status-open{background:#3fb950}.tdbg-status-connecting{background:#d29922}.tdbg-status-closed{background:#f85149}.tdbg-facets{display:flex;flex-wrap:wrap;gap:6px;margin-top:8px}.tdbg-facet{padding:2px 8px;color:var(--tdbg-muted);background:var(--tdbg-bg);border:1px solid var(--tdbg-line);border-radius:999px;cursor:pointer;font:inherit}.tdbg-facet-on{color:var(--tdbg-text);border-color:var(--tdbg-accent);background:#4f9cf02e}.tdbg-table{flex:1;min-height:0;overflow:auto}.tdbg-empty{padding:24px;color:var(--tdbg-muted);text-align:center}.tdbg-row{border-bottom:1px solid var(--tdbg-line)}.tdbg-rowhead{display:flex;align-items:baseline;gap:8px;width:100%;padding:4px 10px;background:none;border:none;color:inherit;cursor:pointer;text-align:left;font:inherit}.tdbg-rowhead:hover{background:var(--tdbg-panel)}.tdbg-caret{width:12px;color:var(--tdbg-muted)}.tdbg-time{color:var(--tdbg-muted);white-space:nowrap}.tdbg-badge{padding:1px 6px;border-radius:4px;background:var(--tdbg-line);color:var(--tdbg-text);white-space:nowrap}.tdbg-suffix-failed,.tdbg-suffix-rejected,.tdbg-suffix-cancelled{background:var(--tdbg-bad-bg);color:var(--tdbg-bad)}.tdbg-suffix-invoked,.tdbg-suffix-listening,.tdbg-suffix-started,.tdbg-suffix-initialized{background:var(--tdbg-good-bg);color:var(--tdbg-good)}.tdbg-name{white-space:nowrap}.tdbg-preview{color:var(--tdbg-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.tdbg-payload-wrap{background:var(--tdbg-panel)}.tdbg-payload{margin:0;padding:8px 10px 10px 30px;background:var(--tdbg-panel);overflow:auto;white-space:pre-wrap;word-break:break-word}.tdbg-media{display:flex;flex-wrap:wrap;gap:12px;padding:10px 10px 4px 30px}.tdbg-blob{margin:0;display:flex;flex-direction:column;gap:4px;max-width:320px}.tdbg-blob-img{max-width:320px;max-height:240px;border:1px solid var(--tdbg-line);border-radius:6px;background:repeating-conic-gradient(#1b202840 0% 25%,transparent 0% 50%) 50% / 16px 16px;object-fit:contain}.tdbg-blob-file{display:inline-block;padding:8px 12px;color:var(--tdbg-accent);border:1px solid var(--tdbg-line);border-radius:6px;text-decoration:none}.tdbg-blob-file:hover{border-color:var(--tdbg-accent)}.tdbg-blob-cap{color:var(--tdbg-muted);font-size:11px;word-break:break-all}.tdbg-muted{color:var(--tdbg-muted)}.tdbg-ref{color:var(--tdbg-accent)}.tdbg-slot{display:flex;flex:1;min-height:0;overflow:hidden}.tdbg-logs{flex:1;min-height:0;overflow:auto;padding:4px 0}.tdbg-logline{display:flex;gap:8px;padding:1px 10px;white-space:pre-wrap;word-break:break-word}.tdbg-logline:hover{background:var(--tdbg-panel)}.tdbg-logtext{flex:1}.tdbg-log-stderr .tdbg-logtext{color:var(--tdbg-bad)}