@shipfox/annotations 2.0.0

package/src/db/annotations.ts

@@ -0,0 +1,180 @@
+import {type AnnotationStyleDto, READ_ANNOTATIONS_MAX_LIMIT} from '@shipfox/annotations-dto';
+import {and, asc, eq, gt, inArray, or, type SQL, sql} from 'drizzle-orm';
+import type {Annotation} from '#core/entities/annotation.js';
+import {db} from './db.js';
+import {annotations, toAnnotation} from './schema/annotations.js';
+
+export const DEFAULT_ANNOTATIONS_READ_LIMIT = READ_ANNOTATIONS_MAX_LIMIT;
+
+export interface ListAnnotationsForRunAttemptParams {
+  workflowRunId: string;
+  workflowRunAttempt: number;
+  workspaceIds: readonly string[];
+  jobExecutionId?: string | undefined;
+  after?: {sequence: number; id: string} | undefined;
+  limit?: number | undefined;
+}
+
+export interface ListAnnotationsForRunAttemptResult {
+  annotations: Annotation[];
+  hasMore: boolean;
+  nextCursor: {sequence: number; id: string} | null;
+}
+
+export async function listAnnotationsForRunAttempt(
+  params: ListAnnotationsForRunAttemptParams,
+): Promise<ListAnnotationsForRunAttemptResult> {
+  if (params.workspaceIds.length === 0) return {annotations: [], hasMore: false, nextCursor: null};
+
+  const limit = params.limit ?? DEFAULT_ANNOTATIONS_READ_LIMIT;
+
+  const conditions: SQL[] = [
+    eq(annotations.workflowRunId, params.workflowRunId),
+    eq(annotations.workflowRunAttempt, params.workflowRunAttempt),
+    inArray(annotations.workspaceId, [...params.workspaceIds]),
+  ];
+  if (params.jobExecutionId) {
+    conditions.push(eq(annotations.jobExecutionId, params.jobExecutionId));
+  }
+  if (params.after) {
+    const cursorCondition = or(
+      gt(annotations.sequence, params.after.sequence),
+      and(eq(annotations.sequence, params.after.sequence), gt(annotations.id, params.after.id)),
+    );
+    if (cursorCondition) conditions.push(cursorCondition);
+  }
+
+  const rows = await db()
+    .select()
+    .from(annotations)
+    .where(and(...conditions))
+    .orderBy(asc(annotations.sequence), asc(annotations.id))
+    .limit(limit + 1);
+
+  const pageRows = rows.slice(0, limit);
+  const last = pageRows.at(-1);
+
+  return {
+    annotations: pageRows.map(toAnnotation),
+    hasMore: rows.length > limit,
+    nextCursor: rows.length > limit && last ? {sequence: last.sequence, id: last.id} : null,
+  };
+}
+
+export interface StoredAnnotation {
+  id: string;
+  context: string;
+  style: AnnotationStyleDto;
+  body: string;
+  bodyBytes: number;
+  sequence: number;
+}
+
+export interface CreateAnnotationParams {
+  workspaceId: string;
+  projectId: string;
+  workflowRunId: string;
+  workflowRunAttempt: number;
+  workflowRunAttemptId: string;
+  jobId: string;
+  jobExecutionId: string;
+  originStepId: string;
+  originStepAttempt: number;
+  context: string;
+  style: AnnotationStyleDto;
+  body: string;
+  bodyBytes: number;
+  sequence: number;
+}
+
+export interface UpdateAnnotationParams {
+  id: string;
+  originStepId: string;
+  originStepAttempt: number;
+  style: AnnotationStyleDto;
+  body: string;
+  bodyBytes: number;
+}
+
+export interface AnnotationWriteRepository {
+  loadCurrentAnnotations(jobExecutionId: string): Promise<Map<string, StoredAnnotation>>;
+  removeAnnotation(jobExecutionId: string, context: string): Promise<void>;
+  createAnnotation(params: CreateAnnotationParams): Promise<StoredAnnotation>;
+  updateAnnotation(params: UpdateAnnotationParams): Promise<StoredAnnotation>;
+}
+
+export function withAnnotationLock<T>(
+  jobExecutionId: string,
+  work: (repo: AnnotationWriteRepository) => Promise<T>,
+): Promise<T> {
+  return db().transaction(async (tx) => {
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${jobExecutionId}))`);
+
+    const repo: AnnotationWriteRepository = {
+      loadCurrentAnnotations: async (lockedJobExecutionId) => {
+        const rows = await tx
+          .select({
+            id: annotations.id,
+            context: annotations.context,
+            style: annotations.style,
+            body: annotations.body,
+            bodyBytes: annotations.bodyBytes,
+            sequence: annotations.sequence,
+          })
+          .from(annotations)
+          .where(eq(annotations.jobExecutionId, lockedJobExecutionId));
+
+        return new Map(rows.map((row) => [row.context, row]));
+      },
+      removeAnnotation: async (lockedJobExecutionId, context) => {
+        await tx
+          .delete(annotations)
+          .where(
+            and(
+              eq(annotations.jobExecutionId, lockedJobExecutionId),
+              eq(annotations.context, context),
+            ),
+          );
+      },
+      createAnnotation: async (params) => {
+        const [row] = await tx.insert(annotations).values(params).returning({
+          id: annotations.id,
+          context: annotations.context,
+          style: annotations.style,
+          body: annotations.body,
+          bodyBytes: annotations.bodyBytes,
+          sequence: annotations.sequence,
+        });
+
+        if (!row) throw new Error('createAnnotation: insert returned no row');
+        return row;
+      },
+      updateAnnotation: async (params) => {
+        const [row] = await tx
+          .update(annotations)
+          .set({
+            originStepId: params.originStepId,
+            originStepAttempt: params.originStepAttempt,
+            style: params.style,
+            body: params.body,
+            bodyBytes: params.bodyBytes,
+            updatedAt: new Date(),
+          })
+          .where(eq(annotations.id, params.id))
+          .returning({
+            id: annotations.id,
+            context: annotations.context,
+            style: annotations.style,
+            body: annotations.body,
+            bodyBytes: annotations.bodyBytes,
+            sequence: annotations.sequence,
+          });
+
+        if (!row) throw new Error('updateAnnotation: update returned no row');
+        return row;
+      },
+    };
+
+    return await work(repo);
+  });
+}

package/src/db/db.ts

@@ -0,0 +1,19 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {annotations} from './schema/annotations.js';
+
+export const schema = {annotations};
+
+export type Database = NodePgDatabase<typeof schema>;
+export type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0];
+
+let _db: Database | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

package/src/db/index.ts

@@ -0,0 +1,7 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');
+
+export type {ListAnnotationsForRunAttemptParams} from './annotations.js';
+export {DEFAULT_ANNOTATIONS_READ_LIMIT, listAnnotationsForRunAttempt} from './annotations.js';

package/src/db/schema/annotations.test.ts

@@ -0,0 +1,50 @@
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {annotationFactory} from '#test/index.js';
+import {annotations, toAnnotation} from './annotations.js';
+
+describe('annotations schema', () => {
+  it('maps a persisted annotation row to the domain entity', async () => {
+    const createdAt = new Date('2026-07-07T10:00:00.000Z');
+    const updatedAt = new Date('2026-07-07T10:01:00.000Z');
+    const annotation = await annotationFactory.create({
+      id: '11111111-1111-4111-8111-111111111111',
+      workspaceId: '22222222-2222-4222-8222-222222222222',
+      projectId: '33333333-3333-4333-8333-333333333333',
+      workflowRunId: '44444444-4444-4444-8444-444444444444',
+      workflowRunAttempt: 4,
+      workflowRunAttemptId: '55555555-5555-4555-8555-555555555555',
+      jobId: '66666666-6666-4666-8666-666666666666',
+      jobExecutionId: '77777777-7777-4777-8777-777777777777',
+      originStepId: '88888888-8888-4888-8888-888888888888',
+      originStepAttempt: 3,
+      context: 'deploy',
+      style: 'success',
+      body: 'Deployed **v42** to staging',
+      bodyBytes: Buffer.byteLength('Deployed **v42** to staging'),
+      sequence: 2,
+      createdAt,
+      updatedAt,
+    });
+
+    const [row] = await db().select().from(annotations).where(eq(annotations.id, annotation.id));
+
+    expect(row).toBeDefined();
+    expect(row ? toAnnotation(row) : undefined).toEqual(annotation);
+  });
+
+  it.each([
+    ' deploy ',
+    '\tdeploy\n',
+  ])('rejects untrimmed context values at the database boundary: %s', async (context) => {
+    const createAnnotation = annotationFactory.create({context});
+
+    await expect(createAnnotation).rejects.toThrow();
+  });
+
+  it('rejects non-positive workflow run attempts at the database boundary', async () => {
+    const createAnnotation = annotationFactory.create({workflowRunAttempt: 0});
+
+    await expect(createAnnotation).rejects.toThrow();
+  });
+});

package/src/db/schema/annotations.ts

@@ -0,0 +1,96 @@
+import {
+  ANNOTATION_CONTEXT_MAX_LENGTH,
+  ANNOTATION_CONTEXT_TRIM_CODE_POINTS,
+  ANNOTATION_STYLES,
+} from '@shipfox/annotations-dto';
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {
+  check,
+  index,
+  integer,
+  pgEnum,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import type {Annotation} from '#core/entities/annotation.js';
+import {pgTable} from './common.js';
+
+export const annotationStyleEnum = pgEnum('annotations_style', [...ANNOTATION_STYLES]);
+
+const annotationContextTrimCharactersSql = sql`concat(${sql.join(
+  ANNOTATION_CONTEXT_TRIM_CODE_POINTS.map((codePoint) => sql.raw(`chr(${codePoint})`)),
+  sql`, `,
+)})`;
+
+export const annotations = pgTable(
+  'annotations',
+  {
+    id: uuidv7PrimaryKey(),
+    workspaceId: uuid('workspace_id').notNull(),
+    projectId: uuid('project_id').notNull(),
+    workflowRunId: uuid('workflow_run_id').notNull(),
+    workflowRunAttempt: integer('workflow_run_attempt').notNull(),
+    workflowRunAttemptId: uuid('workflow_run_attempt_id').notNull(),
+    jobId: uuid('job_id').notNull(),
+    jobExecutionId: uuid('job_execution_id').notNull(),
+    originStepId: uuid('origin_step_id').notNull(),
+    originStepAttempt: integer('origin_step_attempt').notNull(),
+    context: text('context').notNull(),
+    style: annotationStyleEnum('style').notNull().default('default'),
+    body: text('body').notNull(),
+    bodyBytes: integer('body_bytes').notNull(),
+    sequence: integer('sequence').notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('annotations_job_execution_context_unique').on(table.jobExecutionId, table.context),
+    index('annotations_workflow_run_attempt_idx').on(table.workflowRunId, table.workflowRunAttempt),
+    index('annotations_workflow_run_attempt_id_idx').on(table.workflowRunAttemptId),
+    index('annotations_job_execution_id_idx').on(table.jobExecutionId),
+    check('annotations_workflow_run_attempt_positive_ck', sql`${table.workflowRunAttempt} > 0`),
+    check('annotations_origin_step_attempt_positive_ck', sql`${table.originStepAttempt} > 0`),
+    check(
+      'annotations_body_bytes_matches_body_ck',
+      sql`${table.bodyBytes} = octet_length(${table.body})`,
+    ),
+    check('annotations_sequence_positive_ck', sql`${table.sequence} > 0`),
+    check('annotations_context_not_empty_ck', sql`length(${table.context}) > 0`),
+    check(
+      'annotations_context_trimmed_ck',
+      sql`${table.context} = btrim(${table.context}, ${annotationContextTrimCharactersSql})`,
+    ),
+    check(
+      'annotations_context_max_length_ck',
+      sql`length(${table.context}) <= ${ANNOTATION_CONTEXT_MAX_LENGTH}`,
+    ),
+  ],
+);
+
+export type AnnotationDb = typeof annotations.$inferSelect;
+export type AnnotationCreateDb = typeof annotations.$inferInsert;
+
+export function toAnnotation(row: AnnotationDb): Annotation {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    projectId: row.projectId,
+    workflowRunId: row.workflowRunId,
+    workflowRunAttempt: row.workflowRunAttempt,
+    workflowRunAttemptId: row.workflowRunAttemptId,
+    jobId: row.jobId,
+    jobExecutionId: row.jobExecutionId,
+    originStepId: row.originStepId,
+    originStepAttempt: row.originStepAttempt,
+    context: row.context,
+    style: row.style,
+    body: row.body,
+    bodyBytes: row.bodyBytes,
+    sequence: row.sequence,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/db/schema/common.ts

@@ -0,0 +1,3 @@
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `annotations_${name}`);

package/src/index.ts

@@ -0,0 +1,17 @@
+import type {ShipfoxModule} from '@shipfox/node-module';
+import {db} from '#db/db.js';
+import {migrationsPath} from '#db/index.js';
+import {annotationsRoutes} from '#presentation/routes/index.js';
+
+export {
+  AnnotationBodyTooLargeError,
+  AnnotationCountLimitExceededError,
+  AnnotationTotalBytesLimitExceededError,
+} from '#core/errors.js';
+export {type WriteAnnotationsParams, writeAnnotations} from '#core/write-annotations.js';
+
+export const annotationsModule: ShipfoxModule = {
+  name: 'annotations',
+  database: {db, migrationsPath},
+  routes: annotationsRoutes,
+};

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

@@ -0,0 +1,42 @@
+import type {Annotation} from '#core/entities/annotation.js';
+import {toAnnotationDto} from './annotation.js';
+
+describe('toAnnotationDto', () => {
+  it('maps an annotation domain entity to the public DTO shape', () => {
+    const annotation: Annotation = {
+      id: '11111111-1111-4111-8111-111111111111',
+      workspaceId: '22222222-2222-4222-8222-222222222222',
+      projectId: '33333333-3333-4333-8333-333333333333',
+      workflowRunId: '44444444-4444-4444-8444-444444444444',
+      workflowRunAttempt: 2,
+      workflowRunAttemptId: '55555555-5555-4555-8555-555555555555',
+      jobId: '66666666-6666-4666-8666-666666666666',
+      jobExecutionId: '77777777-7777-4777-8777-777777777777',
+      originStepId: '88888888-8888-4888-8888-888888888888',
+      originStepAttempt: 3,
+      context: 'deploy',
+      style: 'success',
+      sequence: 4,
+      body: 'Deployed **v42**',
+      bodyBytes: 16,
+      createdAt: new Date('2026-07-07T10:00:00.000Z'),
+      updatedAt: new Date('2026-07-07T10:01:00.000Z'),
+    };
+
+    const result = toAnnotationDto(annotation);
+
+    expect(result).toEqual({
+      id: '11111111-1111-4111-8111-111111111111',
+      job_id: '66666666-6666-4666-8666-666666666666',
+      job_execution_id: '77777777-7777-4777-8777-777777777777',
+      origin_step_id: '88888888-8888-4888-8888-888888888888',
+      origin_step_attempt: 3,
+      context: 'deploy',
+      style: 'success',
+      sequence: 4,
+      body: 'Deployed **v42**',
+    });
+    expect(result).not.toHaveProperty('workspace_id');
+    expect(result).not.toHaveProperty('workflow_run_attempt_id');
+  });
+});

package/src/presentation/dto/annotation.ts

@@ -0,0 +1,16 @@
+import type {AnnotationDto} from '@shipfox/annotations-dto';
+import type {Annotation} from '#core/entities/annotation.js';
+
+export function toAnnotationDto(annotation: Annotation): AnnotationDto {
+  return {
+    id: annotation.id,
+    job_id: annotation.jobId,
+    job_execution_id: annotation.jobExecutionId,
+    origin_step_id: annotation.originStepId,
+    origin_step_attempt: annotation.originStepAttempt,
+    context: annotation.context,
+    style: annotation.style,
+    sequence: annotation.sequence,
+    body: annotation.body,
+  };
+}

package/src/presentation/dto/index.ts

@@ -0,0 +1 @@
+export {toAnnotationDto} from './annotation.js';

package/src/presentation/routes/index.ts

@@ -0,0 +1,17 @@
+import {AUTH_LEASED_JOB, AUTH_USER} from '@shipfox/api-auth-context';
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {readAnnotationsRoute} from './read-annotations.js';
+import {writeAnnotationsRoute} from './write-annotations.js';
+
+export const annotationsRoutes: RouteGroup[] = [
+  {
+    prefix: '/annotations',
+    auth: AUTH_USER,
+    routes: [readAnnotationsRoute],
+  },
+  {
+    prefix: '/runs/jobs/current',
+    auth: AUTH_LEASED_JOB,
+    routes: [writeAnnotationsRoute],
+  },
+];