@shipfox/api-definitions 2.0.0

package/src/db/sync-states.ts

@@ -0,0 +1,86 @@
+import {and, desc, eq} from 'drizzle-orm';
+import type {
+  DefinitionSyncErrorCode,
+  DefinitionSyncState,
+  DefinitionSyncStatus,
+} from '#core/entities/sync-state.js';
+import {db} from './db.js';
+import {definitionSyncStates, toDefinitionSyncState} from './schema/sync-states.js';
+
+export interface DefinitionSyncStateKey {
+  projectId: string;
+  sourceConnectionId: string;
+  sourceExternalRepositoryId: string;
+  ref: string;
+}
+
+export interface MarkDefinitionSyncParams extends DefinitionSyncStateKey {
+  status: DefinitionSyncStatus;
+  lastErrorCode?: DefinitionSyncErrorCode | null | undefined;
+  lastErrorMessage?: string | null | undefined;
+  startedAt?: Date | null | undefined;
+  finishedAt?: Date | null | undefined;
+}
+
+export async function markDefinitionSyncState(
+  params: MarkDefinitionSyncParams,
+): Promise<DefinitionSyncState> {
+  const now = new Date();
+  const [row] = await db()
+    .insert(definitionSyncStates)
+    .values({
+      projectId: params.projectId,
+      sourceConnectionId: params.sourceConnectionId,
+      sourceExternalRepositoryId: params.sourceExternalRepositoryId,
+      ref: params.ref,
+      status: params.status,
+      lastErrorCode: params.lastErrorCode ?? null,
+      lastErrorMessage: params.lastErrorMessage ?? null,
+      startedAt: params.startedAt ?? null,
+      finishedAt: params.finishedAt ?? null,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [
+        definitionSyncStates.projectId,
+        definitionSyncStates.sourceConnectionId,
+        definitionSyncStates.sourceExternalRepositoryId,
+        definitionSyncStates.ref,
+      ],
+      set: {
+        status: params.status,
+        lastErrorCode: params.lastErrorCode ?? null,
+        lastErrorMessage: params.lastErrorMessage ?? null,
+        ...(params.startedAt !== undefined ? {startedAt: params.startedAt} : {}),
+        ...(params.finishedAt !== undefined ? {finishedAt: params.finishedAt} : {}),
+        updatedAt: now,
+      },
+    })
+    .returning();
+
+  if (!row) throw new Error('Definition sync state upsert returned no rows');
+  return toDefinitionSyncState(row);
+}
+
+export async function getLatestDefinitionSyncState(params: {
+  projectId: string;
+  sourceConnectionId: string;
+  sourceExternalRepositoryId: string;
+}): Promise<DefinitionSyncState | undefined> {
+  const rows = await db()
+    .select()
+    .from(definitionSyncStates)
+    .where(
+      and(
+        eq(definitionSyncStates.projectId, params.projectId),
+        eq(definitionSyncStates.sourceConnectionId, params.sourceConnectionId),
+        eq(definitionSyncStates.sourceExternalRepositoryId, params.sourceExternalRepositoryId),
+      ),
+    )
+    .orderBy(desc(definitionSyncStates.updatedAt))
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+  return toDefinitionSyncState(row);
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {
+  DEFINITION_RESOLVED,
+  type DefinitionsEventMap,
+  definitionsEventSchemas,
+} from '@shipfox/api-definitions-dto';
+import type {
+  AgentToolSelectionCatalogs,
+  GetIntegrationConnectionByIdFn,
+  IntegrationSourceControlService,
+  LoadWorkspaceConnectionSnapshot,
+} from '@shipfox/api-integration-core';
+import {
+  PROJECT_SOURCE_BOUND,
+  PROJECT_SOURCE_COMMIT_OBSERVED,
+  type ProjectsEventMap,
+} from '@shipfox/api-projects-dto';
+import {type ShipfoxModule, subscriberFactory} from '@shipfox/node-module';
+import {logger} from '@shipfox/node-opentelemetry';
+import {db, definitionsOutbox, migrationsPath} from '#db/index.js';
+import {createDefinitionRoutes} from '#presentation/index.js';
+import {
+  onProjectSourceBound,
+  onProjectSourceCommitObserved,
+} from '#presentation/subscribers/index.js';
+import {createDefinitionSyncActivities, DEFINITIONS_TASK_QUEUE} from '#temporal/index.js';
+
+export type {
+  WorkflowDefinition,
+  WorkflowDefinitionPayload,
+  WorkflowEnvTemplates,
+  WorkflowModel,
+  WorkflowModelJobCheckout,
+  WorkflowSourceSnapshot,
+  WorkflowSpec,
+} from '#core/index.js';
+export {
+  DEFAULT_JOB_CHECKOUT,
+  DEFAULT_JOB_SUCCESS,
+  DEFAULT_RUN_TIMEOUT_MS,
+  normalizeWorkflowDocument,
+} from '#core/index.js';
+export {db, definitionsOutbox, getDefinitionById, migrationsPath} from '#db/index.js';
+export {routes} from '#presentation/index.js';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const workflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
+
+const subscriber = subscriberFactory<DefinitionsEventMap & ProjectsEventMap>();
+
+export interface CreateDefinitionsModuleOptions {
+  sourceControl: IntegrationSourceControlService;
+  agentToolSelectionCatalogs?: AgentToolSelectionCatalogs | undefined;
+  loadWorkspaceConnectionSnapshot?: LoadWorkspaceConnectionSnapshot | undefined;
+  getIntegrationConnectionById?: GetIntegrationConnectionByIdFn | undefined;
+}
+
+export function createDefinitionsModule({
+  sourceControl,
+  agentToolSelectionCatalogs,
+  loadWorkspaceConnectionSnapshot,
+  getIntegrationConnectionById,
+}: CreateDefinitionsModuleOptions): ShipfoxModule {
+  const integrationValidation =
+    agentToolSelectionCatalogs === undefined ||
+    loadWorkspaceConnectionSnapshot === undefined ||
+    getIntegrationConnectionById === undefined
+      ? undefined
+      : {
+          agentToolSelectionCatalogs,
+          loadWorkspaceConnectionSnapshot,
+          getIntegrationConnectionById,
+        };
+
+  return {
+    name: 'definitions',
+    database: {db, migrationsPath},
+    routes: createDefinitionRoutes({
+      agentToolSelectionCatalogs,
+      loadWorkspaceConnectionSnapshot,
+      getIntegrationConnectionById,
+    }),
+    publishers: [
+      {name: 'definitions', table: definitionsOutbox, db, eventSchemas: definitionsEventSchemas},
+    ],
+    subscribers: [
+      subscriber(DEFINITION_RESOLVED, (_payload, event) => {
+        logger().info({event}, 'Definition resolved');
+        return Promise.resolve();
+      }),
+      subscriber(PROJECT_SOURCE_BOUND, onProjectSourceBound),
+      subscriber(PROJECT_SOURCE_COMMIT_OBSERVED, onProjectSourceCommitObserved),
+    ],
+    workers: [
+      {
+        taskQueue: DEFINITIONS_TASK_QUEUE,
+        workflowsPath,
+        activities: () => createDefinitionSyncActivities(sourceControl, integrationValidation),
+        workflows: [],
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,59 @@
+import type {WorkflowDefinition} from '#core/entities/workflow-definition.js';
+import {normalizeWorkflowDocument} from '#core/workflow-model/index.js';
+import {toDefinitionDto} from './definition.js';
+
+describe('toDefinitionDto', () => {
+  it('maps the workflow definition entity to the public DTO shape', () => {
+    const document = {
+      name: 'Manual workflow',
+      runner: 'ubuntu-latest',
+      triggers: {
+        run_now: {
+          source: 'manual',
+          event: 'fire',
+        },
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'pnpm build'}],
+        },
+      },
+    };
+    const definition: WorkflowDefinition = {
+      id: '019e98ab-6656-7ca1-b9ad-1ca4442c479d',
+      projectId: '019e98ab-b90f-7265-b13c-8b441c991381',
+      configPath: '.shipfox/workflows/manual.yml',
+      source: 'manual',
+      sha: null,
+      ref: null,
+      name: document.name,
+      definition: document,
+      document,
+      model: normalizeWorkflowDocument(document),
+      sourceSnapshot: null,
+      contentHash: null,
+      fetchedAt: new Date('2026-06-09T10:00:00.000Z'),
+      createdAt: new Date('2026-06-09T10:00:01.000Z'),
+      updatedAt: new Date('2026-06-09T10:00:02.000Z'),
+      deletedAt: null,
+    };
+
+    const result = toDefinitionDto(definition);
+
+    expect(result).toEqual({
+      id: definition.id,
+      project_id: definition.projectId,
+      config_path: definition.configPath,
+      source: 'manual',
+      sha: null,
+      ref: null,
+      name: document.name,
+      workflow_document: document,
+      workflow_model: definition.model,
+      manual_trigger: {name: 'run_now'},
+      fetched_at: '2026-06-09T10:00:00.000Z',
+      created_at: '2026-06-09T10:00:01.000Z',
+      updated_at: '2026-06-09T10:00:02.000Z',
+    });
+  });
+});

package/src/presentation/dto/definition.ts

@@ -0,0 +1,41 @@
+import type {DefinitionDto, DefinitionSyncSummaryDto} from '@shipfox/api-definitions-dto';
+import type {DefinitionSyncState} from '#core/entities/sync-state.js';
+import type {WorkflowDefinition} from '#core/entities/workflow-definition.js';
+import {UNRESOLVED_SYNC_REF} from '#core/sync-definitions.js';
+
+export function toDefinitionDto(definition: WorkflowDefinition): DefinitionDto {
+  const manualEntry = Object.entries(definition.document.triggers ?? {}).find(
+    ([, trigger]) => trigger.source === 'manual',
+  );
+  return {
+    id: definition.id,
+    project_id: definition.projectId,
+    config_path: definition.configPath,
+    source: definition.source,
+    sha: definition.sha,
+    ref: definition.ref,
+    name: definition.name,
+    workflow_document: definition.document,
+    workflow_model: definition.model,
+    manual_trigger: manualEntry ? {name: manualEntry[0]} : null,
+    fetched_at: definition.fetchedAt.toISOString(),
+    created_at: definition.createdAt.toISOString(),
+    updated_at: definition.updatedAt.toISOString(),
+  };
+}
+
+export function toDefinitionSyncSummaryDto(
+  syncState: DefinitionSyncState | undefined,
+): DefinitionSyncSummaryDto | null {
+  if (!syncState) return null;
+
+  return {
+    ref: syncState.ref === UNRESOLVED_SYNC_REF ? null : syncState.ref,
+    status: syncState.status,
+    last_sync_at: (syncState.finishedAt ?? syncState.updatedAt).toISOString(),
+    started_at: syncState.startedAt?.toISOString() ?? null,
+    finished_at: syncState.finishedAt?.toISOString() ?? null,
+    last_error_code: syncState.lastErrorCode,
+    last_error_message: syncState.lastErrorMessage,
+  };
+}

package/src/presentation/dto/index.ts

@@ -0,0 +1 @@
+export {toDefinitionDto, toDefinitionSyncSummaryDto} from './definition.js';

package/src/presentation/index.ts

@@ -0,0 +1 @@
+export {createDefinitionRoutes, definitionRoutes as routes} from './routes/index.js';

package/src/presentation/routes/create-definition.test.ts

@@ -0,0 +1,356 @@
+import {buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {buildCreateDefinitionRoute, createDefinitionRoute} from './create-definition.js';
+
+const projectAccessState = vi.hoisted(() => ({workspaceId: '', sourceConnectionId: ''}));
+
+vi.mock('@shipfox/api-projects', () => ({
+  ProjectNotFoundError: class ProjectNotFoundError extends Error {},
+  requireProjectAccess: vi.fn(({projectId}) =>
+    Promise.resolve({
+      project: {
+        id: projectId,
+        workspaceId: projectAccessState.workspaceId,
+        sourceConnectionId: projectAccessState.sourceConnectionId,
+      },
+      workspaceId: projectAccessState.workspaceId,
+    }),
+  ),
+}));
+
+describe('POST /api/definitions', () => {
+  let app: FastifyInstance;
+  let workspaceId: string;
+  let projectId: string;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    app.addHook('onRequest', (request, _reply, done) => {
+      setUserContext(
+        request,
+        buildUserContext({
+          userId: crypto.randomUUID(),
+          email: 'user@example.com',
+          memberships: [{workspaceId, role: 'admin'}],
+        }),
+      );
+      done();
+    });
+    app.post('/api/definitions', createDefinitionRoute);
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    projectAccessState.workspaceId = workspaceId;
+    projectAccessState.sourceConnectionId = crypto.randomUUID();
+  });
+
+  const validYaml = `
+name: Test Workflow
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+  test('valid YAML returns 200 with definition response', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, config_path: '.shipfox/workflows/test.yml', yaml: validYaml},
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.id).toBeDefined();
+    expect(body.project_id).toBe(projectId);
+    expect(body.config_path).toBe('.shipfox/workflows/test.yml');
+    expect(body.source).toBe('manual');
+    expect(body.name).toBe('Test Workflow');
+    expect(body.workflow_document.name).toBe('Test Workflow');
+    expect(body.workflow_model.kind).toBe('workflow');
+    expect(body.sha).toBeNull();
+    expect(body.ref).toBeNull();
+    expect(body.fetched_at).toBeDefined();
+  });
+
+  test('skips connection snapshot loading when YAML has no integrations', async () => {
+    const loadWorkspaceConnectionSnapshot = vi.fn(() => Promise.resolve(new Map()));
+    const appWithOptions = Fastify();
+    appWithOptions.setValidatorCompiler(validatorCompiler);
+    appWithOptions.setSerializerCompiler(serializerCompiler);
+    appWithOptions.addHook('onRequest', (request, _reply, done) => {
+      setUserContext(
+        request,
+        buildUserContext({
+          userId: crypto.randomUUID(),
+          email: 'user@example.com',
+          memberships: [{workspaceId, role: 'admin'}],
+        }),
+      );
+      done();
+    });
+    appWithOptions.post(
+      '/api/definitions',
+      buildCreateDefinitionRoute({
+        agentToolSelectionCatalogs: new Map(),
+        loadWorkspaceConnectionSnapshot,
+      }),
+    );
+    await appWithOptions.ready();
+
+    const res = await appWithOptions.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {
+        project_id: projectId,
+        config_path: '.shipfox/workflows/test.yml',
+        yaml: validYaml,
+      },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(loadWorkspaceConnectionSnapshot).not.toHaveBeenCalled();
+  });
+
+  test('uses the project source connection as the default integration connection', async () => {
+    const loadWorkspaceConnectionSnapshot = vi.fn(() =>
+      Promise.resolve(
+        new Map([
+          [
+            'github-main',
+            {
+              id: projectAccessState.sourceConnectionId,
+              provider: 'github',
+              capabilities: ['agent_tools'] as const,
+            },
+          ],
+        ]),
+      ),
+    );
+    const getIntegrationConnectionById = vi.fn(() =>
+      Promise.resolve({
+        id: projectAccessState.sourceConnectionId,
+        workspaceId,
+        provider: 'github',
+        externalAccountId: 'installation-1',
+        slug: 'github-main',
+        displayName: 'GitHub',
+        lifecycleStatus: 'active' as const,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+    );
+    const appWithOptions = Fastify();
+    appWithOptions.setValidatorCompiler(validatorCompiler);
+    appWithOptions.setSerializerCompiler(serializerCompiler);
+    appWithOptions.addHook('onRequest', (request, _reply, done) => {
+      setUserContext(
+        request,
+        buildUserContext({
+          userId: crypto.randomUUID(),
+          email: 'user@example.com',
+          memberships: [{workspaceId, role: 'admin'}],
+        }),
+      );
+      done();
+    });
+    appWithOptions.post(
+      '/api/definitions',
+      buildCreateDefinitionRoute({
+        agentToolSelectionCatalogs: new Map([
+          [
+            'github',
+            {
+              selectors: [
+                {token: 'issue_read', kind: 'family', sensitivity: 'read', sensitive: false},
+              ],
+            },
+          ],
+        ]),
+        loadWorkspaceConnectionSnapshot,
+        getIntegrationConnectionById,
+      }),
+    );
+    await appWithOptions.ready();
+
+    const res = await appWithOptions.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {
+        project_id: projectId,
+        config_path: '.shipfox/workflows/test.yml',
+        yaml: `
+name: Agent Workflow
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - prompt: Fix the issue
+        integrations:
+          - include: [issue_read]
+`,
+      },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(getIntegrationConnectionById).toHaveBeenCalledWith(
+      projectAccessState.sourceConnectionId,
+    );
+  });
+
+  test('invalid YAML syntax returns 400', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {
+        project_id: projectId,
+        config_path: 'test.yml',
+        yaml: 'name: Bad\n  invalid:\nindentation',
+      },
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  test('valid YAML with invalid definition returns 400 with error code', async () => {
+    const yamlMissingName = `
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, config_path: 'test.yml', yaml: yamlMissingName},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('invalid-workflow-definition');
+  });
+
+  test('cyclic DAG returns 400 with dag error code', async () => {
+    const cyclicYaml = `
+name: Cyclic
+runner: ubuntu-latest
+jobs:
+  a:
+    needs: b
+    steps:
+      - run: echo a
+  b:
+    needs: a
+    steps:
+      - run: echo b
+`;
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, config_path: 'test.yml', yaml: cyclicYaml},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('invalid-workflow-definition');
+  });
+
+  test('upsert same config_path updates the definition', async () => {
+    const payload1 = {project_id: projectId, config_path: 'deploy.yml', yaml: validYaml};
+
+    const res1 = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: payload1,
+    });
+
+    const updatedYaml = `
+name: Updated Workflow
+runner: ubuntu-latest
+jobs:
+  deploy:
+    steps:
+      - run: ./deploy.sh
+`;
+    const res2 = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, config_path: 'deploy.yml', yaml: updatedYaml},
+    });
+
+    expect(res2.statusCode).toBe(200);
+    expect(res2.json().id).toBe(res1.json().id);
+    expect(res2.json().name).toBe('Updated Workflow');
+  });
+
+  test('runner-less YAML returns validation details with the runner path', async () => {
+    const yaml = `
+name: Missing Runner
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, config_path: 'test.yml', yaml},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({
+      code: 'invalid-workflow-definition',
+      details: [expect.objectContaining({path: 'jobs.build.runner'})],
+    });
+  });
+
+  test('missing body fields returns 400', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  test('invalid projectId UUID returns 400', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: 'not-a-uuid', config_path: 'test.yml', yaml: validYaml},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toBeDefined();
+  });
+
+  test('creates a manual definition without a config path', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, yaml: validYaml},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().config_path).toBeNull();
+    expect(res.json().source).toBe('manual');
+  });
+
+  test('rejects a VCS definition without a config path', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/definitions',
+      payload: {project_id: projectId, source: 'vcs', yaml: validYaml},
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});