@nwire/studio 0.12.1 → 0.13.1

package/src/components/LiveTable.vue

@@ -0,0 +1,186 @@
+<script setup lang="ts">
+/**
+ * `LiveTable` — the telemetry firehose as a keyboard-navigable, sortable table.
+ * Presentational + behavioral: it renders the rows it's handed (already
+ * filtered by the page), colours each by kind, sorts on header click, and
+ * drives selection with ↑/↓/Enter. All data math lives in `lib/live-table`.
+ *
+ *   <LiveTable :rows="rows" v-model:selectedIndex="i" @select="open" />
+ */
+import { computed, ref, watch } from "vue";
+import { ChevronUp, ChevronDown } from "lucide-vue-next";
+import type { TelemetryRecord } from "@/lib/telemetry";
+import {
+  recordSubject,
+  recordDuration,
+  recordTime,
+  sortRecords,
+  nextIndex,
+  shortId,
+  type SortKey,
+  type SortDir,
+} from "@/lib/live-table";
+import { kindColor, recordColorKey } from "@/lib/kind-colors";
+
+const props = withDefaults(
+  defineProps<{
+    rows: readonly TelemetryRecord[];
+    selectedIndex?: number;
+    /** Initial sort column. Default `time`. */
+    sortKey?: SortKey;
+    /** Initial sort direction. Default `desc` (newest first). */
+    sortDir?: SortDir;
+  }>(),
+  { selectedIndex: -1, sortKey: "time", sortDir: "desc" },
+);
+
+const emit = defineEmits<{
+  "update:selectedIndex": [index: number];
+  select: [record: TelemetryRecord, index: number];
+}>();
+
+const sortKey = ref<SortKey>(props.sortKey);
+const sortDir = ref<SortDir>(props.sortDir);
+
+const sorted = computed(() => sortRecords(props.rows, sortKey.value, sortDir.value));
+
+function toggleSort(key: SortKey): void {
+  if (sortKey.value === key) {
+    sortDir.value = sortDir.value === "asc" ? "desc" : "asc";
+  } else {
+    sortKey.value = key;
+    sortDir.value = key === "subject" || key === "kind" ? "asc" : "desc";
+  }
+}
+
+function move(delta: number): void {
+  const i = nextIndex(props.selectedIndex, sorted.value.length, delta);
+  emit("update:selectedIndex", i);
+}
+
+function onKeydown(e: KeyboardEvent): void {
+  if (e.key === "ArrowDown") {
+    e.preventDefault();
+    move(1);
+  } else if (e.key === "ArrowUp") {
+    e.preventDefault();
+    move(-1);
+  } else if (e.key === "Enter") {
+    const r = sorted.value[props.selectedIndex];
+    if (r) emit("select", r, props.selectedIndex);
+  }
+}
+
+function choose(r: TelemetryRecord, i: number): void {
+  emit("update:selectedIndex", i);
+  emit("select", r, i);
+}
+
+function timeLabel(r: TelemetryRecord): string {
+  const t = recordTime(r);
+  return t > 0 ? new Date(t).toLocaleTimeString() : "—";
+}
+
+function durationLabel(r: TelemetryRecord): string {
+  const d = recordDuration(r);
+  return d === undefined ? "" : `${Math.round(d)}ms`;
+}
+
+// Keep the selected row in view as the selection moves by keyboard.
+const rowEls = ref<HTMLElement[]>([]);
+watch(
+  () => props.selectedIndex,
+  (i) => {
+    rowEls.value[i]?.scrollIntoView({ block: "nearest" });
+  },
+);
+
+const columns: { key: SortKey; label: string; align?: string }[] = [
+  { key: "time", label: "Time" },
+  { key: "kind", label: "Kind" },
+  { key: "subject", label: "Subject" },
+  { key: "duration", label: "Duration", align: "text-right" },
+];
+</script>
+
+<template>
+  <div
+    class="h-full overflow-auto outline-none focus:ring-1 focus:ring-zinc-700 rounded"
+    tabindex="0"
+    role="grid"
+    data-testid="live-table"
+    @keydown="onKeydown"
+  >
+    <table class="w-full text-sm border-collapse">
+      <thead class="sticky top-0 z-10 bg-zinc-950">
+        <tr class="border-b border-zinc-800 text-left">
+          <th
+            v-for="col in columns"
+            :key="col.key"
+            class="px-3 py-2 text-[10px] uppercase tracking-wider text-zinc-500 font-medium cursor-pointer select-none hover:text-zinc-300"
+            :class="col.align"
+            :data-testid="`col-${col.key}`"
+            @click="toggleSort(col.key)"
+          >
+            <span class="inline-flex items-center gap-1">
+              {{ col.label }}
+              <component
+                :is="sortDir === 'asc' ? ChevronUp : ChevronDown"
+                v-if="sortKey === col.key"
+                class="w-3 h-3"
+              />
+            </span>
+          </th>
+          <th class="px-3 py-2 text-[10px] uppercase tracking-wider text-zinc-500 font-medium">
+            Correlation
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr
+          v-for="(r, i) in sorted"
+          :key="i"
+          :ref="
+            (el) => {
+              if (el) rowEls[i] = el as HTMLElement;
+            }
+          "
+          class="border-b border-zinc-900 cursor-pointer transition-colors"
+          :class="i === selectedIndex ? 'bg-zinc-900/80' : 'hover:bg-zinc-900/40'"
+          :aria-selected="i === selectedIndex"
+          role="row"
+          data-testid="live-row"
+          @click="choose(r, i)"
+        >
+          <td class="px-3 py-1.5 text-[11px] text-zinc-500 tabular-nums whitespace-nowrap">
+            {{ timeLabel(r) }}
+          </td>
+          <td class="px-3 py-1.5 whitespace-nowrap">
+            <span
+              class="inline-flex items-center gap-1.5 font-mono text-[11px]"
+              data-testid="row-kind"
+            >
+              <span
+                class="inline-block w-2 h-2 rounded-full shrink-0"
+                :style="{ backgroundColor: kindColor(recordColorKey(r.kind)) }"
+              />
+              {{ r.kind }}
+            </span>
+          </td>
+          <td class="px-3 py-1.5 font-mono text-[12px] text-zinc-200 max-w-[22rem] truncate">
+            {{ recordSubject(r) }}
+            <span v-if="r.appName" class="text-zinc-600 text-[10px] ml-1">{{ r.appName }}</span>
+          </td>
+          <td
+            class="px-3 py-1.5 text-right text-[11px] text-zinc-400 tabular-nums whitespace-nowrap"
+          >
+            {{ durationLabel(r) }}
+          </td>
+          <td class="px-3 py-1.5 font-mono text-[10px] text-zinc-600 whitespace-nowrap">
+            {{ shortId(r.envelope?.correlationId) }}
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</template>

package/src/components/MetadataInspector.stories.ts

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+import { expect, within } from "storybook/test";
+import MetadataInspector from "./MetadataInspector.vue";
+
+const meta: Meta<typeof MetadataInspector> = {
+  title: "Flow/MetadataInspector",
+  component: MetadataInspector,
+  tags: ["autodocs"],
+};
+export default meta;
+
+type Story = StoryObj<typeof MetadataInspector>;
+
+export const Span: Story = {
+  args: {
+    label: "Span · action.completed",
+    data: {
+      kind: "action.completed",
+      durationMs: 12.4,
+      envelope: {
+        messageId: "m-1a2b",
+        correlationId: "c-9f8e",
+        causationId: "m-1a2b",
+        tenant: "acme",
+        userId: "u-42",
+      },
+      input: { authorId: "demo", body: "hello world", flagged: false },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement);
+    await expect(c.getAllByTestId("meta-row").length).toBeGreaterThan(3);
+    await expect(c.getByText("envelope.correlationId")).toBeInTheDocument();
+  },
+};
+
+export const Failure: Story = {
+  args: {
+    label: "Span · action.failed",
+    data: {
+      kind: "action.failed",
+      error: { name: "PaymentDeclined", message: "card declined", code: 402 },
+      envelope: { messageId: "m-7", correlationId: "c-9f8e", causationId: "m-1a2b" },
+    },
+  },
+};
+
+export const Empty: Story = {
+  args: { label: "Span", data: {} },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByTestId("meta-empty")).toBeInTheDocument();
+  },
+};

package/src/components/MetadataInspector.vue

@@ -0,0 +1,105 @@
+<script setup lang="ts">
+/**
+ * `MetadataInspector` — a flat, copyable view of a nested record. Flattens the
+ * value to dot-notation `key → value` rows (via `flattenMetadata`), colours each
+ * value by type, copies a single value on row-click, and copies the whole thing
+ * as JSON from the header. Used in the trace inspector for the selected span's
+ * envelope / payload / error.
+ *
+ *   <MetadataInspector :data="record" label="Span" />
+ */
+import { computed, ref } from "vue";
+import { Copy, Check } from "lucide-vue-next";
+import { flattenMetadata, type MetaEntry } from "@/lib/metadata";
+
+const props = withDefaults(
+  defineProps<{
+    /** Any value — object, array, or primitive. */
+    data: unknown;
+    /** Optional heading. */
+    label?: string;
+  }>(),
+  { label: undefined },
+);
+
+const entries = computed<MetaEntry[]>(() => flattenMetadata(props.data));
+const copied = ref<string | null>(null);
+
+async function copy(text: string, key: string): Promise<void> {
+  try {
+    await navigator.clipboard?.writeText(text);
+    copied.value = key;
+    setTimeout(() => {
+      if (copied.value === key) copied.value = null;
+    }, 1200);
+  } catch {
+    /* clipboard unavailable (or denied) — copy is best-effort */
+  }
+}
+
+const valueClass: Record<MetaEntry["type"], string> = {
+  string: "text-amber-200",
+  number: "text-sky-300",
+  boolean: "text-violet-300",
+  null: "text-zinc-500 italic",
+};
+
+function display(e: MetaEntry): string {
+  return e.value === null ? "null" : String(e.value);
+}
+</script>
+
+<template>
+  <div class="flex flex-col min-h-0" data-testid="metadata-inspector">
+    <div v-if="label" class="flex items-center justify-between px-3 py-2 border-b border-zinc-800">
+      <h3 class="text-[10px] uppercase tracking-wide text-zinc-500">{{ label }}</h3>
+      <button
+        class="inline-flex items-center gap-1 text-[10px] text-zinc-500 hover:text-zinc-300"
+        data-testid="meta-copy-all"
+        title="Copy as JSON"
+        @click="copy(JSON.stringify(data, null, 2), '__all__')"
+      >
+        <component :is="copied === '__all__' ? Check : Copy" class="w-3 h-3" />
+        JSON
+      </button>
+    </div>
+
+    <div
+      v-if="entries.length === 0"
+      class="px-3 py-4 text-xs text-zinc-600 italic"
+      data-testid="meta-empty"
+    >
+      No metadata.
+    </div>
+
+    <ul v-else class="overflow-auto divide-y divide-zinc-900/70">
+      <li
+        v-for="e in entries"
+        :key="e.path"
+        class="group flex items-baseline gap-2 px-3 py-1 hover:bg-zinc-900/50 cursor-pointer"
+        data-testid="meta-row"
+        :title="`Copy ${e.path}`"
+        @click="copy(display(e), e.path)"
+      >
+        <span
+          class="font-mono text-[11px] text-zinc-500 shrink-0 max-w-[45%] truncate"
+          data-testid="meta-key"
+        >
+          {{ e.path }}
+        </span>
+        <span
+          class="font-mono text-[11px] break-all"
+          :class="valueClass[e.type]"
+          data-testid="meta-value"
+        >
+          {{ display(e) }}
+        </span>
+        <component
+          :is="copied === e.path ? Check : Copy"
+          class="w-3 h-3 ml-auto shrink-0 self-center opacity-0 group-hover:opacity-100"
+          :class="copied === e.path ? 'text-emerald-400' : 'text-zinc-600'"
+        />
+      </li>
+    </ul>
+  </div>
+</template>

package/src/components/NodeCard.stories.ts

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+import NodeCard from "./NodeCard.vue";
+import type { BcNodeDetail } from "@/lib/bc-graph";
+
+const detail: BcNodeDetail = {
+  id: "action:orders.place",
+  kind: "action",
+  name: "orders.place",
+  app: "orders",
+  description: "An authenticated customer places an order from their cart.",
+  public: true,
+  source: { file: "/examples/orders/app/actions.ts", line: 40, column: 6 },
+  schema: {
+    type: "object",
+    properties: { cartId: { type: "string" }, total: { type: "number" } },
+    required: ["cartId"],
+  },
+  emits: ["orders.placed"],
+  extra: { retry: 3 },
+};
+
+const meta: Meta<typeof NodeCard> = {
+  title: "Map/NodeCard",
+  component: NodeCard,
+  tags: ["autodocs"],
+};
+export default meta;
+
+type Story = StoryObj<typeof NodeCard>;
+
+export const Action: Story = {
+  render: () => ({
+    components: { NodeCard },
+    setup: () => ({ detail }),
+    template: `<div class="h-[480px] w-[360px] bg-zinc-950 border border-zinc-800"><NodeCard :detail="detail" /></div>`,
+  }),
+};
+
+export const Empty: Story = {
+  render: () => ({
+    components: { NodeCard },
+    template: `<div class="h-[480px] w-[360px] bg-zinc-950 border border-zinc-800"><NodeCard :detail="null" /></div>`,
+  }),
+};

package/src/components/NodeCard.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+/**
+ * `NodeCard` — the Map's detail panel for a selected primitive. Leads with
+ * intent (kind, name, description, visibility), then the concrete surface:
+ * input schema, emitted events, `file:line` source, and any remaining
+ * kind-specific fields. Pure presentational — it takes a resolved
+ * `BcNodeDetail` and emits navigation intents.
+ */
+import { computed } from "vue";
+import { Globe, Lock } from "lucide-vue-next";
+import type { BcNodeDetail } from "@/lib/bc-graph";
+import { kindColor } from "@/lib/kind-colors";
+import KindBadge from "./KindBadge.vue";
+import SchemaTree from "./SchemaTree.vue";
+import JsonView from "./JsonView.vue";
+import SourcePill from "./SourcePill.vue";
+
+const props = defineProps<{ detail: BcNodeDetail | null }>();
+
+const emit = defineEmits<{
+  (e: "open-source", source: NonNullable<BcNodeDetail["source"]>): void;
+  (e: "select-event", name: string): void;
+}>();
+
+const hasExtra = computed(() => props.detail != null && Object.keys(props.detail.extra).length > 0);
+
+/** Show a config module from its `config/` segment down — drop the absolute prefix. */
+function configFileLabel(file: string): string {
+  const i = file.search(/(^|[/\\])config[/\\]/);
+  return i === -1 ? file : file.slice(i).replace(/^[/\\]/, "");
+}
+</script>
+
+<template>
+  <div v-if="detail" class="flex flex-col h-full" data-testid="node-card">
+    <div class="px-4 py-3 border-b border-zinc-800">
+      <div class="flex items-center gap-2">
+        <span
+          class="h-2.5 w-2.5 rounded-full shrink-0"
+          :style="{ background: kindColor(detail.kind) }"
+        />
+        <KindBadge>{{ detail.kind }}</KindBadge>
+        <component
+          :is="detail.public ? Globe : Lock"
+          class="w-3.5 h-3.5 shrink-0"
+          :class="detail.public ? 'text-emerald-500' : 'text-zinc-600'"
+          :data-testid="detail.public ? 'node-public' : 'node-private'"
+        />
+      </div>
+      <div class="mt-1.5 font-mono text-sm text-zinc-100 break-all">{{ detail.name }}</div>
+      <div v-if="detail.app" class="text-[11px] text-zinc-500">{{ detail.app }}</div>
+    </div>
+
+    <div class="flex-1 overflow-y-auto p-4 space-y-4">
+      <p v-if="detail.description" class="text-sm text-zinc-300 leading-relaxed">
+        {{ detail.description }}
+      </p>
+
+      <SchemaTree v-if="detail.schema" :schema="detail.schema" label="Input schema" />
+
+      <div v-if="detail.emits?.length" class="space-y-1.5">
+        <h3 class="text-xs uppercase tracking-wide text-zinc-500">Emits</h3>
+        <div class="flex flex-wrap gap-1.5">
+          <button
+            v-for="ev in detail.emits"
+            :key="ev"
+            type="button"
+            class="font-mono text-[11px] px-2 py-0.5 rounded border border-zinc-800 bg-zinc-900 text-zinc-300 hover:border-zinc-700"
+            :data-testid="`emits-${ev}`"
+            @click="emit('select-event', ev)"
+          >
+            {{ ev }}
+          </button>
+        </div>
+      </div>
+
+      <div v-if="detail.invariants?.length" class="space-y-1.5" data-testid="business-rules">
+        <h3 class="text-xs uppercase tracking-wide text-zinc-500">Business rules</h3>
+        <ul class="space-y-2">
+          <li
+            v-for="(inv, i) in detail.invariants"
+            :key="i"
+            class="rounded border border-zinc-800 bg-zinc-900/60 px-2.5 py-2"
+          >
+            <p v-if="inv.message" class="text-sm text-zinc-200 leading-snug">{{ inv.message }}</p>
+            <p v-else class="text-sm italic text-zinc-500 leading-snug">
+              (rule with no stated message)
+            </p>
+            <code class="mt-1 block font-mono text-[11px] text-zinc-500 break-all">{{
+              inv.rule
+            }}</code>
+          </li>
+        </ul>
+      </div>
+
+      <div v-if="detail.env?.length" class="space-y-1.5" data-testid="environment">
+        <h3 class="text-xs uppercase tracking-wide text-zinc-500">Environment</h3>
+        <div class="flex flex-wrap gap-1.5">
+          <code
+            v-for="name in detail.env"
+            :key="name"
+            class="font-mono text-[11px] px-2 py-0.5 rounded border border-zinc-800 bg-zinc-900 text-zinc-300"
+            :data-testid="`env-${name}`"
+          >
+            {{ name }}
+          </code>
+        </div>
+      </div>
+
+      <div v-if="detail.config?.length" class="space-y-1.5" data-testid="config">
+        <h3 class="text-xs uppercase tracking-wide text-zinc-500">Config</h3>
+        <ul class="space-y-2">
+          <li
+            v-for="mod in detail.config"
+            :key="mod.file"
+            class="rounded border border-zinc-800 bg-zinc-900/60 px-2.5 py-2"
+          >
+            <code class="block font-mono text-[11px] text-zinc-400 break-all">{{
+              configFileLabel(mod.file)
+            }}</code>
+            <div v-if="mod.keys.length" class="mt-1.5 flex flex-wrap gap-1">
+              <span
+                v-for="k in mod.keys"
+                :key="k"
+                class="font-mono text-[11px] px-1.5 py-0.5 rounded bg-zinc-800 text-zinc-300"
+                >{{ k }}</span
+              >
+            </div>
+            <p v-else class="mt-1 text-[11px] italic text-zinc-500">(no top-level keys found)</p>
+          </li>
+        </ul>
+      </div>
+
+      <JsonView v-if="hasExtra" :value="detail.extra" label="Details" />
+
+      <div v-if="detail.source">
+        <h3 class="text-xs uppercase tracking-wide text-zinc-500 mb-1.5">Source</h3>
+        <SourcePill :source="detail.source" @click="emit('open-source', detail.source!)" />
+      </div>
+    </div>
+  </div>
+
+  <div
+    v-else
+    class="h-full flex items-center justify-center p-8 text-center text-xs text-zinc-600"
+    data-testid="node-card-empty"
+  >
+    Select a primitive to inspect it.
+  </div>
+</template>

package/src/components/RcaPanel.stories.ts

@@ -0,0 +1,95 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+import { expect, within, userEvent } from "storybook/test";
+import RcaPanel from "./RcaPanel.vue";
+import { groupIncidents } from "@/lib/rca";
+import type { TelemetryRecord } from "@/lib/telemetry";
+
+const env = (m: string, c: string) => ({
+  messageId: m,
+  causationId: c,
+  correlationId: "c-9f8e",
+  tenant: "acme",
+  userId: "u-42",
+});
+
+// A failed chain: dispatch → retrying action.failed → dead-lettered.
+const RECORDS: TelemetryRecord[] = [
+  {
+    kind: "action.dispatched",
+    action: "orders.charge",
+    appName: "billing",
+    ts: "2026-01-01T00:00:00.000Z",
+    durationMs: 4,
+    envelope: env("m1", "m1"),
+  },
+  {
+    kind: "event.published",
+    event: "ChargeStarted",
+    appName: "billing",
+    ts: "2026-01-01T00:00:00.010Z",
+    envelope: env("m2", "m1"),
+  },
+  {
+    kind: "action.failed",
+    action: "orders.charge",
+    appName: "billing",
+    attempt: 1,
+    maxAttempts: 3,
+    willRetry: true,
+    durationMs: 40,
+    ts: "2026-01-01T00:00:00.050Z",
+    error: {
+      name: "TimeoutError",
+      message: "upstream timed out",
+      stack:
+        "TimeoutError: upstream timed out\n  at chargeCard (apps/billing/orders.charge.ts:42:11)",
+    },
+    envelope: env("m3", "m1"),
+  },
+  {
+    kind: "dlq.recorded",
+    action: "orders.charge",
+    appName: "billing",
+    attempts: 3,
+    ts: "2026-01-01T00:00:00.300Z",
+    error: { name: "TimeoutError", message: "upstream timed out" },
+    envelope: env("m4", "m1"),
+  },
+];
+
+const incident = groupIncidents(RECORDS)[0]!;
+
+const meta: Meta<typeof RcaPanel> = {
+  title: "Errors/RcaPanel",
+  component: RcaPanel,
+  tags: ["autodocs"],
+  decorators: [
+    (story) => ({
+      components: { story },
+      template:
+        '<div class="h-[480px] border border-zinc-800 rounded-lg overflow-hidden"><story /></div>',
+    }),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof RcaPanel>;
+
+export const Default: Story = {
+  args: { incident, source: { file: "apps/billing/orders.charge.ts", line: 42 } },
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement);
+    await expect(c.getByTestId("rca-what")).toBeInTheDocument();
+    await expect(c.getByTestId("rca-suggestion")).toBeInTheDocument();
+
+    await userEvent.click(c.getByTestId("rca-tab-timeline"));
+    await expect(c.getAllByTestId("rca-timeline-row")).toHaveLength(4);
+
+    await userEvent.click(c.getByTestId("rca-tab-evidence"));
+    await expect(c.getByTestId("rca-evidence")).toHaveTextContent("TimeoutError");
+  },
+};
+
+export const WithoutSource: Story = {
+  args: { incident },
+};