@shipfox/api-workflows 13.1.0 → 15.0.0

package/drizzle/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1786266649202,
       "tag": "0003_output_invalid_reason",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1787477580166,
+      "tag": "0004_dev_run_origin",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "13.1.0",
+  "version": "15.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,30 +23,30 @@
     "drizzle-orm": "^0.45.2",
     "js-yaml": "^4.1.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-agent-dto": "13.1.0",
+    "@shipfox/api-auth-context": "15.0.0",
+    "@shipfox/api-auth-dto": "15.0.0",
+    "@shipfox/api-agent-dto": "15.0.0",
     "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-definitions-dto": "12.3.0",
-    "@shipfox/api-projects-dto": "12.2.0",
-    "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-runners-dto": "13.0.0",
+    "@shipfox/api-definitions-dto": "15.0.0",
+    "@shipfox/api-projects-dto": "15.0.0",
+    "@shipfox/api-integration-core-dto": "15.0.0",
+    "@shipfox/api-runners-dto": "14.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "13.1.0",
-    "@shipfox/api-workspaces-dto": "12.0.0",
+    "@shipfox/api-workflows-dto": "15.0.0",
+    "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.2.0",
+    "@shipfox/expression": "2.3.0",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
-    "@shipfox/node-fastify": "0.4.2",
-    "@shipfox/node-module": "1.0.6",
-    "@shipfox/node-opentelemetry": "0.6.4",
+    "@shipfox/node-fastify": "0.4.3",
+    "@shipfox/node-module": "1.0.7",
+    "@shipfox/node-opentelemetry": "0.6.5",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.5.0",
-    "@shipfox/node-temporal": "0.4.5",
+    "@shipfox/node-temporal": "0.4.6",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.0.1"
+    "@shipfox/workflow-document": "3.2.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/checkout.test.ts

@@ -3,9 +3,24 @@ import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module'
 import {projectFactory} from '#test/factories/project.js';
 import {createStepCheckoutSpec} from './checkout.js';
 import type {Step} from './entities/step.js';
-import type {WorkflowRunTriggerReference} from './entities/workflow-run.js';
+import type {WorkflowRunDevSource, WorkflowRunTriggerReference} from './entities/workflow-run.js';
 import {CheckoutConfigInvalidError, CheckoutIntentUnresolvedError} from './errors.js';
 
+const syncedRun = {origin: 'synced', devSource: null} as const;
+
+function devRun(commit: string): {origin: 'dev'; devSource: WorkflowRunDevSource} {
+  return {
+    origin: 'dev',
+    devSource: {
+      ref: 'fix-triage-prompt',
+      commit,
+      configPath: '.shipfox/workflows/triage-sentry.yml',
+      initiatedByUserId: crypto.randomUUID(),
+      replayOfEventId: null,
+    },
+  };
+}
+
 const getProjectById = vi.fn();
 const resolveCheckoutTarget = vi.fn();
 const projects = {
@@ -46,6 +61,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     const result = await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -96,6 +112,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     const result = await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -134,6 +151,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -167,6 +185,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -200,6 +219,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -216,6 +236,41 @@ describe('createStepCheckoutSpec', () => {
     });
   });
 
+  it('falls through to the dev commit when a same-project trigger has no commit', async () => {
+    const project = projectFactory.build();
+    const devCommit = 'b'.repeat(40);
+    const triggerReference = {...triggerReferenceFor(project.id), commit: null};
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: devCommit,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun(devCommit),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: devCommit,
+      permissions: {contents: 'read'},
+    });
+  });
+
   it('keeps the provider default ref for a cross-repository target', async () => {
     const project = projectFactory.build();
     const targetProjectId = crypto.randomUUID();
@@ -232,6 +287,142 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: expect.any(String),
+      externalRepositoryId: 'github:412',
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('checks out the dev commit for a dev run without a trigger reference', async () => {
+    const project = projectFactory.build();
+    const devCommit = 'b'.repeat(40);
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: devCommit,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun(devCommit),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: devCommit,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('prefers the event commit over the dev commit on a dev replay of a same-project push', async () => {
+    const project = projectFactory.build();
+    const eventCommit = 'c'.repeat(40);
+    const triggerReference = {...triggerReferenceFor(project.id), commit: eventCommit};
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: eventCommit,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun('b'.repeat(40)),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: eventCommit,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('preserves an explicit ref on a dev run', async () => {
+    const project = projectFactory.build();
+    const explicitRef = 'refs/heads/feature/checkout';
+    const step = checkoutStep({ref: explicitRef, permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: explicitRef,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun('b'.repeat(40)),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: explicitRef,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('keeps the provider default ref for a cross-project target in a dev run', async () => {
+    const project = projectFactory.build();
+    const targetProjectId = crypto.randomUUID();
+    const step = checkoutStep({project: targetProjectId});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: targetProjectId,
+      connectionId: crypto.randomUUID(),
+      externalRepositoryId: 'github:412',
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/target.git',
+      ref: 'main',
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun('b'.repeat(40)),
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -263,6 +454,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -294,6 +486,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -330,6 +523,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -350,6 +544,7 @@ describe('createStepCheckoutSpec', () => {
     {connection: 'github'},
   ])('rejects invalid checkout target shape: %j', async (checkout) => {
     const act = createStepCheckoutSpec({
+      run: syncedRun,
       step: checkoutStep(checkout),
       workspaceId: crypto.randomUUID(),
       projectId: crypto.randomUUID(),
@@ -368,6 +563,7 @@ describe('createStepCheckoutSpec', () => {
     getProjectById.mockResolvedValue({project: null});
 
     const act = createStepCheckoutSpec({
+      run: syncedRun,
       step: checkoutStep({}),
       workspaceId: crypto.randomUUID(),
       projectId,
@@ -387,6 +583,7 @@ describe('createStepCheckoutSpec', () => {
     resolveConnection.mockResolvedValue(null);
 
     const act = createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,

package/src/core/checkout.ts

@@ -3,7 +3,10 @@ import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module'
 import {checkoutTargetValidationIssues} from '@shipfox/workflow-document';
 import {z} from 'zod';
 import type {Step} from '#core/entities/step.js';
-import type {WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
+import type {
+  WorkflowRunOriginState,
+  WorkflowRunTriggerReference,
+} from '#core/entities/workflow-run.js';
 import {CheckoutConfigInvalidError, CheckoutIntentUnresolvedError} from './errors.js';
 
 const checkoutConfigSchema = z
@@ -39,6 +42,7 @@ export async function createStepCheckoutSpec({
   workspaceId,
   projectId,
   triggerReference,
+  run,
   integrations,
   projects,
 }: {
@@ -46,6 +50,8 @@ export async function createStepCheckoutSpec({
   workspaceId: string;
   projectId: string;
   triggerReference?: WorkflowRunTriggerReference | null | undefined;
+  /** The run's origin state; a dev run checks out its dev commit by default. */
+  run: WorkflowRunOriginState;
   integrations: IntegrationsModuleClient;
   projects: ProjectsModuleClient;
 }): Promise<{
@@ -79,11 +85,18 @@ export async function createStepCheckoutSpec({
     },
     target,
   });
-  const ref =
-    checkout.ref ??
-    (triggerReference?.project?.id === resolvedTarget.projectId
+  // Explicit step refs win, followed by same-project event commits (including
+  // replays), then the pinned dev commit for the run's own project. Other targets
+  // intentionally use the provider default branch.
+  const triggerCommitRef =
+    triggerReference?.project?.id === resolvedTarget.projectId
       ? (triggerReference.commit ?? undefined)
-      : undefined);
+      : undefined;
+  const devCommitRef =
+    run.origin === 'dev' && resolvedTarget.projectId === projectId
+      ? run.devSource.commit
+      : undefined;
+  const ref = checkout.ref ?? triggerCommitRef ?? devCommitRef;
   const response = await integrations.createCheckoutSpec({
     workspaceId,
     connectionId: resolvedTarget.connectionId,

package/src/core/entities/job.ts

@@ -69,7 +69,7 @@ export interface Job {
 
 export interface JobListeningTrigger {
   readonly source: string;
-  readonly event: string;
+  readonly event?: string;
   readonly inputs?: Readonly<Record<string, unknown>>;
   readonly filter?: string;
 }

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

@@ -5,6 +5,24 @@ import type {WorkflowRunAttempt} from './workflow-run-attempt.js';
 
 export type WorkflowRunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled';
 
+export type WorkflowRunOrigin = 'synced' | 'dev';
+
+/**
+ * Why a dev run was created: the ref and pinned commit the definition came from, the
+ * file that ran, the user who started it, and the journaled event it replays when any.
+ */
+export interface WorkflowRunDevSource {
+  ref: string;
+  commit: string;
+  configPath: string;
+  initiatedByUserId: string;
+  replayOfEventId: string | null;
+}
+
+export type WorkflowRunOriginState =
+  | {origin: 'synced'; devSource: null}
+  | {origin: 'dev'; devSource: WorkflowRunDevSource};
+
 export type TerminalWorkflowRunStatus = Extract<
   WorkflowRunStatus,
   'succeeded' | 'failed' | 'cancelled'
@@ -40,14 +58,16 @@ export type TriggerPayload =
       source: 'manual';
       provider?: 'manual' | undefined;
       event: 'fire';
-      subscriptionId: string;
+      // A dev trigger has no subscription row, so the id is optional here.
+      subscriptionId?: string | undefined;
       userId: string;
     }
   | {
       source: 'cron';
       provider?: 'cron' | undefined;
       event: 'tick';
-      scheduleId: string;
+      // A dev trigger has no schedule row, so the id is optional here.
+      scheduleId?: string | undefined;
     }
   // Integration sources (github, gitlab, sentry, …) flow through opaquely: the
   // run records what fired it and carries the raw event payload, without the
@@ -60,7 +80,7 @@ export type TriggerPayload =
       data: unknown;
     };
 
-export interface WorkflowRun {
+export type WorkflowRun = WorkflowRunOriginState & {
   id: string;
   workspaceId: string;
   projectId: string;
@@ -89,7 +109,7 @@ export interface WorkflowRun {
   updatedAt: Date;
   startedAt: Date | null;
   finishedAt: Date | null;
-}
+};
 
 export interface StepDetail extends Step {
   attempts: StepAttempt[];
@@ -103,11 +123,11 @@ export interface WorkflowJobDetail extends Job {
   jobExecutions: JobExecutionDetail[];
 }
 
-export interface WorkflowRunDetail extends WorkflowRun {
+export type WorkflowRunDetail = WorkflowRun & {
   runAttempt: WorkflowRunAttempt;
   latestAttempt: number;
   jobs: WorkflowJobDetail[];
   /** Whether any job execution of this attempt reached its runner, decided here so the detail
    * and the list cannot answer it differently. */
   hasStartedJobExecution: boolean;
-}
+};

package/src/core/index.ts

@@ -35,8 +35,8 @@ export {
   deriveJobSuccess,
   type JobActivationDecision,
 } from './job-transition/index.js';
-export type {RunWorkflowParams} from './run-workflow.js';
-export {runWorkflow} from './run-workflow.js';
+export type {RunDevWorkflowParams, RunWorkflowParams} from './run-workflow.js';
+export {runDevWorkflow, runWorkflow} from './run-workflow.js';
 export {
   type MaterializedWorkflowJob,
   type MaterializedWorkflowStep,

package/src/core/job-transition/decide-job-activation.test.ts

@@ -121,6 +121,8 @@ function workflowRun(): WorkflowRun {
     workflowName: 'Run',
     nameOverride: null,
     status: 'pending',
+    origin: 'synced',
+    devSource: null,
     currentAttempt: 1,
     triggerProvider: null,
     triggerSource: 'manual',