@shipfox/client-workflows 14.0.1 → 16.0.0

package/src/components/workflow-status/status-visuals.ts

@@ -13,12 +13,15 @@ export interface WorkflowStatusVisual {
 
 // The status -> visual mapping shared by the run-header pill (color + label) and
 // WorkflowStatusIcon (which renders the glyph per kind). The exhaustive switch turns any new
-// status the API grows into (DESIGN.md section 9) into a compile error; reserve the `warning`
-// tone for the queued/awaiting-* states when they land.
+// status the API grows into (DESIGN.md section 9) into a compile error.
 export function getWorkflowStatusVisual(status: WorkflowDisplayStatus): WorkflowStatusVisual {
   switch (status) {
     case 'pending':
       return {kind: 'pending', label: 'Pending', dot: 'neutral', badge: 'neutral'};
+    // Waiting on a runner is the awaiting-* state the warning tone was held for: the run is
+    // live but nothing is executing, which is the operator's problem to see, not ours to hide.
+    case 'queued':
+      return {kind: 'queued', label: 'Queued', dot: 'warning', badge: 'warning'};
     case 'running':
       return {kind: 'running', label: 'Running', dot: 'info', badge: 'info'};
     case 'listening':

package/src/components/workflow-status/workflow-status-icon.stories.tsx

@@ -6,6 +6,7 @@ import {WorkflowStatusIcon} from './workflow-status-icon.js';
 
 const statuses: WorkflowDisplayStatus[] = [
   'pending',
+  'queued',
   'running',
   'listening',
   'succeeded',

package/src/components/workflow-status/workflow-status-icon.tsx

@@ -46,6 +46,8 @@ const PENDING_RING_MASK = 'radial-gradient(circle closest-side, transparent 0 52
 
 export interface WorkflowStatusIconProps {
   status: WorkflowDisplayStatus;
+  /** Accessible status label when the surrounding surface needs to name its scope. */
+  ariaLabel?: string | undefined;
   /** Optical diameter in px: 14 in the DAG node and run row. */
   size?: number;
   /** Pulsing halo for the running state. */
@@ -65,6 +67,7 @@ export interface WorkflowStatusIconProps {
  */
 export function WorkflowStatusIcon({
   status,
+  ariaLabel,
   size = 14,
   ripple = true,
   tooltip = true,
@@ -86,6 +89,24 @@ export function WorkflowStatusIcon({
         <Icon name="pulseLine" size={Math.max(8, Math.round(size * 0.7))} className="text-white" />
       </span>
     );
+  } else if (visual.kind === 'queued') {
+    // An hourglass in the same filled disc the listening state uses, so waiting reads as its
+    // own shape rather than as a pending ring that happens to be a different colour.
+    glyph = (
+      <span
+        className={cn(
+          'inline-flex shrink-0 items-center justify-center rounded-full bg-current',
+          box,
+          toneByVariant.warning,
+        )}
+      >
+        <Icon
+          name="hourglassLine"
+          size={Math.max(8, Math.round(size * 0.7))}
+          className="text-white"
+        />
+      </span>
+    );
   } else if (visual.kind === 'running') {
     glyph = <Dot variant="info" ripple={ripple} className={box} />;
   } else if (visual.kind === 'pending') {
@@ -112,7 +133,11 @@ export function WorkflowStatusIcon({
   }
 
   const indicator = (
-    <span role="img" aria-label={visual.label} className={cn('inline-flex shrink-0', className)}>
+    <span
+      role="img"
+      aria-label={ariaLabel ?? visual.label}
+      className={cn('inline-flex shrink-0', className)}
+    >
       {glyph}
     </span>
   );

package/src/core/entities/job-execution.ts

@@ -113,9 +113,24 @@ export function jobExecutionRunTimeFromTimestamps({
   finishedAt: string | null;
 }): JobExecutionTime | null {
   if (startedAt === null) return null;
-  if (finishedAt === null) return {state: 'live', fromIso: startedAt};
+  return elapsedTimeFromTimestamps({from: startedAt, to: finishedAt});
+}
+
+/**
+ * The elapsed span between two marks, still accruing while the closing mark is missing. Every
+ * duration this app shows is one of these, so queue time and run time measure the same way and
+ * only differ in which marks they read.
+ */
+export function elapsedTimeFromTimestamps({
+  from,
+  to,
+}: {
+  from: string;
+  to: string | null;
+}): JobExecutionTime | null {
+  if (to === null) return {state: 'live', fromIso: from};
 
-  const elapsed = durationBetween(startedAt, finishedAt);
+  const elapsed = durationBetween(from, to);
   return elapsed === null ? null : {state: 'fixed', elapsed};
 }
 

package/src/core/entities/step.ts

@@ -81,3 +81,29 @@ export interface Step {
   updatedAt: string;
   attempts: StepAttempt[];
 }
+
+export function resolveStepAttempt(
+  step: Step,
+  attemptId: string | undefined,
+): StepAttempt | undefined {
+  const attemptById = attemptId
+    ? step.attempts.find((attempt) => attempt.id === attemptId)
+    : undefined;
+  if (attemptById) return attemptById;
+
+  const currentAttempt = step.attempts.find((attempt) => attempt.attempt === step.currentAttempt);
+  if (currentAttempt) return currentAttempt;
+
+  return step.attempts.reduce<StepAttempt | undefined>((latest, attempt) => {
+    if (!latest) return attempt;
+    return compareStepAttempts(attempt, latest) > 0 ? attempt : latest;
+  }, undefined);
+}
+
+export function compareStepAttempts(left: StepAttempt, right: StepAttempt): number {
+  return (
+    left.attempt - right.attempt ||
+    left.executionOrder - right.executionOrder ||
+    left.id.localeCompare(right.id)
+  );
+}

package/src/core/entities/workflow-run-display.test.ts

@@ -0,0 +1,159 @@
+import {
+  workflowJob,
+  workflowJobExecutionDto,
+  workflowRunJobsFixture,
+  workflowRunListItem,
+} from '#test/fixtures/workflow-run.js';
+import {
+  workflowRunBlockingJob,
+  workflowRunDetailDisplay,
+  workflowRunListItemDisplay,
+} from './workflow-run.js';
+
+const ATTEMPT_STARTED_AT = '2026-05-07T01:00:00.000Z';
+const WORK_STARTED_AT = '2026-05-07T01:02:00.000Z';
+const FINISHED_AT = '2026-05-07T01:05:00.000Z';
+
+describe('workflowRunDetailDisplay', () => {
+  test('reads a running attempt whose jobs have not started as queued', () => {
+    const display = workflowRunDetailDisplay(
+      runDetail({jobs: [pendingJob()], startedAt: ATTEMPT_STARTED_AT}),
+    );
+
+    expect(display.status).toBe('queued');
+    expect(display.duration).toEqual({kind: 'queue', state: 'live', fromIso: ATTEMPT_STARTED_AT});
+  });
+
+  test('measures run time from the first execution, not from the attempt', () => {
+    const display = workflowRunDetailDisplay(
+      runDetail({
+        jobs: [startedJob(), pendingJob()],
+        startedAt: ATTEMPT_STARTED_AT,
+      }),
+    );
+
+    expect(display.status).toBe('running');
+    expect(display.duration).toEqual({kind: 'run', state: 'live', fromIso: WORK_STARTED_AT});
+  });
+
+  test('does not treat skipped jobs as started work', () => {
+    const display = workflowRunDetailDisplay(
+      runDetail({
+        jobs: [workflowJob({key: 'skipped', status: 'skipped'}), pendingJob()],
+        startedAt: ATTEMPT_STARTED_AT,
+      }),
+    );
+
+    expect(display.status).toBe('queued');
+    expect(display.duration).toMatchObject({kind: 'queue'});
+  });
+
+  test('keeps the queue reading for a run cancelled before anything started', () => {
+    const display = workflowRunDetailDisplay(
+      runDetail({
+        status: 'cancelled',
+        jobs: [pendingJob()],
+        startedAt: ATTEMPT_STARTED_AT,
+        finishedAt: FINISHED_AT,
+      }),
+    );
+
+    expect(display.status).toBe('cancelled');
+    expect(display.duration).toMatchObject({kind: 'queue', state: 'fixed'});
+  });
+
+  test('does not claim a queue when the run carries no jobs to prove one', () => {
+    const display = workflowRunDetailDisplay(runDetail({jobs: [], startedAt: ATTEMPT_STARTED_AT}));
+
+    expect(display.status).toBe('running');
+    expect(display.duration).toEqual({kind: 'run', state: 'live', fromIso: ATTEMPT_STARTED_AT});
+  });
+
+  test('has no duration before the attempt starts', () => {
+    expect(workflowRunDetailDisplay(runDetail({jobs: [pendingJob()]})).duration).toBeNull();
+  });
+});
+
+describe('workflowRunListItemDisplay', () => {
+  test('reaches the detail page verdict from job status counts alone', () => {
+    const run = workflowRunListItem({
+      status: 'running',
+      ...workflowRunJobsFixture(['pending', 'pending']),
+      started_at: ATTEMPT_STARTED_AT,
+    });
+
+    const display = workflowRunListItemDisplay(run);
+
+    expect(display.status).toBe('queued');
+    expect(display.duration).toEqual({kind: 'queue', state: 'live', fromIso: ATTEMPT_STARTED_AT});
+  });
+
+  test('stays running once any job has left pending', () => {
+    const run = workflowRunListItem({
+      status: 'running',
+      ...workflowRunJobsFixture(['succeeded', 'pending']),
+      started_at: ATTEMPT_STARTED_AT,
+    });
+
+    const display = workflowRunListItemDisplay(run);
+
+    expect(display.status).toBe('running');
+    expect(display.duration).toMatchObject({kind: 'run'});
+  });
+});
+
+describe('workflowRunBlockingJob', () => {
+  test('ignores finished queued executions when finding the blocking job', () => {
+    const historicalJob = workflowJob({
+      key: 'historical',
+      job_executions: [
+        workflowJobExecutionDto({
+          status: 'succeeded',
+          queued_at: '2026-05-07T00:59:00.000Z',
+          finished_at: '2026-05-07T01:00:00.000Z',
+        }),
+      ],
+    });
+    const currentJob = workflowJob({
+      key: 'current',
+      job_executions: [workflowJobExecutionDto({queued_at: '2026-05-07T01:01:00.000Z'})],
+    });
+
+    expect(workflowRunBlockingJob([historicalJob, currentJob])?.key).toBe('current');
+  });
+});
+
+function pendingJob() {
+  return workflowJob({
+    key: 'lint',
+    job_executions: [workflowJobExecutionDto({queued_at: ATTEMPT_STARTED_AT})],
+  });
+}
+
+function startedJob() {
+  return workflowJob({
+    key: 'build',
+    status: 'running',
+    job_executions: [
+      workflowJobExecutionDto({
+        status: 'running',
+        queued_at: ATTEMPT_STARTED_AT,
+        started_at: WORK_STARTED_AT,
+      }),
+    ],
+  });
+}
+
+function runDetail({
+  status = 'running',
+  jobs,
+  startedAt = null,
+  finishedAt = null,
+}: {
+  status?: 'running' | 'cancelled';
+  jobs: ReturnType<typeof workflowJob>[];
+  startedAt?: string | null;
+  finishedAt?: string | null;
+}) {
+  return {runAttempt: {status, startedAt, finishedAt}, jobs};
+}

package/src/core/entities/workflow-run.ts

@@ -1,10 +1,15 @@
 import {type Job, type JobStatus, WORKFLOW_JOB_STATUSES} from './job.js';
+import {elapsedTimeFromTimestamps, type JobExecutionDisplayDuration} from './job-execution.js';
 import type {WorkflowRunAttempt, WorkflowRunAttemptSummary} from './workflow-run-attempt.js';
 
 export type WorkflowRunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled';
 export type WorkflowRunRerunMode = 'all' | 'failed';
 export type WorkflowStatus = WorkflowRunStatus | (typeof WORKFLOW_JOB_STATUSES)[number];
-export type WorkflowDisplayStatus = WorkflowStatus | 'listening';
+/**
+ * `listening` and `queued` are display-only: the API never returns them, and both are derived
+ * from the jobs a run already carries.
+ */
+export type WorkflowDisplayStatus = WorkflowStatus | 'listening' | 'queued';
 
 export const WORKFLOW_RUN_STATUSES = [
   'pending',
@@ -14,6 +19,13 @@ export const WORKFLOW_RUN_STATUSES = [
   'cancelled',
 ] as const satisfies readonly WorkflowRunStatus[];
 
+export const WORKFLOW_DISPLAY_STATUSES = [
+  ...WORKFLOW_RUN_STATUSES,
+  ...WORKFLOW_JOB_STATUSES,
+  'listening',
+  'queued',
+] as const satisfies readonly WorkflowDisplayStatus[];
+
 export const TERMINAL_WORKFLOW_RUN_STATUSES = [
   'succeeded',
   'failed',
@@ -172,3 +184,129 @@ export function isWorkflowRunTerminal(status: WorkflowRunStatus): boolean {
 export function isWorkflowStatus(status: string): status is WorkflowStatus {
   return WORKFLOW_STATUSES.has(status as WorkflowStatus);
 }
+
+/**
+ * A run's headline duration, split the way a job's already is. An attempt's `startedAt` marks
+ * when the orchestrator picked the run up, not when work began, so a run whose jobs are all
+ * still waiting for a runner reads as queue time rather than as run time.
+ */
+export type WorkflowRunDisplayDuration = JobExecutionDisplayDuration;
+
+/** What every surface shows for a run, derived together so status and duration cannot disagree. */
+export interface WorkflowRunDisplay {
+  status: WorkflowDisplayStatus;
+  duration: WorkflowRunDisplayDuration | null;
+}
+
+/**
+ * The evidence a surface can offer about a run's progress.
+ *
+ * `jobStatuses` is what every surface has: the list carries status counts, the detail carries
+ * whole jobs. `firstStartedAt` is the detail's extra precision, and where it is absent the
+ * attempt's own mark stands in.
+ */
+export interface WorkflowRunProgress {
+  runStatus: WorkflowRunStatus;
+  startedAt: string | null;
+  finishedAt: string | null;
+  jobStatuses: JobStatus[];
+  firstStartedAt?: string | null | undefined;
+}
+
+/** When the run's earliest execution began, or null while none of them has. */
+export function workflowRunFirstStartedAt(jobs: Job[]): string | null {
+  let earliest: string | null = null;
+  let earliestMs = Number.POSITIVE_INFINITY;
+
+  for (const job of jobs) {
+    for (const {startedAt} of job.jobExecutions) {
+      if (startedAt === null) continue;
+      const startedMs = new Date(startedAt).getTime();
+      if (!Number.isFinite(startedMs) || startedMs >= earliestMs) continue;
+      earliest = startedAt;
+      earliestMs = startedMs;
+    }
+  }
+
+  return earliest;
+}
+
+/**
+ * Whether any work has begun. A run with no jobs on hand is a run whose jobs were not fetched,
+ * which is no evidence that nothing started, so it counts as started rather than claiming a
+ * queue this surface cannot see.
+ */
+function workflowRunHasStarted({jobStatuses, firstStartedAt}: WorkflowRunProgress): boolean {
+  if (firstStartedAt != null) return true;
+  if (jobStatuses.length === 0) return true;
+  return jobStatuses.some((status) => status !== 'pending' && status !== 'skipped');
+}
+
+/**
+ * The single rule behind every run readout. An attempt's `startedAt` marks when the
+ * orchestrator picked the run up, not when work began, so a run whose jobs are all still
+ * waiting reads as `Queued` for queue time. Calling that "running for 2h" sends an operator to
+ * debug a build that never began.
+ */
+export function deriveWorkflowRunDisplay(progress: WorkflowRunProgress): WorkflowRunDisplay {
+  const {runStatus, startedAt, finishedAt, firstStartedAt} = progress;
+  const hasStarted = workflowRunHasStarted(progress);
+  const status = runStatus === 'running' && !hasStarted ? 'queued' : runStatus;
+
+  if (startedAt === null) return {status, duration: null};
+
+  // A run cancelled before anything started keeps its queue reading rather than reporting a
+  // run that never was.
+  const time = elapsedTimeFromTimestamps({from: firstStartedAt ?? startedAt, to: finishedAt});
+  if (time === null) return {status, duration: null};
+
+  return {status, duration: {kind: hasStarted ? 'run' : 'queue', ...time}};
+}
+
+/** The run detail's reading: whole jobs, so queue and run time split on the first execution. */
+export function workflowRunDetailDisplay(run: {
+  runAttempt: Pick<WorkflowRunAttemptSummary, 'status' | 'startedAt' | 'finishedAt'>;
+  jobs: Job[];
+}): WorkflowRunDisplay {
+  return deriveWorkflowRunDisplay({
+    runStatus: run.runAttempt.status,
+    startedAt: run.runAttempt.startedAt,
+    finishedAt: run.runAttempt.finishedAt,
+    jobStatuses: run.jobs.map((job) => job.status),
+    firstStartedAt: workflowRunFirstStartedAt(run.jobs),
+  });
+}
+
+/**
+ * The run list's reading: status counts cover every job, not just the drawn preview, so a row
+ * reaches the same verdict as the detail page without fetching a single timestamp more.
+ */
+export function workflowRunListItemDisplay(run: WorkflowRunListItem): WorkflowRunDisplay {
+  return deriveWorkflowRunDisplay({
+    runStatus: run.status,
+    startedAt: run.runAttempt.startedAt,
+    finishedAt: run.runAttempt.finishedAt,
+    jobStatuses: run.jobs.statusCounts.filter(({count}) => count > 0).map(({status}) => status),
+  });
+}
+
+/**
+ * The job the run is waiting on: the one queued longest without starting. Named only so a
+ * queued run says what it waits for instead of showing a number with no subject.
+ */
+export function workflowRunBlockingJob(jobs: Job[]): Job | null {
+  let blocking: Job | null = null;
+  let queuedMs = Number.POSITIVE_INFINITY;
+
+  for (const job of jobs) {
+    for (const {queuedAt, startedAt, finishedAt} of job.jobExecutions) {
+      if (queuedAt === null || startedAt !== null || finishedAt !== null) continue;
+      const candidateMs = new Date(queuedAt).getTime();
+      if (!Number.isFinite(candidateMs) || candidateMs >= queuedMs) continue;
+      blocking = job;
+      queuedMs = candidateMs;
+    }
+  }
+
+  return blocking;
+}