@shipfox/api-workflows 11.0.0 → 12.1.0

package/src/presentation/dto/checkout-token.test.ts

@@ -23,11 +23,12 @@ describe('toCheckoutTokenDto', () => {
       },
     };
 
-    const dto = toCheckoutTokenDto(spec, {persist: true});
+    const dto = toCheckoutTokenDto(spec, {fetchDepth: 1, persist: true});
 
     expect(dto).toEqual({
       repository_url: 'https://github.com/acme/repo.git',
       ref: 'main',
+      fetch_depth: 1,
       git_author: {
         name: 'shipfox-test[bot]',
         email: '1+shipfox-test[bot]@users.noreply.github.com',
@@ -55,17 +56,22 @@ describe('toCheckoutTokenDto', () => {
       },
     };
 
-    const dto = toCheckoutTokenDto(spec, {persist: false});
+    const dto = toCheckoutTokenDto(spec, {fetchDepth: 0, persist: false});
 
+    expect(dto).toMatchObject({fetch_depth: 0});
     expect(dto.auth).toMatchObject({carry: 'header', host: 'github.com', persist: false});
   });
 
   it('omits auth when the spec has no credentials', () => {
     const spec: CheckoutSpec = {repositoryUrl: 'https://example.com/acme/repo.git', ref: 'trunk'};
 
-    const dto = toCheckoutTokenDto(spec, {persist: true});
+    const dto = toCheckoutTokenDto(spec, {fetchDepth: 1, persist: true});
 
-    expect(dto).toEqual({repository_url: 'https://example.com/acme/repo.git', ref: 'trunk'});
+    expect(dto).toEqual({
+      repository_url: 'https://example.com/acme/repo.git',
+      ref: 'trunk',
+      fetch_depth: 1,
+    });
     expect(dto.auth).toBeUndefined();
   });
 
@@ -75,7 +81,7 @@ describe('toCheckoutTokenDto', () => {
       ref: 'main',
     };
 
-    expect(() => toCheckoutTokenDto(spec, {persist: true})).toThrow();
+    expect(() => toCheckoutTokenDto(spec, {fetchDepth: 1, persist: true})).toThrow();
   });
 
   it('rejects an scp-like URL that embeds credentials', () => {
@@ -84,15 +90,19 @@ describe('toCheckoutTokenDto', () => {
       ref: 'main',
     };
 
-    expect(() => toCheckoutTokenDto(spec, {persist: true})).toThrow();
+    expect(() => toCheckoutTokenDto(spec, {fetchDepth: 1, persist: true})).toThrow();
   });
 
   it('accepts a credential-free scp-like URL', () => {
     const spec: CheckoutSpec = {repositoryUrl: 'git@github.com:acme/repo.git', ref: 'main'};
 
-    const dto = toCheckoutTokenDto(spec, {persist: true});
+    const dto = toCheckoutTokenDto(spec, {fetchDepth: 1, persist: true});
 
-    expect(dto).toEqual({repository_url: 'git@github.com:acme/repo.git', ref: 'main'});
+    expect(dto).toEqual({
+      repository_url: 'git@github.com:acme/repo.git',
+      ref: 'main',
+      fetch_depth: 1,
+    });
   });
 
   it('maps the host from an scp-like credentialed URL', () => {
@@ -106,7 +116,7 @@ describe('toCheckoutTokenDto', () => {
       },
     };
 
-    const dto = toCheckoutTokenDto(spec, {persist: true});
+    const dto = toCheckoutTokenDto(spec, {fetchDepth: 1, persist: true});
 
     expect(dto.auth).toMatchObject({host: 'github.com'});
   });

package/src/presentation/dto/checkout-token.ts

@@ -47,7 +47,7 @@ function assertNoScpCredentials(repositoryUrl: string): void {
 
 export function toCheckoutTokenDto(
   spec: CheckoutSpec,
-  options: {persist: boolean},
+  options: {fetchDepth: number; persist: boolean},
 ): CheckoutTokenResponseDto {
   assertNoEmbeddedCredentials(spec.repositoryUrl);
 
@@ -57,6 +57,7 @@ export function toCheckoutTokenDto(
   return {
     repository_url: spec.repositoryUrl,
     ref: spec.ref,
+    fetch_depth: options.fetchDepth,
     ...(spec.gitAuthor
       ? {git_author: {name: spec.gitAuthor.name, email: spec.gitAuthor.email}}
       : {}),

package/src/presentation/dto/index.ts

@@ -1,3 +1,3 @@
 export {toJobDto, toJobExecutionDto} from './job.js';
 export {toStepAttemptDto, toStepDto} from './step.js';
-export {toRunAttemptDto, toRunDto} from './workflow-run.js';
+export {toRunAttemptDto, toRunDto, toRunListItemDto} from './workflow-run.js';

package/src/presentation/dto/job.test.ts

@@ -28,6 +28,10 @@ describe('toJobExecutionDto', () => {
           event: 'deployment_status',
           delivery_id: 'delivery-1',
           received_at: '2026-06-25T00:00:00.000Z',
+          project: null,
+          repository: null,
+          ref: null,
+          commit: null,
           data: {state: 'success'},
         },
       ],
@@ -42,6 +46,10 @@ describe('toJobExecutionDto', () => {
         event: 'deployment_status',
         delivery_id: 'delivery-1',
         received_at: '2026-06-25T00:00:00.000Z',
+        project: null,
+        repository: null,
+        ref: null,
+        commit: null,
         data: {state: 'success'},
       },
     ]);
@@ -90,6 +98,7 @@ function jobExecutionEntity(overrides: Partial<JobExecution> = {}): JobExecution
     id: '33333333-3333-4333-8333-333333333333',
     jobId: '11111111-1111-4111-8111-111111111111',
     sequence: 1,
+    nameOverride: 'deploy',
     name: 'deploy',
     runner: null,
     status: 'pending',

package/src/presentation/dto/step.test.ts

@@ -114,6 +114,18 @@ describe('toStepDto error category', () => {
     });
   });
 
+  it("derives category 'setup' for a checkout step error and surfaces the reason", () => {
+    const dto = toStepDto(
+      step({type: 'checkout', error: {message: 'Checkout failed', reason: 'checkout_failed'}}),
+    );
+
+    expect(dto.error).toEqual({
+      message: 'Checkout failed',
+      reason: 'checkout_failed',
+      category: 'setup',
+    });
+  });
+
   it("derives category 'user' for a run step error", () => {
     const dto = toStepDto(
       step({type: 'run', error: {message: 'Command exited with code 1', exitCode: 1}}),

package/src/presentation/dto/step.ts

@@ -40,7 +40,7 @@ function toStepErrorDto(
 
 // Inverse of toStepErrorDto: reported wire errors land on the domain row in
 // camelCase so the read path renders them back without a special case. `category`
-// is intentionally NOT persisted — the server derives it from the step type on
+// is intentionally NOT persisted: the server derives it from the step type on
 // read, so a runner-supplied category is ignored here.
 export function fromStepErrorDto(error: StepErrorDto | undefined): Record<string, unknown> | null {
   if (!error) return null;
@@ -107,7 +107,10 @@ export function toStepDto(step: Step): StepDto {
     status: step.status,
     type: step.type,
     config: step.config,
-    error: toStepErrorDto(step.error, step.type === 'setup' ? 'setup' : 'user'),
+    error: toStepErrorDto(
+      step.error,
+      step.type === 'setup' || step.type === 'checkout' ? 'setup' : 'user',
+    ),
     position: step.position,
     current_attempt: step.currentAttempt,
     created_at: step.createdAt.toISOString(),

package/src/presentation/dto/workflow-run.ts

@@ -1,13 +1,21 @@
-import type {WorkflowRunAttemptDto, WorkflowRunDto} from '@shipfox/api-workflows-dto';
-import type {WorkflowRun} from '#core/entities/workflow-run.js';
+import type {
+  WorkflowRunAttemptDto,
+  WorkflowRunDto,
+  WorkflowRunListItemDto,
+  WorkflowRunTriggerReferenceDto,
+} from '@shipfox/api-workflows-dto';
+import type {WorkflowRun, WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
 import type {WorkflowRunAttempt} from '#core/entities/workflow-run-attempt.js';
+import type {WorkflowRunJobsSummary} from '#db/index.js';
 
 export function toRunDto(run: WorkflowRun, latestAttempt = run.currentAttempt): WorkflowRunDto {
   return {
     id: run.id,
     project_id: run.projectId,
     definition_id: run.definitionId,
+    number: run.number,
     name: run.name,
+    workflow_name: run.workflowName,
     status: run.status,
     current_attempt: run.currentAttempt,
     latest_attempt: latestAttempt,
@@ -15,6 +23,7 @@ export function toRunDto(run: WorkflowRun, latestAttempt = run.currentAttempt):
     trigger_source: run.triggerSource,
     trigger_event: run.triggerEvent,
     trigger_payload: run.triggerPayload,
+    trigger_reference: toTriggerReferenceDto(run.triggerReference),
     inputs: run.inputs,
     source_snapshot: run.sourceSnapshot,
     created_at: run.createdAt.toISOString(),
@@ -24,6 +33,39 @@ export function toRunDto(run: WorkflowRun, latestAttempt = run.currentAttempt):
   };
 }
 
+const EMPTY_JOBS: WorkflowRunJobsSummary = {preview: [], statusCounts: []};
+
+export function toRunListItemDto(
+  run: WorkflowRun,
+  jobs: WorkflowRunJobsSummary = EMPTY_JOBS,
+): WorkflowRunListItemDto {
+  return {
+    ...toRunDto(run),
+    jobs: jobs.preview.map((job) => ({
+      id: job.id,
+      key: job.key,
+      name: job.name,
+      status: job.status,
+      position: job.position,
+    })),
+    job_status_counts: jobs.statusCounts.map(({status, count}) => ({status, count})),
+  };
+}
+
+// The persisted reference predates `actor` and carries an internal project id the client has
+// no use for, so each field is read defensively rather than spread onto the response.
+function toTriggerReferenceDto(
+  reference: WorkflowRunTriggerReference | null | undefined,
+): WorkflowRunTriggerReferenceDto | null {
+  if (!reference) return null;
+  return {
+    repository: reference.repository ?? null,
+    ref: reference.ref ?? null,
+    commit: reference.commit ?? null,
+    actor: reference.actor ?? null,
+  };
+}
+
 export function toRunAttemptDto(attempt: WorkflowRunAttempt): WorkflowRunAttemptDto {
   return {
     id: attempt.id,

package/src/presentation/inter-module.test.ts

@@ -309,6 +309,58 @@ describe('Workflows inter-module presentation', () => {
     ).toBe(code);
   });
 
+  test.each([
+    ['suspended', 'workspace-suspended'],
+    ['deleted', 'workspace-deleted'],
+  ] as const)('rejects fire deliveries with a pre-resolved trigger reference for %s workspaces', async (status, code) => {
+    const jobId = '00000000-0000-4000-8000-000000000006';
+    const workspaceId = '00000000-0000-4000-8000-000000000007';
+    mocks.getJobScope.mockResolvedValue({workspaceId, projectId: input.projectId});
+    const getWorkspaceOperatingState = vi.fn().mockResolvedValue({status});
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: {} as never,
+      projects: {} as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {getWorkspaceOperatingState} as never,
+    });
+
+    const error = await Promise.resolve(
+      presentation.handlers.deliverEventToJobListener(
+        {
+          jobId,
+          disposition: 'fire',
+          eventRef: 'event-1',
+          deliveryId: 'delivery-1',
+          source: 'github',
+          event: 'push',
+          provider: 'github',
+          payload: {},
+          receivedAt: '2026-07-20T12:00:00.000Z',
+          triggerReference: {
+            project: {id: input.projectId},
+            repository: 'acme/api',
+            ref: 'refs/heads/main',
+            commit: 'a'.repeat(40),
+            actor: 'octocat',
+          },
+        },
+        {signal: new AbortController().signal},
+      ),
+    ).catch((caught: unknown) => caught);
+
+    expect(getWorkspaceOperatingState).toHaveBeenCalledWith({workspaceId});
+    expect(mocks.deliverEventToListener).not.toHaveBeenCalled();
+    expect(
+      isInterModuleKnownError(
+        workflowsInterModuleContract.methods.deliverEventToJobListener,
+        error,
+      ) && error.code,
+    ).toBe(code);
+  });
+
   test('allows resolve deliveries for suspended workspaces', async () => {
     const jobId = '00000000-0000-4000-8000-000000000006';
     mocks.getJobScope.mockResolvedValue({workspaceId: input.workspaceId});
@@ -343,4 +395,117 @@ describe('Workflows inter-module presentation', () => {
     expect(getWorkspaceOperatingState).not.toHaveBeenCalled();
     expect(mocks.deliverEventToListener).toHaveBeenCalled();
   });
+
+  test('persists a null trigger reference when fire delivery has no source connection', async () => {
+    const jobId = '00000000-0000-4000-8000-000000000006';
+    const workspaceId = '00000000-0000-4000-8000-000000000007';
+    mocks.getJobScope.mockResolvedValue({workspaceId});
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: {} as never,
+      projects: {} as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {
+        getWorkspaceOperatingState: vi.fn().mockResolvedValue({status: 'active'}),
+      } as never,
+    });
+
+    await presentation.handlers.deliverEventToJobListener(
+      {
+        jobId,
+        disposition: 'fire',
+        eventRef: 'event-1',
+        deliveryId: 'delivery-1',
+        source: 'github',
+        event: 'push',
+        provider: 'github',
+        payload: {},
+        receivedAt: '2026-07-20T12:00:00.000Z',
+      },
+      {signal: new AbortController().signal},
+    );
+
+    expect(mocks.deliverEventToListener).toHaveBeenCalledWith(
+      expect.objectContaining({triggerReference: null}),
+    );
+  });
+
+  test('resolves and persists the trigger reference for fire deliveries', async () => {
+    const jobId = '00000000-0000-4000-8000-000000000006';
+    const workspaceId = '00000000-0000-4000-8000-000000000007';
+    const connectionId = '00000000-0000-4000-8000-000000000008';
+    const projectId = '00000000-0000-4000-8000-000000000009';
+    const externalRepositoryId = 'github:42';
+    const integrations = {
+      resolveTriggerReference: vi.fn().mockResolvedValue({
+        externalRepositoryId,
+        ref: 'refs/heads/main',
+        commit: 'a'.repeat(40),
+      }),
+      resolveSourceRepository: vi.fn().mockResolvedValue({
+        repository: {owner: 'acme', name: 'api'},
+      }),
+    };
+    const projects = {
+      getProjectBySource: vi.fn().mockResolvedValue({project: {id: projectId}}),
+    };
+    mocks.getJobScope.mockResolvedValue({workspaceId, projectId: input.projectId});
+    const getWorkspaceOperatingState = vi.fn().mockResolvedValue({status: 'active'});
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: integrations as never,
+      projects: projects as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {getWorkspaceOperatingState} as never,
+    });
+
+    await presentation.handlers.deliverEventToJobListener(
+      {
+        jobId,
+        disposition: 'fire',
+        eventRef: 'event-1',
+        deliveryId: 'delivery-1',
+        source: 'github',
+        event: 'push',
+        provider: 'github',
+        triggerConnectionId: connectionId,
+        payload: {ref: 'refs/heads/main'},
+        receivedAt: '2026-07-20T12:00:00.000Z',
+      },
+      {signal: new AbortController().signal},
+    );
+
+    expect(integrations.resolveTriggerReference).toHaveBeenCalledWith({
+      workspaceId,
+      connectionId,
+      payload: {ref: 'refs/heads/main'},
+    });
+    expect(projects.getProjectBySource).toHaveBeenCalledWith({
+      workspaceId,
+      sourceConnectionId: connectionId,
+      sourceExternalRepositoryId: externalRepositoryId,
+    });
+    expect(mocks.deliverEventToListener).toHaveBeenCalledWith({
+      jobId,
+      disposition: 'fire',
+      eventRef: 'event-1',
+      deliveryId: 'delivery-1',
+      source: 'github',
+      event: 'push',
+      provider: 'github',
+      triggerConnectionId: connectionId,
+      payload: {ref: 'refs/heads/main'},
+      receivedAt: new Date('2026-07-20T12:00:00.000Z'),
+      triggerReference: {
+        project: {id: projectId},
+        repository: 'acme/api',
+        ref: 'refs/heads/main',
+        commit: 'a'.repeat(40),
+      },
+    });
+  });
 });

package/src/presentation/inter-module.ts

@@ -14,6 +14,7 @@ import {
   type InterModulePresentation,
 } from '@shipfox/inter-module';
 import {DEFAULT_HARNESS, harnessSchema} from '@shipfox/workflow-document';
+import type {WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
 import {
   InvalidJobRunnerLabelsError,
   WorkspaceDeletedError,
@@ -28,6 +29,7 @@ import {
   ProjectMismatchError,
   runWorkflow,
 } from '#core/index.js';
+import {resolveWorkflowRunTriggerReference} from '#core/resolve-trigger-reference.js';
 import {assertWorkspaceAdmitsNewJobs} from '#core/workspace-admission.js';
 import {getJobScope, getStepById, getStepByIdForJobExecution} from '#db/index.js';
 import {deliverEventToListener} from '#db/job-listener-events.js';
@@ -57,6 +59,7 @@ export function createWorkflowsInterModulePresentation(params: {
             projectId: input.projectId,
             definitionId: input.definitionId,
             triggerPayload: input.triggerPayload,
+            triggerConnectionId: input.triggerConnectionId,
             inputs: input.inputs,
             triggerIdempotencyKey: input.idempotencyKey,
             integrations: params.integrations,
@@ -69,14 +72,45 @@ export function createWorkflowsInterModulePresentation(params: {
         throw toStartRunKnownError(error, input.definitionId);
       }
     },
+    resolveWorkflowRunTriggerReference: async (input) =>
+      await resolveWorkflowRunTriggerReference({
+        workspaceId: input.workspaceId,
+        triggerConnectionId: input.triggerConnectionId,
+        triggerPayload: input.triggerPayload,
+        integrations: params.integrations,
+        projects: params.projects,
+      }),
     deliverEventToJobListener: async (input) => {
       const method = workflowsInterModuleContract.methods.deliverEventToJobListener;
       try {
-        if (input.disposition === 'fire') {
-          const scope = await getJobScope(input.jobId);
-          if (scope) await assertWorkspaceAdmitsNewJobs(params.workspaces, scope.workspaceId);
+        const scope = input.disposition === 'fire' ? await getJobScope(input.jobId) : undefined;
+        if (scope) {
+          await assertWorkspaceAdmitsNewJobs(params.workspaces, scope.workspaceId);
         }
-        return await deliverEventToListener({...input, receivedAt: new Date(input.receivedAt)});
+
+        let triggerReference: WorkflowRunTriggerReference | null = null;
+        if (input.triggerReference !== undefined) {
+          triggerReference = input.triggerReference;
+        } else if (scope) {
+          triggerReference = await resolveWorkflowRunTriggerReference({
+            workspaceId: scope.workspaceId,
+            triggerConnectionId: input.triggerConnectionId,
+            triggerPayload: {
+              provider: input.provider,
+              source: input.source,
+              event: input.event,
+              deliveryId: input.deliveryId,
+              data: input.payload,
+            },
+            integrations: params.integrations,
+            projects: params.projects,
+          });
+        }
+        return await deliverEventToListener({
+          ...input,
+          triggerReference,
+          receivedAt: new Date(input.receivedAt),
+        });
       } catch (error) {
         const workspaceError = toWorkspaceAdmissionKnownError(method, error);
         if (workspaceError !== undefined) throw workspaceError;