@shipfox/api-definitions 2.0.0

package/src/presentation/subscribers/on-project-source-bound.test.ts

@@ -0,0 +1,65 @@
+import type {ProjectSourceBoundEvent} from '@shipfox/api-projects-dto';
+import {onProjectSourceBound} from './on-project-source-bound.js';
+
+const startMock = vi.fn();
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({
+    workflow: {
+      start: startMock,
+    },
+  }),
+}));
+
+function buildPayload(): ProjectSourceBoundEvent {
+  return {
+    actorId: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    projectId: crypto.randomUUID(),
+    sourceConnectionId: crypto.randomUUID(),
+    provider: 'gitea',
+    externalRepositoryId: 'gitea:gitea-owner/platform',
+  };
+}
+
+describe('onProjectSourceBound', () => {
+  beforeEach(() => {
+    startMock.mockReset();
+    startMock.mockResolvedValue({});
+  });
+
+  it('starts a definition sync workflow keyed on project + bind', async () => {
+    const payload = buildPayload();
+
+    const result = onProjectSourceBound(payload);
+    await result;
+
+    expect(startMock).toHaveBeenCalledTimes(1);
+    expect(startMock).toHaveBeenCalledWith('definitionSyncWorkflow', {
+      taskQueue: 'definitions-sync',
+      workflowId: `definition-sync:${payload.projectId}:bind`,
+      workflowIdConflictPolicy: 'USE_EXISTING',
+      workflowIdReusePolicy: 'ALLOW_DUPLICATE',
+      args: [
+        {
+          projectId: payload.projectId,
+          workspaceId: payload.workspaceId,
+          sourceConnectionId: payload.sourceConnectionId,
+          sourceExternalRepositoryId: payload.externalRepositoryId,
+          sourceRef: undefined,
+          sourceCommitSha: undefined,
+        },
+      ],
+    });
+  });
+
+  it('rethrows when the temporal client fails to start', async () => {
+    const failure = new Error('temporal unavailable');
+    startMock.mockRejectedValueOnce(failure);
+    const payload = buildPayload();
+
+    const result = onProjectSourceBound(payload);
+
+    await expect(result).rejects.toBe(failure);
+  });
+});

package/src/presentation/subscribers/on-project-source-bound.ts

@@ -0,0 +1,11 @@
+import type {ProjectSourceBoundEvent} from '@shipfox/api-projects-dto';
+import {startDefinitionSync} from './start-definition-sync.js';
+
+export async function onProjectSourceBound(payload: ProjectSourceBoundEvent): Promise<void> {
+  await startDefinitionSync({
+    projectId: payload.projectId,
+    workspaceId: payload.workspaceId,
+    sourceConnectionId: payload.sourceConnectionId,
+    externalRepositoryId: payload.externalRepositoryId,
+  });
+}

package/src/presentation/subscribers/on-project-source-commit-observed.test.ts

@@ -0,0 +1,56 @@
+import type {ProjectSourceCommitObservedEvent} from '@shipfox/api-projects-dto';
+import {onProjectSourceCommitObserved} from './on-project-source-commit-observed.js';
+
+const startMock = vi.fn();
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({
+    workflow: {
+      start: startMock,
+    },
+  }),
+}));
+
+function buildPayload(): ProjectSourceCommitObservedEvent {
+  return {
+    workspaceId: crypto.randomUUID(),
+    projectId: crypto.randomUUID(),
+    sourceConnectionId: crypto.randomUUID(),
+    provider: 'github',
+    externalRepositoryId: 'github:42',
+    ref: 'main',
+    headCommitSha: 'abc123',
+  };
+}
+
+describe('onProjectSourceCommitObserved', () => {
+  beforeEach(() => {
+    startMock.mockReset();
+    startMock.mockResolvedValue({});
+  });
+
+  it('starts a definition sync workflow keyed on project + source commit sha', async () => {
+    const payload = buildPayload();
+
+    const result = onProjectSourceCommitObserved(payload);
+    await result;
+
+    expect(startMock).toHaveBeenCalledTimes(1);
+    expect(startMock).toHaveBeenCalledWith('definitionSyncWorkflow', {
+      taskQueue: 'definitions-sync',
+      workflowId: `definition-sync:${payload.projectId}:${payload.headCommitSha}`,
+      workflowIdConflictPolicy: 'USE_EXISTING',
+      workflowIdReusePolicy: 'ALLOW_DUPLICATE',
+      args: [
+        {
+          projectId: payload.projectId,
+          workspaceId: payload.workspaceId,
+          sourceConnectionId: payload.sourceConnectionId,
+          sourceExternalRepositoryId: payload.externalRepositoryId,
+          sourceRef: payload.ref,
+          sourceCommitSha: payload.headCommitSha,
+        },
+      ],
+    });
+  });
+});

package/src/presentation/subscribers/on-project-source-commit-observed.ts

@@ -0,0 +1,15 @@
+import type {ProjectSourceCommitObservedEvent} from '@shipfox/api-projects-dto';
+import {startDefinitionSync} from './start-definition-sync.js';
+
+export async function onProjectSourceCommitObserved(
+  payload: ProjectSourceCommitObservedEvent,
+): Promise<void> {
+  await startDefinitionSync({
+    projectId: payload.projectId,
+    workspaceId: payload.workspaceId,
+    sourceConnectionId: payload.sourceConnectionId,
+    externalRepositoryId: payload.externalRepositoryId,
+    sourceRef: payload.ref,
+    sourceCommitSha: payload.headCommitSha,
+  });
+}

package/src/presentation/subscribers/start-definition-sync.ts

@@ -0,0 +1,38 @@
+import {temporalClient} from '@shipfox/node-temporal';
+import {DEFINITION_SYNC_WORKFLOW, DEFINITIONS_TASK_QUEUE} from '#temporal/index.js';
+
+export interface StartDefinitionSyncParams {
+  projectId: string;
+  workspaceId: string;
+  sourceConnectionId: string;
+  externalRepositoryId: string;
+  sourceRef?: string | undefined;
+  sourceCommitSha?: string | undefined;
+}
+
+export async function startDefinitionSync(params: StartDefinitionSyncParams): Promise<void> {
+  const workflowId = buildWorkflowId(params);
+
+  await temporalClient().workflow.start(DEFINITION_SYNC_WORKFLOW, {
+    taskQueue: DEFINITIONS_TASK_QUEUE,
+    workflowId,
+    workflowIdConflictPolicy: 'USE_EXISTING',
+    workflowIdReusePolicy: 'ALLOW_DUPLICATE',
+    args: [
+      {
+        projectId: params.projectId,
+        workspaceId: params.workspaceId,
+        sourceConnectionId: params.sourceConnectionId,
+        sourceExternalRepositoryId: params.externalRepositoryId,
+        sourceRef: params.sourceRef,
+        sourceCommitSha: params.sourceCommitSha,
+      },
+    ],
+  });
+}
+
+function buildWorkflowId(params: StartDefinitionSyncParams): string {
+  return params.sourceCommitSha
+    ? `definition-sync:${params.projectId}:${params.sourceCommitSha}`
+    : `definition-sync:${params.projectId}:bind`;
+}

package/src/temporal/activities/index.ts

@@ -0,0 +1,10 @@
+export type {
+  DiscoverWorkflowsActivityResult,
+  FetchAndApplyActivityInput,
+  FetchAndApplyActivityResult,
+  MarkSyncFailedActivityInput,
+  PrepareSyncResult,
+  SyncRefScopedInput,
+  SyncWorkflowInput,
+} from './sync-activities.js';
+export {createDefinitionSyncActivities} from './sync-activities.js';

package/src/temporal/activities/sync-activities.test.ts

@@ -0,0 +1,337 @@
+import {
+  IntegrationProviderError,
+  type IntegrationSourceControlService,
+} from '@shipfox/api-integration-core';
+import {ApplicationFailure} from '@temporalio/common';
+import {sql} from 'drizzle-orm';
+import {db, definitionSyncStates} from '#db/index.js';
+import {workflowDefinitions} from '#db/schema/definitions.js';
+import {createDefinitionSyncActivities} from './sync-activities.js';
+
+vi.mock('@temporalio/activity', () => ({
+  Context: {
+    current: () => ({heartbeat: vi.fn()}),
+  },
+}));
+
+const validYaml = `
+name: CI
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - run: pnpm test
+`;
+
+function sourceControl(
+  overrides: Partial<IntegrationSourceControlService> = {},
+): IntegrationSourceControlService {
+  return {
+    getConnection: vi.fn(),
+    listRepositories: vi.fn(),
+    resolveRepository: vi.fn(() =>
+      Promise.resolve({
+        connection: {
+          id: 'connection-1',
+          workspaceId: 'workspace-1',
+          provider: 'gitea',
+          externalAccountId: 'gitea-owner',
+          slug: 'gitea_owner',
+          displayName: 'Gitea',
+          lifecycleStatus: 'active' as const,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+        repository: {
+          externalRepositoryId: 'gitea:gitea-owner/platform',
+          owner: 'gitea-owner',
+          name: 'platform',
+          fullName: 'gitea-owner/platform',
+          defaultBranch: 'main',
+          visibility: 'private' as const,
+          cloneUrl: 'https://gitea.local/gitea-owner/platform.git',
+          htmlUrl: 'https://gitea.local/gitea-owner/platform',
+        },
+      }),
+    ),
+    listFiles: vi.fn(() =>
+      Promise.resolve({
+        files: [{path: '.shipfox/workflows/ci.yml', type: 'file' as const, size: validYaml.length}],
+        nextCursor: null,
+      }),
+    ),
+    fetchFile: vi.fn(() =>
+      Promise.resolve({path: '.shipfox/workflows/ci.yml', ref: 'main', content: validYaml}),
+    ),
+    createCheckoutSpec: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe('definition sync activities', () => {
+  let projectId: string;
+  let sourceConnectionId: string;
+
+  beforeEach(() => {
+    projectId = crypto.randomUUID();
+    sourceConnectionId = crypto.randomUUID();
+  });
+
+  describe('prepareDefinitionSync', () => {
+    it('marks the sync state as syncing and returns the resolved ref', async () => {
+      const activities = createDefinitionSyncActivities(sourceControl());
+
+      const result = await activities.prepareDefinitionSync({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+      });
+
+      expect(result).toEqual({sourceRef: 'main', sourceCommitSha: undefined});
+      const rows = await db()
+        .select()
+        .from(definitionSyncStates)
+        .where(sql`${definitionSyncStates.projectId} = ${projectId}`);
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.status).toBe('syncing');
+      expect(rows[0]?.ref).toBe('main');
+    });
+
+    it('keeps source ref and source commit sha separate for commit-triggered sync', async () => {
+      const source = sourceControl();
+      const activities = createDefinitionSyncActivities(source);
+
+      const result = await activities.prepareDefinitionSync({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+        sourceCommitSha: 'abc123',
+      });
+
+      expect(result).toEqual({sourceRef: 'main', sourceCommitSha: 'abc123'});
+      expect(source.resolveRepository).not.toHaveBeenCalled();
+      const rows = await db()
+        .select()
+        .from(definitionSyncStates)
+        .where(sql`${definitionSyncStates.projectId} = ${projectId}`);
+      expect(rows[0]?.ref).toBe('main');
+    });
+
+    it('translates retryable resolveRepository failures into retryable ApplicationFailures', async () => {
+      const activities = createDefinitionSyncActivities(
+        sourceControl({
+          resolveRepository: vi.fn(() => {
+            return Promise.reject(new Error('temporary outage'));
+          }),
+        }),
+      );
+
+      const result = activities.prepareDefinitionSync({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+      });
+
+      await expect(result).rejects.toBeInstanceOf(ApplicationFailure);
+      await expect(result).rejects.toMatchObject({
+        nonRetryable: false,
+        type: 'unknown',
+        message: 'temporary outage',
+      });
+    });
+
+    it('preserves retryable provider error codes for workflow-level failure persistence', async () => {
+      const activities = createDefinitionSyncActivities(
+        sourceControl({
+          resolveRepository: vi.fn(() => {
+            return Promise.reject(
+              new IntegrationProviderError('timeout', 'GitHub request timed out'),
+            );
+          }),
+        }),
+      );
+
+      const result = activities.prepareDefinitionSync({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+      });
+
+      await expect(result).rejects.toMatchObject({
+        nonRetryable: false,
+        type: 'provider-timeout',
+        message: 'GitHub request timed out',
+      });
+    });
+  });
+
+  describe('fetchAndApplyDefinitionWorkflows', () => {
+    it('upserts workflow definitions and soft-deletes orphans', async () => {
+      const activities = createDefinitionSyncActivities(sourceControl());
+
+      const result = await activities.fetchAndApplyDefinitionWorkflows({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+        paths: ['.shipfox/workflows/ci.yml'],
+      });
+
+      expect(result.appliedCount).toBe(1);
+      expect(result.deletedCount).toBe(0);
+    });
+
+    it('translates DefinitionSyncPermanentError into a non-retryable ApplicationFailure', async () => {
+      const activities = createDefinitionSyncActivities(
+        sourceControl({
+          fetchFile: vi.fn(() =>
+            Promise.resolve({
+              path: '.shipfox/workflows/bad.yml',
+              ref: 'main',
+              content: 'name: Bad\n  broken:\nindent',
+            }),
+          ),
+        }),
+      );
+
+      const result = activities.fetchAndApplyDefinitionWorkflows({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+        sourceCommitSha: 'abc123',
+        paths: ['.shipfox/workflows/ci.yml'],
+      });
+
+      await expect(result).rejects.toBeInstanceOf(ApplicationFailure);
+      await expect(result).rejects.toMatchObject({nonRetryable: true, type: 'invalid-definition'});
+    });
+
+    it('fetches from source commit sha while persisting under source ref', async () => {
+      const source = sourceControl();
+      const activities = createDefinitionSyncActivities(source);
+
+      const result = await activities.fetchAndApplyDefinitionWorkflows({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+        sourceCommitSha: 'abc123',
+        paths: ['.shipfox/workflows/ci.yml'],
+      });
+
+      const rows = await db()
+        .select()
+        .from(workflowDefinitions)
+        .where(sql`${workflowDefinitions.projectId} = ${projectId}`);
+      expect(result.appliedCount).toBe(1);
+      expect(source.fetchFile).toHaveBeenCalledWith(
+        expect.objectContaining({ref: 'abc123', path: '.shipfox/workflows/ci.yml'}),
+      );
+      expect(rows[0]?.ref).toBe('main');
+    });
+  });
+
+  describe('markDefinitionSyncFailed', () => {
+    it('persists last_error_code and last_error_message verbatim', async () => {
+      const activities = createDefinitionSyncActivities(sourceControl());
+      await activities.prepareDefinitionSync({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+      });
+
+      const result = activities.markDefinitionSyncFailed({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+        code: 'invalid-definition',
+        message: 'Invalid workflow at .shipfox/workflows/bad.yml',
+      });
+      await result;
+
+      const rows = await db()
+        .select()
+        .from(definitionSyncStates)
+        .where(sql`${definitionSyncStates.projectId} = ${projectId}`);
+      expect(rows[0]?.status).toBe('failed');
+      expect(rows[0]?.lastErrorCode).toBe('invalid-definition');
+      expect(rows[0]?.lastErrorMessage).toBe('Invalid workflow at .shipfox/workflows/bad.yml');
+      expect(rows[0]?.finishedAt).not.toBeNull();
+    });
+
+    it('persists failures with the unresolved sentinel ref when no ref was produced', async () => {
+      const activities = createDefinitionSyncActivities(sourceControl());
+
+      const result = activities.markDefinitionSyncFailed({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: null,
+        code: 'connection-unavailable',
+        message: 'connection disabled before resolving repository',
+      });
+      await result;
+
+      const rows = await db()
+        .select()
+        .from(definitionSyncStates)
+        .where(sql`${definitionSyncStates.projectId} = ${projectId}`);
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.ref).toBe('__unresolved__');
+      expect(rows[0]?.status).toBe('failed');
+      expect(rows[0]?.lastErrorCode).toBe('connection-unavailable');
+      expect(rows[0]?.lastErrorMessage).toBe('connection disabled before resolving repository');
+    });
+  });
+
+  describe('markDefinitionSyncSucceeded', () => {
+    it('clears stale error fields when transitioning to succeeded', async () => {
+      const activities = createDefinitionSyncActivities(sourceControl());
+      await activities.prepareDefinitionSync({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+      });
+      await activities.markDefinitionSyncFailed({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+        code: 'invalid-definition',
+        message: 'something',
+      });
+
+      const result = activities.markDefinitionSyncSucceeded({
+        projectId,
+        workspaceId: crypto.randomUUID(),
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea:gitea-owner/platform',
+        sourceRef: 'main',
+      });
+      await result;
+
+      const rows = await db()
+        .select()
+        .from(definitionSyncStates)
+        .where(sql`${definitionSyncStates.projectId} = ${projectId}`);
+      expect(rows[0]?.status).toBe('succeeded');
+      expect(rows[0]?.lastErrorCode).toBeNull();
+      expect(rows[0]?.lastErrorMessage).toBeNull();
+    });
+  });
+});