@nwire/studio 0.12.0 → 0.13.0

package/src/lib/__tests__/home.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect } from "vitest";
+import {
+  projectHealth,
+  healthBadge,
+  healthLabel,
+  projectPort,
+  sortProjects,
+  projectStats,
+  statsArePending,
+  quickStats,
+  countErrors,
+  activityLabel,
+  recentActivity,
+} from "../home";
+import { manifestView } from "../manifest";
+import type { Manifest } from "../manifest";
+import type { DiscoveredProject } from "../../composables/useDiscovery";
+import type { TelemetryRecord } from "../telemetry";
+import type { ProjectSnapshot } from "../../lib/project-catalog";
+
+function snapshot(over: Partial<ProjectSnapshot> = {}): ProjectSnapshot {
+  return {
+    cwd: "/repo/app",
+    name: "app",
+    lastVisited: "2026-01-01T00:00:00.000Z",
+    ...over,
+  };
+}
+
+function project(over: Partial<DiscoveredProject> = {}): DiscoveredProject {
+  return {
+    cwd: over.snapshot?.cwd ?? over.cwd ?? "/repo/app",
+    snapshot: snapshot(over.snapshot),
+    status: over.status,
+    active: over.active ?? false,
+    ...over,
+  };
+}
+
+describe("projectHealth", () => {
+  it("is running when a live process is registered", () => {
+    expect(projectHealth(project({ status: { processes: [{ port: 4000 }] } }))).toBe("running");
+  });
+  it("is running when the legacy `running` flag is set", () => {
+    expect(projectHealth(project({ status: { running: true } }))).toBe("running");
+  });
+  it("is on-disk when a manifest exists but no process is up", () => {
+    expect(projectHealth(project({ status: { hasManifest: true, processes: [] } }))).toBe(
+      "on-disk",
+    );
+  });
+  it("is unreachable with neither a process nor a manifest", () => {
+    expect(projectHealth(project({ status: { hasManifest: false, processes: [] } }))).toBe(
+      "unreachable",
+    );
+    expect(projectHealth(project({ status: undefined }))).toBe("unreachable");
+  });
+});
+
+describe("health presentation", () => {
+  it("maps health to a badge token", () => {
+    expect(healthBadge("running")).toBe("live");
+    expect(healthBadge("on-disk")).toBe("idle");
+    expect(healthBadge("unreachable")).toBe("error");
+  });
+  it("labels each health", () => {
+    expect(healthLabel("running")).toBe("Running");
+    expect(healthLabel("on-disk")).toBe("On disk");
+    expect(healthLabel("unreachable")).toBe("Unreachable");
+  });
+});
+
+describe("projectPort", () => {
+  it("returns the first process port", () => {
+    expect(projectPort(project({ status: { processes: [{}, { port: 4111 }] } }))).toBe(4111);
+  });
+  it("is undefined when no port is known", () => {
+    expect(projectPort(project({ status: { processes: [] } }))).toBeUndefined();
+  });
+});
+
+describe("sortProjects", () => {
+  it("orders active first, then by health, then by name", () => {
+    const running = project({
+      snapshot: snapshot({ cwd: "/r", name: "running" }),
+      status: { processes: [{}] },
+    });
+    const onDisk = project({
+      snapshot: snapshot({ cwd: "/d", name: "ondisk" }),
+      status: { hasManifest: true },
+    });
+    const dead = project({ snapshot: snapshot({ cwd: "/x", name: "dead" }), status: {} });
+    const active = project({
+      snapshot: snapshot({ cwd: "/a", name: "zeta-active" }),
+      active: true,
+      status: {},
+    });
+
+    const out = sortProjects([dead, onDisk, running, active]);
+    expect(out.map((p) => p.snapshot.name)).toEqual(["zeta-active", "running", "ondisk", "dead"]);
+  });
+  it("does not mutate the input", () => {
+    const list = [
+      project({ snapshot: snapshot({ name: "b" }) }),
+      project({ snapshot: snapshot({ name: "a" }) }),
+    ];
+    const copy = [...list];
+    sortProjects(list);
+    expect(list).toEqual(copy);
+  });
+});
+
+describe("projectStats", () => {
+  it("reads composition counts from the snapshot", () => {
+    const p = project({
+      snapshot: snapshot({
+        composition: { apps: 1, plugins: 2, actions: 3, events: 4, resolvers: 5, workflows: 6 },
+      }),
+    });
+    expect(projectStats(p)).toEqual({
+      apps: 1,
+      plugins: 2,
+      actions: 3,
+      events: 4,
+      resolvers: 5,
+      workflows: 6,
+    });
+  });
+  it("falls back to zeros when no composition is recorded", () => {
+    expect(projectStats(project())).toEqual({
+      apps: 0,
+      plugins: 0,
+      actions: 0,
+      events: 0,
+      resolvers: 0,
+      workflows: 0,
+    });
+  });
+  it("flags a pending (not-yet-scanned) snapshot", () => {
+    expect(statsArePending(project())).toBe(true);
+    expect(
+      statsArePending(
+        project({
+          snapshot: snapshot({ composition: { apps: 0, plugins: 0, actions: 0, events: 0 } }),
+        }),
+      ),
+    ).toBe(false);
+  });
+});
+
+function manifest(): Manifest {
+  return {
+    version: 3,
+    model: {
+      nodes: [
+        { id: "action:a", kind: "action", name: "a" },
+        { id: "action:b", kind: "action", name: "b" },
+        { id: "event:E", kind: "event", name: "E" },
+        { id: "projection:P", kind: "projection", name: "P" },
+        { id: "app:app", kind: "app", name: "app" },
+      ],
+      edges: [],
+    },
+  } as unknown as Manifest;
+}
+
+describe("quickStats", () => {
+  it("derives KPI counts from the manifest view + error count", () => {
+    const stats = quickStats(manifestView(manifest()), 7);
+    const byLabel = Object.fromEntries(stats.map((s) => [s.label, s.value]));
+    expect(byLabel.Nodes).toBe(5);
+    expect(byLabel.Actions).toBe(2);
+    expect(byLabel.Events).toBe(1);
+    expect(byLabel.Projections).toBe(1);
+    expect(byLabel.Errors).toBe(7);
+  });
+  it("reports zeros for a null view (manifest not loaded)", () => {
+    const stats = quickStats(null, 0);
+    expect(stats.every((s) => s.value === 0)).toBe(true);
+  });
+});
+
+describe("countErrors", () => {
+  it("counts failure records", () => {
+    const recs: TelemetryRecord[] = [
+      { kind: "action.dispatched" },
+      { kind: "action.failed" },
+      { kind: "event.published", error: { name: "X", message: "boom" } },
+    ];
+    expect(countErrors(recs)).toBe(2);
+  });
+});
+
+describe("activityLabel", () => {
+  it("prefers the named subject", () => {
+    expect(activityLabel({ kind: "action.dispatched", action: "orders.place" })).toBe(
+      "orders.place",
+    );
+    expect(activityLabel({ kind: "event.published", event: "OrderPlaced" })).toBe("OrderPlaced");
+  });
+  it("falls back to the kind", () => {
+    expect(activityLabel({ kind: "timer.fired" })).toBe("timer.fired");
+  });
+});
+
+describe("recentActivity", () => {
+  const recs: TelemetryRecord[] = [
+    {
+      kind: "action.dispatched",
+      action: "a",
+      ts: "1",
+      envelope: { messageId: "m1", correlationId: "c1", causationId: "m1" },
+    },
+    { kind: "action.failed", action: "b", ts: "2" },
+    { kind: "event.published", event: "E", ts: "3" },
+  ];
+
+  it("returns newest-first, capped at the limit", () => {
+    const items = recentActivity(recs, 2);
+    expect(items.map((i) => i.label)).toEqual(["E", "b"]);
+  });
+  it("marks failures and carries the correlation id + colour family", () => {
+    const items = recentActivity(recs, 3);
+    const failed = items.find((i) => i.label === "b");
+    const dispatched = items.find((i) => i.label === "a");
+    expect(failed?.failed).toBe(true);
+    expect(dispatched?.failed).toBe(false);
+    expect(dispatched?.correlationId).toBe("c1");
+    expect(dispatched?.colorKey).toBe("action");
+  });
+});

package/src/lib/__tests__/inspect.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from "vitest";
+import { manifestView, type Manifest } from "../manifest";
+import {
+  inspectKinds,
+  nodesOfKind,
+  matchesNode,
+  nodeToDetail,
+  relationships,
+  kindLabel,
+  isDispatchable,
+} from "../inspect";
+
+const manifest = {
+  version: 3,
+  // flat arrays — nodeToDetail prefers these for schema
+  actions: [
+    {
+      name: "orders.place",
+      app: "orders",
+      public: true,
+      description: "Place an order",
+      inputSchema: { type: "object" },
+      emits: ["orders.placed"],
+      source: { file: "orders/place.ts", line: 3 },
+    },
+  ],
+  events: [{ name: "orders.placed", app: "orders" }],
+  model: {
+    nodes: [
+      {
+        id: "action:orders.place",
+        kind: "action",
+        name: "orders.place",
+        source: { file: "orders/place.ts", line: 3 },
+        intent: { description: "Place an order", public: true },
+        data: { emits: ["orders.placed"] },
+      },
+      { id: "event:orders.placed", kind: "event", name: "orders.placed" },
+      {
+        id: "plugin:auth",
+        kind: "plugin",
+        name: "auth",
+        source: { file: "plugins/auth.ts", line: 1 },
+        intent: { description: "Auth plugin" },
+        data: { contributes: ["binding:user"] },
+      },
+      { id: "query:orders.by-id", kind: "query", name: "orders.by-id" },
+      {
+        id: "app:orders",
+        kind: "app",
+        name: "orders",
+        intent: { description: "Orders BC" },
+        data: {
+          plugins: ["forge.actions"],
+          env: ["DATABASE_URL", "PORT"],
+          config: [{ file: "/abs/app/config/orders.ts", keys: ["orders", "limits"] }],
+        },
+      },
+    ],
+    edges: [
+      { from: "action:orders.place", to: "event:orders.placed", type: "emits" },
+      { from: "query:orders.by-id", to: "action:orders.place", type: "dispatches" },
+    ],
+  },
+} as unknown as Manifest;
+
+const view = manifestView(manifest);
+
+describe("kindLabel", () => {
+  it("maps kinds to friendly labels, falling back to the raw kind", () => {
+    expect(kindLabel("action")).toBe("Actions");
+    expect(kindLabel("sinkStage")).toBe("Sinks");
+    expect(kindLabel("mystery")).toBe("mystery");
+  });
+});
+
+describe("inspectKinds", () => {
+  it("lists present kinds with counts in curated order", () => {
+    const out = inspectKinds(view);
+    expect(out.map((k) => k.kind)).toEqual(["action", "query", "event", "app", "plugin"]);
+    expect(out.find((k) => k.kind === "action")!.count).toBe(1);
+  });
+  it("returns [] for a null view", () => {
+    expect(inspectKinds(null)).toEqual([]);
+  });
+});
+
+describe("nodesOfKind", () => {
+  it("returns the kind's nodes, name-sorted", () => {
+    expect(nodesOfKind(view, "action").map((n) => n.name)).toEqual(["orders.place"]);
+    expect(nodesOfKind(view, "nope")).toEqual([]);
+  });
+});
+
+describe("matchesNode", () => {
+  const node = nodesOfKind(view, "action")[0]!;
+  it("matches name + description, case-insensitively", () => {
+    expect(matchesNode(node, "PLACE")).toBe(true);
+    expect(matchesNode(node, "place an order")).toBe(true);
+    expect(matchesNode(node, "zzz")).toBe(false);
+  });
+  it("empty query matches", () => {
+    expect(matchesNode(node, "")).toBe(true);
+  });
+});
+
+describe("nodeToDetail", () => {
+  it("prefers the flat entry (carries the schema) for member kinds", () => {
+    const node = nodesOfKind(view, "action")[0]!;
+    const d = nodeToDetail(view, manifest, node)!;
+    expect(d.name).toBe("orders.place");
+    expect(d.schema).toEqual({ type: "object" });
+    expect(d.emits).toEqual(["orders.placed"]);
+    expect(d.public).toBe(true);
+  });
+  it("builds detail from the graph node for structural kinds (no flat entry)", () => {
+    const node = nodesOfKind(view, "plugin")[0]!;
+    const d = nodeToDetail(view, manifest, node)!;
+    expect(d.kind).toBe("plugin");
+    expect(d.description).toBe("Auth plugin");
+    expect(d.source).toEqual({ file: "plugins/auth.ts", line: 1 });
+    expect(d.extra.contributes).toEqual(["binding:user"]);
+  });
+  it("returns null for a null node", () => {
+    expect(nodeToDetail(view, manifest, null)).toBeNull();
+  });
+  it("surfaces env + config on app nodes (not in generic extra)", () => {
+    const node = nodesOfKind(view, "app")[0]!;
+    const d = nodeToDetail(view, manifest, node)!;
+    expect(d.kind).toBe("app");
+    expect(d.env).toEqual(["DATABASE_URL", "PORT"]);
+    expect(d.config).toEqual([{ file: "/abs/app/config/orders.ts", keys: ["orders", "limits"] }]);
+    // env/config render as their own sections — never duplicated into Details.
+    expect(d.extra.env).toBeUndefined();
+    expect(d.extra.config).toBeUndefined();
+    expect(d.extra.plugins).toEqual(["forge.actions"]);
+  });
+});
+
+describe("relationships", () => {
+  it("groups a node's edges by humanized, direction-aware relation", () => {
+    const groups = relationships(view, "action:orders.place");
+    const byLabel = Object.fromEntries(groups.map((g) => [g.label, g.items.map((i) => i.id)]));
+    expect(byLabel["Emits"]).toEqual(["event:orders.placed"]);
+    expect(byLabel["Dispatched by"]).toEqual(["query:orders.by-id"]);
+  });
+  it("is empty for a node with no edges", () => {
+    expect(relationships(view, "event:orders.placed").every((g) => g.items.length)).toBe(true);
+    expect(relationships(view, "nope:x")).toEqual([]);
+  });
+});
+
+describe("isDispatchable", () => {
+  it("is true for action / command / query", () => {
+    expect(isDispatchable("action")).toBe(true);
+    expect(isDispatchable("command")).toBe(true);
+    expect(isDispatchable("query")).toBe(true);
+    expect(isDispatchable("event")).toBe(false);
+  });
+});

package/src/lib/__tests__/kind-colors.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { kindColor, kindVariant, recordColorKey, KIND_COLOR, KIND_LEGEND } from "../kind-colors";
+
+describe("kindColor", () => {
+  it("returns the canonical hex for a known kind", () => {
+    expect(kindColor("action")).toBe(KIND_COLOR.action);
+    expect(kindColor("workflow")).toBe(KIND_COLOR.workflow);
+  });
+
+  it("falls back to the neutral dim for unknown/undefined", () => {
+    expect(kindColor("nope")).toBe("#8a97ad");
+    expect(kindColor(undefined)).toBe("#8a97ad");
+  });
+});
+
+describe("kindVariant", () => {
+  it("maps dispatch kinds to info", () => {
+    for (const k of ["action", "command", "query", "route"]) {
+      expect(kindVariant(k)).toBe("info");
+    }
+  });
+
+  it("maps app to success and actor/externalCall to warning", () => {
+    expect(kindVariant("app")).toBe("success");
+    expect(kindVariant("actor")).toBe("warning");
+    expect(kindVariant("externalCall")).toBe("warning");
+  });
+
+  it("falls back to neutral", () => {
+    expect(kindVariant("event")).toBe("neutral");
+    expect(kindVariant(undefined)).toBe("neutral");
+  });
+});
+
+describe("recordColorKey", () => {
+  it("maps dotted record kinds back to their handler-kind colour key", () => {
+    expect(recordColorKey("action.completed")).toBe("action");
+    expect(recordColorKey("event.published")).toBe("event");
+    expect(recordColorKey("query.executed")).toBe("query");
+    expect(recordColorKey("projection.folded")).toBe("projection");
+    expect(recordColorKey("actor.transitioned")).toBe("actor");
+  });
+
+  it("maps family + stage kinds to their group colour", () => {
+    expect(recordColorKey("reaction.fired")).toBe("workflow");
+    expect(recordColorKey("external.call.failed")).toBe("externalCall");
+    expect(recordColorKey("source.stage")).toBe("sourceStage");
+    expect(recordColorKey("sink.stage")).toBe("sinkStage");
+    expect(kindColor(recordColorKey("external.call.failed"))).toBe(KIND_COLOR.externalCall);
+  });
+});
+
+describe("KIND_LEGEND", () => {
+  it("lists the user-facing handler kinds and every entry has a colour", () => {
+    expect(KIND_LEGEND).toContain("action");
+    expect(KIND_LEGEND).toContain("projection");
+    for (const k of KIND_LEGEND) expect(kindColor(k)).not.toBe("#8a97ad");
+  });
+});

package/src/lib/__tests__/live-table.test.ts

@@ -0,0 +1,194 @@
+import { describe, it, expect } from "vitest";
+import type { TelemetryRecord } from "../telemetry";
+import {
+  recordTime,
+  recordSubject,
+  recordDuration,
+  matchesFilter,
+  filterRecords,
+  sortRecords,
+  nextIndex,
+  computeKpis,
+  distinctKinds,
+  shortId,
+} from "../live-table";
+
+function rec(over: Partial<TelemetryRecord> & { kind: string }): TelemetryRecord {
+  return over as TelemetryRecord;
+}
+
+const dispatched = rec({
+  kind: "action.dispatched",
+  action: "moderation.submit-post",
+  ts: "2026-06-15T10:00:00.000Z",
+  appName: "moderation",
+  envelope: {
+    messageId: "m-1-aaa",
+    correlationId: "c-1-zzz",
+    causationId: "m-1-aaa",
+    tenant: "acme",
+  },
+});
+const completed = rec({
+  kind: "action.completed",
+  action: "moderation.submit-post",
+  durationMs: 42,
+  ts: "2026-06-15T10:00:01.000Z",
+  envelope: { messageId: "m-2", correlationId: "c-1-zzz", causationId: "m-1-aaa" },
+});
+const failed = rec({
+  kind: "action.failed",
+  action: "moderation.submit-post",
+  ts: "2026-06-15T10:00:02.000Z",
+  error: { name: "Error", message: "boom" },
+  envelope: { messageId: "m-3", correlationId: "c-2", causationId: "m-1-aaa" },
+});
+const published = rec({
+  kind: "event.published",
+  event: { name: "post.submitted" },
+  ts: "2026-06-15T10:00:00.500Z",
+  envelope: { messageId: "m-4", correlationId: "c-1-zzz", causationId: "m-1-aaa" },
+});
+
+describe("recordTime", () => {
+  it("parses ts to epoch millis", () => {
+    expect(recordTime(dispatched)).toBe(Date.parse("2026-06-15T10:00:00.000Z"));
+  });
+  it("is 0 when ts is missing or unparseable", () => {
+    expect(recordTime(rec({ kind: "x" }))).toBe(0);
+    expect(recordTime(rec({ kind: "x", ts: "not-a-date" }))).toBe(0);
+  });
+});
+
+describe("recordSubject", () => {
+  it("reads the per-kind subject field", () => {
+    expect(recordSubject(dispatched)).toBe("moderation.submit-post");
+    expect(recordSubject(rec({ kind: "query.executed", query: "users.by-id" }))).toBe(
+      "users.by-id",
+    );
+    expect(recordSubject(rec({ kind: "actor.transitioned", actor: "Post" }))).toBe("Post");
+  });
+  it("unwraps an EventMessage-shaped event or a string event", () => {
+    expect(recordSubject(published)).toBe("post.submitted");
+    expect(recordSubject(rec({ kind: "listener.fired", event: "post.submitted" }))).toBe(
+      "post.submitted",
+    );
+  });
+  it("falls back to em-dash when nothing identifies it", () => {
+    expect(recordSubject(rec({ kind: "mystery" }))).toBe("—");
+  });
+});
+
+describe("recordDuration", () => {
+  it("returns the ms when present, else undefined", () => {
+    expect(recordDuration(completed)).toBe(42);
+    expect(recordDuration(dispatched)).toBeUndefined();
+  });
+});
+
+describe("matchesFilter", () => {
+  it("matches across kind, subject, ids, tenant and error", () => {
+    expect(matchesFilter(dispatched, "submit-post")).toBe(true);
+    expect(matchesFilter(dispatched, "ACME")).toBe(true); // case-insensitive
+    expect(matchesFilter(dispatched, "c-1-zzz")).toBe(true);
+    expect(matchesFilter(failed, "boom")).toBe(true);
+    expect(matchesFilter(dispatched, "nope")).toBe(false);
+  });
+  it("an empty query matches everything", () => {
+    expect(matchesFilter(dispatched, "")).toBe(true);
+    expect(matchesFilter(dispatched, "   ")).toBe(true);
+  });
+});
+
+describe("filterRecords", () => {
+  const all = [dispatched, completed, failed, published];
+  it("filters by kind", () => {
+    expect(filterRecords(all, { kind: "action.failed" })).toEqual([failed]);
+  });
+  it("filters by correlation chain", () => {
+    expect(filterRecords(all, { correlationId: "c-1-zzz" })).toEqual([
+      dispatched,
+      completed,
+      published,
+    ]);
+  });
+  it("filters failures only", () => {
+    expect(filterRecords(all, { failuresOnly: true })).toEqual([failed]);
+  });
+  it("combines clauses (AND)", () => {
+    expect(filterRecords(all, { correlationId: "c-1-zzz", text: "event" })).toEqual([published]);
+  });
+});
+
+describe("sortRecords", () => {
+  const all = [dispatched, completed, failed, published];
+  it("sorts by time descending (newest first) without mutating input", () => {
+    const out = sortRecords(all, "time", "desc");
+    expect(out.map((r) => r.kind)).toEqual([
+      "action.failed",
+      "action.completed",
+      "event.published",
+      "action.dispatched",
+    ]);
+    expect(all[0]).toBe(dispatched); // original order intact
+  });
+  it("sorts by duration ascending (missing durations sort first)", () => {
+    const out = sortRecords(all, "duration", "asc");
+    expect(out[out.length - 1]).toBe(completed); // only one with a duration → last asc
+  });
+  it("sorts by subject and is stable on ties", () => {
+    const a = rec({ kind: "action.completed", action: "z", ts: "2026-06-15T10:00:00.000Z" });
+    const b = rec({ kind: "action.completed", action: "z", ts: "2026-06-15T10:00:05.000Z" });
+    const out = sortRecords([a, b], "subject", "asc");
+    expect(out).toEqual([a, b]); // first-seen order preserved on equal subjects
+  });
+});
+
+describe("nextIndex", () => {
+  it("returns -1 for an empty list", () => {
+    expect(nextIndex(0, 0, 1)).toBe(-1);
+  });
+  it("starts at the head/tail from no selection", () => {
+    expect(nextIndex(-1, 5, 1)).toBe(0);
+    expect(nextIndex(-1, 5, -1)).toBe(4);
+  });
+  it("clamps at the ends (no wrap)", () => {
+    expect(nextIndex(0, 5, -1)).toBe(0);
+    expect(nextIndex(4, 5, 1)).toBe(4);
+    expect(nextIndex(2, 5, 1)).toBe(3);
+  });
+});
+
+describe("computeKpis", () => {
+  it("rolls up totals, failures, distinct kinds + chains, and rate/s", () => {
+    const k = computeKpis([dispatched, completed, failed, published]);
+    expect(k.total).toBe(4);
+    expect(k.failures).toBe(1);
+    expect(k.kinds).toBe(4);
+    expect(k.chains).toBe(2); // c-1-zzz + c-2
+    // span = 2s across 4 records → 2/s
+    expect(k.perSecond).toBe(2);
+  });
+  it("rate is 0 with fewer than two timestamps", () => {
+    expect(computeKpis([dispatched]).perSecond).toBe(0);
+    expect(computeKpis([]).total).toBe(0);
+  });
+});
+
+describe("distinctKinds", () => {
+  it("lists kinds in first-seen order", () => {
+    expect(distinctKinds([completed, dispatched, completed, published])).toEqual([
+      "action.completed",
+      "action.dispatched",
+      "event.published",
+    ]);
+  });
+});
+
+describe("shortId", () => {
+  it("takes the first dash segment", () => {
+    expect(shortId("c-1-zzz")).toBe("c");
+    expect(shortId("abcdef0123456789")).toBe("abcdef01");
+    expect(shortId(undefined)).toBe("—");
+  });
+});