@nwire/studio 0.12.1 → 0.13.0

package/vite.config.ts

@@ -12,6 +12,12 @@ import {
   readSync,
   statSync,
 } from "node:fs";
+import {
+  readManifest,
+  listTelemetryRuns,
+  readTelemetryRun,
+  type TelemetryRunMeta,
+} from "./src/server/nwire-read";
 import { spawnSync } from "node:child_process";
 import { RunnerSupervisor, inspectHealthCheck } from "@nwire/supervisor";
 import type { IncomingMessage, ServerResponse } from "node:http";
@@ -220,9 +226,28 @@ function targetCwd(req: IncomingMessage): string | null {
  * Studio calls this on every `GET /__nwire/manifest.json` so a user
  * editing source never sees stale data — the cache rebuilds itself on
  * the next page load.
+ *
+ * The auto-rebuild is skipped when:
+ *   - `NWIRE_NO_AUTOCACHE=1` is set in the environment (e.g. the e2e harness
+ *     points Studio at a fixture directory that has a committed manifest but no
+ *     real source — running `nwire cache` there would overwrite the fixture).
+ *   - The cwd has no `package.json` (nothing to scan; serve whatever manifest
+ *     is already on disk rather than producing an empty one).
+ * In both cases we fall through to serving the existing manifest, or 404 if
+ * it isn't there yet.
  */
 function ensureCacheBuilt(cwd: string = consumerCwd, opts: { force?: boolean } = {}): boolean {
   const manifestPath = resolve(cwd, ".nwire", "manifest.json");
+
+  // Guard: a fixture-only directory (no package.json) or an explicit opt-out
+  // from the caller env. Serve whatever is on disk; don't overwrite it.
+  if (process.env.NWIRE_NO_AUTOCACHE === "1" && !opts.force) {
+    return existsSync(manifestPath);
+  }
+  if (!existsSync(resolve(cwd, "package.json")) && !opts.force) {
+    return existsSync(manifestPath);
+  }
+
   const cliPath = resolve(here, "..", "nwire-cli", "dist", "cli.js");
   if (!existsSync(cliPath)) {
     return existsSync(manifestPath);
@@ -243,6 +268,63 @@ function ensureCacheBuilt(cwd: string = consumerCwd, opts: { force?: boolean } =
   return existsSync(manifestPath);
 }
 
+// ── Telemetry run helpers ─────────────────────────────────────────────────
+// listTelemetryRuns, readTelemetryRun, TelemetryRunMeta imported from
+// ./src/server/nwire-read — shared with studio-host-api.ts.
+
+/**
+ * Open a JSONL file tail: poll for new content and call `onLine` with each
+ * newly appended, parsed JSON record. Returns a stop handle. Same pattern as
+ * `openLogTail` but parses JSON (telemetry records) instead of raw text.
+ */
+function openJsonlTail(path: string, onRecord: (rec: unknown) => void): { stop: () => void } {
+  if (!existsSync(path)) return { stop: () => {} };
+  let offset = 0;
+  let leftover = "";
+  try {
+    offset = statSync(path).size;
+  } catch {
+    offset = 0;
+  }
+  let stopped = false;
+  const poll = setInterval(() => {
+    if (stopped) return;
+    try {
+      const size = statSync(path).size;
+      if (size <= offset) return;
+      const fd = openSync(path, "r");
+      try {
+        const buf = Buffer.alloc(size - offset);
+        readSync(fd, buf, 0, buf.length, offset);
+        offset = size;
+        const text = leftover + buf.toString("utf8");
+        const lines = text.split(/\r?\n/);
+        // Last element may be an incomplete line — hold it over.
+        leftover = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            onRecord(JSON.parse(trimmed));
+          } catch {
+            // malformed JSON line — skip
+          }
+        }
+      } finally {
+        closeSync(fd);
+      }
+    } catch {
+      // file removed or rotated — stop quietly
+    }
+  }, 250);
+  return {
+    stop: () => {
+      stopped = true;
+      clearInterval(poll);
+    },
+  };
+}
+
 /**
  * Vite middleware that exposes the consumer's `.nwire/manifest.json` to the
  * Studio dev server. If the cache is missing, build it on the fly so the
@@ -390,7 +472,6 @@ function nwireDataPlugin() {
           res.end(JSON.stringify({ error: "unknown project" }));
           return;
         }
-        const manifestPath = resolve(cwd, ".nwire", "manifest.json");
         // Always run the if-stale path. When the fingerprint matches,
         // the CLI exits in a few ms with no spawn cost beyond its own
         // bootstrap; when source moved, the manifest is rebuilt before
@@ -411,8 +492,14 @@ function nwireDataPlugin() {
           );
           return;
         }
+        const raw = readManifest(cwd);
+        if (!raw) {
+          res.statusCode = 404;
+          res.end(JSON.stringify({ error: "manifest.json missing after build" }));
+          return;
+        }
         res.setHeader("Content-Type", "application/json");
-        res.end(readFileSync(manifestPath, "utf8"));
+        res.end(raw);
       });
 
       // Source viewer — reads a file from disk, returns { content, language }.
@@ -461,6 +548,137 @@ function nwireDataPlugin() {
           res.end(JSON.stringify({ error: (err as Error).message }));
         }
       });
+
+      /**
+       * Telemetry run list + single-run records.
+       *
+       *   GET /__nwire/telemetry/runs          → { runs: TelemetryRunMeta[] }
+       *   GET /__nwire/telemetry/runs/:id      → { id, records: unknown[] }
+       *
+       * Both honor `?project=<cwd>`.
+       */
+      server.middlewares.use("/__nwire/telemetry/runs", (req, res) => {
+        const cwd = targetCwd(req);
+        if (!cwd) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ error: "unknown project" }));
+          return;
+        }
+        // connect strips the mount prefix, so req.url is "/" (or "") for the
+        // list and "/<id>" for a single run.
+        const sub = new URL(req.url ?? "/", "http://x").pathname;
+
+        // Exact: list all runs.
+        if (sub === "/" || sub === "") {
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ runs: listTelemetryRuns(cwd) }));
+          return;
+        }
+
+        // Sub-path: single run records.
+        const runIdMatch = /^\/([^/]+)$/.exec(sub);
+        if (runIdMatch) {
+          const runId = decodeURIComponent(runIdMatch[1]!);
+          const file = resolve(cwd, ".nwire", "telemetry", `${runId}.jsonl`);
+          if (!existsSync(file)) {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ error: "run not found", id: runId }));
+            return;
+          }
+          const records = readTelemetryRun(cwd, runId);
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ id: runId, records }));
+          return;
+        }
+
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: "not found" }));
+      });
+
+      /**
+       * Live telemetry tail (SSE).
+       *   GET /__nwire/telemetry/live[?project=<cwd>]
+       *
+       * Finds the current (newest) run file and tails it, streaming each new
+       * JSON record as an SSE `data:` event. Sends backfill (the entire current
+       * file at connection time) first, then polls for appended lines.
+       * Keepalive comments every 25 s to prevent proxy timeouts.
+       */
+      server.middlewares.use("/__nwire/telemetry/live", (req, res) => {
+        const cwd = targetCwd(req);
+        if (!cwd) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ error: "unknown project" }));
+          return;
+        }
+        const runs = listTelemetryRuns(cwd);
+        const current = runs[0]; // newest, or undefined when no runs yet
+        const filePath = current
+          ? resolve(cwd, ".nwire", "telemetry", `${current.id}.jsonl`)
+          : null;
+
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache, no-transform");
+        res.setHeader("Connection", "keep-alive");
+
+        // Emit a meta event so the client knows which run it's tailing.
+        const runMeta = current ?? null;
+        try {
+          res.write(`event: run\ndata: ${JSON.stringify(runMeta)}\n\n`);
+        } catch {
+          return;
+        }
+
+        // Backfill: send all records already in the file.
+        if (filePath && existsSync(filePath)) {
+          const existing = readTelemetryRun(cwd, current!.id);
+          for (const rec of existing) {
+            try {
+              res.write(`data: ${JSON.stringify(rec)}\n\n`);
+            } catch {
+              return;
+            }
+          }
+        }
+
+        if (!filePath) {
+          // No run file yet — just keepalive and wait.
+          const keepalive = setInterval(() => {
+            try {
+              res.write(": keepalive\n\n");
+            } catch {
+              clearInterval(keepalive);
+            }
+          }, 25_000);
+          req.on("close", () => clearInterval(keepalive));
+          return;
+        }
+
+        // Tail for new lines appended after the backfill.
+        const tail = openJsonlTail(filePath, (rec) => {
+          try {
+            res.write(`data: ${JSON.stringify(rec)}\n\n`);
+          } catch {
+            // socket gone — tail.stop() will fire via req.close
+          }
+        });
+        const keepalive = setInterval(() => {
+          try {
+            res.write(": keepalive\n\n");
+          } catch {
+            clearInterval(keepalive);
+          }
+        }, 25_000);
+        req.on("close", () => {
+          tail.stop();
+          clearInterval(keepalive);
+        });
+      });
     },
   };
 }

package/src/lib/__tests__/normalize-cache.test.ts

@@ -1,105 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { normalizeCache } from "../normalize-cache";
-
-describe("normalizeCache", () => {
-  it("fills every expected array when input is empty", () => {
-    const { cache, missingFields } = normalizeCache({});
-    expect(cache).not.toBeNull();
-    expect(cache?.apps).toEqual([]);
-    expect(cache?.actions).toEqual([]);
-    expect(cache?.events).toEqual([]);
-    expect(cache?.actors).toEqual([]);
-    expect(cache?.projections).toEqual([]);
-    expect(cache?.queries).toEqual([]);
-    expect(cache?.resolvers).toEqual([]);
-    expect(cache?.routes).toEqual([]);
-    expect(cache?.workflows).toEqual([]);
-    expect(cache?.graph).toEqual({ events: [] });
-    expect(missingFields).toContain("resolvers");
-    expect(missingFields).toContain("workflows");
-    expect(missingFields).toContain("graph");
-  });
-
-  it("preserves arrays that ARE present", () => {
-    const input = {
-      apps: [{ name: "x", plugins: [] }],
-      actions: [],
-      events: [],
-      actors: [],
-      projections: [],
-      queries: [],
-      resolvers: [{ operation: "Op", version: 1 }],
-      routes: [],
-      workflows: [],
-      externalCalls: [],
-      inboundWebhooks: [],
-      outboxes: [],
-      inboxes: [],
-      crons: [],
-      hooks: [],
-      plugins: [],
-      sinks: [],
-      bindings: [],
-      graph: { events: [] },
-      generatedAt: "2026-05-17T00:00:00Z",
-    };
-    const { cache, missingFields } = normalizeCache(input);
-    expect(cache?.apps).toEqual(input.apps);
-    expect(cache?.resolvers).toEqual(input.resolvers);
-    expect(missingFields).toEqual([]);
-  });
-
-  it("reports the exact list of missing array fields", () => {
-    const { missingFields } = normalizeCache({
-      apps: [],
-      actions: [],
-      events: [],
-      actors: [],
-      projections: [],
-      queries: [],
-      // resolvers + workflows + sinks + graph missing
-      routes: [],
-      externalCalls: [],
-      inboundWebhooks: [],
-      outboxes: [],
-      inboxes: [],
-      crons: [],
-      generatedAt: "2026-05-17T00:00:00Z",
-    });
-    expect([...missingFields].sort()).toEqual([
-      "bindings",
-      "graph",
-      "hooks",
-      "plugins",
-      "resolvers",
-      "sinks",
-      "workflows",
-    ]);
-  });
-
-  it("ignores non-array values masquerading as the field", () => {
-    const { cache, missingFields } = normalizeCache({ resolvers: "not an array" });
-    expect(cache?.resolvers).toEqual([]);
-    expect(missingFields).toContain("resolvers");
-  });
-
-  it("returns null + fatal error when input is not an object", () => {
-    expect(normalizeCache(null).cache).toBeNull();
-    expect(normalizeCache(null).fatalError).toMatch(/not a JSON object/i);
-    expect(normalizeCache([]).cache).toBeNull();
-    expect(normalizeCache("oops").cache).toBeNull();
-    expect(normalizeCache(42).cache).toBeNull();
-  });
-
-  it("synthesises generatedAt when missing", () => {
-    const { cache, missingFields } = normalizeCache({});
-    expect(cache?.generatedAt).toBeTypeOf("string");
-    expect(missingFields).toContain("generatedAt");
-  });
-
-  it("handles graph.events missing while graph exists", () => {
-    const { cache, missingFields } = normalizeCache({ graph: {} });
-    expect(cache?.graph).toEqual({ events: [] });
-    expect(missingFields).toContain("graph.events");
-  });
-});

package/src/lib/cache.ts

@@ -1,312 +0,0 @@
-// Studio data layer — fetch + cache the `.nwire/manifest.json` (built by
-// `nwire cache`). The shape mirrors `@nwire/scan`'s Cache interface but we
-// duplicate it locally so the Studio package doesn't need to depend on
-// scan at runtime (the manifest is just JSON).
-
-import { ref, shallowRef, type Ref } from "vue";
-
-/**
- * `file:line:column` of a `defineX()` call. Studio uses it to render
- * IDE-open chips ("source" pill) next to every primitive.
- */
-export interface SourceLocationEntry {
-  file: string;
-  line: number;
-  column?: number;
-}
-
-export interface ActionEntry {
-  name: string;
-  description?: string;
-  app: string;
-  /** Zod input schema serialized by the scanner. */
-  inputSchema?: unknown;
-  retry?: object;
-  policy?: string | readonly string[];
-  /** True when a handler was wired via defineAction({handler}). */
-  hasInlineHandler: boolean;
-  /** Event names this action emits, in declaration order. */
-  emits: string[];
-  /** True when the action def carries the `.public()` mark. */
-  public?: boolean;
-  persona?: string;
-  journeyStep?: string;
-  capability?: string;
-  slo?: { p95LatencyMs?: number; successRate?: number };
-  tags?: string[];
-  source?: SourceLocationEntry;
-}
-
-export interface ExternalCallEntry {
-  name: string;
-  description?: string;
-  app: string;
-  target?: { provider: string; endpoint: string; region?: string };
-  request?: object;
-  response?: object;
-  hasIdempotencyKey?: boolean;
-  slo?: { p95LatencyMs?: number; successRate?: number };
-  retry?: { max: number; backoff?: string };
-  tags?: string[];
-  source?: SourceLocationEntry;
-}
-
-export interface InboundWebhookEntry {
-  name: string;
-  description?: string;
-  app: string;
-  source?: SourceLocationEntry;
-  path?: string;
-  hasSignatureVerifier?: boolean;
-  dedupe?: { window: string };
-  discriminator?: string;
-  routes?: Record<string, string>;
-  tags?: string[];
-}
-
-export interface OutboxEntry {
-  name: string;
-  description?: string;
-  app: string;
-  publishes?: string[];
-  flushIntervalMs?: number;
-  maxBatch?: number;
-  tags?: string[];
-  source?: SourceLocationEntry;
-}
-
-export interface InboxEntry {
-  name: string;
-  description?: string;
-  app: string;
-  window?: string;
-  on?: string[];
-  tags?: string[];
-  source?: SourceLocationEntry;
-}
-
-export interface CronEntry {
-  name: string;
-  description?: string;
-  app: string;
-  schedule: string;
-  dispatches?: string;
-  timezone?: string;
-  tags?: string[];
-  source?: SourceLocationEntry;
-}
-
-/**
- * Declared workflow (the unified primitive for reactions, translators, and
- * sagas). EventStorming renders each as a synthesized policy node fanning
- * out from its subscribed events to its declared dispatches.
- */
-export interface WorkflowEntry {
-  name: string;
-  app: string;
-  description?: string;
-  /** Event names this workflow listens to. */
-  subscribesTo: string[];
-  /** Action names this workflow dispatches inside its body. */
-  dispatches: string[];
-  /** True when the workflow def carries the `.public()` mark. */
-  public?: boolean;
-  source?: SourceLocationEntry;
-}
-
-export interface EventEntry {
-  name: string;
-  description?: string;
-  app: string;
-  /** True when the event def carries the `.public()` mark — reaches outbound sinks. */
-  public?: boolean;
-  version?: number;
-  audience?: string[];
-  source?: SourceLocationEntry;
-}
-
-export interface ActorEntry {
-  name: string;
-  app: string;
-  /** State names declared in the actor's `states` map. */
-  states: string[];
-  source?: SourceLocationEntry;
-}
-
-export interface ProjectionEntry {
-  name: string;
-  app: string;
-  description?: string;
-  /** Event names this projection folds in. */
-  listens: string[];
-  freshness?: { p95MsBehindStream?: number };
-  source?: SourceLocationEntry;
-}
-
-export interface QueryEntry {
-  name: string;
-  description?: string;
-  app: string;
-  /** Backing projection name (projection-form queries only). */
-  projection?: string;
-  /** True when the query def carries the `.public()` mark. */
-  public?: boolean;
-  slo?: { p95LatencyMs?: number };
-  cacheable?: boolean;
-  source?: SourceLocationEntry;
-}
-
-export interface AppEntry {
-  name: string;
-  description?: string;
-  /** Plugin names installed on this app, in install order. */
-  plugins: string[];
-  tenantModel?: "single" | "per-org" | "per-account" | "per-workspace";
-  tenantKey?: string;
-}
-
-export interface SinkEntry {
-  name: string;
-  app: string;
-  /** Adapter kind tag — "bullmq", "nats", "capture", etc. */
-  kind?: string;
-  position: "early" | "middle" | "terminal";
-  direction: "outbound";
-}
-
-export interface RouteEntry {
-  method: string;
-  path: string;
-  target?: string;
-  targetKind?: "action" | "query" | "resolver";
-  app?: string;
-}
-
-export interface ResolverEntry {
-  operation: string;
-  version: number;
-  status: "draft" | "active" | "deprecated" | "sunset";
-  summary?: string;
-  description?: string;
-  tags?: string[];
-  app: string;
-  bindings: Array<{
-    transport: "rest" | "graphql" | "cli";
-    method?: string;
-    path?: string;
-  }>;
-  params?: object;
-  query?: object;
-  body?: object;
-  returns: Array<{ status: number; kind: "single" | "list" | "empty" }>;
-  errors: Array<{ code: string; status: number }>;
-  successor?: { operation: string; version: number };
-  sunsetDate?: string;
-}
-
-/**
- * One directed edge in the static event graph as emitted by `@nwire/scan`.
- * `from` and `to` are name identifiers (action / event / workflow /
- * projection) per the `via` discriminator. Multiple edges share the
- * same source or target — e.g. one event consumed by N projections
- * shows up as N "folds" edges.
- */
-export interface EventGraphEdge {
-  from: string;
-  to: string;
-  via: "emits" | "folds" | "subscribes" | "dispatches";
-}
-
-export interface HookEntry {
-  id: string;
-  name: string;
-  chain: number;
-  listeners: number;
-  source?: SourceLocationEntry;
-}
-
-export interface PluginEntry {
-  name: string;
-  kind: "plugin" | "module";
-  app: string;
-  source?: SourceLocationEntry;
-}
-
-/**
- * One DI registration on an app's container — surfaced by
- * `container.list()` and emitted by `@nwire/scan` to `.nwire/di.json`.
- * Studio's DI page renders these as a "what's bound + who registered it"
- * table.
- */
-export interface DIBindingEntry {
-  name: string;
-  kind: "singleton" | "transient";
-  app: string;
-  source?: SourceLocationEntry;
-}
-
-export interface Cache {
-  generatedAt: string;
-  apps: AppEntry[];
-  actions: ActionEntry[];
-  events: EventEntry[];
-  actors: ActorEntry[];
-  projections: ProjectionEntry[];
-  queries: QueryEntry[];
-  resolvers: ResolverEntry[];
-  routes: RouteEntry[];
-  workflows: WorkflowEntry[];
-  externalCalls: ExternalCallEntry[];
-  inboundWebhooks: InboundWebhookEntry[];
-  outboxes: OutboxEntry[];
-  inboxes: InboxEntry[];
-  crons: CronEntry[];
-  hooks: HookEntry[];
-  plugins: PluginEntry[];
-  sinks: SinkEntry[];
-  bindings: DIBindingEntry[];
-  graph: { events: EventGraphEdge[] };
-}
-
-import { normalizeCache } from "./normalize-cache";
-
-const cache: Ref<Cache | null> = shallowRef(null);
-const loading = ref(false);
-const error: Ref<string | null> = ref(null);
-/**
- * Fields the cache was missing — non-fatal. Studio renders the affected
- * pages with empty states + shows a "rebuild cache" hint to the operator.
- */
-const missingFields: Ref<readonly string[]> = ref([]);
-
-export function useCache() {
-  if (!cache.value && !loading.value) {
-    void load();
-  }
-  return { cache, loading, error, missingFields, reload: load };
-}
-
-async function load(): Promise<void> {
-  loading.value = true;
-  error.value = null;
-  missingFields.value = [];
-  try {
-    const res = await fetch("/__nwire/manifest.json");
-    if (!res.ok) {
-      error.value = `Cache fetch failed (${res.status}). Run \`nwire cache\` to build it.`;
-      return;
-    }
-    const raw = await res.json();
-    const result = normalizeCache(raw);
-    if (result.fatalError) {
-      error.value = result.fatalError;
-      return;
-    }
-    cache.value = result.cache;
-    missingFields.value = result.missingFields;
-  } catch (e) {
-    error.value = (e as Error).message;
-  } finally {
-    loading.value = false;
-  }
-}