@shipfox/api-projects 2.0.0

package/src/presentation/e2eRoutes/create-project.test.ts

@@ -0,0 +1,119 @@
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import {sql} from 'drizzle-orm';
+import {db} from '#db/index.js';
+import {projectsOutbox} from '#db/schema/outbox.js';
+import {projectsE2eRoutes} from './index.js';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+const E2E_SOURCE_RE = /^e2e:/u;
+
+describe('projects E2E routes', () => {
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  test('creates a project with generated synthetic source values', async () => {
+    const workspaceId = crypto.randomUUID();
+    const app = await createApp({routes: [projectsE2eRoutes], swagger: false});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      payload: {
+        workspace_id: workspaceId,
+        name: '  E2E Project  ',
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({
+      workspace_id: workspaceId,
+      name: 'E2E Project',
+    });
+    expect(res.json().source.connection_id).toMatch(UUID_RE);
+    expect(res.json().source.external_repository_id).toMatch(E2E_SOURCE_RE);
+  });
+
+  test('preserves explicit synthetic source values', async () => {
+    const workspaceId = crypto.randomUUID();
+    const sourceConnectionId = crypto.randomUUID();
+    const app = await createApp({routes: [projectsE2eRoutes], swagger: false});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      payload: {
+        workspace_id: workspaceId,
+        name: 'E2E Project',
+        source_connection_id: sourceConnectionId,
+        source_external_repository_id: 'e2e:explicit',
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().source).toEqual({
+      connection_id: sourceConnectionId,
+      external_repository_id: 'e2e:explicit',
+    });
+  });
+
+  test('returns conflict for duplicate explicit source values', async () => {
+    const workspaceId = crypto.randomUUID();
+    const sourceConnectionId = crypto.randomUUID();
+    const app = await createApp({routes: [projectsE2eRoutes], swagger: false});
+    const payload = {
+      workspace_id: workspaceId,
+      name: 'E2E Project',
+      source_connection_id: sourceConnectionId,
+      source_external_repository_id: 'e2e:duplicate',
+    };
+    await app.inject({method: 'POST', url: '/projects', payload});
+
+    const res = await app.inject({method: 'POST', url: '/projects', payload});
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json()).toMatchObject({
+      code: 'project-already-exists',
+      details: {
+        source_connection_id: sourceConnectionId,
+        source_external_repository_id: 'e2e:duplicate',
+      },
+    });
+  });
+
+  test('rejects invalid bodies', async () => {
+    const app = await createApp({routes: [projectsE2eRoutes], swagger: false});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      payload: {
+        workspace_id: 'not-a-uuid',
+        name: 'E2E Project',
+      },
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  test('does not write project outbox events', async () => {
+    const workspaceId = crypto.randomUUID();
+    const app = await createApp({routes: [projectsE2eRoutes], swagger: false});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      payload: {
+        workspace_id: workspaceId,
+        name: 'E2E Project',
+      },
+    });
+
+    const events = await db()
+      .select()
+      .from(projectsOutbox)
+      .where(sql`${projectsOutbox.payload}->>'projectId' = ${res.json().id}`);
+    expect(res.statusCode).toBe(201);
+    expect(events).toEqual([]);
+  });
+});

package/src/presentation/e2eRoutes/create-project.ts

@@ -0,0 +1,50 @@
+import {randomUUID} from 'node:crypto';
+import {
+  e2eCreateProjectBodySchema,
+  e2eCreateProjectResponseSchema,
+} from '@shipfox/api-projects-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {ProjectAlreadyExistsError} from '#core/index.js';
+import {createProject} from '#db/index.js';
+import {toProjectDto} from '#presentation/dto/index.js';
+
+function syntheticExternalRepositoryId(): string {
+  return `e2e:${randomUUID()}`;
+}
+
+export const createE2eProjectRoute = defineRoute({
+  method: 'POST',
+  path: '/',
+  description: 'Create a synthetic project for E2E tests.',
+  schema: {
+    body: e2eCreateProjectBodySchema,
+    response: {
+      201: e2eCreateProjectResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof ProjectAlreadyExistsError) {
+      throw new ClientError(error.message, 'project-already-exists', {
+        details: {
+          existing_project_id: error.existingProjectId,
+          source_connection_id: error.sourceConnectionId,
+          source_external_repository_id: error.sourceExternalRepositoryId,
+        },
+        status: 409,
+      });
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const project = await createProject({
+      workspaceId: request.body.workspace_id,
+      name: request.body.name,
+      sourceConnectionId: request.body.source_connection_id ?? randomUUID(),
+      sourceExternalRepositoryId:
+        request.body.source_external_repository_id ?? syntheticExternalRepositoryId(),
+    });
+
+    reply.code(201);
+    return toProjectDto(project);
+  },
+});

package/src/presentation/e2eRoutes/index.ts

@@ -0,0 +1,7 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {createE2eProjectRoute} from './create-project.js';
+
+export const projectsE2eRoutes: RouteGroup = {
+  prefix: '/projects',
+  routes: [createE2eProjectRoute],
+};

package/src/presentation/index.ts

@@ -0,0 +1,2 @@
+export {requireProjectAccess} from './auth/require-project-access.js';
+export {createProjectRoutes} from './routes/index.js';

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

@@ -0,0 +1,102 @@
+import {AUTH_USER, requireUserContext, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {
+  IntegrationCapabilityUnavailableError,
+  IntegrationConnectionInactiveError,
+  IntegrationConnectionNotFoundError,
+  IntegrationConnectionWorkspaceMismatchError,
+  IntegrationProviderError,
+  type IntegrationProviderErrorReason,
+  IntegrationProviderUnavailableError,
+  type IntegrationSourceControlService,
+} from '@shipfox/api-integration-core';
+import {createProjectBodySchema, projectResponseSchema} from '@shipfox/api-projects-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {createProjectFromSource, ProjectAlreadyExistsError} from '#core/index.js';
+import {toProjectDto} from '#presentation/dto/index.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+function isProviderError(error: unknown): error is IntegrationProviderError {
+  return (
+    error instanceof IntegrationProviderError ||
+    (error instanceof Error &&
+      'reason' in error &&
+      typeof error.reason === 'string' &&
+      (error.reason === 'repository-not-found' ||
+        error.reason === 'access-denied' ||
+        error.reason === 'rate-limited' ||
+        error.reason === 'timeout' ||
+        error.reason === 'provider-unavailable' ||
+        error.reason === 'malformed-provider-response'))
+  );
+}
+
+export function createProjectRoute(sourceControl: IntegrationSourceControlService) {
+  return defineRoute({
+    method: 'POST',
+    path: '/',
+    auth: AUTH_USER,
+    description: 'Create a project bound to a source repository.',
+    schema: {
+      body: createProjectBodySchema,
+      response: {
+        201: projectResponseSchema,
+      },
+    },
+    errorHandler: (error) => {
+      if (error instanceof IntegrationConnectionNotFoundError) {
+        throw new ClientError(error.message, 'source-connection-not-found', {status: 404});
+      }
+      if (error instanceof IntegrationConnectionWorkspaceMismatchError) {
+        throw new ClientError(error.message, 'forbidden', {status: 403});
+      }
+      if (error instanceof IntegrationConnectionInactiveError) {
+        throw new ClientError(error.message, 'source-connection-inactive', {status: 422});
+      }
+      if (error instanceof IntegrationProviderUnavailableError) {
+        throw new ClientError(error.message, 'integration-provider-unavailable', {status: 422});
+      }
+      if (error instanceof IntegrationCapabilityUnavailableError) {
+        throw new ClientError(error.message, 'integration-capability-unavailable', {status: 422});
+      }
+      if (error instanceof ProjectAlreadyExistsError) {
+        throw new ClientError(error.message, 'project-already-exists', {
+          details: {
+            existing_project_id: error.existingProjectId,
+            source_connection_id: error.sourceConnectionId,
+            source_external_repository_id: error.sourceExternalRepositoryId,
+          },
+          status: 409,
+        });
+      }
+      if (isProviderError(error)) {
+        throw new ClientError(error.message, error.reason, {
+          details: {retry_after_seconds: error.retryAfterSeconds},
+          status: providerStatus(error.reason),
+        });
+      }
+      throw error;
+    },
+    handler: async (request, reply) => {
+      const {workspace_id: workspaceId, name, source} = request.body;
+      const actor = requireUserContext(request);
+
+      requireWorkspaceAccess({request, workspaceId});
+      const project = await createProjectFromSource({
+        actorId: actor.userId,
+        workspaceId,
+        name,
+        sourceConnectionId: source.connection_id,
+        sourceExternalRepositoryId: source.external_repository_id,
+        sourceControl,
+      });
+
+      reply.status(201);
+      return toProjectDto(project);
+    },
+  });
+}

package/src/presentation/routes/cursor.ts

@@ -0,0 +1,5 @@
+export {
+  decodeTimestampIdCursor as decodeProjectCursor,
+  encodeTimestampIdCursor as encodeProjectCursor,
+  type TimestampIdCursor as ProjectCursor,
+} from '@shipfox/node-drizzle';

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

@@ -0,0 +1,24 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {projectResponseSchema} from '@shipfox/api-projects-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {requireProjectAccess} from '#presentation/auth/require-project-access.js';
+import {toProjectDto} from '#presentation/dto/index.js';
+
+export const getProjectRoute = defineRoute({
+  method: 'GET',
+  path: '/:projectId',
+  auth: AUTH_USER,
+  description: 'Get a project.',
+  schema: {
+    params: z.object({projectId: z.string().uuid()}),
+    response: {
+      200: projectResponseSchema,
+    },
+  },
+  handler: async (request) => {
+    const {projectId} = request.params;
+    const {project} = await requireProjectAccess({request, projectId});
+    return toProjectDto(project);
+  },
+});

package/src/presentation/routes/index.ts

@@ -0,0 +1,14 @@
+import type {IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {createProjectRoute} from './create-project.js';
+import {getProjectRoute} from './get-project.js';
+import {listProjectsRoute} from './list-projects.js';
+
+export function createProjectRoutes(sourceControl: IntegrationSourceControlService): RouteGroup[] {
+  return [
+    {
+      prefix: '/projects',
+      routes: [createProjectRoute(sourceControl), listProjectsRoute, getProjectRoute],
+    },
+  ];
+}

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

@@ -0,0 +1,34 @@
+import {AUTH_USER, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {listProjectsQuerySchema, listProjectsResponseSchema} from '@shipfox/api-projects-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {listProjects} from '#db/index.js';
+import {toProjectDto} from '#presentation/dto/index.js';
+import {decodeProjectCursor, encodeProjectCursor} from './cursor.js';
+
+export const listProjectsRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  auth: AUTH_USER,
+  description: 'List projects in a workspace.',
+  schema: {
+    querystring: listProjectsQuerySchema,
+    response: {
+      200: listProjectsResponseSchema,
+    },
+  },
+  handler: async (request) => {
+    const {workspace_id: workspaceId, limit, cursor, search} = request.query;
+    const decodedCursor = decodeProjectCursor(cursor);
+    if (cursor && !decodedCursor) {
+      throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+    }
+
+    requireWorkspaceAccess({request, workspaceId});
+    const result = await listProjects({workspaceId, limit, cursor: decodedCursor, search});
+
+    return {
+      projects: result.projects.map(toProjectDto),
+      next_cursor: result.nextCursor ? encodeProjectCursor(result.nextCursor) : null,
+    };
+  },
+});

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

@@ -0,0 +1,266 @@
+import {
+  AUTH_USER,
+  buildUserContext,
+  setUserContext,
+  type UserContextMembership,
+} from '@shipfox/api-auth-context';
+import type {IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import {IntegrationConnectionNotFoundError} from '@shipfox/api-integration-core';
+import type {AuthMethod} from '@shipfox/node-fastify';
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import {createProjectRoutes} from './index.js';
+
+let authenticatedMemberships: UserContextMembership[] = [];
+
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    setUserContext(
+      request,
+      buildUserContext({
+        userId: 'user-1',
+        email: 'user@example.com',
+        name: 'User One',
+        memberships: authenticatedMemberships,
+      }),
+    );
+    return Promise.resolve();
+  },
+};
+
+describe('project routes', () => {
+  let app: FastifyInstance;
+  let workspaceId: string;
+  let sourceConnectionId: string;
+  let sourceControl: IntegrationSourceControlService;
+
+  beforeEach(async () => {
+    await closeApp();
+    workspaceId = crypto.randomUUID();
+    sourceConnectionId = crypto.randomUUID();
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+    sourceControl = {
+      getConnection: vi.fn(),
+      listRepositories: vi.fn(),
+      resolveRepository: vi.fn(async () => {
+        await Promise.resolve();
+        return {
+          connection: {
+            id: sourceConnectionId,
+            workspaceId,
+            provider: 'gitea' as const,
+            externalAccountId: 'gitea-owner',
+            slug: 'gitea_owner',
+            displayName: 'Gitea',
+            lifecycleStatus: 'active' as const,
+            capabilities: ['source_control' 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(),
+      fetchFile: vi.fn(),
+      createCheckoutSpec: vi.fn(),
+    };
+    app = await createApp({
+      auth: [fakeUserAuth],
+      routes: createProjectRoutes(sourceControl),
+      swagger: false,
+    });
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  test('creates a project for a source repository', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      headers: {authorization: 'Bearer user'},
+      payload: {
+        workspace_id: workspaceId,
+        name: '  Platform  ',
+        source: {
+          connection_id: sourceConnectionId,
+          external_repository_id: 'gitea:gitea-owner/platform',
+        },
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().name).toBe('Platform');
+    expect(res.json().source).toEqual({
+      connection_id: sourceConnectionId,
+      external_repository_id: 'gitea:gitea-owner/platform',
+    });
+  });
+
+  test.each([
+    ['blank after trimming', '   '],
+    ['with control characters', 'Plat\nform'],
+    ['with format characters', 'Plat\u202eform'],
+  ])('rejects a project name %s before resolving the repository', async (_case, name) => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      headers: {authorization: 'Bearer user'},
+      payload: {
+        workspace_id: workspaceId,
+        name,
+        source: {
+          connection_id: sourceConnectionId,
+          external_repository_id: 'gitea:gitea-owner/platform',
+        },
+      },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(sourceControl.resolveRepository).not.toHaveBeenCalled();
+  });
+
+  test('lists projects for a workspace with source references', async () => {
+    const createRes = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      headers: {authorization: 'Bearer user'},
+      payload: {
+        workspace_id: workspaceId,
+        name: 'Platform',
+        source: {
+          connection_id: sourceConnectionId,
+          external_repository_id: 'gitea:gitea-owner/platform',
+        },
+      },
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/projects?workspace_id=${workspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(createRes.statusCode).toBe(201);
+    expect(res.statusCode).toBe(200);
+    expect(res.json().projects.map((project: {id: string}) => project.id)).toContain(
+      createRes.json().id,
+    );
+    expect(res.json().projects[0].source.connection_id).toBe(sourceConnectionId);
+  });
+
+  test('filters projects by `search` (case-insensitive substring on name)', async () => {
+    const names = ['Platform', 'Runner', 'Notifier'];
+    for (const [index, name] of names.entries()) {
+      vi.mocked(sourceControl.resolveRepository).mockResolvedValueOnce({
+        connection: {
+          id: sourceConnectionId,
+          workspaceId,
+          provider: 'gitea',
+          externalAccountId: 'gitea-owner',
+          slug: 'gitea_owner',
+          displayName: 'Gitea',
+          lifecycleStatus: 'active',
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+        repository: {
+          externalRepositoryId: `gitea:gitea-owner/${name.toLowerCase()}-${index}`,
+          owner: 'gitea-owner',
+          name: name.toLowerCase(),
+          fullName: `gitea-owner/${name.toLowerCase()}`,
+          defaultBranch: 'main',
+          visibility: 'private',
+          cloneUrl: `https://gitea.local/gitea-owner/${name.toLowerCase()}.git`,
+          htmlUrl: `https://gitea.local/gitea-owner/${name.toLowerCase()}`,
+        },
+      });
+      await app.inject({
+        method: 'POST',
+        url: '/projects',
+        headers: {authorization: 'Bearer user'},
+        payload: {
+          workspace_id: workspaceId,
+          name,
+          source: {
+            connection_id: sourceConnectionId,
+            external_repository_id: `gitea:gitea-owner/${name.toLowerCase()}-${index}`,
+          },
+        },
+      });
+    }
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/projects?workspace_id=${workspaceId}&search=runn`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    const returned = res.json().projects.map((project: {name: string}) => project.name);
+    expect(returned).toEqual(['Runner']);
+  });
+
+  test('returns 409 when the source repository already has a project', async () => {
+    const payload = {
+      workspace_id: workspaceId,
+      name: 'Platform',
+      source: {
+        connection_id: sourceConnectionId,
+        external_repository_id: 'gitea:gitea-owner/platform',
+      },
+    };
+    await app.inject({
+      method: 'POST',
+      url: '/projects',
+      headers: {authorization: 'Bearer user'},
+      payload,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      headers: {authorization: 'Bearer user'},
+      payload,
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('project-already-exists');
+    expect(res.json().details.source_connection_id).toBe(sourceConnectionId);
+  });
+
+  test('maps missing source connections to a stable error', async () => {
+    vi.mocked(sourceControl.resolveRepository).mockRejectedValueOnce(
+      new IntegrationConnectionNotFoundError(sourceConnectionId),
+    );
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/projects',
+      headers: {authorization: 'Bearer user'},
+      payload: {
+        workspace_id: workspaceId,
+        name: 'Platform',
+        source: {
+          connection_id: sourceConnectionId,
+          external_repository_id: 'gitea:gitea-owner/platform',
+        },
+      },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('source-connection-not-found');
+  });
+});

package/src/presentation/subscribers/index.ts

@@ -0,0 +1 @@
+export {onSourceCommitPushed} from './on-source-commit-pushed.js';