@shipfox/client-workflows 14.0.1 → 16.0.0

package/src/components/job-detail/job-empty-states.tsx

@@ -0,0 +1,248 @@
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import type {Job, JobExecution, Step, StepError} from '#core/workflow-run.js';
+import {
+  AGENT_CONFIG_ISSUES,
+  deriveJobDisplayStatus,
+  deriveJobExecutionDisplayStatus,
+  STEP_ERROR_REASONS,
+} from '#core/workflow-run.js';
+import type {StepListEmptyState} from '../step-list/index.js';
+import {formatJobExecutionTime} from './job-execution-time-text.js';
+
+export function emptyStateForJob(
+  job: Job,
+  jobExecution: JobExecution,
+): StepListEmptyState | undefined {
+  if (job.carriedOver) {
+    return {
+      title: 'Carried over from a previous attempt',
+      description: 'This job did not execute in this run.',
+      status: 'succeeded',
+    };
+  }
+
+  const displayStatus =
+    job.mode === 'listening'
+      ? deriveJobExecutionDisplayStatus(jobExecution)
+      : deriveJobDisplayStatus(job);
+
+  if (jobExecution.status === 'running' && displayStatus === 'pending') {
+    return {
+      title: 'Runner preparing job',
+      description: 'A runner is assigned. Steps will appear here when work begins.',
+      status: displayStatus,
+    };
+  }
+
+  if (displayStatus === 'pending') {
+    return {
+      title: 'Waiting for this job to start',
+      description: 'Steps will appear here once the job starts.',
+      status: displayStatus,
+    };
+  }
+
+  if (displayStatus === 'running') {
+    return {
+      title: 'Waiting for the first step',
+      description: 'The first running step will appear here shortly.',
+      status: displayStatus,
+    };
+  }
+
+  if (displayStatus === 'cancelled') {
+    return {
+      title: 'Cancelled before start',
+      description: 'This job was cancelled before any step started.',
+      status: displayStatus,
+    };
+  }
+
+  if (displayStatus === 'failed') {
+    return {
+      title: 'Job failed before its first step started',
+      description: preStepFailureDescription(jobExecution.statusReason ?? job.statusReason),
+      status: displayStatus,
+    };
+  }
+
+  if (displayStatus === 'succeeded') {
+    return {
+      title: 'Completed without recorded steps',
+      description: `Execution #${jobExecution.sequence} succeeded before any step output was recorded.`,
+      status: displayStatus,
+    };
+  }
+
+  return undefined;
+}
+
+export function emptyStateForMissingExecution(job: Job): StepListEmptyState {
+  if (job.carriedOver) {
+    return {
+      title: 'Carried over from a previous attempt',
+      description: 'This job did not execute in this run.',
+      status: 'succeeded',
+    };
+  }
+
+  if (job.mode === 'listening' && job.listenerStatus === 'listening') {
+    return {
+      title: 'Waiting for trigger events',
+      description: 'Matching trigger events will create job executions here.',
+      status: deriveJobDisplayStatus(job),
+    };
+  }
+
+  if (job.mode === 'listening' && job.listenerStatus === 'resolved') {
+    return {
+      title: 'Listener resolved without executions',
+      description: 'No matching trigger event created a job execution before the listener stopped.',
+      status: job.status,
+    };
+  }
+
+  if (job.status === 'pending') {
+    return {
+      title: 'Waiting for this job to start',
+      description: 'No execution has been created for this job yet.',
+      status: 'pending',
+    };
+  }
+
+  if (job.status === 'skipped') {
+    return {
+      title: 'This job was skipped',
+      description: skippedJobDescription(job.statusReason),
+      status: 'skipped',
+    };
+  }
+
+  if (job.status === 'cancelled') {
+    return {
+      title: 'Cancelled before start',
+      description: 'This job was cancelled before an execution was created.',
+      status: 'cancelled',
+    };
+  }
+
+  return {
+    title: 'Execution details unavailable',
+    description: 'This job finished, but no job execution record is available.',
+    status: job.status,
+  };
+}
+
+export function skippedJobDescription(reason: Job['statusReason']): string {
+  switch (reason) {
+    case 'dependency_not_completed':
+      return 'A required job did not complete, so this job was skipped.';
+    case 'default_gate_rejected':
+      return 'A required job did not succeed, so this job was skipped.';
+    case 'condition_false':
+    case 'condition_rejected':
+      return 'The job condition did not match, so this job was skipped.';
+    case 'condition_errored':
+      return 'The job condition could not be evaluated, so this job was skipped.';
+    case 'user_cancelled':
+    case 'run_cancelled':
+    case 'timed_out':
+    case 'runner_lost':
+    case 'step_failed':
+    case 'unknown':
+    case null:
+      return 'This job did not start.';
+  }
+}
+
+function preStepFailureDescription(reason: string | null): string {
+  switch (reason) {
+    case 'runner_lost':
+      return 'The runner stopped responding before work began. Check runner availability before re-running the workflow.';
+    case 'timed_out':
+      return 'The job timed out before work began. Check runner capacity and timeout configuration before re-running the workflow.';
+    case 'user_cancelled':
+    case 'run_cancelled':
+      return 'The execution ended while the run was being cancelled.';
+    case 'step_failed':
+      return 'The execution failed before step details were recorded. Review run annotations before re-running the workflow.';
+    case 'condition_errored':
+      return 'The job condition could not be evaluated. Review run annotations before re-running the workflow.';
+    case 'dependency_not_completed':
+    case 'default_gate_rejected':
+      return 'A required job did not complete successfully. Resolve that failure before re-running the workflow.';
+    case 'condition_false':
+    case 'condition_rejected':
+      return 'The job condition did not match, so no work started.';
+    case 'unknown':
+    case null:
+      return 'Shipfox did not record a failure reason. Re-run only after checking the runner and workflow configuration.';
+    default:
+      return `The execution ended because ${humanizeFailureReason(reason)}. Resolve that condition before re-running the workflow.`;
+  }
+}
+
+function humanizeFailureReason(reason: string): string {
+  return reason.replaceAll('_', ' ').replaceAll('-', ' ');
+}
+
+export function CarriedOverStepPanel() {
+  return (
+    <EmptyState
+      className="min-h-120 rounded-8 border border-border-neutral-base bg-background-components-base px-16 py-20"
+      icon="componentLine"
+      title="Carried over from a previous attempt"
+      description="Not executed in this run."
+      variant="compact"
+    />
+  );
+}
+
+export function toSelectedAttemptError(
+  step: Step,
+  error: Record<string, unknown> | null,
+): StepError | null {
+  if (error === null) return null;
+
+  const rawReason = error.reason;
+  const parsedReason =
+    typeof rawReason === 'string' &&
+    STEP_ERROR_REASONS.has(rawReason as StepError['reason'] & string)
+      ? (rawReason as NonNullable<StepError['reason']>)
+      : undefined;
+  const rawAgentConfigIssue = error.agentConfigIssue ?? error.agent_config_issue;
+  const agentConfigIssue =
+    typeof rawAgentConfigIssue === 'string' &&
+    AGENT_CONFIG_ISSUES.has(rawAgentConfigIssue as NonNullable<StepError['agentConfigIssue']>)
+      ? (rawAgentConfigIssue as NonNullable<StepError['agentConfigIssue']>)
+      : undefined;
+  const exitCode = error.exitCode ?? error.exit_code;
+  const resolvedReason = parsedReason
+    ? parsedReason
+    : agentConfigIssue
+      ? 'agent_config_invalid'
+      : undefined;
+
+  if (resolvedReason === undefined) return null;
+
+  return {
+    message: typeof error.message === 'string' ? error.message : '',
+    exitCode: exitCode === null || typeof exitCode === 'number' ? exitCode : null,
+    signal: typeof error.signal === 'string' ? error.signal : undefined,
+    reason: resolvedReason,
+    agentConfigIssue,
+    category: step.type === 'setup' || step.type === 'checkout' ? 'setup' : 'user',
+  };
+}
+
+export function isAgentConfigFailure(step: Step, error: StepError | null): boolean {
+  return step.type === 'agent' && error?.reason === 'agent_config_invalid';
+}
+
+export function jobSucceededSummary(job: Job, execution: JobExecution): string | undefined {
+  if (job.carriedOver || execution.status !== 'succeeded') return undefined;
+  const stepCount = execution.steps.filter((step) => step.status === 'succeeded').length;
+  if (stepCount === 0) return undefined;
+  const duration = execution.displayDuration;
+  return `${stepCount} step${stepCount === 1 ? '' : 's'} succeeded${duration ? ` in ${formatJobExecutionTime(duration)}` : ''}`;
+}

package/src/components/job-detail/job-selection.test.ts

@@ -0,0 +1,188 @@
+import {
+  workflowJobDto,
+  workflowJobExecutionDto,
+  workflowRunDetail,
+  workflowStepAttemptDto,
+  workflowStepDto,
+} from '#test/fixtures/workflow-run.js';
+import {resolveWorkflowJobSelection, workflowJobLandingSelection} from './job-selection.js';
+
+describe('resolveWorkflowJobSelection', () => {
+  test('resolves a deep-linked step and exact attempt within the job', () => {
+    const step = workflowStepDto({
+      id: 'step-build',
+      attempts: [
+        workflowStepAttemptDto({id: 'attempt-1', step_id: 'step-build', attempt: 1}),
+        workflowStepAttemptDto({id: 'attempt-2', step_id: 'step-build', attempt: 2}),
+      ],
+    });
+    const job = workflowRunDetail({
+      jobs: [workflowJobDto({id: 'job-build', steps: [step]})],
+    }).jobs[0];
+    if (!job) throw new Error('Expected a job');
+
+    const resolved = resolveWorkflowJobSelection({
+      job,
+      selection: {
+        stepId: 'step-build',
+        stepAttemptId: 'attempt-2',
+        jobExecutionId: 'missing-execution',
+      },
+    });
+
+    expect(resolved.step?.id).toBe('step-build');
+    expect(resolved.attempt?.id).toBe('attempt-2');
+    expect(resolved.selectedAttemptId).toBe('attempt-2');
+  });
+
+  test('drops a step id belonging to another job and uses the default execution', () => {
+    const otherJobStep = workflowStepDto({id: 'step-other'});
+    const job = workflowRunDetail({
+      jobs: [
+        workflowJobDto({
+          id: 'job-build',
+          job_executions: [
+            workflowJobExecutionDto({id: 'execution-old', job_id: 'job-build', sequence: 1}),
+            workflowJobExecutionDto({id: 'execution-build', job_id: 'job-build', sequence: 2}),
+          ],
+        }),
+        workflowJobDto({id: 'job-other', steps: [otherJobStep], position: 1}),
+      ],
+    }).jobs[0];
+    if (!job) throw new Error('Expected a job');
+
+    const resolved = resolveWorkflowJobSelection({
+      job,
+      selection: {stepId: 'step-other', jobExecutionId: 'execution-old'},
+    });
+
+    expect(resolved.step).toBeUndefined();
+    expect(resolved.jobExecution?.id).toBe('execution-build');
+  });
+
+  test('a step wins over a valid execution id from another execution', () => {
+    const step = workflowStepDto({id: 'step-build', job_execution_id: 'execution-two'});
+    const job = workflowRunDetail({
+      jobs: [
+        workflowJobDto({
+          id: 'job-build',
+          job_executions: [
+            workflowJobExecutionDto({id: 'execution-one', job_id: 'job-build', sequence: 1}),
+            workflowJobExecutionDto({
+              id: 'execution-two',
+              job_id: 'job-build',
+              sequence: 2,
+              steps: [step],
+            }),
+          ],
+        }),
+      ],
+    }).jobs[0];
+    if (!job) throw new Error('Expected a job');
+
+    const resolved = resolveWorkflowJobSelection({
+      job,
+      selection: {stepId: 'step-build', jobExecutionId: 'execution-one'},
+    });
+
+    expect(resolved.jobExecution?.id).toBe('execution-two');
+  });
+});
+
+describe('workflowJobLandingSelection', () => {
+  test('selects the running step', () => {
+    const job = workflowRunDetail({
+      jobs: [
+        workflowJobDto({
+          steps: [
+            workflowStepDto({
+              id: 'step-finished',
+              status: 'succeeded',
+              attempts: [workflowStepAttemptDto({status: 'succeeded'})],
+            }),
+            workflowStepDto({
+              id: 'step-running',
+              position: 1,
+              status: 'running',
+              attempts: [workflowStepAttemptDto({id: 'attempt-running', status: 'running'})],
+            }),
+          ],
+        }),
+      ],
+    }).jobs[0]?.jobExecutions[0];
+
+    expect(workflowJobLandingSelection(job)).toEqual({
+      stepId: 'step-running',
+      attemptId: 'attempt-running',
+    });
+  });
+
+  test('selects the first failed step when no step is running', () => {
+    const job = workflowRunDetail({
+      jobs: [
+        workflowJobDto({
+          steps: [
+            workflowStepDto({
+              id: 'step-failed-first',
+              status: 'failed',
+              attempts: [workflowStepAttemptDto({id: 'attempt-failed-first', status: 'failed'})],
+            }),
+            workflowStepDto({
+              id: 'step-failed-second',
+              position: 1,
+              status: 'failed',
+              attempts: [workflowStepAttemptDto({status: 'failed'})],
+            }),
+          ],
+        }),
+      ],
+    }).jobs[0]?.jobExecutions[0];
+
+    expect(workflowJobLandingSelection(job)).toEqual({
+      stepId: 'step-failed-first',
+      attemptId: 'attempt-failed-first',
+    });
+  });
+
+  test('selects the current attempt for the first failed step', () => {
+    const job = workflowRunDetail({
+      jobs: [
+        workflowJobDto({
+          steps: [
+            workflowStepDto({
+              id: 'step-failed',
+              status: 'failed',
+              current_attempt: 2,
+              attempts: [
+                workflowStepAttemptDto({id: 'attempt-old', attempt: 1, status: 'failed'}),
+                workflowStepAttemptDto({id: 'attempt-current', attempt: 2, status: 'failed'}),
+              ],
+            }),
+          ],
+        }),
+      ],
+    }).jobs[0]?.jobExecutions[0];
+
+    expect(workflowJobLandingSelection(job)).toEqual({
+      stepId: 'step-failed',
+      attemptId: 'attempt-current',
+    });
+  });
+
+  test('selects nothing when every step succeeded', () => {
+    const job = workflowRunDetail({
+      jobs: [
+        workflowJobDto({
+          steps: [
+            workflowStepDto({
+              status: 'succeeded',
+              attempts: [workflowStepAttemptDto({status: 'succeeded'})],
+            }),
+          ],
+        }),
+      ],
+    }).jobs[0]?.jobExecutions[0];
+
+    expect(workflowJobLandingSelection(job)).toBeUndefined();
+  });
+});

package/src/components/job-detail/job-selection.ts

@@ -0,0 +1,96 @@
+import {
+  compareStepAttempts,
+  type Job,
+  type JobExecution,
+  resolveJobExecution,
+  resolveStepAttempt,
+  type Step,
+  type StepAttempt,
+} from '#core/workflow-run.js';
+import type {WorkflowJobSearch} from '#routes/inputs.js';
+
+export interface ResolvedWorkflowJobSelection {
+  jobExecution: JobExecution | undefined;
+  step: Step | undefined;
+  attempt: StepAttempt | undefined;
+  selectedAttemptId: string | null;
+}
+
+export interface WorkflowJobLandingSelection {
+  stepId: string;
+  attemptId: string;
+}
+
+/**
+ * Resolves job-scoped URL state. A valid step is authoritative over an execution id because a
+ * step carries its owning execution. A step from another job is ignored and falls back to the
+ * job's default execution rather than following a mangled URL into a different job.
+ */
+export function resolveWorkflowJobSelection({
+  job,
+  selection,
+}: {
+  job: Job;
+  selection: WorkflowJobSearch;
+}): ResolvedWorkflowJobSelection {
+  const step = selection.stepId ? findStep(job, selection.stepId) : undefined;
+  if (step) {
+    const attempt = resolveStepAttempt(step, selection.stepAttemptId);
+    const jobExecution = job.jobExecutions.find(
+      (candidate) => candidate.id === step.jobExecutionId,
+    );
+    return {
+      jobExecution: jobExecution ?? resolveJobExecution(job, undefined),
+      step,
+      attempt,
+      selectedAttemptId: attempt?.id ?? null,
+    };
+  }
+
+  return {
+    jobExecution: selection.stepId
+      ? resolveJobExecution(job, undefined)
+      : resolveJobExecution(job, selection.jobExecutionId),
+    step: undefined,
+    attempt: undefined,
+    selectedAttemptId: null,
+  };
+}
+
+/** Picks the running step, then the first failed step, for the first useful page state. */
+export function workflowJobLandingSelection(
+  jobExecution: JobExecution | undefined,
+): WorkflowJobLandingSelection | undefined {
+  if (!jobExecution) return undefined;
+
+  const entries = orderedStepAttempts(jobExecution);
+  const running = [...entries].reverse().find((entry) => entry.attempt.status === 'running');
+  const failedStep = [...jobExecution.steps]
+    .sort(compareSteps)
+    .find((step) => step.status === 'failed');
+  const failedAttempt = failedStep ? resolveStepAttempt(failedStep, undefined) : undefined;
+  const failed =
+    failedStep && failedAttempt ? {step: failedStep, attempt: failedAttempt} : undefined;
+  const selected = running ?? failed;
+  return selected ? {stepId: selected.step.id, attemptId: selected.attempt.id} : undefined;
+}
+
+function findStep(job: Job, stepId: string): Step | undefined {
+  for (const execution of job.jobExecutions) {
+    const step = execution.steps.find((candidate) => candidate.id === stepId);
+    if (step) return step;
+  }
+  return undefined;
+}
+
+function orderedStepAttempts(jobExecution: JobExecution) {
+  return [...jobExecution.steps]
+    .sort((left, right) => left.position - right.position || left.id.localeCompare(right.id))
+    .flatMap((step) =>
+      [...step.attempts].sort(compareStepAttempts).map((attempt) => ({step, attempt})),
+    );
+}
+
+function compareSteps(left: Step, right: Step): number {
+  return left.position - right.position || left.id.localeCompare(right.id);
+}

package/src/components/{workflow-run-view → job-detail}/step-attempt-log-panel.test.tsx

@@ -2,11 +2,12 @@ import {configureApiClient} from '@shipfox/client-api';
 import {type StepLogSnapshot, stepLogsQueryKeys} from '@shipfox/client-logs';
 import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
 import {act, cleanup, fireEvent, render, screen, waitFor} from '@testing-library/react';
-import type {ReactNode} from 'react';
+import {createRef, type ReactNode} from 'react';
 import {inlineLogBody, outputLine} from '#test/fixtures/logs.js';
 import {StepAttemptLogPanel} from './step-attempt-log-panel.js';
 
 const STEP_ID = '99999999-9999-4999-8999-999999999999';
+const WAITING_FOR_OUTPUT_PATTERN = /Waiting for output ·/;
 type TestLogRecord = StepLogSnapshot['records'][number];
 
 function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
@@ -51,11 +52,20 @@ function renderPanel(
   const wrapper = ({children}: {children: ReactNode}) => (
     <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
   );
+  const pageScrollRef = createRef<HTMLDivElement>();
 
   return {
     queryClient,
     ...render(
-      <StepAttemptLogPanel stepId={STEP_ID} attempt={1} attemptStatus="running" {...props} />,
+      <div ref={pageScrollRef}>
+        <StepAttemptLogPanel
+          stepId={STEP_ID}
+          attempt={1}
+          attemptStatus="running"
+          pageScrollRef={pageScrollRef}
+          {...props}
+        />
+      </div>,
       {wrapper},
     ),
   };
@@ -86,6 +96,19 @@ describe('StepAttemptLogPanel', () => {
     );
   });
 
+  test('shows elapsed waiting-for-output time for a running attempt', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-06-26T12:01:14.000Z'));
+    configureApiClient({
+      baseUrl: 'https://api.example.test',
+      fetchImpl: vi.fn(async () => jsonResponse({code: 'not-found'}, {status: 404})),
+    });
+
+    renderPanel({attemptStartedAt: '2026-06-26T11:59:00.000Z'});
+
+    expect(await screen.findByText(WAITING_FOR_OUTPUT_PATTERN)).toBeInTheDocument();
+    expect(screen.getByText('2m 14s')).toHaveAttribute('aria-hidden', 'true');
+  });
+
   test('waits for missing logs on a terminal attempt until the stream appears', async () => {
     const fetchImpl = vi
       .fn()
@@ -228,12 +251,12 @@ describe('StepAttemptLogPanel', () => {
     });
     const queryKey = stepLogsQueryKeys.detail(STEP_ID, 1);
     queryClient.setQueryData(queryKey, snapshot([outputRecord('first\n')]));
-    renderPanel({attemptStatus: 'succeeded'}, {queryClient});
-    const logRows = await screen.findByRole('log');
-    Object.defineProperty(logRows, 'scrollHeight', {configurable: true, value: 600});
-    Object.defineProperty(logRows, 'clientHeight', {configurable: true, value: 200});
-    logRows.scrollTop = 320;
-    fireEvent.scroll(logRows);
+    const {container} = renderPanel({attemptStatus: 'succeeded'}, {queryClient});
+    const pageScroll = container.firstElementChild as HTMLElement;
+    Object.defineProperty(pageScroll, 'scrollHeight', {configurable: true, value: 600});
+    Object.defineProperty(pageScroll, 'clientHeight', {configurable: true, value: 200});
+    pageScroll.scrollTop = 320;
+    fireEvent.scroll(pageScroll);
 
     act(() => {
       queryClient.setQueryData(
@@ -243,7 +266,7 @@ describe('StepAttemptLogPanel', () => {
     });
 
     await waitFor(() => expect(screen.getByText('second')).toBeInTheDocument());
-    expect(logRows.scrollTop).toBe(320);
+    expect(pageScroll.scrollTop).toBe(320);
   });
 
   test('passes failure anchoring for failed attempts', async () => {