@nwire/studio 0.12.0 → 0.13.0

package/src/lib/__tests__/manifest-health.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import { missingFields } from "../manifest-health";
+import type { Manifest } from "../manifest";
+
+/**
+ * A current-shape manifest carries every kind as a top-level array (empty when
+ * unused) plus `graph.events`. Mirrors the real `@nwire/scan` `buildManifest`
+ * output — apps/resolvers/routes/hooks/plugins/sinks/bindings live under
+ * `topology`/`model`, not at the top level, so they're NOT health-checked.
+ */
+function fullManifest(): Record<string, unknown> {
+  return {
+    version: 3,
+    events: [],
+    actions: [],
+    actors: [],
+    projections: [],
+    queries: [],
+    workflows: [],
+    commands: [],
+    crons: [],
+    externalCalls: [],
+    inboundWebhooks: [],
+    outboxes: [],
+    inboxes: [],
+    resources: [],
+    errors: [],
+    schemas: [],
+    graph: { events: [] },
+  };
+}
+
+describe("missingFields", () => {
+  it("reports nothing for a current-shape manifest", () => {
+    expect(missingFields(fullManifest() as unknown as Manifest)).toEqual([]);
+  });
+
+  it("does not flag the deep-manifest fields kept under topology/model", () => {
+    // Regression: these are NOT top-level arrays in the real manifest; flagging
+    // them false-fired the rebuild banner on every healthy project.
+    const out = missingFields(fullManifest() as unknown as Manifest);
+    for (const f of [
+      "apps",
+      "resolvers",
+      "routes",
+      "hooks",
+      "plugins",
+      "sinks",
+      "bindings",
+      "generatedAt",
+    ]) {
+      expect(out).not.toContain(f);
+    }
+  });
+
+  it("reports every expected field when the manifest is empty", () => {
+    const out = missingFields({} as unknown as Manifest);
+    expect(out).toContain("actions");
+    expect(out).toContain("events");
+    expect(out).toContain("workflows");
+    expect(out).toContain("commands");
+    expect(out).toContain("resources");
+    expect(out).toContain("graph");
+  });
+
+  it("names the genuinely-missing kinds on a legacy manifest (the banner contract)", () => {
+    const legacy = fullManifest();
+    delete legacy.workflows;
+    delete legacy.commands;
+    const out = missingFields(legacy as unknown as Manifest);
+    expect(out).toContain("workflows");
+    expect(out).toContain("commands");
+    expect(out).not.toContain("actions");
+  });
+
+  it("reports the exact list of missing array fields", () => {
+    const partial = {
+      version: 3,
+      events: [],
+      actions: [],
+      actors: [],
+      projections: [],
+      queries: [],
+      // workflows + commands + resources + errors + schemas + graph missing
+      crons: [],
+      externalCalls: [],
+      inboundWebhooks: [],
+      outboxes: [],
+      inboxes: [],
+    };
+    expect([...missingFields(partial as unknown as Manifest)].sort()).toEqual([
+      "commands",
+      "errors",
+      "graph",
+      "resources",
+      "schemas",
+      "workflows",
+    ]);
+  });
+
+  it("treats a non-array masquerading as the field as missing", () => {
+    const m = fullManifest();
+    m.workflows = "not an array";
+    expect(missingFields(m as unknown as Manifest)).toContain("workflows");
+  });
+
+  it("reports graph.events missing while graph exists", () => {
+    const m = fullManifest();
+    m.graph = {};
+    expect(missingFields(m as unknown as Manifest)).toContain("graph.events");
+  });
+
+  it("returns [] for unusable (non-object) input — App renders the error banner instead", () => {
+    expect(missingFields(null)).toEqual([]);
+    expect(missingFields(undefined)).toEqual([]);
+    expect(missingFields([] as unknown as Manifest)).toEqual([]);
+    expect(missingFields("oops" as unknown as Manifest)).toEqual([]);
+    expect(missingFields(42 as unknown as Manifest)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { manifestView } from "../manifest";
+import type { Manifest } from "../manifest";
+
+function fixture(): Manifest {
+  return {
+    version: 3,
+    model: {
+      nodes: [
+        { id: "action:orders.place", kind: "action", name: "orders.place" },
+        { id: "event:OrderPlaced", kind: "event", name: "OrderPlaced" },
+        { id: "app:orders", kind: "app", name: "orders" },
+      ],
+      edges: [
+        { from: "action:orders.place", to: "event:OrderPlaced", type: "emits" },
+        { from: "app:orders", to: "route:POST /orders", type: "mounts" },
+      ],
+    },
+  } as unknown as Manifest;
+}
+
+describe("manifestView", () => {
+  it("selects nodes by kind", () => {
+    const v = manifestView(fixture());
+    expect(v.byKind("action").map((n) => n.name)).toEqual(["orders.place"]);
+    expect(v.byKind("app")).toHaveLength(1);
+    expect(v.byKind("nope")).toEqual([]);
+  });
+  it("looks up a node by id", () => {
+    const v = manifestView(fixture());
+    expect(v.node("event:OrderPlaced")?.name).toBe("OrderPlaced");
+    expect(v.node("missing")).toBeUndefined();
+  });
+  it("filters edges by direction and type", () => {
+    const v = manifestView(fixture());
+    expect(v.edgesOf("action:orders.place", "out")).toHaveLength(1);
+    expect(v.edgesOf("event:OrderPlaced", "in")).toHaveLength(1);
+    expect(v.edgesOf("event:OrderPlaced", "out")).toHaveLength(0);
+    expect(v.edgesOf("action:orders.place", "both")).toHaveLength(1);
+    expect(v.edgesByType("emits")).toHaveLength(1);
+    expect(v.edgesByType("mounts")).toHaveLength(1);
+  });
+  it("flags a version mismatch", () => {
+    expect(manifestView(fixture()).versionMismatch).toBe(false);
+    expect(
+      manifestView({ version: 99, model: { nodes: [], edges: [] } } as unknown as Manifest)
+        .versionMismatch,
+    ).toBe(true);
+  });
+  it("tolerates a manifest with no model (empty graph, no throw)", () => {
+    const v = manifestView({} as Manifest);
+    expect(v.model.nodes).toEqual([]);
+    expect(v.byKind("action")).toEqual([]);
+    expect(v.edgesOf("x")).toEqual([]);
+  });
+
+  it("synthesizes a model from flat arrays when `model` is absent", () => {
+    const flat = {
+      actions: [
+        { name: "orders.place", app: "orders", emits: ["orders.placed"], description: "Place" },
+      ],
+      events: [{ name: "orders.placed", app: "orders" }],
+      queries: [{ name: "orders.by-id", projection: "orders" }],
+      plugins: [{ name: "auth" }],
+    } as unknown as Manifest;
+    const v = manifestView(flat);
+    expect(v.byKind("action").map((n) => n.name)).toEqual(["orders.place"]);
+    expect(v.byKind("plugin")).toHaveLength(1);
+    // action→event emits + query→projection reads edges are derived.
+    expect(v.edgesOf("action:orders.place", "out")).toContainEqual({
+      from: "action:orders.place",
+      to: "event:orders.placed",
+      type: "emits",
+    });
+    expect(v.edgesOf("query:orders.by-id", "out")).toContainEqual({
+      from: "query:orders.by-id",
+      to: "projection:orders",
+      type: "reads",
+    });
+  });
+
+  it("prefers the deep model when present (does not synthesize)", () => {
+    const v = manifestView(fixture());
+    // fixture's model has app + action nodes only — no synthesized 'plugin'.
+    expect(v.byKind("query")).toEqual([]);
+  });
+});

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

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { flattenMetadata } from "../metadata";
+
+describe("flattenMetadata", () => {
+  it("flattens nested objects to dot-notation entries", () => {
+    const entries = flattenMetadata({
+      kind: "action.completed",
+      envelope: { messageId: "m1", correlationId: "c1" },
+    });
+    const map = Object.fromEntries(entries.map((e) => [e.path, e.value]));
+    expect(map.kind).toBe("action.completed");
+    expect(map["envelope.messageId"]).toBe("m1");
+    expect(map["envelope.correlationId"]).toBe("c1");
+  });
+
+  it("indexes arrays by position", () => {
+    const entries = flattenMetadata({ items: [{ id: "a" }, { id: "b" }] });
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("items.0.id");
+    expect(paths).toContain("items.1.id");
+  });
+
+  it("tags each entry with its value type", () => {
+    const entries = flattenMetadata({ s: "x", n: 3, b: true, z: null });
+    const byPath = Object.fromEntries(entries.map((e) => [e.path, e.type]));
+    expect(byPath.s).toBe("string");
+    expect(byPath.n).toBe("number");
+    expect(byPath.b).toBe("boolean");
+    expect(byPath.z).toBe("null");
+  });
+
+  it("drops undefined and functions", () => {
+    const entries = flattenMetadata({ keep: 1, gone: undefined, fn: () => 0 });
+    expect(entries.map((e) => e.path)).toEqual(["keep"]);
+  });
+
+  it("guards against cycles", () => {
+    const a: Record<string, unknown> = { name: "a" };
+    a.self = a;
+    const entries = flattenMetadata(a);
+    expect(entries.some((e) => e.value === "[circular]")).toBe(true);
+  });
+
+  it("wraps a bare primitive under `value`", () => {
+    expect(flattenMetadata("hi")).toEqual([{ path: "value", value: "hi", type: "string" }]);
+  });
+});

package/src/lib/__tests__/node-metrics.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from "vitest";
+import { nodeIdOf, rollupMetrics, edgeActivity, fmtCount, fmtLatency } from "../node-metrics";
+import type { TelemetryRecord } from "../telemetry";
+
+const rec = (r: Partial<TelemetryRecord> & { kind: string }): TelemetryRecord =>
+  r as TelemetryRecord;
+
+describe("node-metrics: nodeIdOf", () => {
+  it("maps each kind to its graph node id via the kind-specific name field", () => {
+    expect(nodeIdOf(rec({ kind: "action.completed", action: "moderation.submit-post" }))).toBe(
+      "action:moderation.submit-post",
+    );
+    expect(nodeIdOf(rec({ kind: "query.executed", query: "moderation.list-pending" }))).toBe(
+      "query:moderation.list-pending",
+    );
+    expect(nodeIdOf(rec({ kind: "projection.folded", projection: "queue-dashboard" }))).toBe(
+      "projection:queue-dashboard",
+    );
+    expect(nodeIdOf(rec({ kind: "actor.transitioned", actor: "post" }))).toBe("actor:post");
+    expect(nodeIdOf(rec({ kind: "reaction.fired", workflow: "auto-moderate" }))).toBe(
+      "workflow:auto-moderate",
+    );
+    expect(nodeIdOf(rec({ kind: "external.call.completed", call: "stripe.charge" }))).toBe(
+      "externalCall:stripe.charge",
+    );
+    expect(nodeIdOf(rec({ kind: "dlq.recorded", action: "moderation.submit-post" }))).toBe(
+      "action:moderation.submit-post",
+    );
+  });
+
+  it("reads the event name from a string or an EventMessage object", () => {
+    // event.emitted / listener.fired stamp a string name.
+    expect(nodeIdOf(rec({ kind: "event.emitted", event: "moderation.post-was-submitted" }))).toBe(
+      "event:moderation.post-was-submitted",
+    );
+    expect(nodeIdOf(rec({ kind: "listener.fired", event: "moderation.post-was-approved" }))).toBe(
+      "event:moderation.post-was-approved",
+    );
+    // event.published stamps an EventMessage object carrying `eventName`
+    // (forge's wire shape) — or `name` on other event-message shapes.
+    expect(
+      nodeIdOf(
+        rec({ kind: "event.published", event: { eventName: "moderation.post-was-rejected" } }),
+      ),
+    ).toBe("event:moderation.post-was-rejected");
+    expect(
+      nodeIdOf(rec({ kind: "event.deduped", event: { name: "moderation.post-was-rejected" } })),
+    ).toBe("event:moderation.post-was-rejected");
+  });
+
+  it("returns null for stage/hook records that name no primitive", () => {
+    expect(nodeIdOf(rec({ kind: "hook.step", hookName: "publish" }))).toBeNull();
+    expect(nodeIdOf(rec({ kind: "source.stage", stage: "auth" }))).toBeNull();
+    expect(nodeIdOf(rec({ kind: "sink.stage", stage: "outbox" }))).toBeNull();
+    expect(nodeIdOf(rec({ kind: "action.completed" }))).toBeNull(); // no name field
+  });
+});
+
+describe("node-metrics: rollupMetrics", () => {
+  it("returns an empty rollup for no records (neutral-placeholder state)", () => {
+    const r = rollupMetrics([]);
+    expect(r.total).toBe(0);
+    expect(r.byNode.size).toBe(0);
+    expect(r.byApp.size).toBe(0);
+  });
+
+  it("counts throughput, errors, and p50 latency per node", () => {
+    const r = rollupMetrics([
+      rec({ kind: "action.completed", action: "a.x", durationMs: 10, appName: "a", ts: "1" }),
+      rec({ kind: "action.completed", action: "a.x", durationMs: 30, appName: "a", ts: "2" }),
+      rec({
+        kind: "action.failed",
+        action: "a.x",
+        durationMs: 20,
+        appName: "a",
+        ts: "3",
+        error: { name: "E", message: "boom" },
+      }),
+    ]);
+    const m = r.byNode.get("action:a.x")!;
+    expect(m.count).toBe(3);
+    expect(m.errors).toBe(1);
+    expect(m.p50).toBe(20); // median of [10,20,30]
+    expect(m.lastTs).toBe("3");
+  });
+
+  it("rolls dispatches/errors/total up per app", () => {
+    const r = rollupMetrics([
+      rec({ kind: "action.dispatched", action: "a.x", appName: "alpha", ts: "1" }),
+      rec({ kind: "query.executed", query: "a.q", appName: "alpha", ts: "2" }),
+      rec({ kind: "event.emitted", event: "a.e", appName: "alpha", ts: "3" }),
+      rec({
+        kind: "action.failed",
+        action: "a.x",
+        appName: "alpha",
+        ts: "4",
+        error: { name: "E", message: "x" },
+      }),
+    ]);
+    const m = r.byApp.get("alpha")!;
+    expect(m.dispatches).toBe(2); // action.dispatched + query.executed
+    expect(m.errors).toBe(1);
+    expect(m.total).toBe(4);
+    expect(m.lastTs).toBe("4");
+  });
+
+  it("is deterministic — same records yield the same rollup", () => {
+    const recs = [
+      rec({ kind: "action.completed", action: "a.x", durationMs: 5, appName: "a", ts: "1" }),
+      rec({ kind: "query.executed", query: "a.q", durationMs: 7, appName: "a", ts: "2" }),
+    ];
+    expect(rollupMetrics(recs)).toEqual(rollupMetrics([...recs]));
+  });
+});
+
+describe("node-metrics: edgeActivity", () => {
+  it("attributes the destination node's volume to the edge and flags it active", () => {
+    const byNode = new Map([
+      ["event:a.e", { count: 4, errors: 0 }],
+      ["action:a.x", { count: 0, errors: 0 }],
+    ]);
+    const act = edgeActivity(byNode, [
+      { id: "action:a.x=>event:a.e", from: "action:a.x", to: "event:a.e" },
+      { id: "event:a.e=>action:a.x", from: "event:a.e", to: "action:a.x" },
+    ]);
+    expect(act.get("action:a.x=>event:a.e")).toEqual({ volume: 4, active: true });
+    expect(act.get("event:a.e=>action:a.x")).toEqual({ volume: 0, active: false });
+  });
+});
+
+describe("node-metrics: formatters", () => {
+  it("fmtCount shows a dim em dash for zero/undefined, the number otherwise", () => {
+    expect(fmtCount(undefined)).toBe("—");
+    expect(fmtCount(0)).toBe("—");
+    expect(fmtCount(7)).toBe("7");
+  });
+
+  it("fmtLatency formats sub-ms, ms, and seconds; '—' when none", () => {
+    expect(fmtLatency(undefined)).toBe("—");
+    expect(fmtLatency(0.4)).toBe("<1ms");
+    expect(fmtLatency(12)).toBe("12ms");
+    expect(fmtLatency(1234)).toBe("1.2s");
+  });
+});

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

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseEnvInput,
+  sortScripts,
+  statusTone,
+  shortId,
+  timeAgo,
+  isActive,
+  activeProcess,
+  type ManagedProcess,
+} from "../operate";
+
+describe("parseEnvInput", () => {
+  it("parses KEY=value lines, skipping blanks + comments", () => {
+    expect(parseEnvInput("A=1\n\n# c\nB=two")).toEqual({ A: "1", B: "two" });
+  });
+  it("strips matching surrounding quotes", () => {
+    expect(parseEnvInput(`A="x y"\nB='z'`)).toEqual({ A: "x y", B: "z" });
+  });
+  it("rejects malformed keys", () => {
+    expect(parseEnvInput("1BAD=x\n=y\nGOOD=ok")).toEqual({ GOOD: "ok" });
+  });
+});
+
+describe("sortScripts", () => {
+  it("puts nwire-prefixed first, each group alphabetical", () => {
+    const out = sortScripts([
+      { name: "test", command: "vitest" },
+      { name: "nwire:dev", command: "nwire dev" },
+      { name: "build", command: "tsc" },
+      { name: "nwire:cache", command: "nwire cache" },
+    ]);
+    expect(out.map((s) => s.name)).toEqual(["nwire:cache", "nwire:dev", "build", "test"]);
+  });
+});
+
+describe("statusTone", () => {
+  it("maps process status to a StatusBadge tone", () => {
+    expect(statusTone("running")).toBe("live");
+    expect(statusTone("starting")).toBe("warn");
+    expect(statusTone("stopping")).toBe("warn");
+    expect(statusTone("crashed")).toBe("error");
+    expect(statusTone("exited")).toBe("idle");
+    expect(statusTone("idle")).toBe("idle");
+  });
+});
+
+describe("shortId", () => {
+  it("takes the first uuid segment", () => {
+    expect(shortId("abc12345-de-fg")).toBe("abc12345");
+    expect(shortId("plainid")).toBe("plainid");
+  });
+});
+
+describe("timeAgo", () => {
+  const base = Date.parse("2026-06-18T12:00:00.000Z");
+  it("formats seconds / minutes / hours", () => {
+    expect(timeAgo("2026-06-18T11:59:50.000Z", base)).toBe("10s ago");
+    expect(timeAgo("2026-06-18T11:55:00.000Z", base)).toBe("5m ago");
+    expect(timeAgo("2026-06-18T10:00:00.000Z", base)).toBe("2h ago");
+  });
+  it("never goes negative", () => {
+    expect(timeAgo("2026-06-18T12:00:30.000Z", base)).toBe("0s ago");
+  });
+});
+
+const proc = (over: Partial<ManagedProcess>): ManagedProcess => ({
+  id: "x",
+  topology: "t",
+  startedAt: "2026-01-01T00:00:00Z",
+  status: "idle",
+  ...over,
+});
+
+describe("isActive", () => {
+  it("is true for running / starting / stopping", () => {
+    expect(isActive("running")).toBe(true);
+    expect(isActive("starting")).toBe(true);
+    expect(isActive("stopping")).toBe(true);
+    expect(isActive("exited")).toBe(false);
+  });
+});
+
+describe("activeProcess", () => {
+  it("returns the most-recently-started running process", () => {
+    const list = [
+      proc({ id: "a", status: "running", startedAt: "2026-01-01T00:00:00Z" }),
+      proc({ id: "b", status: "running", startedAt: "2026-01-02T00:00:00Z" }),
+      proc({ id: "c", status: "exited", startedAt: "2026-01-03T00:00:00Z" }),
+    ];
+    expect(activeProcess(list)?.id).toBe("b");
+  });
+  it("returns undefined when nothing is running", () => {
+    expect(activeProcess([proc({ status: "exited" })])).toBeUndefined();
+    expect(activeProcess([])).toBeUndefined();
+  });
+});

package/src/lib/__tests__/pipeline-flow.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from "vitest";
+import { pipelineFlow, isStageRecord, type StageRecord } from "../pipeline-flow";
+
+const src = (over: Partial<StageRecord> = {}): StageRecord =>
+  ({
+    kind: "source.stage",
+    stage: "s",
+    position: "early",
+    message: { name: "orders.place", kind: "command" },
+    correlationId: "c1",
+    shortCircuited: false,
+    durationMs: 1,
+    appName: "app",
+    ts: "2026-06-16T00:00:00.000Z",
+    ...(over as object),
+  }) as StageRecord;
+
+const sink = (over: Partial<StageRecord> = {}): StageRecord =>
+  ({
+    kind: "sink.stage",
+    stage: "k",
+    position: "terminal",
+    event: "order.placed",
+    correlationId: "c1",
+    shortCircuited: false,
+    durationMs: 1,
+    appName: "app",
+    ts: "2026-06-16T00:00:00.000Z",
+    ...(over as object),
+  }) as StageRecord;
+
+describe("isStageRecord", () => {
+  it("matches only the two stage kinds", () => {
+    expect(isStageRecord({ kind: "source.stage" })).toBe(true);
+    expect(isStageRecord({ kind: "sink.stage" })).toBe(true);
+    expect(isStageRecord({ kind: "action.dispatched" })).toBe(false);
+    expect(isStageRecord({ kind: "hook.step" })).toBe(false);
+  });
+});
+
+describe("pipelineFlow", () => {
+  it("returns empty flows when no correlation is selected", () => {
+    expect(pipelineFlow([src()], undefined)).toEqual({ inbound: [], outbound: [] });
+  });
+
+  it("splits inbound (source) from outbound (sink) for the correlation", () => {
+    const flow = pipelineFlow([src(), sink()], "c1");
+    expect(flow.inbound.map((r) => r.stage)).toEqual(["s"]);
+    expect(flow.outbound.map((r) => r.stage)).toEqual(["k"]);
+    expect(flow.inbound[0]!.label).toBe("orders.place");
+    expect(flow.outbound[0]!.label).toBe("order.placed");
+    expect(flow.inbound[0]!.direction).toBe("inbound");
+    expect(flow.outbound[0]!.direction).toBe("outbound");
+  });
+
+  it("excludes records from other correlations", () => {
+    const flow = pipelineFlow([src(), src({ correlationId: "other" })], "c1");
+    expect(flow.inbound).toHaveLength(1);
+  });
+
+  it("orders inbound by position (early → middle → terminal) then ts", () => {
+    const flow = pipelineFlow(
+      [
+        src({ stage: "term", position: "terminal", ts: "2026-06-16T00:00:01.000Z" }),
+        src({ stage: "early-b", position: "early", ts: "2026-06-16T00:00:00.500Z" }),
+        src({ stage: "early-a", position: "early", ts: "2026-06-16T00:00:00.100Z" }),
+        src({ stage: "mid", position: "middle", ts: "2026-06-16T00:00:00.800Z" }),
+      ],
+      "c1",
+    );
+    expect(flow.inbound.map((r) => r.stage)).toEqual(["early-a", "early-b", "mid", "term"]);
+  });
+
+  it("carries the short-circuit flag and duration through", () => {
+    const flow = pipelineFlow([sink({ shortCircuited: true, durationMs: 12 })], "c1");
+    expect(flow.outbound[0]!.shortCircuited).toBe(true);
+    expect(flow.outbound[0]!.durationMs).toBe(12);
+  });
+});