@nwire/studio 0.12.1 → 0.13.0

package/src/composables/useLogTail.ts

@@ -0,0 +1,51 @@
+/**
+ * `useLogTail` — tail a managed process's stdout/stderr over SSE.
+ *
+ * Watches a process-id ref; (re)opens `/__nwire/run/logs/:id/stream` whenever it
+ * changes, parses each `LogLine`, and keeps a bounded buffer. The scoped
+ * `EventSource` (patched in main.ts) carries `?project=`; SSE reconnects on
+ * drop natively. Shared by the Run + Commands panels so the streaming logic
+ * lives in one place.
+ */
+import { ref, watch, onUnmounted, toValue, type MaybeRefOrGetter } from "vue";
+import type { LogLine } from "@/lib/operate";
+
+const MAX_LINES = 5000;
+
+export function useLogTail(id: MaybeRefOrGetter<string | null | undefined>) {
+  const logs = ref<LogLine[]>([]);
+  let es: EventSource | null = null;
+
+  function close(): void {
+    es?.close();
+    es = null;
+  }
+
+  function clear(): void {
+    logs.value = [];
+  }
+
+  function connect(target: string | null | undefined): void {
+    close();
+    clear();
+    if (!target) return;
+    es = new EventSource(`/__nwire/run/logs/${encodeURIComponent(target)}/stream`);
+    es.onmessage = (msg) => {
+      try {
+        const line = JSON.parse(msg.data) as LogLine;
+        const next =
+          logs.value.length >= MAX_LINES ? logs.value.slice(-(MAX_LINES - 1)) : logs.value.slice();
+        next.push(line);
+        logs.value = next;
+      } catch {
+        /* keepalive comment / non-JSON frame — ignore */
+      }
+    };
+    // EventSource auto-reconnects on error; nothing to do.
+  }
+
+  watch(() => toValue(id), connect, { immediate: true });
+  onUnmounted(close);
+
+  return { logs, clear };
+}

package/src/composables/useManifest.ts

@@ -0,0 +1,43 @@
+/**
+ * `useManifest` — the structure feed. Fetches `.nwire/manifest.json` (the deep
+ * manifest) via TanStack Query and exposes a tolerant native view. Re-keys per
+ * project so a switch refetches.
+ */
+import { computed, toValue, type MaybeRefOrGetter } from "vue";
+import { useQuery } from "@tanstack/vue-query";
+import { manifestView, type Manifest, type ManifestView } from "../lib/manifest";
+
+const MANIFEST_URL = "/__nwire/manifest.json";
+
+export function useManifest(project?: MaybeRefOrGetter<string | undefined | null>) {
+  const key = computed(() => ["manifest", toValue(project) ?? "active"] as const);
+
+  const query = useQuery({
+    queryKey: key,
+    queryFn: async (): Promise<Manifest> => {
+      // The global fetch shim appends `?project=<active cwd>`.
+      const res = await fetch(MANIFEST_URL);
+      if (!res.ok) {
+        throw new Error(`Manifest fetch failed (${res.status}). Run \`nwire cache\` to build it.`);
+      }
+      return (await res.json()) as Manifest;
+    },
+    staleTime: 5_000,
+    // keepPreviousData: smooth refresh, no flash while a refetch is in flight.
+    placeholderData: (prev) => prev,
+  });
+
+  const view = computed<ManifestView | null>(() =>
+    query.data.value ? manifestView(query.data.value) : null,
+  );
+
+  return {
+    manifest: query.data,
+    view,
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+    isError: query.isError,
+    error: computed(() => (query.error.value as Error | null)?.message ?? null),
+    refetch: query.refetch,
+  };
+}

package/src/composables/useProcesses.ts

@@ -0,0 +1,114 @@
+/**
+ * `useProcesses` — the supervisor's managed-process list + lifecycle.
+ *
+ * Polls `/__nwire/run/processes` and exposes start/stop/forget plus the two
+ * launch verbs (topology `start`, package-script `exec-script`, CLI `exec`).
+ * Shared by the Run + Commands panels; the optional `filter` narrows the list
+ * (Commands only shows `nwire …` processes it launched).
+ */
+import { ref, onMounted, onUnmounted } from "vue";
+import type { ManagedProcess } from "@/lib/operate";
+
+interface Options {
+  /** Narrow the polled list (e.g. only CLI processes). */
+  filter?: (p: ManagedProcess) => boolean;
+  /** Poll cadence in ms. Default 2000. */
+  intervalMs?: number;
+}
+
+export function useProcesses(options: Options = {}) {
+  const { filter, intervalMs = 2000 } = options;
+  const processes = ref<ManagedProcess[]>([]);
+  const error = ref<string | null>(null);
+  let poll: ReturnType<typeof setInterval> | null = null;
+
+  async function load(): Promise<void> {
+    try {
+      const res = await fetch("/__nwire/run/processes");
+      const body = (await res.json()) as { processes: ManagedProcess[] };
+      processes.value = filter ? body.processes.filter(filter) : body.processes;
+    } catch {
+      /* transient — keep the last good list */
+    }
+  }
+
+  async function start(payload: {
+    topology: string;
+    port?: number;
+    env?: Record<string, string>;
+  }): Promise<ManagedProcess | null> {
+    return launch("/__nwire/run/start", payload);
+  }
+
+  async function execScript(payload: {
+    script: string;
+    port?: number;
+    env?: Record<string, string>;
+  }): Promise<ManagedProcess | null> {
+    return launch("/__nwire/run/exec-script", payload);
+  }
+
+  async function exec(command: string, args: string[] = []): Promise<ManagedProcess | null> {
+    return launch("/__nwire/run/exec", { command, args });
+  }
+
+  async function launch(url: string, body: unknown): Promise<ManagedProcess | null> {
+    error.value = null;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      const data = (await res.json()) as {
+        process?: ManagedProcess;
+        error?: string;
+      };
+      if (!res.ok) {
+        error.value = data.error ?? `request failed (${res.status})`;
+        return null;
+      }
+      if (data.process) {
+        processes.value = [...processes.value, data.process];
+        return data.process;
+      }
+      await load();
+      return null;
+    } catch (err) {
+      error.value = (err as Error).message;
+      return null;
+    }
+  }
+
+  async function stop(id: string): Promise<void> {
+    try {
+      await fetch(`/__nwire/run/stop/${encodeURIComponent(id)}`, {
+        method: "POST",
+      });
+    } catch {
+      /* ignore */
+    }
+    await load();
+  }
+
+  async function forget(id: string): Promise<void> {
+    try {
+      await fetch(`/__nwire/run/forget/${encodeURIComponent(id)}`, {
+        method: "POST",
+      });
+    } catch {
+      /* ignore */
+    }
+    await load();
+  }
+
+  onMounted(() => {
+    void load();
+    poll = setInterval(load, intervalMs);
+  });
+  onUnmounted(() => {
+    if (poll) clearInterval(poll);
+  });
+
+  return { processes, error, load, start, execScript, exec, stop, forget };
+}

package/src/composables/useProject.ts

@@ -0,0 +1,34 @@
+/**
+ * `useProject` — the active project + a smooth switch. Switching sets the
+ * active cwd (the fetch/EventSource shim scopes to it) and invalidates the
+ * per-project queries so they refetch — no hard page reload.
+ */
+import { computed, ref } from "vue";
+import { useQueryClient } from "@tanstack/vue-query";
+import { getActiveProjectCwd, setActiveProjectCwd, loadCatalog } from "../lib/project-catalog";
+
+export function useProject() {
+  // useQueryClient throws without a provider (e.g. a bare unit test); tolerate it.
+  let queryClient: ReturnType<typeof useQueryClient> | undefined;
+  try {
+    queryClient = useQueryClient();
+  } catch {
+    queryClient = undefined;
+  }
+
+  const activeCwd = ref<string | null>(getActiveProjectCwd());
+  const activeName = computed(() => {
+    const cwd = activeCwd.value;
+    if (!cwd) return null;
+    return loadCatalog()[cwd]?.name ?? cwd;
+  });
+
+  function switchTo(cwd: string | null): void {
+    setActiveProjectCwd(cwd);
+    activeCwd.value = cwd;
+    // Refetch everything against the new active cwd — no reload.
+    void queryClient?.invalidateQueries();
+  }
+
+  return { activeCwd, activeName, switchTo };
+}

package/src/composables/useTelemetry.ts

@@ -0,0 +1,270 @@
+/**
+ * `useTelemetry` — the behavior feed.
+ *
+ * Two modes:
+ *
+ *   LIVE   — holds an SSE connection to `/__nwire/telemetry/live`, which tails
+ *             the current (newest) run file and streams appended records.
+ *             A `run` event from the server backfills the current run on open.
+ *
+ *   HISTORY — fetches a chosen past run's records once via
+ *             `/__nwire/telemetry/runs/:id` and loads them as a static snapshot.
+ *
+ * Switching modes (`source`) clears the buffer and reconnects. Both modes share
+ * the same typed-record parsing/grouping/tree helpers from `../lib/telemetry`.
+ *
+ * Side-effecting (EventSource + fetch) but DI'd: tests inject a fake
+ * EventSource factory + fetch. The pure parsing/grouping/tree live in
+ * `../lib/telemetry`.
+ */
+import {
+  computed,
+  ref,
+  shallowRef,
+  onScopeDispose,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+} from "vue";
+import {
+  parseRecord,
+  groupByCorrelation,
+  buildCorrelationTree,
+  isFailure,
+  type TelemetryRecord,
+} from "../lib/telemetry";
+
+/** The SSE tail of the current (newest) run file. */
+const LIVE_URL = "/__nwire/telemetry/live";
+/** Run list: returns { runs: TelemetryRunMeta[] }. */
+export const RUNS_URL = "/__nwire/telemetry/runs";
+
+/** A past run as returned by GET /__nwire/telemetry/runs. */
+export interface TelemetryRunMeta {
+  readonly id: string;
+  readonly size: number;
+  readonly mtime: string;
+}
+
+/**
+ * The data source for useTelemetry.
+ *   "live"   — stream the current run via SSE.
+ *   run meta — load a specific past run as a static snapshot.
+ */
+export type TelemetrySource = "live" | TelemetryRunMeta;
+
+/** Minimal EventSource surface we depend on — lets tests inject a fake. */
+export interface EventSourceLike {
+  onmessage: ((ev: { data: string }) => void) | null;
+  onerror: ((ev?: unknown) => void) | null;
+  onopen: ((ev?: unknown) => void) | null;
+  /** Listen for named events (e.g. the `run` meta event). */
+  addEventListener?(type: string, listener: (ev: { data: string }) => void): void;
+  close(): void;
+}
+
+export type ConnectionStatus = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+
+export interface UseTelemetryOptions {
+  /** Ring-buffer cap. Default 1000. */
+  readonly limit?: number;
+  /** Connect immediately. Default true. */
+  readonly autoConnect?: boolean;
+  /** Inject an EventSource (tests). Default `new EventSource(url)`. */
+  readonly eventSourceFactory?: (url: string) => EventSourceLike;
+  /** Inject fetch (tests). Default global `fetch`. */
+  readonly fetchFn?: typeof fetch;
+  /** Reconnect backoff in ms (live mode only). Default 1500. */
+  readonly reconnectMs?: number;
+}
+
+export function useTelemetry(
+  project?: MaybeRefOrGetter<string | undefined | null>,
+  options: UseTelemetryOptions = {},
+) {
+  const limit = options.limit ?? 1000;
+  const reconnectMs = options.reconnectMs ?? 1500;
+  const makeSource =
+    options.eventSourceFactory ?? ((url) => new EventSource(url) as EventSourceLike);
+  const doFetch = options.fetchFn ?? ((...a: Parameters<typeof fetch>) => fetch(...a));
+
+  const records = shallowRef<TelemetryRecord[]>([]);
+  const status = ref<ConnectionStatus>("idle");
+  /** The run id that the live SSE stream is tailing (null when none/history). */
+  const currentRunId = ref<string | null>(null);
+  /**
+   * The active source. "live" = streaming; a TelemetryRunMeta = past run
+   * snapshot. Callers set this to switch modes.
+   */
+  const source = ref<TelemetrySource>("live");
+
+  let es: EventSourceLike | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+
+  function push(rec: TelemetryRecord): void {
+    const next = records.value.concat(rec);
+    records.value = next.length > limit ? next.slice(next.length - limit) : next;
+  }
+
+  function clear(): void {
+    records.value = [];
+    currentRunId.value = null;
+  }
+
+  // ── HISTORY mode ────────────────────────────────────────────────────────
+
+  async function loadRun(run: TelemetryRunMeta): Promise<void> {
+    status.value = "connecting";
+    try {
+      const url = `${RUNS_URL}/${encodeURIComponent(run.id)}`;
+      const res = await doFetch(url);
+      if (!res.ok) {
+        status.value = "closed";
+        return;
+      }
+      const body = (await res.json()) as { records?: unknown[] };
+      const parsed = (body.records ?? [])
+        .map(parseRecord)
+        .filter((r): r is TelemetryRecord => r !== null);
+      records.value = parsed.slice(-limit);
+      currentRunId.value = run.id;
+      status.value = "open";
+    } catch {
+      status.value = "closed";
+    }
+  }
+
+  // ── LIVE mode ────────────────────────────────────────────────────────────
+
+  function openLive(): void {
+    if (disposed) return;
+    status.value = status.value === "open" ? "reconnecting" : "connecting";
+    const src = makeSource(LIVE_URL);
+    es = src;
+
+    // The server emits a `run` event with the current run meta.
+    src.addEventListener?.("run", (ev) => {
+      try {
+        const meta = JSON.parse(ev.data) as TelemetryRunMeta | null;
+        currentRunId.value = meta?.id ?? null;
+      } catch {
+        // ignore
+      }
+    });
+
+    src.onopen = () => {
+      status.value = "open";
+    };
+    src.onmessage = (ev) => {
+      // Default `message` events carry telemetry records (backfill + live).
+      const rec = parseRecord(ev.data);
+      if (rec) push(rec);
+    };
+    src.onerror = () => {
+      if (disposed) return;
+      status.value = "reconnecting";
+      src.close();
+      es = null;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      reconnectTimer = setTimeout(() => openLive(), reconnectMs);
+    };
+  }
+
+  // ── Public connect/disconnect ─────────────────────────────────────────────
+
+  function connect(): void {
+    if (disposed) return;
+    clear();
+    const s = source.value;
+    if (s === "live") {
+      if (es) return; // already connected
+      openLive();
+    } else {
+      void loadRun(s);
+    }
+  }
+
+  function disconnect(): void {
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+    es?.close();
+    es = null;
+    status.value = "closed";
+  }
+
+  // Re-key on project change or source change: drop everything + reconnect.
+  watch([() => toValue(project), source], () => {
+    if (disposed) return;
+    disconnect();
+    clear();
+    disposed = false;
+    connect();
+  });
+
+  if (options.autoConnect !== false) connect();
+
+  onScopeDispose(() => {
+    disposed = true;
+    disconnect();
+  });
+
+  const byCorrelation = computed(() => groupByCorrelation(records.value));
+  const tree = computed(() => buildCorrelationTree(records.value));
+  const failures = computed(() => records.value.filter(isFailure));
+
+  return {
+    records,
+    status,
+    /** The run id currently being tailed (live) or viewed (history). */
+    currentRunId,
+    /** The active source — set to "live" or a TelemetryRunMeta to switch. */
+    source,
+    byCorrelation,
+    tree,
+    failures,
+    recent: (kind?: string) =>
+      kind ? records.value.filter((r) => r.kind === kind) : records.value,
+    connect,
+    disconnect,
+    clear,
+  };
+}
+
+/**
+ * `useRunList` — reactive list of past telemetry runs for the given project.
+ * Fetches once on mount; call `refresh()` to reload.
+ */
+export function useRunList(
+  project?: MaybeRefOrGetter<string | undefined | null>,
+  options: { fetchFn?: typeof fetch } = {},
+) {
+  const doFetch = options.fetchFn ?? ((...a: Parameters<typeof fetch>) => fetch(...a));
+  const runs = ref<TelemetryRunMeta[]>([]);
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+
+  async function refresh(): Promise<void> {
+    loading.value = true;
+    error.value = null;
+    try {
+      const proj = toValue(project);
+      const url = proj ? `${RUNS_URL}?project=${encodeURIComponent(proj)}` : RUNS_URL;
+      const res = await doFetch(url);
+      if (!res.ok) {
+        error.value = `Failed to load runs (${res.status})`;
+        return;
+      }
+      const body = (await res.json()) as { runs?: TelemetryRunMeta[] };
+      runs.value = body.runs ?? [];
+    } catch (err) {
+      error.value = (err as Error).message;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  watch(() => toValue(project), refresh, { immediate: true });
+
+  return { runs, loading, error, refresh };
+}