@shipfox/api-definitions 2.0.0

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

@@ -0,0 +1,101 @@
+import {
+  createDefinitionBodySchema,
+  definitionResponseSchema,
+  definitionValidationErrorSchema,
+} from '@shipfox/api-definitions-dto';
+import type {
+  AgentToolSelectionCatalogs,
+  GetIntegrationConnectionByIdFn,
+  LoadWorkspaceConnectionSnapshot,
+} from '@shipfox/api-integration-core';
+import {ProjectNotFoundError, requireProjectAccess} from '@shipfox/api-projects';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {DefinitionParseError} from '#core/errors.js';
+import {hasAgentStepIntegrations} from '#core/has-agent-step-integrations.js';
+import {parseDefinition} from '#core/parse-definition.js';
+import {upsertDefinition} from '#db/definitions.js';
+import {toDefinitionDto} from '#presentation/dto/index.js';
+
+export interface CreateDefinitionRouteOptions {
+  agentToolSelectionCatalogs?: AgentToolSelectionCatalogs | undefined;
+  loadWorkspaceConnectionSnapshot?: LoadWorkspaceConnectionSnapshot | undefined;
+  getIntegrationConnectionById?: GetIntegrationConnectionByIdFn | undefined;
+}
+
+export function buildCreateDefinitionRoute(options: CreateDefinitionRouteOptions = {}) {
+  return defineRoute({
+    method: 'POST',
+    path: '/',
+    description: 'Create or update a workflow definition',
+    schema: {
+      body: createDefinitionBodySchema,
+      response: {
+        200: definitionResponseSchema,
+        400: z.object({
+          code: z.string(),
+          message: z.string().optional(),
+          details: z.array(definitionValidationErrorSchema).optional(),
+        }),
+        404: z.object({code: z.string()}),
+      },
+    },
+    errorHandler: (error, _request, _reply) => {
+      if (error instanceof DefinitionParseError) {
+        throw new ClientError(error.message, 'invalid-workflow-definition', {
+          details: error.details,
+          status: 400,
+        });
+      }
+      if (error instanceof ProjectNotFoundError) {
+        throw new ClientError(error.message, 'project-not-found', {status: 404});
+      }
+      throw error;
+    },
+    handler: async (request) => {
+      const {project_id: projectId, config_path, source, yaml: yamlString, sha, ref} = request.body;
+      const {project} = await requireProjectAccess({request, projectId});
+
+      const structurallyParsed = parseDefinition(yamlString);
+      const {
+        agentToolSelectionCatalogs,
+        loadWorkspaceConnectionSnapshot,
+        getIntegrationConnectionById,
+      } = options;
+      const parsed =
+        agentToolSelectionCatalogs !== undefined &&
+        loadWorkspaceConnectionSnapshot !== undefined &&
+        hasAgentStepIntegrations(structurallyParsed.document)
+          ? parseDefinition(yamlString, {
+              integrationValidationContext: {
+                agentToolSelectionCatalogs,
+                workspaceConnectionSnapshot: await loadWorkspaceConnectionSnapshot(
+                  project.workspaceId,
+                ),
+                defaultConnectionSlug:
+                  getIntegrationConnectionById === undefined
+                    ? undefined
+                    : (await getIntegrationConnectionById(project.sourceConnectionId))?.slug,
+              },
+            })
+          : structurallyParsed;
+
+      const definition = await upsertDefinition({
+        projectId,
+        workspaceId: project.workspaceId,
+        configPath: config_path,
+        source,
+        name: parsed.document.name,
+        document: parsed.document,
+        model: parsed.model,
+        sourceSnapshot: parsed.sourceSnapshot,
+        sha,
+        ref,
+      });
+
+      return toDefinitionDto(definition);
+    },
+  });
+}
+
+export const createDefinitionRoute = buildCreateDefinitionRoute();

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

@@ -0,0 +1,79 @@
+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 {definitionFactory} from '#test/index.js';
+import {getDefinitionRoute} from './get-definition.js';
+
+const projectAccessState = vi.hoisted(() => ({workspaceId: ''}));
+
+vi.mock('@shipfox/api-projects', () => ({
+  ProjectNotFoundError: class ProjectNotFoundError extends Error {},
+  requireProjectAccess: vi.fn(({projectId}) =>
+    Promise.resolve({
+      project: {id: projectId, workspaceId: projectAccessState.workspaceId},
+      workspaceId: projectAccessState.workspaceId,
+    }),
+  ),
+}));
+
+describe('GET /api/definitions/:id', () => {
+  let app: FastifyInstance;
+  let workspaceId: 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.get('/api/definitions/:id', getDefinitionRoute);
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectAccessState.workspaceId = workspaceId;
+  });
+
+  test('returns 200 with definition when found', async () => {
+    const definition = await definitionFactory.create();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions/${definition.id}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().id).toBe(definition.id);
+    expect(res.json().name).toBe(definition.name);
+  });
+
+  test('returns 404 when not found', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions/${crypto.randomUUID()}`,
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  test('returns 400 for invalid UUID', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/definitions/not-a-uuid',
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});

package/src/presentation/routes/get-definition.ts

@@ -0,0 +1,37 @@
+import {definitionResponseSchema} from '@shipfox/api-definitions-dto';
+import {ProjectNotFoundError, requireProjectAccess} from '@shipfox/api-projects';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {getDefinitionById} from '#db/definitions.js';
+import {toDefinitionDto} from '#presentation/dto/index.js';
+
+export const getDefinitionRoute = defineRoute({
+  method: 'GET',
+  path: '/:id',
+  description: 'Get a definition by ID',
+  schema: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+    response: {
+      200: definitionResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof ProjectNotFoundError) {
+      throw new ClientError('Definition not found', 'not-found', {status: 404});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const {id} = request.params;
+    const definition = await getDefinitionById(id);
+
+    if (!definition) {
+      throw new ClientError('Definition not found', 'not-found', {status: 404});
+    }
+    await requireProjectAccess({request, projectId: definition.projectId});
+
+    return toDefinitionDto(definition);
+  },
+});

package/src/presentation/routes/index.test.ts

@@ -0,0 +1,41 @@
+import {AUTH_USER, buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import {type AuthMethod, ClientError, closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {definitionRoutes} from './index.js';
+
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    if (request.headers.authorization !== 'Bearer user') {
+      throw new ClientError('Invalid user token', 'unauthorized', {status: 401});
+    }
+
+    setUserContext(
+      request,
+      buildUserContext({userId: 'user-1', email: 'user@example.com', memberships: []}),
+    );
+    return Promise.resolve();
+  },
+};
+
+afterEach(async () => {
+  await closeApp();
+});
+
+describe('definition route auth', () => {
+  test('uses user auth', () => {
+    expect(definitionRoutes[0]?.auth).toBe(AUTH_USER);
+  });
+
+  test('rejects API-key-only requests', async () => {
+    const app = await createApp({auth: [fakeUserAuth], routes: definitionRoutes, swagger: false});
+    const res = await app.inject({
+      method: 'GET',
+      url: `/definitions?project_id=${crypto.randomUUID()}`,
+      headers: {authorization: 'Bearer api-key'},
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('unauthorized');
+  });
+});

package/src/presentation/routes/index.ts

@@ -0,0 +1,28 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {
+  buildCreateDefinitionRoute,
+  type CreateDefinitionRouteOptions,
+} from './create-definition.js';
+import {getDefinitionRoute} from './get-definition.js';
+import {listDefinitionsRoute} from './list-definitions.js';
+import {validateDefinitionRoute} from './validate-definition.js';
+
+export interface DefinitionRouteOptions extends CreateDefinitionRouteOptions {}
+
+export function createDefinitionRoutes(options: DefinitionRouteOptions = {}): RouteGroup[] {
+  return [
+    {
+      prefix: '/definitions',
+      auth: AUTH_USER,
+      routes: [
+        buildCreateDefinitionRoute(options),
+        listDefinitionsRoute,
+        getDefinitionRoute,
+        validateDefinitionRoute,
+      ],
+    },
+  ];
+}
+
+export const definitionRoutes = createDefinitionRoutes();

package/src/presentation/routes/list-definitions.test.ts

@@ -0,0 +1,195 @@
+import {buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import {encodeStringIdCursor} from '@shipfox/node-drizzle';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {markDefinitionSyncState} from '#db/index.js';
+import {definitionFactory} from '#test/index.js';
+import {listDefinitionsRoute} from './list-definitions.js';
+
+const projectAccessState = vi.hoisted(() => ({
+  workspaceId: '',
+  sourceConnectionId: '',
+  sourceExternalRepositoryId: '',
+}));
+
+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,
+        sourceExternalRepositoryId: projectAccessState.sourceExternalRepositoryId,
+      },
+      workspaceId: projectAccessState.workspaceId,
+    }),
+  ),
+}));
+
+describe('GET /api/definitions', () => {
+  let app: FastifyInstance;
+  let workspaceId: string;
+  let projectId: string;
+  let sourceConnectionId: string;
+  let sourceExternalRepositoryId: 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.get('/api/definitions', listDefinitionsRoute);
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    sourceConnectionId = crypto.randomUUID();
+    sourceExternalRepositoryId = `repo:${crypto.randomUUID()}`;
+    projectAccessState.workspaceId = workspaceId;
+    projectAccessState.sourceConnectionId = sourceConnectionId;
+    projectAccessState.sourceExternalRepositoryId = sourceExternalRepositoryId;
+  });
+
+  test('returns 200 with definitions list and sync summary', async () => {
+    await definitionFactory.create({projectId, name: 'Bravo', configPath: 'b.yml'});
+    await definitionFactory.create({projectId, name: 'Alpha', configPath: 'a.yml'});
+    const startedAt = new Date('2026-05-07T01:00:00.000Z');
+    const finishedAt = new Date('2026-05-07T01:00:05.000Z');
+    await markDefinitionSyncState({
+      projectId,
+      sourceConnectionId,
+      sourceExternalRepositoryId,
+      ref: 'main',
+      status: 'succeeded',
+      startedAt,
+      finishedAt,
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions?project_id=${projectId}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.definitions).toHaveLength(2);
+    expect(body.definitions[0].name).toBe('Alpha');
+    expect(body.definitions[1].name).toBe('Bravo');
+    expect(body.next_cursor).toBeNull();
+    expect(body.sync).toEqual({
+      ref: 'main',
+      status: 'succeeded',
+      last_sync_at: finishedAt.toISOString(),
+      started_at: startedAt.toISOString(),
+      finished_at: finishedAt.toISOString(),
+      last_error_code: null,
+      last_error_message: null,
+    });
+  });
+
+  test('returns 200 with empty array and null sync for project with no definitions', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions?project_id=${projectId}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().definitions).toEqual([]);
+    expect(res.json().sync).toBeNull();
+    expect(res.json().next_cursor).toBeNull();
+  });
+
+  test('returns failed sync summary', async () => {
+    const startedAt = new Date('2026-05-07T02:00:00.000Z');
+    await markDefinitionSyncState({
+      projectId,
+      sourceConnectionId,
+      sourceExternalRepositoryId,
+      ref: 'main',
+      status: 'failed',
+      startedAt,
+      lastErrorCode: 'no-workflow-files',
+      lastErrorMessage: 'No workflow files found',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions?project_id=${projectId}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sync).toMatchObject({
+      ref: 'main',
+      status: 'failed',
+      started_at: startedAt.toISOString(),
+      finished_at: null,
+      last_error_code: 'no-workflow-files',
+      last_error_message: 'No workflow files found',
+    });
+  });
+
+  test('invalid projectId UUID returns 400', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/definitions?project_id=not-a-uuid',
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  test('paginates alphabetically with name and id cursor', async () => {
+    const bravo = await definitionFactory.create({projectId, name: 'Bravo', configPath: 'b.yml'});
+    const charlie = await definitionFactory.create({
+      projectId,
+      name: 'Charlie',
+      configPath: 'c.yml',
+    });
+    await definitionFactory.create({projectId, name: 'Alpha', configPath: 'a.yml'});
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions?project_id=${projectId}&limit=2`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.definitions.map((definition: {name: string}) => definition.name)).toEqual([
+      'Alpha',
+      'Bravo',
+    ]);
+    expect(body.next_cursor).toBe(encodeStringIdCursor({value: bravo.name, id: bravo.id}));
+
+    const next = await app.inject({
+      method: 'GET',
+      url: `/api/definitions?project_id=${projectId}&limit=2&cursor=${body.next_cursor}`,
+    });
+    expect(next.statusCode).toBe(200);
+    expect(next.json().definitions.map((definition: {id: string}) => definition.id)).toEqual([
+      charlie.id,
+    ]);
+  });
+
+  test('invalid cursor returns stable client error', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/definitions?project_id=${projectId}&cursor=not-a-cursor`,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('invalid-cursor');
+  });
+});

package/src/presentation/routes/list-definitions.ts

@@ -0,0 +1,49 @@
+import {
+  definitionListQuerySchema,
+  definitionListResponseSchema,
+} from '@shipfox/api-definitions-dto';
+import {ProjectNotFoundError, requireProjectAccess} from '@shipfox/api-projects';
+import {decodeStringIdCursor, encodeStringIdCursor} from '@shipfox/node-drizzle';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {listDefinitions} from '#db/definitions.js';
+import {getLatestDefinitionSyncState} from '#db/sync-states.js';
+import {toDefinitionDto, toDefinitionSyncSummaryDto} from '#presentation/dto/index.js';
+
+export const listDefinitionsRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  description: 'List all definitions for a project',
+  schema: {
+    querystring: definitionListQuerySchema,
+    response: {
+      200: definitionListResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof ProjectNotFoundError) {
+      throw new ClientError(error.message, 'project-not-found', {status: 404});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const {project_id: projectId, limit, cursor} = request.query;
+    const decodedCursor = decodeStringIdCursor(cursor);
+    if (cursor && !decodedCursor) {
+      throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+    }
+
+    const {project} = await requireProjectAccess({request, projectId});
+    const result = await listDefinitions({projectId, limit, cursor: decodedCursor});
+    const syncState = await getLatestDefinitionSyncState({
+      projectId,
+      sourceConnectionId: project.sourceConnectionId,
+      sourceExternalRepositoryId: project.sourceExternalRepositoryId,
+    });
+
+    return {
+      definitions: result.definitions.map(toDefinitionDto),
+      sync: toDefinitionSyncSummaryDto(syncState),
+      next_cursor: result.nextCursor ? encodeStringIdCursor(result.nextCursor) : null,
+    };
+  },
+});

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

@@ -0,0 +1,63 @@
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {validateDefinitionRoute} from './validate-definition.js';
+
+describe('POST /definitions/validate', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    app.post('/definitions/validate', validateDefinitionRoute);
+    await app.ready();
+  });
+
+  test('valid YAML returns 200 with { valid: true }', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/definitions/validate',
+      payload: {
+        yaml: `
+name: Test
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`,
+      },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.valid).toBe(true);
+    expect(body.workflow_document.name).toBe('Test');
+    expect(body.workflow_model.kind).toBe('workflow');
+  });
+
+  test('invalid YAML returns 200 with { valid: false, errors }', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/definitions/validate',
+      payload: {yaml: 'name: Bad\n  invalid:\nindentation'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.valid).toBe(false);
+    expect(body.errors).toBeDefined();
+    expect(body.errors.length).toBeGreaterThan(0);
+  });
+
+  test('missing body returns 400', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/definitions/validate',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});

package/src/presentation/routes/validate-definition.ts

@@ -0,0 +1,46 @@
+import {definitionDtoSchema, definitionValidationErrorSchema} from '@shipfox/api-definitions-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {validateDefinition} from '#core/validate-definition.js';
+
+const validateBodySchema = z.object({
+  yaml: z.string().min(1).max(1_000_000),
+});
+
+const validationResultSchema = z.union([
+  z.object({
+    valid: z.literal(true),
+    workflow_document: definitionDtoSchema.shape.workflow_document,
+    workflow_model: definitionDtoSchema.shape.workflow_model,
+  }),
+  z.object({
+    valid: z.literal(false),
+    errors: z.array(definitionValidationErrorSchema),
+  }),
+]);
+
+export const validateDefinitionRoute = defineRoute({
+  method: 'POST',
+  path: '/validate',
+  description: 'Validate a workflow definition without persisting',
+  schema: {
+    body: validateBodySchema,
+    response: {
+      200: validationResultSchema,
+    },
+  },
+  handler: (request) => {
+    const {yaml} = request.body;
+    const result = validateDefinition(yaml);
+
+    if (result.valid) {
+      return {
+        valid: true as const,
+        workflow_document: result.definition.document,
+        workflow_model: result.definition.model,
+      };
+    }
+
+    return result;
+  },
+});

package/src/presentation/subscribers/index.ts

@@ -0,0 +1,2 @@
+export {onProjectSourceBound} from './on-project-source-bound.js';
+export {onProjectSourceCommitObserved} from './on-project-source-commit-observed.js';