@shipfox/api-workflows-dto 12.5.0 → 12.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows-dto",
   "license": "MIT",
-  "version": "12.5.0",
+  "version": "12.7.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   type JobStatusDto,
   type JobStatusReasonDto,
   jobDtoSchema,
+  jobExecutionStatusSchema,
   jobListeningBatchSchema,
   jobListeningSchema,
   jobModeSchema,
@@ -95,6 +96,7 @@ export {
   workflowRunDetailResponseSchema,
   workflowRunDtoSchema,
   workflowRunJobDetailDtoSchema,
+  workflowRunJobDisplayStatusCountDtoSchema,
   workflowRunJobExecutionDetailDtoSchema,
   workflowRunJobStatusCountDtoSchema,
   workflowRunJobSummaryDtoSchema,
@@ -109,6 +111,7 @@ export {
 export {type StepSourceLocationDto, stepSourceLocationSchema} from '#schemas/step.js';
 export {
   WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
+  type WorkflowRunJobDisplayStatusCountDto,
   type WorkflowRunJobStatusCountDto,
   type WorkflowRunJobSummaryDto,
   type WorkflowRunListItemDto,

package/src/schemas/index.ts

@@ -81,6 +81,7 @@ export {
   stepStatusReasonSchema,
 } from './step.js';
 export {
+  jobExecutionStatusSchema,
   type RerunWorkflowRunBodyDto,
   rerunWorkflowRunBodySchema,
   WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
@@ -89,6 +90,7 @@ export {
   type WorkflowRunAttemptDto,
   type WorkflowRunAttemptsResponseDto,
   type WorkflowRunDto,
+  type WorkflowRunJobDisplayStatusCountDto,
   type WorkflowRunJobStatusCountDto,
   type WorkflowRunJobSummaryDto,
   type WorkflowRunListItemDto,
@@ -104,6 +106,7 @@ export {
   workflowRunAttemptDtoSchema,
   workflowRunAttemptsResponseSchema,
   workflowRunDtoSchema,
+  workflowRunJobDisplayStatusCountDtoSchema,
   workflowRunJobStatusCountDtoSchema,
   workflowRunJobSummaryDtoSchema,
   workflowRunListItemSchema,
@@ -118,7 +121,6 @@ export {
 export {
   type JobExecutionDto,
   jobExecutionDtoSchema,
-  jobExecutionStatusSchema,
   type StepAttemptDetailResponseDto,
   stepAttemptDetailResponseSchema,
   type WorkflowRunDetailResponseDto,

package/src/schemas/workflow-run-detail.ts

@@ -3,15 +3,11 @@ import {evaluationTraceSchema} from './evaluation-trace.js';
 import {jobDtoSchema} from './job.js';
 import {workflowExecutionEventSchema} from './job-listening.js';
 import {stepAttemptDetailDtoSchema, stepAttemptDtoSchema, stepDtoSchema} from './step.js';
-import {workflowRunAttemptDtoSchema, workflowRunResponseSchema} from './workflow-run.js';
-
-export const jobExecutionStatusSchema = z.enum([
-  'pending',
-  'running',
-  'succeeded',
-  'failed',
-  'cancelled',
-]);
+import {
+  jobExecutionStatusSchema,
+  workflowRunAttemptDtoSchema,
+  workflowRunResponseSchema,
+} from './workflow-run.js';
 
 export const jobExecutionDtoSchema = z.object({
   id: z.string().uuid(),
@@ -76,6 +72,14 @@ export type WorkflowRunJobDetailDto = z.infer<typeof workflowRunJobDetailDtoSche
 export const workflowRunDetailResponseSchema = workflowRunResponseSchema.extend({
   run_attempt: workflowRunAttemptDtoSchema,
   jobs: z.array(workflowRunJobDetailDtoSchema),
+  /**
+   * Whether any job execution of this attempt reached its runner. Redundant with the executions
+   * below, and deliberately so: the server decides it once for both this response and the run
+   * list, which is what keeps the two surfaces from reaching different answers.
+   *
+   * Defaults to started for the same rollout reason as the list item's copy.
+   */
+  has_started_job_execution: z.boolean().optional().default(true),
 });
 
 export type WorkflowRunDetailResponseDto = z.infer<typeof workflowRunDetailResponseSchema>;

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

@@ -107,6 +107,9 @@ describe('workflow run list item schema', () => {
       key: `job-${position}`,
       name: null,
       status: 'succeeded' as const,
+      mode: 'one_shot' as const,
+      listener_status: 'inactive' as const,
+      execution_status: null,
       position,
     };
   }
@@ -117,10 +120,60 @@ describe('workflow run list item schema', () => {
       source_snapshot: null,
       jobs: [jobDto(0)],
       job_status_counts: [{status: 'succeeded', count: 1}],
+      has_started_job_execution: true,
     });
 
     expect(result.jobs).toHaveLength(1);
     expect(result.jobs[0]?.status).toBe('succeeded');
+    expect(result.jobs[0]?.execution_status).toBeNull();
+  });
+
+  test('carries execution evidence and listening state for display derivation', () => {
+    const result = workflowRunListItemSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: [
+        {
+          ...jobDto(0),
+          mode: 'listening',
+          listener_status: 'listening',
+          execution_status: 'running',
+        },
+      ],
+      job_status_counts: [{status: 'running', count: 1}],
+      job_display_status_counts: [{status: 'listening', count: 1}],
+    });
+
+    expect(result.jobs[0]).toMatchObject({
+      mode: 'listening',
+      listener_status: 'listening',
+      execution_status: 'running',
+    });
+    expect(result.job_status_counts).toEqual([{status: 'running', count: 1}]);
+    expect(result.job_display_status_counts).toEqual([{status: 'listening', count: 1}]);
+  });
+
+  test('accepts a pre-display-state API response during a mixed-version rollout', () => {
+    const {
+      mode: _mode,
+      listener_status: _listenerStatus,
+      execution_status: _executionStatus,
+      ...legacyJob
+    } = jobDto(0);
+
+    const result = workflowRunListItemSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: [legacyJob],
+      job_status_counts: [{status: 'running', count: 1}],
+    });
+
+    expect(result.jobs[0]).toMatchObject({
+      mode: 'one_shot',
+      listener_status: 'inactive',
+      execution_status: null,
+    });
+    expect(result.job_display_status_counts).toBeUndefined();
   });
 
   // The preview is a bounded slice, so counts describe jobs the payload never carried.
@@ -133,6 +186,7 @@ describe('workflow run list item schema', () => {
         {status: 'succeeded', count: 40},
         {status: 'failed', count: 2},
       ],
+      has_started_job_execution: true,
     });
 
     expect(result.job_status_counts).toHaveLength(2);
@@ -144,6 +198,7 @@ describe('workflow run list item schema', () => {
       source_snapshot: null,
       jobs: Array.from({length: WORKFLOW_RUN_JOB_PREVIEW_LIMIT + 1}, (_, index) => jobDto(index)),
       job_status_counts: [],
+      has_started_job_execution: false,
     });
 
     expect(result.success).toBe(false);

package/src/schemas/workflow-run.ts

@@ -1,5 +1,6 @@
 import {z} from 'zod';
 import {jobStatusSchema} from './job.js';
+import {jobModeSchema, listenerStatusSchema} from './job-listening.js';
 
 export const workflowRunStatusSchema = z.enum([
   'pending',
@@ -11,6 +12,14 @@ export const workflowRunStatusSchema = z.enum([
 
 export type WorkflowRunStatusDto = z.infer<typeof workflowRunStatusSchema>;
 
+export const jobExecutionStatusSchema = z.enum([
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
 export const workflowRunRerunModeSchema = z.enum(['all', 'failed']);
 
 export type WorkflowRunRerunModeDto = z.infer<typeof workflowRunRerunModeSchema>;
@@ -137,16 +146,22 @@ export const workflowRunAttemptsResponseSchema = z.object({
 export type WorkflowRunAttemptsResponseDto = z.infer<typeof workflowRunAttemptsResponseSchema>;
 
 // The run list renders a status glyph per job so a failing run can be read without being
-// opened, which needs the current attempt's jobs in graph order but none of their steps.
+// opened. Runtime state comes from the selected execution rather than the job verdict, while
+// mode and listener status let the client apply the same display rule as run detail. These
+// fields default to the pre-display-state contract so a web client can roll out before or
+// alongside an API deployment without rejecting an older response.
 export const workflowRunJobSummaryDtoSchema = z.object({
   id: z.string().uuid(),
   key: z.string(),
   name: z.string().nullable(),
   status: jobStatusSchema,
+  mode: jobModeSchema.optional().default('one_shot'),
+  listener_status: listenerStatusSchema.optional().default('inactive'),
+  execution_status: jobExecutionStatusSchema.nullable().optional().default(null),
   position: z.number().int().nonnegative(),
 });
 
-export type WorkflowRunJobSummaryDto = z.infer<typeof workflowRunJobSummaryDtoSchema>;
+export type WorkflowRunJobSummaryDto = z.input<typeof workflowRunJobSummaryDtoSchema>;
 
 /**
  * How many jobs a run list row carries in graph order.
@@ -158,7 +173,7 @@ export type WorkflowRunJobSummaryDto = z.infer<typeof workflowRunJobSummaryDtoSc
  */
 export const WORKFLOW_RUN_JOB_PREVIEW_LIMIT = 16;
 
-/** One status and how many of the run's jobs hold it, counted over all of them. */
+/** The persisted job verdict and how many of the run's jobs carry it, counted over all of them. */
 export const workflowRunJobStatusCountDtoSchema = z.object({
   status: jobStatusSchema,
   count: z.number().int().positive(),
@@ -166,14 +181,37 @@ export const workflowRunJobStatusCountDtoSchema = z.object({
 
 export type WorkflowRunJobStatusCountDto = z.infer<typeof workflowRunJobStatusCountDtoSchema>;
 
+/** One display status and how many of the run's jobs render it, counted over all of them. */
+export const workflowRunJobDisplayStatusCountDtoSchema = z.object({
+  status: jobStatusSchema.or(z.literal('listening')),
+  count: z.number().int().positive(),
+});
+
+export type WorkflowRunJobDisplayStatusCountDto = z.infer<
+  typeof workflowRunJobDisplayStatusCountDtoSchema
+>;
+
 export const workflowRunListItemSchema = workflowRunResponseSchema.extend({
   /** Up to `WORKFLOW_RUN_JOB_PREVIEW_LIMIT` jobs in graph order, not the whole set. */
   jobs: z.array(workflowRunJobSummaryDtoSchema).max(WORKFLOW_RUN_JOB_PREVIEW_LIMIT),
-  /** Counted over every job of the attempt, including those past the preview. */
+  /** Persisted verdict counts, kept stable so older web clients can consume new responses. */
   job_status_counts: z.array(workflowRunJobStatusCountDtoSchema),
+  /**
+   * Display-state counts over every job of the attempt, including those past the preview.
+   * Optional so a new web client can consume an older API response during rollout.
+   */
+  job_display_status_counts: z.array(workflowRunJobDisplayStatusCountDtoSchema).optional(),
+  /**
+   * Whether any job execution in the attempt reached its runner. A `cancelled` job does not say
+   * this on its own, so the counts above cannot answer it.
+   *
+   * Defaults to started, so an older API response during a rollout keeps the reading a run had
+   * before this field existed rather than claiming work that ran never began.
+   */
+  has_started_job_execution: z.boolean().optional().default(true),
 });
 
-export type WorkflowRunListItemDto = z.infer<typeof workflowRunListItemSchema>;
+export type WorkflowRunListItemDto = z.input<typeof workflowRunListItemSchema>;
 
 export const workflowRunListResponseSchema = z.object({
   runs: z.array(workflowRunListItemSchema),
@@ -181,7 +219,7 @@ export const workflowRunListResponseSchema = z.object({
   filtered_total_count: z.number().int().nonnegative().nullable(),
 });
 
-export type WorkflowRunListResponseDto = z.infer<typeof workflowRunListResponseSchema>;
+export type WorkflowRunListResponseDto = z.input<typeof workflowRunListResponseSchema>;
 
 const aggregateBucketSchema = z.object({
   value: z.string(),