@stigmer/react 1.0.3 → 2.0.0

package/src/workflow/useWorkflowVersion.ts

@@ -0,0 +1,120 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { StigmerError } from "@stigmer/sdk";
+import {
+  GetWorkflowVersionInputSchema,
+  type WorkflowVersionEntry,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+const CODE_UNIMPLEMENTED = 12;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useWorkflowVersion}. */
+export interface UseWorkflowVersionReturn {
+  /** The resolved version entry, or `null` while loading / on error / when disabled. */
+  readonly version: WorkflowVersionEntry | null;
+  /** `true` while the fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Data hook that fetches a single workflow version entry by ID and hash.
+ *
+ * Calls `stigmer.workflow.getVersion()` to retrieve the full version
+ * details for a specific content hash. Useful for inspecting a
+ * particular historical version outside the timeline listing.
+ *
+ * **Graceful degradation**: If the backend returns UNIMPLEMENTED, the
+ * hook resolves to `null` without raising an error.
+ *
+ * Pass `null` for either `workflowId` or `versionHash` to skip
+ * fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { version, isLoading } = useWorkflowVersion(workflowId, selectedHash);
+ *
+ * if (version) {
+ *   return <pre>{version.validatedYaml}</pre>;
+ * }
+ * ```
+ */
+export function useWorkflowVersion(
+  workflowId: string | null,
+  versionHash: string | null,
+): UseWorkflowVersionReturn {
+  const stigmer = useStigmer();
+  const [version, setVersion] = useState<WorkflowVersionEntry | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const fetchIdRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    if (!workflowId || !versionHash) {
+      setVersion(null);
+      setError(null);
+      return;
+    }
+
+    const fetchId = ++fetchIdRef.current;
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await stigmer.workflow.getVersion(
+        create(GetWorkflowVersionInputSchema, { workflowId, versionHash }),
+      );
+
+      if (fetchIdRef.current !== fetchId) return;
+      setVersion(result);
+    } catch (err) {
+      if (fetchIdRef.current !== fetchId) return;
+      if (isUnimplemented(err)) {
+        setVersion(null);
+      } else {
+        setError(toError(err));
+        setVersion(null);
+      }
+    } finally {
+      if (fetchIdRef.current === fetchId) {
+        setIsLoading(false);
+      }
+    }
+  }, [workflowId, versionHash, stigmer]);
+
+  useEffect(() => {
+    doFetch();
+  }, [doFetch]);
+
+  const refetch = useCallback(() => {
+    doFetch();
+  }, [doFetch]);
+
+  return useMemo(
+    () => ({ version, isLoading, error, refetch }),
+    [version, isLoading, error, refetch],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Error detection
+// ---------------------------------------------------------------------------
+
+function isUnimplemented(err: unknown): boolean {
+  return err instanceof StigmerError && err.connectCode === CODE_UNIMPLEMENTED;
+}

package/src/workflow/useWorkflowVersionDiff.ts

@@ -0,0 +1,120 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { StigmerError } from "@stigmer/sdk";
+import { GetWorkflowVersionInputSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { computeUnifiedDiff, type DiffLine } from "./workflow-yaml-diff";
+
+const CODE_UNIMPLEMENTED = 12;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useWorkflowVersionDiff}. */
+export interface UseWorkflowVersionDiffReturn {
+  /** Array of diff lines, or `null` while loading / on error / when disabled. */
+  readonly diff: readonly DiffLine[] | null;
+  /** `true` while both versions are being fetched and diffed. */
+  readonly isLoading: boolean;
+  /** Error from the fetch or diff computation, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Data hook that computes a unified YAML diff between two workflow versions.
+ *
+ * Fetches both version entries via `stigmer.workflow.getVersion()` in
+ * parallel, extracts their `validatedYaml` fields, and runs
+ * {@link computeUnifiedDiff} to produce a line-by-line diff result.
+ *
+ * **Graceful degradation**: If the backend returns UNIMPLEMENTED for
+ * either fetch, the hook resolves to `null` without raising an error.
+ *
+ * Pass `null` for any parameter to disable fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { diff, isLoading } = useWorkflowVersionDiff(workflowId, hashA, hashB);
+ *
+ * if (diff) {
+ *   return <DiffViewer lines={diff} />;
+ * }
+ * ```
+ */
+export function useWorkflowVersionDiff(
+  workflowId: string | null,
+  hashA: string | null,
+  hashB: string | null,
+): UseWorkflowVersionDiffReturn {
+  const stigmer = useStigmer();
+  const [diff, setDiff] = useState<readonly DiffLine[] | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const fetchIdRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    if (!workflowId || !hashA || !hashB) {
+      setDiff(null);
+      setError(null);
+      return;
+    }
+
+    const fetchId = ++fetchIdRef.current;
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const [resultA, resultB] = await Promise.all([
+        stigmer.workflow.getVersion(create(GetWorkflowVersionInputSchema, { workflowId, versionHash: hashA })),
+        stigmer.workflow.getVersion(create(GetWorkflowVersionInputSchema, { workflowId, versionHash: hashB })),
+      ]);
+
+      if (fetchIdRef.current !== fetchId) return;
+
+      const yamlA = resultA.validatedYaml ?? "";
+      const yamlB = resultB.validatedYaml ?? "";
+
+      const diffResult = computeUnifiedDiff(yamlA, yamlB);
+
+      if (fetchIdRef.current !== fetchId) return;
+      setDiff(diffResult);
+    } catch (err) {
+      if (fetchIdRef.current !== fetchId) return;
+      if (isUnimplemented(err)) {
+        setDiff(null);
+      } else {
+        setError(toError(err));
+        setDiff(null);
+      }
+    } finally {
+      if (fetchIdRef.current === fetchId) {
+        setIsLoading(false);
+      }
+    }
+  }, [workflowId, hashA, hashB, stigmer]);
+
+  useEffect(() => {
+    doFetch();
+  }, [doFetch]);
+
+  return useMemo(
+    () => ({ diff, isLoading, error }),
+    [diff, isLoading, error],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Error detection
+// ---------------------------------------------------------------------------
+
+function isUnimplemented(err: unknown): boolean {
+  return err instanceof StigmerError && err.connectCode === CODE_UNIMPLEMENTED;
+}

package/src/workflow/useWorkflowVersions.ts

@@ -0,0 +1,162 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { StigmerError } from "@stigmer/sdk";
+import {
+  ListWorkflowVersionsInputSchema,
+  type WorkflowVersionEntry as ProtoWorkflowVersionEntry,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+import type { VersionEntry } from "../version-history/types";
+
+const CODE_UNIMPLEMENTED = 12;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useWorkflowVersions}. */
+export interface UseWorkflowVersionsReturn {
+  /** Version entries mapped to the generic timeline format (newest first). */
+  readonly versions: readonly VersionEntry[];
+  /** `true` when no versions are available (RPC unimplemented or empty response). */
+  readonly isEmpty: boolean;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request (excludes UNIMPLEMENTED), or `null`. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+  /**
+   * Look up the validated YAML for a version by its hash.
+   * Returns `null` if the version hash is not found or has no YAML content.
+   */
+  readonly getValidatedYaml: (versionHash: string) => string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Data hook that fetches version history for a workflow.
+ *
+ * Calls the `listVersions` RPC via the SDK client and maps the response
+ * to generic {@link VersionEntry} objects for the `VersionTimeline`
+ * component.
+ *
+ * **Graceful degradation**: If the backend returns UNIMPLEMENTED (the
+ * RPC handler hasn't been deployed yet), the hook treats it as an empty
+ * response — `versions` is `[]` and `isEmpty` is `true`. No error is
+ * surfaced to the consumer.
+ *
+ * Pass `null` for `org` or `slug` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { versions, isEmpty, isLoading } = useWorkflowVersions("acme", "deploy-pipeline");
+ *
+ * if (!isEmpty) {
+ *   return <VersionTimeline entries={versions} />;
+ * }
+ * ```
+ */
+export function useWorkflowVersions(
+  org: string | null,
+  slug: string | null,
+): UseWorkflowVersionsReturn {
+  const stigmer = useStigmer();
+
+  const {
+    data: rawVersions,
+    isLoading,
+    error,
+    refetch,
+  } = useFetch(
+    org && slug
+      ? async () => {
+          try {
+            const request = create(ListWorkflowVersionsInputSchema, {
+              org,
+              slug,
+            });
+            const response = await stigmer.workflow.listVersions(request);
+            return response.versions;
+          } catch (err) {
+            if (isUnimplemented(err)) return [];
+            throw err;
+          }
+        }
+      : null,
+    [org, slug, stigmer],
+    [] as ProtoWorkflowVersionEntry[],
+  );
+
+  const versions = useMemo(
+    () => rawVersions.map(mapProtoToVersionEntry),
+    [rawVersions],
+  );
+
+  const validatedYamlMap = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const entry of rawVersions) {
+      if (entry.versionHash && entry.validatedYaml) {
+        map.set(entry.versionHash, entry.validatedYaml);
+      }
+    }
+    return map;
+  }, [rawVersions]);
+
+  const getValidatedYaml = useCallback(
+    (versionHash: string): string | null =>
+      validatedYamlMap.get(versionHash) ?? null,
+    [validatedYamlMap],
+  );
+
+  const isEmpty = versions.length === 0;
+
+  return useMemo(
+    () => ({ versions, isEmpty, isLoading, error, refetch, getValidatedYaml }),
+    [versions, isEmpty, isLoading, error, refetch, getValidatedYaml],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Proto → generic mapping
+// ---------------------------------------------------------------------------
+
+function mapProtoToVersionEntry(proto: ProtoWorkflowVersionEntry): VersionEntry {
+  return {
+    id: proto.versionHash,
+    timestamp: proto.appliedAt ? timestampDate(proto.appliedAt) : new Date(0),
+    actor: proto.appliedBy
+      ? {
+          id: proto.appliedBy.id,
+          avatar: proto.appliedBy.avatar || undefined,
+          displayName: undefined,
+        }
+      : undefined,
+    label: proto.versionHash.slice(0, 12),
+    sublabel: proto.message || undefined,
+    isCurrent: proto.isCurrent,
+    tag: proto.tag || undefined,
+    gitProvenance: proto.gitProvenance
+      ? {
+          remoteUrl: proto.gitProvenance.remoteUrl,
+          ref: proto.gitProvenance.ref,
+          commit: proto.gitProvenance.commit,
+        }
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error detection
+// ---------------------------------------------------------------------------
+
+function isUnimplemented(err: unknown): boolean {
+  return err instanceof StigmerError && err.connectCode === CODE_UNIMPLEMENTED;
+}

package/src/workflow/waterfall/WaterfallBar.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+import type { WaterfallEntry, WaterfallAttempt, WaterfallSpan } from "../execution/derive-waterfall-entries";
+import type { DerivedTaskState } from "../../internal/store/workflow-execution-event-store";
+
+export interface WaterfallBarProps {
+  readonly entry: WaterfallEntry;
+  /** Total visible range in ms (from WaterfallScale.totalMs). */
+  readonly totalMs: number;
+  /** Current elapsed ms (for live-growing bars). */
+  readonly nowMs: number;
+  readonly className?: string;
+}
+
+type BarStatus = DerivedTaskState["status"] | "not_reached";
+
+const STATUS_COLORS: Record<BarStatus, string> = {
+  completed: "bg-[var(--stgm-success,#22c55e)]",
+  running: "bg-[var(--stgm-primary,#3b82f6)]",
+  failed: "bg-[var(--stgm-destructive,#ef4444)]",
+  retrying: "bg-[var(--stgm-warning,#f59e0b)]",
+  waiting_approval: "bg-[var(--stgm-warning,#f59e0b)]",
+  skipped: "bg-[var(--stgm-muted,#d4d4d4)]",
+  pending: "bg-[var(--stgm-muted,#d4d4d4)]",
+  not_reached: "bg-[var(--stgm-muted,#d4d4d4)]",
+};
+
+const ATTEMPT_STATUS_COLORS: Record<WaterfallAttempt["status"], string> = {
+  completed: "bg-[var(--stgm-success,#22c55e)]",
+  running: "bg-[var(--stgm-primary,#3b82f6)]",
+  failed: "bg-[var(--stgm-destructive,#ef4444)]",
+};
+
+/**
+ * Renders the horizontal bar(s) for a single waterfall entry.
+ *
+ * When attempts are present (retries), renders individual attempt
+ * segments with backoff gaps. Otherwise, renders a single bar.
+ * Running bars animate with a pulsing trailing edge (respects
+ * `prefers-reduced-motion`).
+ */
+export const WaterfallBar = memo(function WaterfallBar({
+  entry,
+  totalMs,
+  nowMs,
+  className,
+}: WaterfallBarProps) {
+  if (totalMs <= 0) return null;
+
+  const effectiveEnd = entry.endMs ?? nowMs;
+
+  // Use attempt segments when available
+  if (entry.attempts.length > 1) {
+    return (
+      <div className={cn("relative h-3", className)}>
+        {entry.attempts.map((attempt, i) => (
+          <AttemptSegment
+            key={i}
+            attempt={attempt}
+            totalMs={totalMs}
+            nowMs={nowMs}
+          />
+        ))}
+        {entry.children.map((child, i) => (
+          <ChildSpan key={i} span={child} totalMs={totalMs} nowMs={nowMs} />
+        ))}
+      </div>
+    );
+  }
+
+  // Single bar for non-retry tasks
+  const leftPct = (entry.startMs / totalMs) * 100;
+  const widthPct = ((effectiveEnd - entry.startMs) / totalMs) * 100;
+  const isRunning = entry.status === "running" || entry.status === "waiting_approval";
+
+  return (
+    <div className={cn("relative h-3", className)}>
+      {/* Approval wait segment (drawn first, behind main bar) */}
+      {entry.approvalWaitMs != null && entry.approvalWaitMs > 0 && (
+        <div
+          className="absolute top-0 h-full rounded-sm bg-[var(--stgm-warning,#f59e0b)] opacity-30"
+          style={{
+            left: `${leftPct}%`,
+            width: `${(entry.approvalWaitMs / totalMs) * 100}%`,
+          }}
+        />
+      )}
+
+      {/* Main bar */}
+      <div
+        className={cn(
+          "absolute top-0.5 h-2 rounded-sm transition-[width] duration-100",
+          STATUS_COLORS[entry.status],
+          isRunning && "motion-safe:animate-pulse",
+        )}
+        style={{
+          left: `${leftPct}%`,
+          width: `${Math.max(widthPct, 0.2)}%`,
+        }}
+      />
+
+      {/* Child spans (agent calls) */}
+      {entry.children.map((child, i) => (
+        <ChildSpan key={i} span={child} totalMs={totalMs} nowMs={nowMs} />
+      ))}
+    </div>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Internal components
+// ---------------------------------------------------------------------------
+
+function AttemptSegment({
+  attempt,
+  totalMs,
+  nowMs,
+}: {
+  readonly attempt: WaterfallAttempt;
+  readonly totalMs: number;
+  readonly nowMs: number;
+}) {
+  const effectiveEnd = attempt.endMs ?? nowMs;
+  const leftPct = (attempt.startMs / totalMs) * 100;
+  const widthPct = ((effectiveEnd - attempt.startMs) / totalMs) * 100;
+  const isRunning = attempt.status === "running";
+
+  return (
+    <div
+      className={cn(
+        "absolute top-0.5 h-2 rounded-sm",
+        ATTEMPT_STATUS_COLORS[attempt.status],
+        isRunning && "motion-safe:animate-pulse",
+      )}
+      style={{
+        left: `${leftPct}%`,
+        width: `${Math.max(widthPct, 0.2)}%`,
+      }}
+    />
+  );
+}
+
+function ChildSpan({
+  span,
+  totalMs,
+  nowMs,
+}: {
+  readonly span: WaterfallSpan;
+  readonly totalMs: number;
+  readonly nowMs: number;
+}) {
+  const effectiveEnd = span.endMs ?? nowMs;
+  const leftPct = (span.startMs / totalMs) * 100;
+  const widthPct = ((effectiveEnd - span.startMs) / totalMs) * 100;
+
+  return (
+    <div
+      className="absolute top-1 h-1 rounded-sm bg-[var(--stgm-chart-purple,#8b5cf6)] opacity-60"
+      style={{
+        left: `${leftPct}%`,
+        width: `${Math.max(widthPct, 0.15)}%`,
+      }}
+    />
+  );
+}

package/src/workflow/waterfall/WaterfallRow.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { memo, useCallback } from "react";
+import { cn } from "@stigmer/theme";
+import type { WaterfallEntry } from "../execution/derive-waterfall-entries";
+import { WaterfallBar } from "./WaterfallBar";
+import { formatDuration, formatMicroUsd } from "../format-utils";
+
+export interface WaterfallRowProps {
+  readonly entry: WaterfallEntry;
+  readonly totalMs: number;
+  readonly nowMs: number;
+  readonly isSelected: boolean;
+  readonly onSelect: (taskName: string) => void;
+  readonly className?: string;
+}
+
+const BIGINT_ZERO = BigInt(0);
+
+/**
+ * A single row in the waterfall: task label on the left, bar on the right.
+ *
+ * Wrapped in `React.memo` so only the actively-running row re-renders
+ * during live streaming (DD-010). Selection state is the primary
+ * re-render trigger for completed rows.
+ */
+export const WaterfallRow = memo(function WaterfallRow({
+  entry,
+  totalMs,
+  nowMs,
+  isSelected,
+  onSelect,
+  className,
+}: WaterfallRowProps) {
+  const handleClick = useCallback(() => {
+    onSelect(entry.taskName);
+  }, [onSelect, entry.taskName]);
+
+  const effectiveDuration = entry.endMs != null
+    ? entry.endMs - entry.startMs
+    : nowMs - entry.startMs;
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={cn(
+        "flex w-full items-center gap-2 px-2 py-0.5 text-left transition-colors hover:bg-[var(--stgm-muted,#f5f5f5)]",
+        isSelected && "bg-[var(--stgm-accent,#f0f4ff)]",
+        className,
+      )}
+      aria-label={`Task ${entry.taskName}, ${entry.status}, ${formatDuration(entry.durationMs || effectiveDuration)}`}
+      data-task-name={entry.taskName}
+    >
+      {/* Label column */}
+      <div className="flex w-36 shrink-0 items-center gap-1.5 overflow-hidden">
+        <StatusDot status={entry.status} />
+        <span className="truncate text-[11px] font-medium text-[var(--stgm-foreground,#171717)]">
+          {entry.taskName}
+        </span>
+      </div>
+
+      {/* Duration chip */}
+      <span className="w-14 shrink-0 text-right text-[10px] tabular-nums text-[var(--stgm-muted-foreground,#737373)]">
+        {entry.status === "skipped" || entry.status === "not_reached"
+          ? "—"
+          : formatDuration(entry.durationMs || effectiveDuration)}
+      </span>
+
+      {/* Cost chip (only when non-zero) */}
+      <span className="w-12 shrink-0 text-right text-[10px] tabular-nums text-[var(--stgm-muted-foreground,#737373)]">
+        {entry.costMicros > BIGINT_ZERO
+          ? formatMicroUsd(entry.costMicros)
+          : ""}
+      </span>
+
+      {/* Bar column */}
+      <div className="min-w-0 flex-1">
+        <WaterfallBar
+          entry={entry}
+          totalMs={totalMs}
+          nowMs={nowMs}
+        />
+      </div>
+    </button>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Status dot
+// ---------------------------------------------------------------------------
+
+function StatusDot({ status }: { readonly status: WaterfallEntry["status"] }) {
+  const color = STATUS_DOT_COLORS[status] ?? "bg-[var(--stgm-muted,#d4d4d4)]";
+  return (
+    <span
+      className={cn("inline-block size-1.5 shrink-0 rounded-full", color)}
+      aria-hidden="true"
+    />
+  );
+}
+
+const STATUS_DOT_COLORS: Record<string, string> = {
+  completed: "bg-[var(--stgm-success,#22c55e)]",
+  running: "bg-[var(--stgm-primary,#3b82f6)]",
+  failed: "bg-[var(--stgm-destructive,#ef4444)]",
+  retrying: "bg-[var(--stgm-warning,#f59e0b)]",
+  waiting_approval: "bg-[var(--stgm-warning,#f59e0b)]",
+  skipped: "bg-[var(--stgm-muted,#d4d4d4)]",
+  pending: "bg-[var(--stgm-muted,#d4d4d4)]",
+  not_reached: "bg-[var(--stgm-muted,#d4d4d4)]",
+};