@shipfox/client-workflows 19.0.0 → 20.0.0

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

@@ -6,21 +6,17 @@ import {
   type ListenerStatus,
   WORKFLOW_JOB_STATUSES,
 } from './job.js';
-import {
-  elapsedTimeFromTimestamps,
-  type JobExecutionDisplayDuration,
-  type JobExecutionStatus,
-} from './job-execution.js';
+import type {JobExecutionStatus} 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];
 /**
- * `listening` and `queued` are display-only: the API never returns them, and both are derived
- * from the jobs a run already carries.
+ * `listening` is display-only: the API never returns it, and it is derived from the listener
+ * state a job already carries.
  */
-export type WorkflowDisplayStatus = WorkflowStatus | 'listening' | 'queued';
+export type WorkflowDisplayStatus = WorkflowStatus | 'listening';
 
 export const WORKFLOW_RUN_STATUSES = [
   'pending',
@@ -34,7 +30,6 @@ export const WORKFLOW_DISPLAY_STATUSES = [
   ...WORKFLOW_RUN_STATUSES,
   ...WORKFLOW_JOB_STATUSES,
   'listening',
-  'queued',
 ] as const satisfies readonly WorkflowDisplayStatus[];
 
 export const TERMINAL_WORKFLOW_RUN_STATUSES = [
@@ -87,11 +82,14 @@ export interface WorkflowRunJobStatusCount {
  * of them.
  *
  * `preview` is capped by the API, so `preview.length` is not the job count and the strip
- * reads `total` and `statusCounts` for anything it says rather than anything it draws.
+ * reads `total` and `statusCounts` for anything it says rather than anything it draws. The API
+ * also reports whether any job execution has started because a terminal `cancelled` job can have
+ * started work even though its job status does not preserve that distinction.
  */
 export interface WorkflowRunJobs {
   preview: WorkflowRunJobSummary[];
   statusCounts: WorkflowRunJobStatusCount[];
+  hasStartedJobExecution: boolean;
   total: number;
 }
 
@@ -132,6 +130,7 @@ export interface WorkflowRunDetail extends WorkflowRun {
   latestAttempt: number;
   runAttempt: WorkflowRunAttempt;
   jobs: Job[];
+  hasStartedJobExecution: boolean;
 }
 
 export interface WorkflowRunListPage {
@@ -198,129 +197,3 @@ 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: JobDisplayStatus[];
-  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;
-}

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

@@ -103,6 +103,7 @@ describe('workflow run model mapping', () => {
       latest_attempt: 4,
       started_at: '2026-05-07T01:01:10.000Z',
       finished_at: null,
+      has_started_job_execution: true,
     });
 
     const run = toWorkflowRunListItem(dto);
@@ -122,6 +123,7 @@ describe('workflow run model mapping', () => {
     expect(run).not.toHaveProperty('startedAt');
     expect(run).not.toHaveProperty('finishedAt');
     expect(run).not.toHaveProperty('displayDuration');
+    expect(run.jobs.hasStartedJobExecution).toBe(true);
     expect(run.runAttempt.displayDuration).toEqual({
       state: 'live',
       fromIso: '2026-05-07T01:01:10.000Z',

package/src/core/workflow-run.ts

@@ -59,14 +59,11 @@ export type {
   WorkflowDisplayStatus,
   WorkflowRun,
   WorkflowRunDetail,
-  WorkflowRunDisplay,
-  WorkflowRunDisplayDuration,
   WorkflowRunJobStatusCount,
   WorkflowRunJobSummary,
   WorkflowRunJobs,
   WorkflowRunListItem,
   WorkflowRunListPage,
-  WorkflowRunProgress,
   WorkflowRunRecord,
   WorkflowRunRerunMode,
   WorkflowRunStatus,
@@ -75,19 +72,14 @@ export type {
   WorkflowStatus,
 } from './entities/workflow-run.js';
 export {
-  deriveWorkflowRunDisplay,
   isWorkflowRunTerminal,
   isWorkflowStatus,
   TERMINAL_WORKFLOW_RUN_STATUSES,
   WORKFLOW_DISPLAY_STATUSES,
   WORKFLOW_RUN_STATUSES,
   workflowRunActor,
-  workflowRunBlockingJob,
   workflowRunBranchLabel,
   workflowRunCommitLabel,
-  workflowRunDetailDisplay,
-  workflowRunFirstStartedAt,
-  workflowRunListItemDisplay,
   workflowRunTriggerDisplayLabel,
   workflowRunTriggerLabel,
 } from './entities/workflow-run.js';

package/src/hooks/api/workflow-run-mapper.ts

@@ -119,6 +119,7 @@ export function toWorkflowRunListItem(dto: WorkflowRunListItemDto): WorkflowRunL
         position: job.position,
       })),
       statusCounts,
+      hasStartedJobExecution: dto.has_started_job_execution ?? true,
       // Derived rather than sent: the counts already cover every job, and a separate total
       // would be a second source of truth that could disagree with them.
       total: statusCounts.reduce((sum, entry) => sum + entry.count, 0),
@@ -146,6 +147,7 @@ export function toWorkflowRunDetail(dto: WorkflowRunDetailResponseDto): Workflow
     latestAttempt: dto.latest_attempt,
     runAttempt: toWorkflowRunAttempt(dto.run_attempt),
     jobs: dto.jobs.map(toJob),
+    hasStartedJobExecution: dto.has_started_job_execution ?? true,
   };
 }
 

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

@@ -358,7 +358,7 @@ function buildTempRun({
     updatedAt: createdAt,
     isTemporary: true,
     // The optimistic row genuinely has no jobs yet: the server has not planned the graph.
-    jobs: {preview: [], statusCounts: [], total: 0},
+    jobs: {preview: [], statusCounts: [], hasStartedJobExecution: false, total: 0},
     runAttempt: new WorkflowRunAttemptSummary({
       workflowRunId: id,
       attempt: 1,

package/test/fixtures/workflow-run.ts

@@ -82,6 +82,7 @@ export function workflowRunDto(
     jobs: [],
     job_status_counts: [],
     job_display_status_counts: [],
+    has_started_job_execution: false,
     ...overrides,
   };
 }
@@ -136,10 +137,18 @@ function executionStatusForFixtureStatus(
  *
  * Built from one list so the two can never disagree. A fixture whose counts contradicted its
  * preview would hide exactly the bug the split exists to prevent.
+ *
+ * `has_started_job_execution` follows the statuses where they settle it: `succeeded` and `failed`
+ * cannot be reached without running. `pending`, `skipped`, and `cancelled` leave it open, which is
+ * the ambiguity the server flag exists to resolve, so those default to not started and a case that
+ * needs the other reading overrides it.
  */
 export function workflowRunJobsFixture(
   statuses: readonly JobStatusDto[],
-): Pick<WorkflowRunListItemDto, 'jobs' | 'job_status_counts' | 'job_display_status_counts'> {
+): Pick<
+  WorkflowRunListItemDto,
+  'jobs' | 'job_status_counts' | 'job_display_status_counts' | 'has_started_job_execution'
+> {
   const counts = new Map<JobStatusDto, number>();
   for (const status of statuses) counts.set(status, (counts.get(status) ?? 0) + 1);
 
@@ -152,6 +161,9 @@ export function workflowRunJobsFixture(
     jobs: preview,
     job_status_counts: [...counts.entries()].map(([status, count]) => ({status, count})),
     job_display_status_counts: [...counts.entries()].map(([status, count]) => ({status, count})),
+    has_started_job_execution: statuses.some(
+      (status) => status === 'running' || status === 'succeeded' || status === 'failed',
+    ),
   };
 }
 
@@ -159,7 +171,10 @@ export function workflowRunJobsFixture(
 export function workflowRunJobsOfStatus(
   count: number,
   status: JobStatusDto = 'succeeded',
-): Pick<WorkflowRunListItemDto, 'jobs' | 'job_status_counts' | 'job_display_status_counts'> {
+): Pick<
+  WorkflowRunListItemDto,
+  'jobs' | 'job_status_counts' | 'job_display_status_counts' | 'has_started_job_execution'
+> {
   return workflowRunJobsFixture(Array.from({length: count}, () => status));
 }
 
@@ -189,7 +204,12 @@ export function workflowRunListPage(
 export function workflowRunDetailDto(
   overrides: Partial<WorkflowRunDetailResponseDto> = {},
 ): WorkflowRunDetailResponseDto {
-  const {jobs, run_attempt: runAttemptOverride, ...runOverrides} = overrides;
+  const {
+    jobs,
+    run_attempt: runAttemptOverride,
+    has_started_job_execution: hasStartedOverride,
+    ...runOverrides
+  } = overrides;
   const run = workflowRunDto(runOverrides);
 
   return {
@@ -205,6 +225,13 @@ export function workflowRunDetailDto(
         finished_at: run.finished_at,
       }),
     jobs: jobs ?? [],
+    // Follows the executions the case actually built, so the fixture cannot claim a run started
+    // while carrying no execution that did.
+    has_started_job_execution:
+      hasStartedOverride ??
+      (jobs ?? []).some((job) =>
+        job.job_executions.some((execution) => execution.started_at != null),
+      ),
   };
 }