@shipfox/api-workflows-dto 13.1.0 → 14.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows-dto",
   "license": "MIT",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "13.1.0",
+    "@shipfox/api-agent-dto": "14.0.0",
     "@shipfox/inter-module": "0.2.3"
   },
   "imports": {

package/src/index.ts

@@ -78,11 +78,13 @@ export {
   type WorkflowRunAttemptDto,
   type WorkflowRunAttemptsResponseDto,
   type WorkflowRunDetailResponseDto,
+  type WorkflowRunDevSourceDto,
   type WorkflowRunDto,
   type WorkflowRunJobDetailDto,
   type WorkflowRunJobExecutionDetailDto,
   type WorkflowRunListQueryDto,
   type WorkflowRunListResponseDto,
+  type WorkflowRunOriginDto,
   type WorkflowRunRerunModeDto,
   type WorkflowRunResponseDto,
   type WorkflowRunStatusDto,
@@ -94,6 +96,7 @@ export {
   workflowRunAttemptDtoSchema,
   workflowRunAttemptsResponseSchema,
   workflowRunDetailResponseSchema,
+  workflowRunDevSourceSchema,
   workflowRunDtoSchema,
   workflowRunJobDetailDtoSchema,
   workflowRunJobDisplayStatusCountDtoSchema,
@@ -103,6 +106,7 @@ export {
   workflowRunListItemSchema,
   workflowRunListQuerySchema,
   workflowRunListResponseSchema,
+  workflowRunOriginSchema,
   workflowRunRerunModeSchema,
   workflowRunResponseSchema,
   workflowRunStatusSchema,

package/src/schemas/index.ts

@@ -89,6 +89,7 @@ export {
   type WorkflowRunAggregatesResponseDto,
   type WorkflowRunAttemptDto,
   type WorkflowRunAttemptsResponseDto,
+  type WorkflowRunDevSourceDto,
   type WorkflowRunDto,
   type WorkflowRunJobDisplayStatusCountDto,
   type WorkflowRunJobStatusCountDto,
@@ -96,6 +97,7 @@ export {
   type WorkflowRunListItemDto,
   type WorkflowRunListQueryDto,
   type WorkflowRunListResponseDto,
+  type WorkflowRunOriginDto,
   type WorkflowRunRerunModeDto,
   type WorkflowRunResponseDto,
   type WorkflowRunStatusDto,
@@ -105,6 +107,7 @@ export {
   workflowRunAggregatesResponseSchema,
   workflowRunAttemptDtoSchema,
   workflowRunAttemptsResponseSchema,
+  workflowRunDevSourceSchema,
   workflowRunDtoSchema,
   workflowRunJobDisplayStatusCountDtoSchema,
   workflowRunJobStatusCountDtoSchema,
@@ -112,6 +115,7 @@ export {
   workflowRunListItemSchema,
   workflowRunListQuerySchema,
   workflowRunListResponseSchema,
+  workflowRunOriginSchema,
   workflowRunRerunModeSchema,
   workflowRunResponseSchema,
   workflowRunStatusSchema,

package/src/schemas/job-listening.test.ts

@@ -22,6 +22,27 @@ describe('jobListeningSchema', () => {
 
     expect(result).toEqual(input);
   });
+
+  it('parses listener matchers with the event omitted', () => {
+    const input = {
+      on: [{source: 'github_acme'}],
+      until: [{source: 'github_acme', filter: 'event.action == "closed"'}],
+      timeout_ms: 1000,
+      max_executions: 3,
+      batch: null,
+      on_resolve: 'finish',
+      execution_timeout_ms: null,
+      name: null,
+    };
+
+    const result = jobListeningSchema.parse(input);
+
+    expect(result.on).toEqual([{source: 'github_acme'}]);
+    expect(result.until?.[0]).toEqual({
+      source: 'github_acme',
+      filter: 'event.action == "closed"',
+    });
+  });
 });
 
 describe('execution context schemas', () => {

package/src/schemas/job-listening.ts

@@ -6,7 +6,7 @@ export const resolutionReasonSchema = z.enum(['until', 'timeout', 'max_execution
 
 export const listeningTriggerSchema = z.object({
   source: z.string(),
-  event: z.string(),
+  event: z.string().optional(),
   inputs: z.record(z.string(), z.unknown()).optional(),
   filter: z.string().optional(),
 });

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

@@ -5,8 +5,9 @@ import {workflowExecutionEventSchema} from './job-listening.js';
 import {stepAttemptDetailDtoSchema, stepAttemptDtoSchema, stepDtoSchema} from './step.js';
 import {
   jobExecutionStatusSchema,
+  validateWorkflowRunOrigin,
   workflowRunAttemptDtoSchema,
-  workflowRunResponseSchema,
+  workflowRunDtoFields,
 } from './workflow-run.js';
 
 export const jobExecutionDtoSchema = z.object({
@@ -69,17 +70,20 @@ export type WorkflowRunJobDetailDto = z.infer<typeof workflowRunJobDetailDtoSche
 
 // The run detail read model returned by `GET /workflows/runs/:id`: a run plus its
 // jobs, each job's steps, and each step's attempt history.
-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 const workflowRunDetailResponseSchema = z
+  .object({
+    ...workflowRunDtoFields,
+    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),
+  })
+  .superRefine(validateWorkflowRunOrigin);
 
 export type WorkflowRunDetailResponseDto = z.infer<typeof workflowRunDetailResponseSchema>;

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

@@ -2,6 +2,7 @@ import {
   WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
   workflowRunDtoSchema,
   workflowRunListItemSchema,
+  workflowRunListQuerySchema,
   workflowSourceSnapshotSchema,
 } from './workflow-run.js';
 
@@ -13,6 +14,8 @@ const baseRun = {
   name: 'Build',
   workflow_name: 'Build',
   status: 'pending',
+  origin: 'synced',
+  dev_source: null,
   source_run_id: null,
   root_run_id: null,
   attempt: 1,
@@ -31,6 +34,8 @@ const baseRun = {
   finished_at: null,
 };
 
+const {origin: _origin, dev_source: _devSource, ...legacyRun} = baseRun;
+
 describe('workflow source snapshot schemas', () => {
   test('accepts YAML source snapshots', () => {
     const result = workflowSourceSnapshotSchema.parse({
@@ -100,6 +105,152 @@ describe('workflow run trigger reference schema', () => {
   });
 });
 
+describe('workflow run origin schemas', () => {
+  test('defaults missing origin fields for a legacy response', () => {
+    const result = workflowRunDtoSchema.parse({...legacyRun, source_snapshot: null});
+
+    expect(result.origin).toBe('synced');
+    expect(result.dev_source).toBeNull();
+  });
+
+  test('accepts a dev run with its provenance', () => {
+    const result = workflowRunDtoSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      origin: 'dev',
+      dev_source: {
+        ref: 'fix-triage-prompt',
+        commit: 'abc123',
+        config_path: '.shipfox/workflows/triage-sentry.yml',
+        initiated_by_user_id: '55555555-5555-4555-8555-555555555555',
+        replay_of_event_id: '66666666-6666-4666-8666-666666666666',
+      },
+    });
+
+    expect(result.origin).toBe('dev');
+    expect(result.dev_source).toMatchObject({
+      ref: 'fix-triage-prompt',
+      replay_of_event_id: '66666666-6666-4666-8666-666666666666',
+    });
+  });
+
+  test('accepts a dev run without a replayed event', () => {
+    const result = workflowRunDtoSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      origin: 'dev',
+      dev_source: {
+        ref: 'fix-triage-prompt',
+        commit: 'abc123',
+        config_path: '.shipfox/workflows/triage-sentry.yml',
+        initiated_by_user_id: '55555555-5555-4555-8555-555555555555',
+        replay_of_event_id: null,
+      },
+    });
+
+    expect(result.dev_source?.replay_of_event_id).toBeNull();
+  });
+
+  test('rejects synced runs with dev provenance', () => {
+    const result = workflowRunDtoSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      dev_source: {
+        ref: 'fix-triage-prompt',
+        commit: 'abc123',
+        config_path: '.shipfox/workflows/triage-sentry.yml',
+        initiated_by_user_id: '55555555-5555-4555-8555-555555555555',
+        replay_of_event_id: null,
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects dev runs without provenance', () => {
+    const result = workflowRunDtoSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      origin: 'dev',
+      dev_source: null,
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects an unknown origin value', () => {
+    const result = workflowRunDtoSchema.safeParse({...baseRun, origin: 'staging'});
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects a dev source missing a field rather than defaulting it', () => {
+    const result = workflowRunDtoSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      origin: 'dev',
+      dev_source: {
+        ref: 'fix-triage-prompt',
+        commit: 'abc123',
+        config_path: '.shipfox/workflows/triage-sentry.yml',
+        initiated_by_user_id: '55555555-5555-4555-8555-555555555555',
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects a non-uuid initiated user id', () => {
+    const result = workflowRunDtoSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      origin: 'dev',
+      dev_source: {
+        ref: 'fix-triage-prompt',
+        commit: 'abc123',
+        config_path: '.shipfox/workflows/triage-sentry.yml',
+        initiated_by_user_id: 'not-a-uuid',
+        replay_of_event_id: null,
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects a non-uuid replayed event id', () => {
+    const result = workflowRunDtoSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      origin: 'dev',
+      dev_source: {
+        ref: 'fix-triage-prompt',
+        commit: 'abc123',
+        config_path: '.shipfox/workflows/triage-sentry.yml',
+        initiated_by_user_id: '55555555-5555-4555-8555-555555555555',
+        replay_of_event_id: 'not-a-uuid',
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('workflow run list query schema', () => {
+  const baseQuery = {project_id: '22222222-2222-4222-8222-222222222222'};
+
+  test('accepts an origin facet', () => {
+    const result = workflowRunListQuerySchema.parse({...baseQuery, origin: 'dev'});
+
+    expect(result.origin).toBe('dev');
+  });
+
+  test('rejects an unknown origin facet', () => {
+    const result = workflowRunListQuerySchema.safeParse({...baseQuery, origin: 'staging'});
+
+    expect(result.success).toBe(false);
+  });
+});
+
 describe('workflow run list item schema', () => {
   function jobDto(position: number) {
     return {

package/src/schemas/workflow-run.ts

@@ -24,6 +24,22 @@ export const workflowRunRerunModeSchema = z.enum(['all', 'failed']);
 
 export type WorkflowRunRerunModeDto = z.infer<typeof workflowRunRerunModeSchema>;
 
+export const workflowRunOriginSchema = z.enum(['synced', 'dev']);
+
+export type WorkflowRunOriginDto = z.infer<typeof workflowRunOriginSchema>;
+
+// Dev-run provenance: the ref and pinned commit the definition came from, the file that
+// ran, the user who started the run, and the journaled event it replays when any.
+export const workflowRunDevSourceSchema = z.object({
+  ref: z.string(),
+  commit: z.string(),
+  config_path: z.string(),
+  initiated_by_user_id: z.string().uuid(),
+  replay_of_event_id: z.string().uuid().nullable(),
+});
+
+export type WorkflowRunDevSourceDto = z.infer<typeof workflowRunDevSourceSchema>;
+
 export const rerunWorkflowRunBodySchema = z.object({
   mode: workflowRunRerunModeSchema,
 });
@@ -38,6 +54,7 @@ const runListQueryBaseSchema = z.object({
   status: workflowRunStatusSchema.optional(),
   definition_id: z.string().uuid().optional(),
   trigger_source: z.string().optional(),
+  origin: workflowRunOriginSchema.optional(),
   created_from: isoDateTimeSchema.optional(),
   created_to: isoDateTimeSchema.optional(),
 });
@@ -97,7 +114,7 @@ export const workflowRunTriggerReferenceSchema = z.object({
 
 export type WorkflowRunTriggerReferenceDto = z.infer<typeof workflowRunTriggerReferenceSchema>;
 
-export const workflowRunDtoSchema = z.object({
+export const workflowRunDtoFields = {
   id: z.string().uuid(),
   project_id: z.string().uuid(),
   definition_id: z.string().uuid(),
@@ -105,6 +122,9 @@ export const workflowRunDtoSchema = z.object({
   name: z.string(),
   workflow_name: z.string(),
   status: workflowRunStatusSchema,
+  // These defaults keep the response contract compatible while API and web deploys overlap.
+  origin: workflowRunOriginSchema.optional().default('synced'),
+  dev_source: workflowRunDevSourceSchema.nullable().optional().default(null),
   current_attempt: z.number().int().positive(),
   latest_attempt: z.number().int().positive(),
   trigger_provider: z.string().nullable(),
@@ -118,7 +138,31 @@ export const workflowRunDtoSchema = z.object({
   updated_at: z.string(),
   started_at: z.string().nullable(),
   finished_at: z.string().nullable(),
-});
+};
+
+export function validateWorkflowRunOrigin(
+  value: {origin: WorkflowRunOriginDto; dev_source: WorkflowRunDevSourceDto | null},
+  ctx: z.RefinementCtx,
+) {
+  if (value.origin === 'synced' && value.dev_source !== null) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Synced runs cannot include dev_source',
+      path: ['dev_source'],
+    });
+  }
+  if (value.origin === 'dev' && value.dev_source === null) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Dev runs require dev_source',
+      path: ['dev_source'],
+    });
+  }
+}
+
+export const workflowRunDtoSchema = z
+  .object(workflowRunDtoFields)
+  .superRefine(validateWorkflowRunOrigin);
 
 export type WorkflowRunDto = z.infer<typeof workflowRunDtoSchema>;
 
@@ -191,27 +235,35 @@ 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),
-  /** 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.input<typeof workflowRunListItemSchema>;
+export const workflowRunListItemSchema = z
+  .object({
+    ...workflowRunDtoFields,
+    /** 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),
+    /** 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),
+  })
+  .superRefine(validateWorkflowRunOrigin);
+
+type WorkflowRunListItemInput = z.input<typeof workflowRunListItemSchema>;
+
+export type WorkflowRunListItemDto = Omit<WorkflowRunListItemInput, 'origin' | 'dev_source'> & {
+  origin: WorkflowRunOriginDto;
+  dev_source: WorkflowRunDevSourceDto | null;
+};
 
 export const workflowRunListResponseSchema = z.object({
   runs: z.array(workflowRunListItemSchema),
@@ -219,7 +271,11 @@ export const workflowRunListResponseSchema = z.object({
   filtered_total_count: z.number().int().nonnegative().nullable(),
 });
 
-export type WorkflowRunListResponseDto = z.input<typeof workflowRunListResponseSchema>;
+type WorkflowRunListResponseInput = z.input<typeof workflowRunListResponseSchema>;
+
+export type WorkflowRunListResponseDto = Omit<WorkflowRunListResponseInput, 'runs'> & {
+  runs: WorkflowRunListItemDto[];
+};
 
 const aggregateBucketSchema = z.object({
   value: z.string(),