@nwire/studio 0.12.0 → 0.13.0

package/src/lib/inspect.ts

@@ -0,0 +1,226 @@
+/**
+ * Inspect — pure selectors that turn the deep manifest into the unified
+ * per-kind browser: the kind switcher (what's present + counts), a node's full
+ * detail (reusing `BcNodeDetail` so `NodeCard` renders it), and a node's
+ * relationships (its graph edges, grouped + humanized). Native: reads
+ * `ManifestView` / `GraphNode` / `GraphEdge` from `@nwire/scan` — no adapter.
+ */
+import type { Manifest, ManifestView, GraphNode, GraphEdge, EdgeType } from "./manifest";
+import {
+  nodeDetail,
+  toInvariants,
+  toConfigModules,
+  toEnvVars,
+  type BcNodeDetail,
+} from "./bc-graph";
+
+/** Friendly labels per graph node kind. */
+const KIND_LABELS: Record<string, string> = {
+  action: "Actions",
+  query: "Queries",
+  event: "Events",
+  actor: "Actors",
+  workflow: "Workflows",
+  projection: "Projections",
+  command: "Commands",
+  route: "Routes",
+  cron: "Crons",
+  externalCall: "External calls",
+  inboundWebhook: "Webhooks",
+  outbox: "Outboxes",
+  inbox: "Inboxes",
+  sinkStage: "Sinks",
+  sourceStage: "Sources",
+  plugin: "Plugins",
+  capability: "Capabilities",
+  kind: "Ctx kinds",
+  hook: "Hooks",
+  app: "Apps",
+  schema: "Schemas",
+  resource: "Resources",
+  error: "Errors",
+  binding: "Bindings",
+};
+
+/** Curated display order; kinds not listed fall to the end, alphabetical. */
+const KIND_ORDER: readonly string[] = [
+  "action",
+  "query",
+  "event",
+  "actor",
+  "workflow",
+  "projection",
+  "command",
+  "route",
+  "cron",
+  "externalCall",
+  "inboundWebhook",
+  "sinkStage",
+  "sourceStage",
+  "app",
+  "plugin",
+  "capability",
+  "hook",
+  "schema",
+  "resource",
+  "error",
+];
+
+/** Human label for a kind (falls back to the raw kind). */
+export function kindLabel(kind: string): string {
+  return KIND_LABELS[kind] ?? kind;
+}
+
+export interface InspectKindEntry {
+  readonly kind: string;
+  readonly label: string;
+  readonly count: number;
+}
+
+/**
+ * Which kinds are present in the manifest + their counts, in curated order
+ * (then alphabetical for anything uncurated). Only kinds with ≥1 node appear.
+ */
+export function inspectKinds(view: ManifestView | null): InspectKindEntry[] {
+  if (!view) return [];
+  const counts = new Map<string, number>();
+  for (const n of view.model.nodes) counts.set(n.kind, (counts.get(n.kind) ?? 0) + 1);
+
+  const rank = (k: string): number => {
+    const i = KIND_ORDER.indexOf(k);
+    return i === -1 ? KIND_ORDER.length : i;
+  };
+
+  return [...counts.entries()]
+    .map(([kind, count]) => ({ kind, label: kindLabel(kind), count }))
+    .sort((a, b) => rank(a.kind) - rank(b.kind) || a.label.localeCompare(b.label));
+}
+
+/** Nodes of one kind, name-sorted — the master list for the active tab. */
+export function nodesOfKind(view: ManifestView | null, kind: string): GraphNode[] {
+  if (!view) return [];
+  return view
+    .byKind(kind)
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Free-text match over a node's name + intent description. */
+export function matchesNode(node: GraphNode, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  return (
+    node.name.toLowerCase().includes(q) ||
+    (node.intent?.description?.toLowerCase().includes(q) ?? false)
+  );
+}
+
+/**
+ * Resolve a graph node to a full `BcNodeDetail` (so `NodeCard` renders it).
+ * Prefers the flat-array entry (carries the input schema) and falls back to the
+ * graph node's own intent + `data` for kinds without a flat array.
+ */
+export function nodeToDetail(
+  view: ManifestView | null,
+  manifest: Manifest | null | undefined,
+  node: GraphNode | null | undefined,
+): BcNodeDetail | null {
+  if (!node) return null;
+  const flat = nodeDetail(manifest, node.id);
+  if (flat) return flat;
+
+  // Structural kinds (plugin, hook, route, capability, …) have no flat entry —
+  // build the detail from the graph node itself.
+  const data = node.data ?? {};
+  // env/config are surfaced as their own sections, never in the generic Details.
+  const env = toEnvVars(data.env);
+  const config = toConfigModules(data.config);
+  const extra: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (k !== "emits" && k !== "env" && k !== "config" && v !== undefined) extra[k] = v;
+  }
+  const intent = node.intent ?? {};
+  if (intent.persona) extra.persona = intent.persona;
+  if (intent.journeyStep) extra.journeyStep = intent.journeyStep;
+  if (intent.capability) extra.capability = intent.capability;
+  if (intent.tags?.length) extra.tags = intent.tags;
+  // Invariants are surfaced as their own section, never in the generic Details.
+  delete extra.invariants;
+
+  return {
+    id: node.id,
+    kind: node.kind,
+    name: node.name,
+    description: intent.description,
+    public: intent.public === true,
+    source: node.source as BcNodeDetail["source"],
+    emits: Array.isArray(data.emits) ? (data.emits as string[]) : undefined,
+    invariants: toInvariants(intent.invariants),
+    env,
+    config,
+    extra,
+  };
+}
+
+export interface RelatedNode {
+  readonly id: string;
+  readonly kind: string;
+  readonly name: string;
+}
+
+export interface RelationGroup {
+  readonly label: string;
+  readonly items: readonly RelatedNode[];
+}
+
+/** Direction-aware human labels per edge type. */
+const RELATION_LABELS: Record<EdgeType, { out: string; in: string }> = {
+  triggers: { out: "Triggers", in: "Triggered by" },
+  emits: { out: "Emits", in: "Emitted by" },
+  delivers: { out: "Delivers to", in: "Receives from" },
+  transitions: { out: "Transitions to", in: "Transitioned from" },
+  dispatches: { out: "Dispatches", in: "Dispatched by" },
+  reads: { out: "Reads", in: "Read by" },
+  calls: { out: "Calls", in: "Called by" },
+  provides: { out: "Provides", in: "Provided by" },
+  contributes: { out: "Contributes", in: "Contributed by" },
+  mounts: { out: "Mounts", in: "Mounted by" },
+};
+
+function nameOfId(id: string): { kind: string; name: string } {
+  const i = id.indexOf(":");
+  return i === -1 ? { kind: "", name: id } : { kind: id.slice(0, i), name: id.slice(i + 1) };
+}
+
+/**
+ * A node's edges, grouped by humanized relation (direction-aware) — the
+ * "Relationships" panel. Empty when the node has no edges.
+ */
+export function relationships(view: ManifestView | null, id: string | null): RelationGroup[] {
+  if (!view || !id) return [];
+  const groups = new Map<string, RelatedNode[]>();
+  const push = (label: string, otherId: string): void => {
+    const { kind, name } = nameOfId(otherId);
+    const item = { id: otherId, kind, name };
+    const list = groups.get(label);
+    if (list) {
+      if (!list.some((x) => x.id === otherId)) list.push(item);
+    } else {
+      groups.set(label, [item]);
+    }
+  };
+
+  for (const e of view.edgesOf(id, "both") as GraphEdge[]) {
+    const labels = RELATION_LABELS[e.type];
+    if (!labels) continue;
+    if (e.from === id) push(labels.out, e.to);
+    if (e.to === id) push(labels.in, e.from);
+  }
+
+  return [...groups.entries()].map(([label, items]) => ({ label, items }));
+}
+
+/** Kinds that can be invoked from the Operate/Dispatch surface. */
+export function isDispatchable(kind: string): boolean {
+  return kind === "action" || kind === "command" || kind === "query";
+}

package/src/lib/kind-colors.ts

@@ -0,0 +1,132 @@
+/**
+ * The one kind→colour map — the Studio visual language for handler kinds and
+ * graph node kinds. Pure data + helpers so components and the graph canvas
+ * agree on colour and read the same in Storybook and tests.
+ */
+
+/** Canonical hex per kind (matches `studio-redesign.html`). */
+export const KIND_COLOR: Record<string, string> = {
+  action: "#7c9cff",
+  query: "#36c6a8",
+  event: "#c08bff",
+  listener: "#9aa7ff",
+  actor: "#ffb454",
+  workflow: "#ff7eb6",
+  projection: "#5ad1ff",
+  command: "#7c9cff",
+  // structural / topology kinds
+  app: "#39d98a",
+  plugin: "#8a97ad",
+  capability: "#8a97ad",
+  route: "#5ad1ff",
+  sinkStage: "#5c6a82",
+  sourceStage: "#5c6a82",
+  hook: "#8a97ad",
+  externalCall: "#ffca45",
+};
+
+const FALLBACK = "#8a97ad";
+
+/** Hex colour for a kind (falls back to a neutral dim). */
+export function kindColor(kind: string | undefined): string {
+  return (kind && KIND_COLOR[kind]) || FALLBACK;
+}
+
+/** Map a graph node kind to a KindBadge variant (semantic palette). */
+export function kindVariant(
+  kind: string | undefined,
+): "info" | "success" | "warning" | "danger" | "neutral" {
+  switch (kind) {
+    case "action":
+    case "command":
+    case "query":
+    case "route":
+      return "info";
+    case "app":
+      return "success";
+    case "actor":
+    case "externalCall":
+      return "warning";
+    default:
+      return "neutral";
+  }
+}
+
+/**
+ * Map a dotted telemetry record kind (e.g. `action.completed`, `event.published`,
+ * `external.call.failed`) to a colour key in `KIND_COLOR`, so a live record reads
+ * with the same colour as its handler kind on the Map.
+ */
+export function recordColorKey(recordKind: string): string {
+  const base = recordKind.split(".")[0] ?? recordKind;
+  switch (base) {
+    case "action":
+    case "event":
+    case "query":
+    case "actor":
+    case "projection":
+    case "listener":
+    case "workflow":
+      return base;
+    case "reaction":
+      return "workflow"; // reactions are workflow-family sagas
+    case "external":
+      return "externalCall";
+    case "source":
+      return "sourceStage";
+    case "sink":
+      return "sinkStage";
+    case "hook":
+      return "hook";
+    default:
+      return base;
+  }
+}
+
+/** The legend order shown under the canvas. */
+export const KIND_LEGEND: readonly string[] = [
+  "action",
+  "query",
+  "event",
+  "listener",
+  "actor",
+  "workflow",
+  "projection",
+];
+
+/**
+ * Lucide icon name per kind — the one glyph that reads a node's role at a
+ * glance on the service map. Names match `lucide-vue-next` exports; the canvas
+ * resolves them dynamically so components and the legend agree.
+ */
+export const KIND_ICON: Record<string, string> = {
+  // sources — what enters the app
+  route: "Globe",
+  inboundWebhook: "Webhook",
+  cron: "Clock",
+  command: "Terminal",
+  // handlers — what runs
+  action: "Zap",
+  query: "Search",
+  // effects — what running produces
+  event: "Radio",
+  externalCall: "ExternalLink",
+  workflow: "GitBranch",
+  actor: "Box",
+  projection: "LayoutGrid",
+  listener: "Ear",
+  // structural
+  app: "Boxes",
+  plugin: "Plug",
+  capability: "Plug",
+  sinkStage: "ArrowDownToLine",
+  sourceStage: "ArrowUpFromLine",
+  hook: "Anchor",
+};
+
+const ICON_FALLBACK = "Circle";
+
+/** Lucide icon name for a kind (falls back to a neutral circle). */
+export function kindIcon(kind: string | undefined): string {
+  return (kind && KIND_ICON[kind]) || ICON_FALLBACK;
+}

package/src/lib/live-table.ts

@@ -0,0 +1,204 @@
+/**
+ * Pure logic behind the live telemetry table — subject extraction, time
+ * parsing, text filtering, sorting, and KPI roll-ups. Kept DOM-free so the
+ * firehose's behavior is unit-tested without mounting a component; `LiveTable`
+ * and the Streams page render what these return.
+ */
+import type { TelemetryRecord } from "./telemetry";
+import { isFailure } from "./telemetry";
+
+/** Sortable columns. `time` is the default (newest first). */
+export type SortKey = "time" | "kind" | "subject" | "duration";
+export type SortDir = "asc" | "desc";
+
+/** Epoch millis for a record's `ts` (0 when absent/unparseable — sorts last desc). */
+export function recordTime(r: TelemetryRecord): number {
+  if (!r.ts) return 0;
+  const t = Date.parse(r.ts);
+  return Number.isNaN(t) ? 0 : t;
+}
+
+/**
+ * The primary noun a record is about — the handler/event/actor it concerns.
+ * Reads the per-kind field the runtime + forge stamp (`action`, `event`,
+ * `actor`, …); `event` may be a string or an `EventMessage`-shaped object.
+ */
+export function recordSubject(r: TelemetryRecord): string {
+  const ev = r.event;
+  const eventName =
+    typeof ev === "string"
+      ? ev
+      : ev && typeof ev === "object"
+        ? ((ev as { name?: string; type?: string }).name ??
+          (ev as { name?: string; type?: string }).type)
+        : undefined;
+  const pick =
+    (r.action as string | undefined) ??
+    (r.query as string | undefined) ??
+    (r.projection as string | undefined) ??
+    (r.actor as string | undefined) ??
+    (r.workflow as string | undefined) ??
+    (r.call as string | undefined) ??
+    (r.timer as string | undefined) ??
+    (r.sourceEvent as string | undefined) ??
+    eventName ??
+    (r.listener as string | undefined);
+  return pick ?? "—";
+}
+
+/** Duration in ms when the record carries one, else `undefined`. */
+export function recordDuration(r: TelemetryRecord): number | undefined {
+  return typeof r.durationMs === "number" ? r.durationMs : undefined;
+}
+
+/** Lower-cased haystack of everything a text filter should match against. */
+function haystack(r: TelemetryRecord): string {
+  const env = r.envelope;
+  return [
+    r.kind,
+    recordSubject(r),
+    r.appName,
+    env?.correlationId,
+    env?.causationId,
+    env?.messageId,
+    env?.tenant,
+    env?.userId,
+    r.error?.message,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+/** Free-text match across kind, subject, ids, tenant, user, app, and error. */
+export function matchesFilter(r: TelemetryRecord, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  return haystack(r).includes(q);
+}
+
+export interface FilterSpec {
+  /** Free text. */
+  readonly text?: string;
+  /** Restrict to a single record kind (exact). */
+  readonly kind?: string | null;
+  /** Restrict to one correlation chain. */
+  readonly correlationId?: string | null;
+  /** Only failures (the Errors-family kinds, or a stamped `error`). */
+  readonly failuresOnly?: boolean;
+}
+
+/** Apply every active filter clause. Order-independent; all must pass. */
+export function filterRecords(
+  records: readonly TelemetryRecord[],
+  spec: FilterSpec,
+): TelemetryRecord[] {
+  return records.filter((r) => {
+    if (spec.kind && r.kind !== spec.kind) return false;
+    if (spec.correlationId && r.envelope?.correlationId !== spec.correlationId) return false;
+    if (spec.failuresOnly && !isFailure(r)) return false;
+    if (spec.text && !matchesFilter(r, spec.text)) return false;
+    return true;
+  });
+}
+
+/** Stable sort by the chosen column + direction (input array is not mutated). */
+export function sortRecords(
+  records: readonly TelemetryRecord[],
+  key: SortKey,
+  dir: SortDir,
+): TelemetryRecord[] {
+  const sign = dir === "asc" ? 1 : -1;
+  return records
+    .map((r, i) => [r, i] as const)
+    .sort(([a, ai], [b, bi]) => {
+      const d = compare(a, b, key);
+      return d !== 0 ? d * sign : ai - bi; // stable on ties
+    })
+    .map(([r]) => r);
+}
+
+function compare(a: TelemetryRecord, b: TelemetryRecord, key: SortKey): number {
+  switch (key) {
+    case "time":
+      return recordTime(a) - recordTime(b);
+    case "duration":
+      return (recordDuration(a) ?? -1) - (recordDuration(b) ?? -1);
+    case "kind":
+      return a.kind.localeCompare(b.kind);
+    case "subject":
+      return recordSubject(a).localeCompare(recordSubject(b));
+  }
+}
+
+/** Clamp-and-wrap the selection index when the user presses ↑/↓. */
+export function nextIndex(current: number, length: number, delta: number): number {
+  if (length === 0) return -1;
+  if (current < 0) return delta > 0 ? 0 : length - 1;
+  const next = current + delta;
+  if (next < 0) return 0;
+  if (next >= length) return length - 1;
+  return next;
+}
+
+export interface StreamKpis {
+  /** Total records in the buffer. */
+  readonly total: number;
+  /** How many are failures. */
+  readonly failures: number;
+  /** Distinct record kinds seen. */
+  readonly kinds: number;
+  /** Distinct correlation chains seen. */
+  readonly chains: number;
+  /** Records per second over the buffer's time span (0 when < 2 records). */
+  readonly perSecond: number;
+}
+
+/** Roll the buffer up into the header strip's numbers. */
+export function computeKpis(records: readonly TelemetryRecord[]): StreamKpis {
+  const kinds = new Set<string>();
+  const chains = new Set<string>();
+  let failures = 0;
+  let min = Infinity;
+  let max = -Infinity;
+  for (const r of records) {
+    kinds.add(r.kind);
+    const cid = r.envelope?.correlationId;
+    if (cid) chains.add(cid);
+    if (isFailure(r)) failures++;
+    const t = recordTime(r);
+    if (t > 0) {
+      if (t < min) min = t;
+      if (t > max) max = t;
+    }
+  }
+  const spanSec = max > min ? (max - min) / 1000 : 0;
+  const perSecond = spanSec > 0 ? Math.round((records.length / spanSec) * 10) / 10 : 0;
+  return {
+    total: records.length,
+    failures,
+    kinds: kinds.size,
+    chains: chains.size,
+    perSecond,
+  };
+}
+
+/** The distinct kinds present, in first-seen order — drives the kind filter. */
+export function distinctKinds(records: readonly TelemetryRecord[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const r of records) {
+    if (!seen.has(r.kind)) {
+      seen.add(r.kind);
+      out.push(r.kind);
+    }
+  }
+  return out;
+}
+
+/** Short id for display (first dash-segment, else first 8 chars). */
+export function shortId(id: string | undefined): string {
+  if (!id) return "—";
+  if (id.includes("-")) return id.split("-")[0] || id.slice(0, 8);
+  return id.slice(0, 8);
+}

package/src/lib/manifest-health.ts

@@ -0,0 +1,71 @@
+/**
+ * Manifest health — pure checks over a raw `.nwire/manifest.json` payload.
+ *
+ * The manifest is generated by `@nwire/scan` and its schema evolves. A Studio
+ * served against a manifest built by an older scanner must not crash; pages
+ * that depend on a not-yet-present field render an empty state, and the operator
+ * gets a "rebuild" hint naming exactly what's missing.
+ *
+ * Reports against the native manifest directly so App.vue can drive the
+ * stale-manifest banner from the deep manifest, no flat reshape in between.
+ */
+import type { Manifest } from "./manifest";
+
+/**
+ * Top-level array fields the *current* `@nwire/scan` emits on every manifest
+ * (always present, empty when a kind is unused — verified against real
+ * `buildManifest` output). A field that's absent (or not an array) means the
+ * manifest was built by an older scanner; we name it in the rebuild hint.
+ *
+ * Deliberately NOT the old flat-cache set: the deep manifest keeps apps,
+ * resolvers, routes, hooks, plugins, sinks, bindings under `topology`/`model`,
+ * not as top-level arrays — checking for them here false-flagged every real
+ * manifest. `generatedAt` isn't emitted at top level either, so it's dropped.
+ */
+const ARRAY_FIELDS = [
+  "events",
+  "actions",
+  "actors",
+  "projections",
+  "queries",
+  "workflows",
+  "commands",
+  "crons",
+  "externalCalls",
+  "inboundWebhooks",
+  "outboxes",
+  "inboxes",
+  "resources",
+  "errors",
+  "schemas",
+] as const;
+
+/**
+ * The field paths a manifest is missing relative to the current schema. Empty
+ * when the manifest is current-shape. Pure — no DOM, unit-testable.
+ *
+ * Order matches the schema declaration so the banner reads predictably
+ * (`resolvers`, `workflows`, …).
+ */
+export function missingFields(manifest: Manifest | null | undefined): string[] {
+  if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return [];
+  }
+
+  const input = manifest as unknown as Record<string, unknown>;
+  const missing: string[] = [];
+
+  for (const field of ARRAY_FIELDS) {
+    if (!Array.isArray(input[field])) missing.push(field);
+  }
+
+  // graph.events — nested arrays.
+  const rawGraph = input.graph as { events?: unknown } | undefined;
+  if (!rawGraph || typeof rawGraph !== "object") {
+    missing.push("graph");
+  } else if (!Array.isArray(rawGraph.events)) {
+    missing.push("graph.events");
+  }
+
+  return missing;
+}