@nwire/studio 0.9.1

package/src/lib/cache.ts

@@ -0,0 +1,334 @@
+// 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;
+  module: string;
+  app: string;
+  schema: object;
+  retry?: object;
+  policy?: string | readonly string[];
+  hasInlineHandler: boolean;
+  emits: string[];
+  /** True when the module's manifest marked this action `.public()`. */
+  public?: boolean;
+  persona?: string;
+  journeyStep?: string;
+  capability?: string;
+  slo?: { p95LatencyMs?: number; successRate?: number };
+  tags?: string[];
+  source?: SourceLocationEntry;
+}
+
+export interface ExternalCallEntry {
+  name: string;
+  description?: string;
+  module: 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[];
+}
+
+export interface InboundWebhookEntry {
+  name: string;
+  description?: string;
+  module: string;
+  app: string;
+  source: string;
+  path: string;
+  hasSignatureVerifier: boolean;
+  dedupe?: { window: string };
+  discriminator: string;
+  routes: Record<string, string>;
+  tags?: string[];
+}
+
+export interface OutboxEntry {
+  name: string;
+  description?: string;
+  module: string;
+  app: string;
+  publishes: string[];
+  flushIntervalMs: number;
+  maxBatch: number;
+  tags?: string[];
+}
+
+export interface InboxEntry {
+  name: string;
+  description?: string;
+  module: string;
+  app: string;
+  window: string;
+  on: string[];
+  tags?: string[];
+}
+
+export interface CronEntry {
+  name: string;
+  description?: string;
+  module: string;
+  app: string;
+  schedule: string;
+  dispatches: string;
+  timezone?: string;
+  tags?: string[];
+}
+
+/**
+ * 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;
+  module: string;
+  app: string;
+  description?: string;
+  subscribesTo: string[];
+  dispatches: string[];
+  /** True when the module's manifest marked this workflow `.public()`. */
+  public?: boolean;
+  source?: SourceLocationEntry;
+}
+
+export interface EventEntry {
+  name: string;
+  description?: string;
+  module: string;
+  app: string;
+  visibility: "public" | "internal";
+  /** True when the module's manifest marked this event `.public()`. */
+  public?: boolean;
+  schema: object;
+  outcome?: "success" | "failure" | "milestone" | "warning";
+  businessWeight?: number;
+  audience?: string[];
+  source?: SourceLocationEntry;
+}
+
+export interface ActorEntry {
+  name: string;
+  module: string;
+  app: string;
+  key: string;
+  initial: string;
+  states: Array<{
+    name: string;
+    final?: boolean;
+    on: Array<{ eventName: string; target?: string }>;
+    after: Array<{ timerName: string; action: string; delay: string }>;
+  }>;
+  methods: string[];
+  schema: object;
+  stuckThresholds?: Record<string, number>;
+  slas?: Record<string, { maxDurationMs: number; escalateTo?: string }>;
+  source?: SourceLocationEntry;
+}
+
+export interface ProjectionEntry {
+  name: string;
+  module: string;
+  app: string;
+  listens: string[];
+  description?: string;
+  freshness?: { p95MsBehindStream?: number };
+  source?: SourceLocationEntry;
+}
+
+export interface QueryEntry {
+  name: string;
+  description?: string;
+  module: string;
+  app: string;
+  projection: string;
+  schema: object;
+  /** True when the module's manifest marked this query `.public()`. */
+  public?: boolean;
+  slo?: { p95LatencyMs?: number };
+  cacheable?: boolean;
+  source?: SourceLocationEntry;
+}
+
+export interface ModuleEntry {
+  name: string;
+  app: string;
+  provides: { events: string[]; actions: string[] };
+  needs: { events: string[]; externalEvents: string[]; actions: string[] };
+  counts: {
+    actions: number;
+    actors: number;
+    projections: number;
+    queries: number;
+    workflows: number;
+    events: number;
+    routes: number;
+  };
+  description?: string;
+  owners?: string[];
+  journey?: { id: string; label: string; description?: string }[];
+  source?: SourceLocationEntry;
+}
+
+export interface AppEntry {
+  name: string;
+  description?: string;
+  modules: string[];
+  tenantModel?: "single" | "per-org" | "per-account" | "per-workspace";
+  tenantKey?: string;
+}
+
+export interface RouteEntry {
+  method: string;
+  path: string;
+  target: string;
+  targetKind: "action" | "query" | "resolver";
+  module: string;
+  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;
+}
+
+export interface EventGraphEdge {
+  event: string;
+  producer: { app: string; module: string };
+  consumers: Array<{
+    app: string;
+    module: string;
+    via: "workflow" | "projection" | "actor" | "external";
+  }>;
+}
+
+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[];
+  modules: ModuleEntry[];
+  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[];
+  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;
+  }
+}

package/src/lib/normalize-cache.ts

@@ -0,0 +1,92 @@
+/**
+ * Cache normalizer — defends Studio against stale or partial
+ * `.nwire/manifest.json` payloads.
+ *
+ * Reality check: the manifest is generated by `@nwire/scan` and its schema
+ * evolves. A Studio served against a manifest built before a given field
+ * exists must not crash — pages that depend on that field should render
+ * an empty state, not a TypeError.
+ *
+ * The normalizer:
+ *   1. Returns `null` if the value isn't an object (Studio renders an error
+ *      banner instead of throwing).
+ *   2. Fills every expected array field with `[]`.
+ *   3. Fills nested shapes (graph.events) with safe defaults.
+ *   4. Reports which fields were missing — surfaced as a warning so the
+ *      operator knows the cache is stale and can rebuild.
+ */
+
+import type { Cache } from "./cache";
+
+export interface NormalizeResult {
+  /** The normalized cache, ready to render. `null` if the input is unusable. */
+  readonly cache: Cache | null;
+  /** Field paths that were missing in the input and filled with defaults. */
+  readonly missingFields: readonly string[];
+  /** Human-readable description of what made the input unusable. */
+  readonly fatalError?: string;
+}
+
+const ARRAY_FIELDS = [
+  "apps",
+  "modules",
+  "actions",
+  "events",
+  "actors",
+  "projections",
+  "queries",
+  "resolvers",
+  "routes",
+  "workflows",
+  "externalCalls",
+  "inboundWebhooks",
+  "outboxes",
+  "inboxes",
+  "crons",
+  "hooks",
+  "plugins",
+  "bindings",
+] as const;
+
+export function normalizeCache(raw: unknown): NormalizeResult {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return {
+      cache: null,
+      missingFields: [],
+      fatalError: "Manifest is not a JSON object.",
+    };
+  }
+
+  const input = raw as Record<string, unknown>;
+  const missing: string[] = [];
+
+  const out: Record<string, unknown> = {
+    generatedAt:
+      typeof input.generatedAt === "string" ? input.generatedAt : new Date(0).toISOString(),
+  };
+  if (typeof input.generatedAt !== "string") missing.push("generatedAt");
+
+  for (const field of ARRAY_FIELDS) {
+    if (Array.isArray(input[field])) {
+      out[field] = input[field];
+    } else {
+      out[field] = [];
+      missing.push(field);
+    }
+  }
+
+  // graph.events — nested arrays
+  const rawGraph = input.graph as { events?: unknown } | undefined;
+  if (rawGraph && typeof rawGraph === "object" && Array.isArray(rawGraph.events)) {
+    out.graph = { events: rawGraph.events };
+  } else {
+    out.graph = { events: [] };
+    if (!rawGraph) missing.push("graph");
+    else missing.push("graph.events");
+  }
+
+  return {
+    cache: out as unknown as Cache,
+    missingFields: missing,
+  };
+}

package/src/lib/project-catalog.ts

@@ -0,0 +1,125 @@
+/**
+ * Project catalog — a localStorage-backed directory of every Nwire project
+ * the user has opened in Studio. Each visit writes a snapshot so the
+ * `/projects` page can list "your projects" with stats even when the
+ * Studio instance for that project isn't currently running.
+ *
+ * Storage key:  `nwire.projects` → Record<cwd, ProjectSnapshot>
+ *
+ * Snapshots are per-cwd so multiple worktrees of the same repo show up
+ * as siblings, which is what a polyrepo dev wants.
+ */
+
+const STORAGE_KEY = "nwire.projects";
+
+/**
+ * What we remember about a project across visits. Everything but `cwd` +
+ * `name` is "best-known so far" — the snapshot the project's own Studio
+ * wrote on its last visit. The catalog page reconciles this against live
+ * status (running processes) fetched server-side from each cwd's
+ * `.nwire/processes/` registry.
+ */
+export interface ProjectSnapshot {
+  readonly cwd: string;
+  readonly name: string;
+  /** ISO timestamp of the last time this project's Studio was open. */
+  readonly lastVisited: string;
+  /** Composition counts from the last manifest seen. Optional — early
+   *  visits before scan finishes may not have them. */
+  readonly composition?: {
+    readonly apps: number;
+    readonly modules: number;
+    readonly actions: number;
+    readonly events: number;
+    readonly resolvers?: number;
+    readonly workflows?: number;
+  };
+}
+
+/** Read every known project. Returns an empty record on first run. */
+export function loadCatalog(): Record<string, ProjectSnapshot> {
+  if (typeof localStorage === "undefined") return {};
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Record<string, ProjectSnapshot>;
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Upsert this Studio's current project. Called on App mount whenever the
+ * `/__nwire/project` + cache fetches resolve. Existing snapshots are
+ * merged so we never lose the old composition during a fresh load.
+ */
+export function upsertCurrent(snapshot: ProjectSnapshot): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    const catalog = loadCatalog();
+    const prior = catalog[snapshot.cwd];
+    catalog[snapshot.cwd] = {
+      ...prior,
+      ...snapshot,
+      // Preserve the prior composition until the new visit produces one.
+      composition: snapshot.composition ?? prior?.composition,
+    };
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(catalog));
+  } catch {
+    // localStorage may be full or disabled; the catalog page just sees
+    // an empty entry next time.
+  }
+}
+
+/**
+ * Active-project state — which catalog entry every fetch is scoped to. Reads
+ * + writes through localStorage so a Studio refresh keeps the same view.
+ * Returns null when no choice has been recorded (caller should default to
+ * the launch-time project from `/__nwire/project`).
+ */
+const ACTIVE_KEY = "nwire.activeProject";
+export function getActiveProjectCwd(): string | null {
+  if (typeof localStorage === "undefined") return null;
+  try {
+    return localStorage.getItem(ACTIVE_KEY);
+  } catch {
+    return null;
+  }
+}
+export function setActiveProjectCwd(cwd: string | null): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    if (cwd) localStorage.setItem(ACTIVE_KEY, cwd);
+    else localStorage.removeItem(ACTIVE_KEY);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * `fetch` wrapper that appends `?project=<cwd>` to every Studio-internal
+ * URL. The server's `targetCwd(req)` reads this and serves the right
+ * project's manifest, scripts, processes, etc. — single-project behavior
+ * is preserved when the active project happens to equal the launch one.
+ *
+ * Pass through `RequestInit` unchanged; we only mutate the URL.
+ */
+export function projectFetch(input: string, init?: RequestInit): Promise<Response> {
+  const cwd = getActiveProjectCwd();
+  if (!cwd) return fetch(input, init);
+  const sep = input.includes("?") ? "&" : "?";
+  return fetch(`${input}${sep}project=${encodeURIComponent(cwd)}`, init);
+}
+
+/** Remove a project from the catalog (Catalog page "Forget" action). */
+export function forgetProject(cwd: string): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    const catalog = loadCatalog();
+    delete catalog[cwd];
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(catalog));
+  } catch {
+    // ignore
+  }
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/main.ts

@@ -0,0 +1,112 @@
+import { createApp } from "vue";
+import { createRouter, createWebHistory } from "vue-router";
+import App from "./App.vue";
+import "./style.css";
+import { getActiveProjectCwd, loadCatalog } from "./lib/project-catalog";
+
+// Multi-project Studio (Shape A) — every Studio-internal URL needs to
+// carry `?project=<cwd>` so the server routes it to the right project's
+// manifest / processes / wire. Wrap `fetch` once at boot rather than
+// touching every call site. Only the `/__nwire/*` and `/_nwire/*` paths
+// are decorated; everything else (Vite HMR, third-party APIs) passes
+// through unchanged.
+const originalFetch = window.fetch.bind(window);
+window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+  const cwd = getActiveProjectCwd();
+  if (!cwd) return originalFetch(input as RequestInfo, init);
+  const url =
+    typeof input === "string"
+      ? input
+      : input instanceof URL
+        ? input.toString()
+        : (input as Request).url;
+  if (!url.startsWith("/__nwire/") && !url.startsWith("/_nwire/")) {
+    return originalFetch(input as RequestInfo, init);
+  }
+  const sep = url.includes("?") ? "&" : "?";
+  const next = `${url}${sep}project=${encodeURIComponent(cwd)}`;
+  return originalFetch(next, init);
+}) as typeof window.fetch;
+
+// EventSource is used for SSE (Run logs, live event stream, trace
+// telemetry). It bypasses fetch, so we patch its constructor to inject
+// the same query param. Same allowlist as the fetch wrapper.
+const OriginalEventSource = window.EventSource;
+class ScopedEventSource extends OriginalEventSource {
+  constructor(url: string | URL, init?: EventSourceInit) {
+    const cwd = getActiveProjectCwd();
+    const str = typeof url === "string" ? url : url.toString();
+    if (cwd && (str.startsWith("/__nwire/") || str.startsWith("/_nwire/"))) {
+      const sep = str.includes("?") ? "&" : "?";
+      super(`${str}${sep}project=${encodeURIComponent(cwd)}`, init);
+    } else {
+      super(url, init);
+    }
+  }
+}
+(window as unknown as { EventSource: typeof OriginalEventSource }).EventSource = ScopedEventSource;
+
+import Home from "./pages/Home.vue";
+import Overview from "./pages/Overview.vue";
+import Topology from "./pages/Topology.vue";
+import Trace from "./pages/Trace.vue";
+import Actions from "./pages/Actions.vue";
+import Events from "./pages/Events.vue";
+import Modules from "./pages/Modules.vue";
+import Workflows from "./pages/Workflows.vue";
+import Hooks from "./pages/Hooks.vue";
+import Plugins from "./pages/Plugins.vue";
+import Live from "./pages/Live.vue";
+import Dispatch from "./pages/Dispatch.vue";
+import Run from "./pages/Run.vue";
+import Commands from "./pages/Commands.vue";
+import Projects from "./pages/Projects.vue";
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: "/", component: Home, name: "home" },
+    { path: "/overview", component: Overview, name: "overview" },
+    { path: "/topology", component: Topology, name: "topology" },
+    { path: "/trace", component: Trace, name: "trace" },
+    // Back-compat redirect — the page formerly known as EventStorm.
+    { path: "/eventstorm", redirect: "/trace" },
+    { path: "/modules", component: Modules, name: "modules" },
+    { path: "/actions", component: Actions, name: "actions" },
+    { path: "/events", component: Events, name: "events" },
+    { path: "/workflows", component: Workflows, name: "workflows" },
+    { path: "/hooks", component: Hooks, name: "hooks" },
+    { path: "/plugins", component: Plugins, name: "plugins" },
+    { path: "/dispatch", component: Dispatch, name: "dispatch" },
+    { path: "/live", component: Live, name: "live" },
+    { path: "/run", component: Run, name: "run" },
+    { path: "/commands", component: Commands, name: "commands" },
+    { path: "/projects", component: Projects, name: "projects" },
+  ],
+});
+
+/**
+ * Register every catalog cwd with the running Studio process BEFORE mounting
+ * Vue. The fetch shim above appends `?project=<cwd>` to every nwire request,
+ * and the server's allowlist only includes `NWIRE_CWD` by default — so the
+ * first cache fetch from useCache() would 400 without this hand-shake.
+ */
+async function bootstrap() {
+  const catalog = loadCatalog();
+  const cwds = Object.keys(catalog);
+  const active = getActiveProjectCwd();
+  if (active && !cwds.includes(active)) cwds.push(active);
+  await Promise.all(
+    cwds.map((cwd) =>
+      originalFetch("/__nwire/projects/register", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ cwd }),
+      }).catch(() => {
+        /* stale localStorage entry — server rejects; catalog page lets user forget */
+      }),
+    ),
+  );
+  createApp(App).use(router).mount("#app");
+}
+void bootstrap();