okengine 0.11.2 → 0.13.0

package/src/console/ui-next/src/features/flows/traces/graph-filter.ts

@@ -0,0 +1,175 @@
+/**
+ * Pure helpers for graph-driven Traces filtering.
+ *
+ * A click on a Flow graph node resolves to a {@link GraphFilter} that the
+ * Traces pane applies on top of its existing status / duration / advanced
+ * filters. Flow nodes map to the dimension query (`flow = X`); unit nodes
+ * map to `unit = X`. Signal / element / resource clicks match via Manifest
+ * + ledger (the AND-only dimension query cannot express those ORs).
+ */
+
+import type { Manifest } from "../../../../../../manifest/types.ts";
+import type { RunRow } from "@/client.ts";
+import { ELEMENT_ICONS, type OkeElement } from "@/lib/element-icons.ts";
+import { unitOfFlowId } from "../graph/build-flow-graph.ts";
+import { elementsOfRun } from "../graph/element-map.ts";
+import { flowTouchesNode } from "../graph/neighborhood.ts";
+import { matchesDimensionQuery, upsertClause, type DimensionQuery } from "./dimension-query.ts";
+
+/** A filter derived from a graph node click. */
+export type GraphFilter =
+  | { readonly kind: "flow"; readonly flowId: string }
+  | { readonly kind: "signal"; readonly signal: string }
+  | { readonly kind: "unit"; readonly unit: string }
+  | { readonly kind: "element"; readonly element: OkeElement }
+  | { readonly kind: "resource"; readonly nodeId: string };
+
+const OKE_ELEMENT_SET = new Set<string>(Object.keys(ELEMENT_ICONS));
+
+/**
+ * Resolve a clicked graph node id into a {@link GraphFilter}.
+ *
+ * @param nodeId - React Flow node id
+ */
+export function graphFilterForNodeId(nodeId: string): GraphFilter | null {
+  if (nodeId.startsWith("flow:")) {
+    return { kind: "flow", flowId: nodeId.slice(5) };
+  }
+  if (nodeId.startsWith("signal:")) {
+    return { kind: "signal", signal: nodeId.slice(7) };
+  }
+  if (nodeId.startsWith("unit:")) {
+    return { kind: "unit", unit: nodeId.slice(5) };
+  }
+  if (nodeId.startsWith("element:")) {
+    const element = nodeId.slice(8);
+    if (OKE_ELEMENT_SET.has(element)) return { kind: "element", element: element as OkeElement };
+    return null;
+  }
+  if (nodeId.startsWith("type:")) {
+    const element = nodeId.slice(5).split(":")[0];
+    if (element && OKE_ELEMENT_SET.has(element)) {
+      return { kind: "element", element: element as OkeElement };
+    }
+    return null;
+  }
+  if (
+    nodeId.startsWith("sql:") ||
+    nodeId.startsWith("kv:") ||
+    nodeId.startsWith("files:") ||
+    nodeId.startsWith("index:") ||
+    nodeId.startsWith("vault:") ||
+    nodeId.startsWith("channel:") ||
+    nodeId.startsWith("gate:") ||
+    nodeId.startsWith("clock:") ||
+    nodeId.startsWith("ai:")
+  ) {
+    return { kind: "resource", nodeId };
+  }
+  return null;
+}
+
+/**
+ * Short label for the Traces graph-filter chip.
+ *
+ * @param filter - Active graph filter
+ */
+export function graphFilterLabel(filter: GraphFilter): string {
+  switch (filter.kind) {
+    case "flow":
+      return filter.flowId;
+    case "signal":
+      return `signal:${filter.signal}`;
+    case "unit":
+      return filter.unit;
+    case "element":
+      return ELEMENT_ICONS[filter.element].label;
+    case "resource":
+      return filter.nodeId;
+  }
+}
+
+/**
+ * Apply a graph filter on top of the pane's existing advanced dimension query.
+ *
+ * Flow clicks upsert `flow = X`; unit clicks upsert `unit = X`. Other kinds
+ * leave the dimension query untouched (matched by {@link matchesGraphFilter}).
+ *
+ * @param query - Current advanced dimension query
+ * @param filter - Graph filter (or `null` to leave the query as-is)
+ */
+export function applyGraphFilterToQuery(
+  query: DimensionQuery,
+  filter: GraphFilter | null,
+): DimensionQuery {
+  if (filter?.kind === "flow") {
+    return upsertClause(query, { dimension: "flow", op: "=", value: filter.flowId });
+  }
+  if (filter?.kind === "unit") {
+    return upsertClause(query, { dimension: "unit", op: "=", value: filter.unit });
+  }
+  return query;
+}
+
+/**
+ * Whether a run matches a graph filter.
+ *
+ * @param run - Projected run row
+ * @param filter - Graph filter
+ * @param manifest - Manifest snapshot (for signal / resource resolution)
+ */
+export function matchesGraphFilter(
+  run: RunRow,
+  filter: GraphFilter,
+  manifest: Manifest | null,
+): boolean {
+  if (filter.kind === "flow") {
+    return matchesDimensionQuery(run, {
+      clauses: [{ dimension: "flow", op: "=", value: filter.flowId }],
+    });
+  }
+  if (filter.kind === "unit") {
+    return (run.unit ?? unitOfFlowId(run.flow)) === filter.unit;
+  }
+  if (filter.kind === "element") {
+    if (filter.element === "flow") return true;
+    return elementsOfRun(run).includes(filter.element);
+  }
+  if (filter.kind === "resource") {
+    return runTouchesResource(run, filter.nodeId, manifest);
+  }
+  const flows = manifest?.flows ?? {};
+  for (const [flowId, flow] of Object.entries(flows)) {
+    if (flowId !== run.flow) continue;
+    if (flow.trigger?.signal === filter.signal) return true;
+    if (flow.effects?.emits?.includes(filter.signal)) return true;
+  }
+  return false;
+}
+
+function runTouchesResource(run: RunRow, nodeId: string, manifest: Manifest | null): boolean {
+  const suffix = nodeId.includes(":") ? nodeId.slice(nodeId.indexOf(":") + 1) : nodeId;
+  if (run.effects.some((effect) => effect.resource === nodeId || effect.resource === suffix)) {
+    return true;
+  }
+  if (run.gates.some((name) => nodeId === `gate:${name}`)) return true;
+  const flow = manifest?.flows?.[run.flow];
+  if (flow && flowTouchesNode(flow, run.flow, nodeId)) return true;
+  return false;
+}
+
+/**
+ * Filter a run population by a graph filter (no-op when `null`).
+ *
+ * @param runs - Scoped runs
+ * @param filter - Graph filter or `null`
+ * @param manifest - Manifest snapshot
+ */
+export function filterRunsByGraph(
+  runs: readonly RunRow[],
+  filter: GraphFilter | null,
+  manifest: Manifest | null,
+): RunRow[] {
+  if (!filter) return [...runs];
+  return runs.filter((run) => matchesGraphFilter(run, filter, manifest));
+}

package/src/console/ui-next/src/features/flows/traces/http-method.ts

@@ -0,0 +1,134 @@
+/**
+ * HTTP method accent for the REQUEST section badge.
+ */
+
+import {
+  Add01Icon,
+  ApiIcon,
+  Delete02Icon,
+  Edit02Icon,
+  File01Icon,
+  PencilEdit01Icon,
+  Search01Icon,
+  Settings01Icon,
+  ViewIcon,
+} from "@hugeicons/core-free-icons";
+import type { ElementHugeIcon } from "@/lib/element-icons.ts";
+
+/** Known HTTP methods from Manifest `HttpTrigger.method`. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
+
+/**
+ * Units-tree display rank: GET → POST → QUERY → PATCH/PUT → DELETE.
+ *
+ * PATCH and PUT share a rank. Unknown verbs and missing methods sort last.
+ *
+ * @param method - HTTP method string (case-insensitive) or null for non-HTTP
+ */
+export function httpMethodSortRank(method: string | null | undefined): number {
+  switch ((method ?? "").toUpperCase()) {
+    case "GET":
+      return 0;
+    case "POST":
+      return 1;
+    case "QUERY":
+      return 2;
+    case "PUT":
+    case "PATCH":
+      return 3;
+    case "DELETE":
+      return 4;
+    case "HEAD":
+      return 5;
+    case "OPTIONS":
+      return 6;
+    default:
+      return method ? 7 : 8;
+  }
+}
+
+/**
+ * CRUD-shaped glyph per HTTP method — Units tree wells.
+ *
+ * @param method - HTTP method string (case-insensitive)
+ */
+export function httpMethodIcon(method: string): ElementHugeIcon {
+  switch (method.toUpperCase()) {
+    case "GET":
+      return ViewIcon;
+    case "QUERY":
+      return Search01Icon;
+    case "POST":
+      return Add01Icon;
+    case "PUT":
+      return Edit02Icon;
+    case "PATCH":
+      return PencilEdit01Icon;
+    case "DELETE":
+      return Delete02Icon;
+    case "HEAD":
+      return File01Icon;
+    case "OPTIONS":
+      return Settings01Icon;
+    default:
+      return ApiIcon;
+  }
+}
+
+/**
+ * Tailwind classes for a method badge — distinct accents per verb, matching
+ * common API-tool convention (GET green, POST blue, PUT amber, PATCH violet,
+ * DELETE rose).
+ *
+ * @param method - HTTP method string (case-insensitive)
+ */
+export function httpMethodBadgeClass(method: string): string {
+  switch (method.toUpperCase()) {
+    case "GET":
+      return "border-emerald-500/35 bg-emerald-500/15 text-emerald-700 dark:text-emerald-400";
+    case "POST":
+      return "border-sky-500/35 bg-sky-500/15 text-sky-700 dark:text-sky-400";
+    case "PUT":
+      return "border-amber-500/35 bg-amber-500/15 text-amber-800 dark:text-amber-400";
+    case "PATCH":
+      return "border-violet-500/35 bg-violet-500/15 text-violet-700 dark:text-violet-400";
+    case "DELETE":
+      return "border-rose-500/35 bg-rose-500/15 text-rose-700 dark:text-rose-400";
+    case "HEAD":
+      return "border-slate-500/35 bg-slate-500/15 text-slate-700 dark:text-slate-300";
+    case "OPTIONS":
+      return "border-zinc-500/35 bg-zinc-500/15 text-zinc-700 dark:text-zinc-300";
+    case "QUERY":
+      return "border-emerald-500/35 bg-emerald-500/15 text-emerald-700 dark:text-emerald-400";
+    default:
+      return "border-border bg-muted text-muted-foreground";
+  }
+}
+
+/**
+ * Solid rail fill for the Request protocol frame (matches badge accents).
+ *
+ * @param method - HTTP method string (case-insensitive)
+ */
+export function httpMethodRailClass(method: string): string {
+  switch (method.toUpperCase()) {
+    case "GET":
+      return "bg-emerald-500";
+    case "POST":
+      return "bg-sky-500";
+    case "PUT":
+      return "bg-amber-500";
+    case "PATCH":
+      return "bg-violet-500";
+    case "DELETE":
+      return "bg-rose-500";
+    case "HEAD":
+      return "bg-slate-400";
+    case "OPTIONS":
+      return "bg-zinc-400";
+    case "QUERY":
+      return "bg-emerald-500";
+    default:
+      return "bg-muted-foreground";
+  }
+}

package/src/console/ui-next/src/features/flows/traces/replay-playback.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for Replay playback mapping helpers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../../../../../../manifest/types.ts";
+import {
+  activeEffectIndexAt,
+  activeNodeAt,
+  barPlayed,
+  playbackDurationMs,
+  playbackNodeSteps,
+} from "./replay-playback.ts";
+import type { WaterfallBar } from "./waterfall-bars.ts";
+
+function bar(index: number, offsetRatio: number): WaterfallBar {
+  return {
+    index,
+    kind: "read",
+    resource: "sql:bookings",
+    startOffsetMs: offsetRatio * 100,
+    durationMs: 10,
+    offsetRatio,
+    widthRatio: 0.1,
+  };
+}
+
+const MANIFEST: Manifest = {
+  app: "skyport",
+  flows: {
+    "bookings.create": {
+      trigger: { http: { method: "POST", path: "/bookings" } },
+      effects: { emits: ["order-placed"] },
+    },
+    "fulfillment.onOrder": {
+      trigger: { signal: "order-placed" },
+    },
+  },
+} as unknown as Manifest;
+
+describe("playbackDurationMs", () => {
+  test("stays within the snappy band", () => {
+    expect(playbackDurationMs(0)).toBe(900);
+    expect(playbackDurationMs(10)).toBe(700);
+    expect(playbackDurationMs(200)).toBe(1200);
+    expect(playbackDurationMs(10_000)).toBe(1600);
+  });
+});
+
+describe("activeEffectIndexAt", () => {
+  const bars = [bar(0, 0), bar(1, 0.3), bar(2, 0.7)];
+
+  test("returns -1 before the first bar", () => {
+    expect(activeEffectIndexAt([bar(0, 0.2)], 0.1)).toBe(-1);
+  });
+
+  test("returns the latest started bar", () => {
+    expect(activeEffectIndexAt(bars, 0)).toBe(0);
+    expect(activeEffectIndexAt(bars, 0.35)).toBe(1);
+    expect(activeEffectIndexAt(bars, 1)).toBe(2);
+  });
+});
+
+describe("barPlayed", () => {
+  test("true once the playhead passes the bar start", () => {
+    expect(barPlayed(bar(0, 0.3), 0.2)).toBe(false);
+    expect(barPlayed(bar(0, 0.3), 0.3)).toBe(true);
+    expect(barPlayed(bar(0, 0.3), 0.9)).toBe(true);
+  });
+});
+
+describe("playbackNodeSteps", () => {
+  test("interleaves the linking signal between chained flows", () => {
+    const steps = playbackNodeSteps(new Set(["bookings.create", "fulfillment.onOrder"]), MANIFEST);
+    expect(steps).toEqual([
+      "flow:bookings.create",
+      "signal:order-placed",
+      "flow:fulfillment.onOrder",
+    ]);
+  });
+
+  test("omits the signal step when no emit/consume pair is declared", () => {
+    const steps = playbackNodeSteps(new Set(["bookings.create", "ops.nightlyReconcile"]), MANIFEST);
+    expect(steps).toEqual(["flow:bookings.create", "flow:ops.nightlyReconcile"]);
+  });
+});
+
+describe("activeNodeAt", () => {
+  const steps = ["flow:a", "signal:s", "flow:b"];
+
+  test("null for empty steps", () => {
+    expect(activeNodeAt([], 0.5)).toBeNull();
+  });
+
+  test("maps progress onto ordered steps", () => {
+    expect(activeNodeAt(steps, 0)).toBe("flow:a");
+    expect(activeNodeAt(steps, 0.4)).toBe("signal:s");
+    expect(activeNodeAt(steps, 0.9)).toBe("flow:b");
+    expect(activeNodeAt(steps, 1)).toBe("flow:b");
+  });
+});

package/src/console/ui-next/src/features/flows/traces/replay-playback.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure mapping helpers for the Replay playback animation.
+ *
+ * Playback is a single progress value in `[0, 1]` driven by Motion. These
+ * helpers map that progress onto effect indices (waterfall) and ordered graph
+ * node ids (chain pulse) so the animation logic stays timer-free and unit
+ * testable.
+ */
+
+import type { Manifest } from "../../../../../../manifest/types.ts";
+import type { WaterfallBar } from "./waterfall-bars.ts";
+
+/**
+ * Playback duration in ms for a run. Scales lightly with the run's real
+ * duration but stays in a snappy band so the animation reads as a replay,
+ * not a real-time re-run.
+ *
+ * @param runDurationMs - Run wall duration
+ */
+export function playbackDurationMs(runDurationMs: number): number {
+  if (!Number.isFinite(runDurationMs) || runDurationMs <= 0) return 900;
+  return Math.min(1600, Math.max(700, runDurationMs * 6));
+}
+
+/**
+ * Index of the latest effect whose bar has started at `progress`, or `-1`
+ * when the playhead has not reached the first effect yet.
+ *
+ * @param bars - Waterfall bars (offsetRatio in `[0, 1]`)
+ * @param progress - Playback progress in `[0, 1]`
+ */
+export function activeEffectIndexAt(bars: readonly WaterfallBar[], progress: number): number {
+  let active = -1;
+  for (const bar of bars) {
+    if (bar.offsetRatio <= progress) active = bar.index;
+  }
+  return active;
+}
+
+/**
+ * Whether a bar is "played" (the playhead has passed its start).
+ *
+ * @param bar - Waterfall bar
+ * @param progress - Playback progress in `[0, 1]`
+ */
+export function barPlayed(bar: WaterfallBar, progress: number): boolean {
+  return bar.offsetRatio <= progress;
+}
+
+/**
+ * Ordered chain steps for the graph pulse: ancestor → current → descendant
+ * flow ids, with the signal node that links two consecutive flows inserted
+ * between them when the Manifest declares the emit/consume pair.
+ *
+ * @param chainFlowIds - Flow ids on the causal chain (unordered set)
+ * @param manifest - Manifest snapshot
+ */
+export function playbackNodeSteps(
+  chainFlowIds: ReadonlySet<string>,
+  manifest: Manifest | null,
+): readonly string[] {
+  const flows = manifest?.flows ?? {};
+  const chain = [...chainFlowIds];
+  const steps: string[] = [];
+  for (let i = 0; i < chain.length; i++) {
+    const flowId = chain[i]!;
+    steps.push(`flow:${flowId}`);
+    const next = chain[i + 1];
+    if (!next) break;
+    const signal = linkingSignal(flowId, next, flows);
+    if (signal) steps.push(`signal:${signal}`);
+  }
+  return steps;
+}
+
+/**
+ * Signal emitted by `from` that triggers `to`, when declared.
+ *
+ * @param from - Upstream flow id
+ * @param to - Downstream flow id
+ * @param flows - Manifest flows
+ */
+function linkingSignal(
+  from: string,
+  to: string,
+  flows: NonNullable<Manifest["flows"]>,
+): string | null {
+  const upstream = flows[from];
+  const downstream = flows[to];
+  if (!upstream || !downstream) return null;
+  const triggerSignal = downstream.trigger?.signal;
+  if (!triggerSignal) return null;
+  return upstream.effects?.emits?.includes(triggerSignal) ? triggerSignal : null;
+}
+
+/**
+ * Active graph node id at `progress` over the ordered `steps`, or `null`
+ * when there is nothing to pulse.
+ *
+ * @param steps - Ordered node ids from {@link playbackNodeSteps}
+ * @param progress - Playback progress in `[0, 1]`
+ */
+export function activeNodeAt(steps: readonly string[], progress: number): string | null {
+  if (steps.length === 0) return null;
+  const clamped = Math.min(0.999, Math.max(0, progress));
+  return steps[Math.floor(clamped * steps.length)] ?? null;
+}

package/src/console/ui-next/src/features/flows/traces/request-input-view.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for request input field projection.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  fieldCopyText,
+  inputByteLabel,
+  inputFieldRows,
+  inputShapeHint,
+} from "./request-input-view.ts";
+
+describe("inputFieldRows", () => {
+  test("projects plain objects into typed rows", () => {
+    expect(
+      inputFieldRows({
+        bookingId: "bk_8f2a",
+        seats: 2,
+        ok: true,
+        meta: { cabin: "economy" },
+      }),
+    ).toEqual([
+      { key: "bookingId", value: "bk_8f2a", display: "bk_8f2a", kind: "string" },
+      { key: "seats", value: 2, display: "2", kind: "number" },
+      { key: "ok", value: true, display: "true", kind: "boolean" },
+      {
+        key: "meta",
+        value: { cabin: "economy" },
+        display: '{"cabin":"economy"}',
+        kind: "object",
+      },
+    ]);
+  });
+
+  test("returns null for arrays and scalars", () => {
+    expect(inputFieldRows(["a"])).toBeNull();
+    expect(inputFieldRows("x")).toBeNull();
+    expect(inputFieldRows(null)).toBeNull();
+  });
+});
+
+describe("inputShapeHint", () => {
+  test("counts fields and items", () => {
+    expect(inputShapeHint({ a: 1, b: 2 })).toBe("2 fields");
+    expect(inputShapeHint([1])).toBe("1 item");
+  });
+});
+
+describe("inputByteLabel", () => {
+  test("labels UTF-8 payload size", () => {
+    expect(inputByteLabel('{"a":1}')).toBe("7 B");
+  });
+});
+
+describe("fieldCopyText", () => {
+  test("copies strings raw and others as JSON", () => {
+    expect(fieldCopyText("hello")).toBe("hello");
+    expect(fieldCopyText({ x: 1 })).toBe('{"x":1}');
+  });
+});

package/src/console/ui-next/src/features/flows/traces/request-input-view.ts

@@ -0,0 +1,108 @@
+/**
+ * Helpers for rendering run.input in the trace Request section.
+ */
+
+/** Scalar / container kind for a top-level input field. */
+export type InputFieldKind = "string" | "number" | "boolean" | "null" | "object" | "array";
+
+/** One top-level field row for the Fields view. */
+export type InputFieldRow = {
+  /** Object key. */
+  readonly key: string;
+  /** Raw value (for copy). */
+  readonly value: unknown;
+  /** Display string in the value column. */
+  readonly display: string;
+  /** Value kind chip. */
+  readonly kind: InputFieldKind;
+};
+
+/**
+ * Flatten a plain object into field rows. Nested objects/arrays stay as one
+ * row with a compact JSON display. Returns `null` when Fields view is not
+ * appropriate (arrays, scalars, null).
+ *
+ * @param value - Stored run input
+ */
+export function inputFieldRows(value: unknown): readonly InputFieldRow[] | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return Object.entries(value as Record<string, unknown>).map(([key, v]) => ({
+    key,
+    value: v,
+    display: formatFieldDisplay(v),
+    kind: fieldKind(v),
+  }));
+}
+
+/**
+ * Human shape hint for the body chrome (e.g. `"2 fields"`).
+ *
+ * @param value - Stored run input
+ */
+export function inputShapeHint(value: unknown): string | null {
+  if (Array.isArray(value)) {
+    const n = value.length;
+    return `${n} ${n === 1 ? "item" : "items"}`;
+  }
+  if (value !== null && typeof value === "object") {
+    const n = Object.keys(value).length;
+    return `${n} ${n === 1 ? "field" : "fields"}`;
+  }
+  if (typeof value === "string") return `${value.length} chars`;
+  return null;
+}
+
+/**
+ * Compact UTF-8 byte size label for the serialized body.
+ *
+ * @param json - Serialized JSON text
+ */
+export function inputByteLabel(json: string): string {
+  const bytes = new TextEncoder().encode(json).length;
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+/**
+ * Clipboard text for a field value — strings as-is, others as JSON.
+ *
+ * @param value - Field value
+ */
+export function fieldCopyText(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function fieldKind(value: unknown): InputFieldKind {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  switch (typeof value) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "object":
+      return "object";
+    default:
+      return "string";
+  }
+}
+
+function formatFieldDisplay(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}