@shipfox/client-workflows 0.2.0

package/src/hooks/api/workflow-runs.ts

@@ -0,0 +1,485 @@
+import type {
+  RerunWorkflowRunBodyDto,
+  WorkflowRunAttemptsResponseDto,
+  WorkflowRunDetailResponseDto,
+  WorkflowRunDto,
+  WorkflowRunListResponseDto,
+  WorkflowRunRerunModeDto,
+  WorkflowRunResponseDto,
+} from '@shipfox/api-workflows-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {
+  type InfiniteData,
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query';
+import {
+  isWorkflowRunTerminal,
+  toWorkflowRunAttempt,
+  toWorkflowRunDetail,
+  toWorkflowRunListItem,
+  toWorkflowRunListPage,
+  type WorkflowRun,
+  type WorkflowRunAttempt,
+  type WorkflowRunDetail,
+  type WorkflowRunListPage,
+  type WorkflowRunStatus,
+} from '#core/workflow-run.js';
+
+export interface WorkflowRunFilters {
+  status?: WorkflowRunStatus | undefined;
+  definitionId?: string | undefined;
+  triggerSource?: string | undefined;
+  createdFrom?: string | undefined;
+  createdTo?: string | undefined;
+}
+
+export const workflowRunsQueryKeys = {
+  all: ['workflow-runs'] as const,
+  lists: (projectId: string) => [...workflowRunsQueryKeys.all, 'list', projectId] as const,
+  list: (projectId: string, filters: WorkflowRunFilters) =>
+    [...workflowRunsQueryKeys.lists(projectId), normalizeFilters(filters)] as const,
+  detail: (workflowRunId: string, runAttempt?: number | undefined) =>
+    [...workflowRunsQueryKeys.all, 'detail', workflowRunId, runAttempt ?? null] as const,
+  attempts: (workflowRunId: string) =>
+    [...workflowRunsQueryKeys.all, 'attempts', workflowRunId] as const,
+};
+
+function normalizeFilters(filters: WorkflowRunFilters) {
+  return {
+    status: filters.status ?? null,
+    definitionId: filters.definitionId ?? null,
+    triggerSource: filters.triggerSource ?? null,
+    createdFrom: filters.createdFrom ?? null,
+    createdTo: filters.createdTo ?? null,
+  };
+}
+
+function appendFilters(params: URLSearchParams, filters: WorkflowRunFilters) {
+  if (filters.status) params.set('status', filters.status);
+  if (filters.definitionId) params.set('definition_id', filters.definitionId);
+  if (filters.triggerSource) params.set('trigger_source', filters.triggerSource);
+  if (filters.createdFrom) params.set('created_from', filters.createdFrom);
+  if (filters.createdTo) params.set('created_to', filters.createdTo);
+}
+
+async function listWorkflowRunsDto({
+  projectId,
+  filters,
+  limit = 50,
+  cursor,
+  signal,
+}: {
+  projectId: string;
+  filters: WorkflowRunFilters;
+  limit?: number;
+  cursor?: string | undefined;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams({project_id: projectId, limit: String(limit)});
+  if (cursor) params.set('cursor', cursor);
+  appendFilters(params, filters);
+  return await apiRequest<WorkflowRunListResponseDto>(`/workflows/runs?${params.toString()}`, {
+    signal,
+  });
+}
+
+/**
+ * Fire the manual trigger of a workflow definition.
+ *
+ * The server resolves the manual subscription by definition id (workflows
+ * may declare at most one manual trigger). `inputs` are forwarded to the
+ * run when provided.
+ */
+export async function fireManualWorkflow({
+  definitionId,
+  inputs,
+}: {
+  definitionId: string;
+  inputs?: Record<string, unknown>;
+}) {
+  return await apiRequest<{workflow_run_id: string}>(
+    `/workflow-definitions/${definitionId}/fire-manual`,
+    {
+      method: 'POST',
+      body: inputs ? {inputs} : {},
+    },
+  );
+}
+
+const ACTIVE_POLL_MS = 4_000;
+const IDLE_POLL_MS = 30_000;
+
+type RunListInfinite = InfiniteData<WorkflowRunListResponseDto, string | undefined>;
+
+function toWorkflowRunInfiniteData(
+  data: InfiniteData<WorkflowRunListResponseDto, string | undefined>,
+): InfiniteData<WorkflowRunListPage, string | undefined> {
+  return {
+    ...data,
+    pages: data.pages.map(toWorkflowRunListPage),
+  };
+}
+
+export function useWorkflowRunsInfiniteQuery(
+  projectId: string | undefined,
+  filters: WorkflowRunFilters,
+  limit = 50,
+) {
+  // Polling is owned by react-query, not the page. Polling fast (4s) while
+  // any non-terminal run is visible covers state transitions; polling slow
+  // (30s) when idle covers brand-new external runs (webhook/schedule
+  // triggers) without leaving the list stale.
+  //
+  // We disable polling once the user has loaded more than one page. With
+  // cursor pagination the cursor that bounds page 1 was computed from
+  // page 0's last row; if a refetch shifts that boundary, a small range
+  // of rows can drop into a between-pages gap. Users who scrolled into
+  // history opted into "reading mode": pause until they refocus, filter,
+  // or scroll back.
+  return useInfiniteQuery({
+    queryKey: projectId
+      ? workflowRunsQueryKeys.list(projectId, filters)
+      : [...workflowRunsQueryKeys.all, 'list'],
+    enabled: Boolean(projectId),
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({pageParam, signal}) =>
+      listWorkflowRunsDto({projectId: projectId ?? '', filters, limit, cursor: pageParam, signal}),
+    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+    select: toWorkflowRunInfiniteData,
+    placeholderData: keepPreviousData,
+    staleTime: 2_000,
+    refetchOnWindowFocus: true,
+    refetchInterval: (query) => {
+      const data = query.state.data;
+      if (!data || data.pages.length > 1) return false;
+      const hasActive = data.pages.some((page) =>
+        page.runs.some((run) => !isWorkflowRunTerminal(run.status)),
+      );
+      return hasActive ? ACTIVE_POLL_MS : IDLE_POLL_MS;
+    },
+    refetchIntervalInBackground: false,
+  });
+}
+
+async function getWorkflowRunDto({
+  workflowRunId,
+  runAttempt,
+  signal,
+}: {
+  workflowRunId: string;
+  runAttempt?: number | undefined;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams();
+  if (runAttempt) params.set('attempt', String(runAttempt));
+  const query = params.size > 0 ? `?${params.toString()}` : '';
+  return await apiRequest<WorkflowRunDetailResponseDto>(
+    `/workflows/runs/${workflowRunId}${query}`,
+    {
+      signal,
+    },
+  );
+}
+
+async function getWorkflowRunAttemptsDto({
+  workflowRunId,
+  signal,
+}: {
+  workflowRunId: string;
+  signal?: AbortSignal;
+}) {
+  return await apiRequest<WorkflowRunAttemptsResponseDto>(
+    `/workflows/runs/${workflowRunId}/attempts`,
+    {
+      signal,
+    },
+  );
+}
+
+async function cancelWorkflowRunDto({workflowRunId}: {workflowRunId: string}) {
+  return await apiRequest<WorkflowRunDto>(`/workflows/runs/${workflowRunId}/cancel`, {
+    method: 'POST',
+  });
+}
+
+export async function rerunWorkflowRun({
+  workflowRunId,
+  mode,
+}: {
+  workflowRunId: string;
+  mode: WorkflowRunRerunModeDto;
+}) {
+  return await apiRequest<WorkflowRunResponseDto>(`/workflows/runs/${workflowRunId}/rerun`, {
+    method: 'POST',
+    body: {mode} satisfies RerunWorkflowRunBodyDto,
+  });
+}
+
+export function useRerunWorkflowRunMutation(projectId: string) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: rerunWorkflowRun,
+    onSuccess: async (_run, variables) => {
+      await Promise.all([
+        queryClient.invalidateQueries({queryKey: workflowRunsQueryKeys.lists(projectId)}),
+        queryClient.invalidateQueries({
+          queryKey: workflowRunsQueryKeys.detail(variables.workflowRunId),
+        }),
+        queryClient.invalidateQueries({
+          queryKey: workflowRunsQueryKeys.attempts(variables.workflowRunId),
+        }),
+      ]);
+    },
+  });
+}
+
+function filtersAcceptManualPendingRun(
+  filters: WorkflowRunFilters,
+  definitionId: string,
+  now: Date,
+): boolean {
+  if (filters.status && filters.status !== 'pending') return false;
+  if (filters.definitionId && filters.definitionId !== definitionId) return false;
+  if (filters.triggerSource && filters.triggerSource !== 'manual') return false;
+  if (filters.createdFrom && Date.parse(filters.createdFrom) > now.getTime()) return false;
+  if (filters.createdTo && Date.parse(filters.createdTo) < now.getTime()) return false;
+  return true;
+}
+
+function buildTempRun({
+  projectId,
+  definitionId,
+  name,
+  createdAt,
+}: {
+  projectId: string;
+  definitionId: string;
+  name: string;
+  createdAt: string;
+}): WorkflowRunDto {
+  return {
+    id: `temp-${cryptoRandomId()}`,
+    project_id: projectId,
+    definition_id: definitionId,
+    name,
+    status: 'pending',
+    current_attempt: 1,
+    latest_attempt: 1,
+    trigger_provider: null,
+    trigger_source: 'manual',
+    trigger_event: 'fire',
+    trigger_payload: {source: 'manual', event: 'fire'},
+    inputs: null,
+    source_snapshot: null,
+    created_at: createdAt,
+    updated_at: createdAt,
+    started_at: null,
+    finished_at: null,
+  };
+}
+
+function cryptoRandomId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+export interface FireManualWorkflowVariables {
+  projectId: string;
+  definitionId: string;
+  inputs?: Record<string, unknown>;
+}
+
+export function useFireManualWorkflowMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (variables: FireManualWorkflowVariables) =>
+      fireManualWorkflow(
+        variables.inputs
+          ? {definitionId: variables.definitionId, inputs: variables.inputs}
+          : {definitionId: variables.definitionId},
+      ),
+    onMutate: (variables) => {
+      const definitionName = lookupDefinitionName(
+        queryClient,
+        variables.projectId,
+        variables.definitionId,
+      );
+      const createdAt = new Date().toISOString();
+      const tempRun = buildTempRun({
+        projectId: variables.projectId,
+        definitionId: variables.definitionId,
+        name: definitionName ?? 'New run',
+        createdAt,
+      });
+
+      const listsKey = workflowRunsQueryKeys.lists(variables.projectId);
+      const touchedQueryKeys: Array<readonly unknown[]> = [];
+
+      const entries = queryClient.getQueriesData<RunListInfinite>({queryKey: listsKey});
+      const now = new Date(createdAt);
+      for (const [queryKey] of entries) {
+        const filters = readFiltersFromKey(queryKey);
+        if (!filters) continue;
+        if (!filtersAcceptManualPendingRun(filters, variables.definitionId, now)) continue;
+
+        touchedQueryKeys.push(queryKey);
+        queryClient.setQueryData<RunListInfinite>(queryKey, (current) => {
+          if (!current || current.pages.length === 0) return current;
+          const firstPage = current.pages[0];
+          if (!firstPage) return current;
+          const nextFirstPage: WorkflowRunListResponseDto = {
+            ...firstPage,
+            runs: [tempRun, ...firstPage.runs],
+            filtered_total_count:
+              firstPage.filtered_total_count != null ? firstPage.filtered_total_count + 1 : null,
+          };
+          return {...current, pages: [nextFirstPage, ...current.pages.slice(1)]};
+        });
+      }
+
+      return {tempWorkflowRunId: tempRun.id, touchedQueryKeys};
+    },
+    onError: (_error, _variables, context) => {
+      if (!context) return;
+      for (const queryKey of context.touchedQueryKeys) {
+        queryClient.setQueryData<RunListInfinite>(queryKey, (current) => {
+          if (!current) return current;
+          let removedCount = 0;
+          const pages = current.pages.map((page) => {
+            const runs = page.runs.filter((run) => {
+              if (run.id !== context.tempWorkflowRunId) return true;
+              removedCount += 1;
+              return false;
+            });
+            if (runs.length === page.runs.length) return page;
+            return {
+              ...page,
+              runs,
+              filtered_total_count:
+                page.filtered_total_count != null
+                  ? Math.max(0, page.filtered_total_count - removedCount)
+                  : null,
+            };
+          });
+          if (removedCount === 0) return current;
+          return {...current, pages};
+        });
+      }
+    },
+    onSuccess: (_data, variables) => {
+      void queryClient.invalidateQueries({
+        queryKey: workflowRunsQueryKeys.lists(variables.projectId),
+      });
+    },
+  });
+}
+
+function readFiltersFromKey(queryKey: readonly unknown[]): WorkflowRunFilters | null {
+  if (queryKey.length < 4) return null;
+  const normalized = queryKey[3];
+  if (!normalized || typeof normalized !== 'object') return null;
+  const obj = normalized as Record<string, unknown>;
+  return {
+    status: (obj.status as WorkflowRunStatus | null) ?? undefined,
+    definitionId: (obj.definitionId as string | null) ?? undefined,
+    triggerSource: (obj.triggerSource as string | null) ?? undefined,
+    createdFrom: (obj.createdFrom as string | null) ?? undefined,
+    createdTo: (obj.createdTo as string | null) ?? undefined,
+  };
+}
+
+function lookupDefinitionName(
+  queryClient: ReturnType<typeof useQueryClient>,
+  projectId: string,
+  definitionId: string,
+): string | undefined {
+  const entries = queryClient.getQueriesData<
+    InfiniteData<{definitions: Array<{id: string; project_id: string; name: string}>}>
+  >({queryKey: ['definitions', 'list', projectId]});
+  for (const [, data] of entries) {
+    if (!data) continue;
+    for (const page of data.pages) {
+      const match = page.definitions.find((d) => d.id === definitionId);
+      if (match) return match.name;
+    }
+  }
+  return undefined;
+}
+
+export function useWorkflowRunQuery(workflowRunId: string | undefined) {
+  return useWorkflowRunAttemptQuery({workflowRunId, runAttempt: undefined});
+}
+
+export function useWorkflowRunAttemptQuery({
+  workflowRunId,
+  runAttempt,
+}: {
+  workflowRunId: string | undefined;
+  runAttempt?: number | undefined;
+}) {
+  // Poll a non-terminal run so the open run detail stays live (same cadence as the run
+  // list); stop once the run is terminal.
+  return useQuery({
+    queryKey: workflowRunId
+      ? workflowRunsQueryKeys.detail(workflowRunId, runAttempt)
+      : [...workflowRunsQueryKeys.all, 'detail'],
+    enabled: Boolean(workflowRunId),
+    queryFn: ({signal}) =>
+      getWorkflowRunDto({workflowRunId: workflowRunId ?? '', runAttempt, signal}),
+    select: toWorkflowRunDetail,
+    staleTime: 2_000,
+    refetchOnWindowFocus: true,
+    refetchInterval: (query) => {
+      const status: WorkflowRunDetail['runAttempt']['status'] | undefined =
+        query.state.data?.run_attempt.status;
+      if (!status) return false;
+      return isWorkflowRunTerminal(status) ? false : ACTIVE_POLL_MS;
+    },
+    refetchIntervalInBackground: false,
+  });
+}
+
+export function useWorkflowRunAttemptsQuery({
+  workflowRunId,
+  enabled,
+}: {
+  workflowRunId: string | undefined;
+  enabled: boolean;
+}) {
+  return useQuery({
+    queryKey: workflowRunId
+      ? workflowRunsQueryKeys.attempts(workflowRunId)
+      : [...workflowRunsQueryKeys.all, 'attempts'],
+    enabled: Boolean(workflowRunId) && enabled,
+    queryFn: ({signal}) => getWorkflowRunAttemptsDto({workflowRunId: workflowRunId ?? '', signal}),
+    select: (dto): WorkflowRunAttempt[] => dto.attempts.map(toWorkflowRunAttempt),
+    staleTime: 0,
+    refetchOnMount: true,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useCancelWorkflowRunMutation(run: WorkflowRun | undefined) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async () => {
+      if (!run) throw new Error('Workflow run is not loaded');
+      return toWorkflowRunListItem(await cancelWorkflowRunDto({workflowRunId: run.id}));
+    },
+    onSuccess: async () => {
+      if (!run) return;
+      await Promise.all([
+        queryClient.invalidateQueries({queryKey: workflowRunsQueryKeys.detail(run.id)}),
+        queryClient.invalidateQueries({queryKey: workflowRunsQueryKeys.lists(run.projectId)}),
+        queryClient.invalidateQueries({queryKey: workflowRunsQueryKeys.attempts(run.id)}),
+      ]);
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export type {
+  AgentConfigIssue,
+  JobDisplayDuration,
+  JobExecutionDisplayDuration,
+  JobExecutionStatus,
+  JobExecutionTime,
+  JobStatus,
+  Step,
+  StepAttempt,
+  StepAttemptDisplayDuration,
+  StepError,
+  StepErrorCategory,
+  StepErrorReason,
+  StepGateResult,
+  StepSourceLocation,
+  WorkflowRun,
+  WorkflowRunAttempt,
+  WorkflowRunDetail,
+  WorkflowRunListPage,
+  WorkflowRunStatus,
+  WorkflowSourceSnapshot,
+  WorkflowStatus,
+} from '#core/workflow-run.js';
+export {
+  isWorkflowRunTerminal,
+  isWorkflowStatus,
+  Job,
+  JobExecution,
+  TERMINAL_WORKFLOW_RUN_STATUSES,
+  WORKFLOW_RUN_STATUSES,
+  workflowRunShortId,
+  workflowRunTriggerLabel,
+} from '#core/workflow-run.js';
+export {
+  type FireManualWorkflowVariables,
+  fireManualWorkflow,
+  useCancelWorkflowRunMutation,
+  useFireManualWorkflowMutation,
+  useWorkflowRunAttemptsQuery,
+  useWorkflowRunQuery,
+  useWorkflowRunsInfiniteQuery,
+  type WorkflowRunFilters,
+  workflowRunsQueryKeys,
+} from './hooks/api/workflow-runs.js';
+export {WorkflowRunPage} from './pages/workflow-run-page.js';

package/src/page-harness-budget.test.ts

@@ -0,0 +1,33 @@
+import {readdirSync, readFileSync} from 'node:fs';
+import {dirname, join, relative} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+// Keeps page-harness imports intentional because each one mounts router, query,
+// and API-client providers around the test.
+const PAGE_HARNESS_ALLOWLIST = [
+  'src/components/workflow-run-summary/workflow-run-attempt-switcher.test.tsx',
+  'src/components/workflow-run-view/workflow-run-view.test.tsx',
+  'src/pages/workflow-run-page.test.tsx',
+];
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(srcDir);
+
+function collectTestFiles(dir: string): string[] {
+  return readdirSync(dir, {withFileTypes: true}).flatMap((entry) => {
+    const entryPath = join(dir, entry.name);
+    if (entry.isDirectory()) return collectTestFiles(entryPath);
+    return entry.isFile() && entry.name.endsWith('.test.tsx') ? [entryPath] : [];
+  });
+}
+
+describe('page harness budget', () => {
+  it('is imported only by the allowlisted page-wiring tests', () => {
+    const harnessImporters = collectTestFiles(srcDir)
+      .filter((file) => readFileSync(file, 'utf8').includes("'#test/pages"))
+      .map((file) => relative(packageRoot, file))
+      .sort();
+
+    expect(harnessImporters).toEqual(PAGE_HARNESS_ALLOWLIST);
+  });
+});

package/src/pages/workflow-run-first-time-use.tsx

@@ -0,0 +1,17 @@
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+
+/**
+ * Shown when a project has no workflow runs yet, in place of the empty rail and the
+ * perpetual detail skeleton the loading-driven layout would otherwise leave behind.
+ */
+export function WorkflowRunFirstTimeUse() {
+  return (
+    <div className="flex min-h-0 flex-1 items-center justify-center p-16">
+      <EmptyState
+        icon="pulseLine"
+        title="No workflow runs yet"
+        description="Runs will appear here once this project's workflows start running."
+      />
+    </div>
+  );
+}