@critical-path/core 0.27.0 → 0.29.0

package/src/plugins/plugins.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  CriticalPathEngine,
+  CustomFieldValidationError,
+  ValidationError,
+  WorkflowValidationError,
+  type CriticalPathPlugin
+} from '../index.js';
+
+const strictWorkflow = {
+  name: 'Strict',
+  defaultStatusKey: 'todo',
+  statuses: [
+    { key: 'todo', label: 'To Do', category: 'not_started' as const },
+    { key: 'doing', label: 'Doing', category: 'in_progress' as const },
+    { key: 'done', label: 'Done', category: 'completed' as const }
+  ],
+  transitions: [
+    { fromStatusKey: 'todo', toStatusKey: 'doing' },
+    { fromStatusKey: 'doing', toStatusKey: 'done' }
+  ]
+};
+
+describe('plugin system', () => {
+  it('runs init once with the engine before ready resolves', async () => {
+    const init = vi.fn(async (engine: CriticalPathEngine) => {
+      await engine.createProject({ name: 'Seeded by plugin' });
+    });
+    const engine = new CriticalPathEngine({ plugins: [{ id: 'seed', name: 'Seed', version: '1', init }] });
+    await engine.ready;
+
+    expect(init).toHaveBeenCalledTimes(1);
+    expect(init).toHaveBeenCalledWith(engine);
+    expect(await engine.getProjects()).toHaveLength(1);
+  });
+
+  it('surfaces init failures through ready without unhandled rejections', async () => {
+    const engine = new CriticalPathEngine({
+      plugins: [{ id: 'bad', name: 'Bad', version: '1', init: () => Promise.reject(new Error('boom')) }]
+    });
+    await expect(engine.ready).rejects.toThrow('boom');
+  });
+
+  it('validates values of plugin-registered custom field types and rejects unknown types', async () => {
+    const urlField: CriticalPathPlugin = {
+      id: 'url-field',
+      name: 'URL field',
+      version: '1',
+      customFieldTypes: [
+        { type: 'url', validate: (value) => (typeof value === 'string' && /^https?:\/\//.test(value) ? null : 'must be an http(s) URL') }
+      ]
+    };
+    const engine = new CriticalPathEngine({ plugins: [urlField] });
+    const project = await engine.createProject({
+      name: 'Links',
+      customFieldDefinitions: [{ id: 'f1', key: 'spec', label: 'Spec', type: 'url' }]
+    });
+
+    await engine.createTask({ projectId: project.id, title: 'ok', customFields: { spec: 'https://example.com' } });
+    await expect(engine.createTask({ projectId: project.id, title: 'bad', customFields: { spec: 'ftp://x' } })).rejects.toThrow(
+      /must be an http\(s\) URL/
+    );
+    await expect(
+      engine.createProject({ name: 'Unknown', customFieldDefinitions: [{ id: 'f', key: 'x', label: 'X', type: 'nope' }] })
+    ).rejects.toThrow(CustomFieldValidationError);
+  });
+
+  it('refuses custom field types that clash with built-in or already registered types', () => {
+    const clash = (type: string): CriticalPathPlugin => ({
+      id: `p-${type}-${Math.random()}`,
+      name: 'Clash',
+      version: '1',
+      customFieldTypes: [{ type, validate: () => null }]
+    });
+    expect(() => new CriticalPathEngine({ plugins: [clash('number')] })).toThrow(/already exists/);
+    expect(() => new CriticalPathEngine({ plugins: [clash('money'), clash('money')] })).toThrow(/already exists/);
+  });
+
+  it('validates the output of before-hooks, so plugins cannot bypass workflow rules', async () => {
+    const skipAhead: CriticalPathPlugin = {
+      id: 'skip',
+      name: 'Skip ahead',
+      version: '1',
+      hooks: { beforeTaskUpdate: (_id, updates) => ({ ...updates, status: 'done' }) }
+    };
+    const engine = new CriticalPathEngine({ plugins: [skipAhead] });
+    const workflow = await engine.createWorkflow(strictWorkflow);
+    const project = await engine.createProject({ name: 'Strict', workflowId: workflow.id });
+    const task = await engine.createTask({ projectId: project.id, title: 'T' });
+
+    await expect(engine.updateTask(task.id, { title: 'renamed' })).rejects.toThrow(WorkflowValidationError);
+    expect((await engine.getTask(task.id))?.status).toBe('todo');
+  });
+
+  it('prevents before-hooks from moving tasks between projects', async () => {
+    let otherProjectId = '';
+    const mover: CriticalPathPlugin = {
+      id: 'mover',
+      name: 'Mover',
+      version: '1',
+      hooks: {
+        beforeTaskCreate: (task) => (task.title === 'move me' ? { ...task, projectId: otherProjectId } : task),
+        beforeTaskUpdate: (_id, updates) => ({ ...updates, projectId: otherProjectId })
+      }
+    };
+    const engine = new CriticalPathEngine({ plugins: [mover] });
+    const home = await engine.createProject({ name: 'Home' });
+    otherProjectId = (await engine.createProject({ name: 'Other' })).id;
+
+    await expect(engine.createTask({ projectId: home.id, title: 'move me' })).rejects.toThrow(ValidationError);
+    const task = await engine.createTask({ projectId: home.id, title: 'stay' });
+    await engine.updateTask(task.id, { title: 'still here' });
+    expect((await engine.getTask(task.id))?.projectId).toBe(home.id);
+  });
+
+  it('enforces required custom fields even when none are supplied', async () => {
+    const engine = new CriticalPathEngine();
+    const project = await engine.createProject({
+      name: 'Required',
+      customFieldDefinitions: [{ id: 'f', key: 'client', label: 'Client', type: 'text', required: true }]
+    });
+    await expect(engine.createTask({ projectId: project.id, title: 'missing' })).rejects.toThrow(/required/);
+  });
+
+  it('logs after-hook failures without failing the write or skipping events', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const engine = new CriticalPathEngine({
+      plugins: [{ id: 'flaky', name: 'Flaky', version: '1', hooks: { afterTaskCreate: () => { throw new Error('downstream'); } } }]
+    });
+    const published: string[] = [];
+    engine.events.subscribe('task.created', (e) => void published.push(e.name));
+
+    const project = await engine.createProject({ name: 'After' });
+    const task = await engine.createTask({ projectId: project.id, title: 'stored' });
+    expect(await engine.getTask(task.id)).not.toBeNull();
+    expect(published).toEqual(['task.created']);
+    expect(consoleError).toHaveBeenCalledWith(expect.stringContaining('"flaky" afterTaskCreate'), expect.any(Error));
+    consoleError.mockRestore();
+  });
+
+  it('passes the deleted task to delete hooks', async () => {
+    const seen: string[] = [];
+    const engine = new CriticalPathEngine({
+      plugins: [
+        {
+          id: 'audit',
+          name: 'Audit',
+          version: '1',
+          hooks: {
+            beforeTaskDelete: (_id, task) => void seen.push(`before:${task.title}`),
+            afterTaskDelete: (_id, task) => void seen.push(`after:${task.title}`)
+          }
+        }
+      ]
+    });
+    const project = await engine.createProject({ name: 'Del' });
+    const task = await engine.createTask({ projectId: project.id, title: 'gone' });
+    await engine.deleteTask(task.id);
+    expect(seen).toEqual(['before:gone', 'after:gone']);
+  });
+});

package/src/schemas/index.ts

@@ -65,7 +65,8 @@ export const CustomFieldDefinitionSchema = strictObject({
   id: z.string(),
   key: nonEmpty,
   label: z.string(),
-  type: z.enum(['text', 'number', 'date', 'boolean', 'single_select', 'multi_select', 'user']),
+  /** Built-in type or one registered by a plugin (checked by the engine). */
+  type: nonEmpty,
   options: z.array(z.string()).optional(),
   required: z.boolean().optional(),
   defaultValue: z.unknown().optional()

package/src/store/firebase.ts

@@ -104,6 +104,10 @@ export interface FirebaseStoreConfig {
   db: FirestoreDBInterface;
 }
 
+/**
+ * Removes `undefined` values, which Firestore rejects. Update methods write the complete merged
+ * record without `{ merge: true }`, so a field cleared with `undefined` is actually removed.
+ */
 export function sanitizeFirestoreData<T>(obj: T): T {
   if (obj === null || typeof obj !== 'object') {
     return obj;
@@ -162,7 +166,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('projects').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('projects').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -202,7 +206,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('workflows').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('workflows').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -238,7 +242,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!existing) return null;
 
     const updated: Team = { ...existing, ...updates, updatedAt: new Date().toISOString() };
-    await this.db.collection('teams').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('teams').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -274,7 +278,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!existing) return null;
 
     const updated: TaskContainer = { ...existing, ...updates, updatedAt: new Date().toISOString() };
-    await this.db.collection('containers').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('containers').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -318,7 +322,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!existing) return null;
 
     const updated: Deliverable = { ...existing, ...updates, updatedAt: new Date().toISOString() };
-    await this.db.collection('deliverables').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('deliverables').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -363,7 +367,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('tasks').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('tasks').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -399,7 +403,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!snap.exists) return null;
 
     const updated: Iteration = { ...snap.data(), id, ...updates };
-    await this.db.collection('iterations').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('iterations').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -439,7 +443,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('comments').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('comments').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -567,6 +571,27 @@ export class FirebaseStore implements StorageAdapter {
     return newDep;
   }
 
+  async getDependency(id: string): Promise<TaskDependency | null> {
+    const doc = await this.db.collection('dependencies').doc(id).get();
+    return doc.exists ? ({ ...doc.data(), id: doc.id } as TaskDependency) : null;
+  }
+
+  async removeDependency(id: string): Promise<boolean> {
+    return this.deleteDoc('dependencies', id);
+  }
+
+  async deleteTimeEntry(id: string): Promise<boolean> {
+    return this.deleteDoc('time_entries', id);
+  }
+
+  private async deleteDoc(collection: string, id: string): Promise<boolean> {
+    const ref = this.db.collection(collection).doc(id);
+    const doc = await ref.get();
+    if (!doc.exists) return false;
+    await ref.delete();
+    return true;
+  }
+
   // --- Webhooks ---
   async getWebhooks(): Promise<Webhook[]> {
     const snap = await this.db.collection('webhooks').get();

package/src/store/index.ts

@@ -92,11 +92,15 @@ export interface ActivityRepository {
 export interface TimeEntryRepository {
   getTimeEntries(taskId: string): Promise<TimeEntry[]>;
   logTime(entry: Omit<TimeEntry, 'id' | 'loggedAt'> & { loggedAt?: string }): Promise<TimeEntry>;
+  deleteTimeEntry(id: string): Promise<boolean>;
 }
 
 export interface DependencyRepository {
+  /** Dependencies where `taskId` is either the dependent or the upstream task. */
   getDependencies(taskId: string): Promise<TaskDependency[]>;
+  getDependency(id: string): Promise<TaskDependency | null>;
   addDependency(dep: Omit<TaskDependency, 'id'>): Promise<TaskDependency>;
+  removeDependency(id: string): Promise<boolean>;
 }
 
 export interface WebhookRepository {
@@ -522,6 +526,10 @@ export class InMemoryStore implements StorageAdapter {
     return newEntry;
   }
 
+  async deleteTimeEntry(id: string): Promise<boolean> {
+    return this.timeEntries.delete(id);
+  }
+
   // Dependencies
   async getDependencies(taskId: string): Promise<TaskDependency[]> {
     return Array.from(this.dependencies.values()).filter(
@@ -529,6 +537,10 @@ export class InMemoryStore implements StorageAdapter {
     );
   }
 
+  async getDependency(id: string): Promise<TaskDependency | null> {
+    return this.dependencies.get(id) ?? null;
+  }
+
   async addDependency(dep: Omit<TaskDependency, 'id'>): Promise<TaskDependency> {
     const id = `dep_${Math.random().toString(36).substring(2, 9)}`;
     const newDep: TaskDependency = { ...dep, id };
@@ -536,6 +548,10 @@ export class InMemoryStore implements StorageAdapter {
     return newDep;
   }
 
+  async removeDependency(id: string): Promise<boolean> {
+    return this.dependencies.delete(id);
+  }
+
   // Webhooks
   async getWebhooks(): Promise<Webhook[]> {
     return Array.from(this.webhooks.values());

package/src/store/sqlite.ts

@@ -18,6 +18,14 @@ import type {
 } from '../types/index.js';
 import { generateProjectKey } from '../utils/key.js';
 
+/**
+ * SQLite returns NULL columns as `null`, while domain objects leave unset optional fields out.
+ * Dropping nulls keeps SQLiteStore results identical to the other adapters.
+ */
+function dropNulls<T extends object>(row: T): T {
+  return Object.fromEntries(Object.entries(row).filter(([, value]) => value !== null)) as T;
+}
+
 export interface SQLiteStoreConfig {
   /**
    * Database file path (e.g., 'critical-path.db' or ':memory:').
@@ -516,13 +524,13 @@ export class SQLiteStore implements StorageAdapter {
   async getContainers(projectId: string): Promise<TaskContainer[]> {
     const stmt = this.db.prepare('SELECT * FROM containers WHERE projectId = ?');
     const rows = stmt.all(projectId) as any[];
-    return rows;
+    return rows.map(dropNulls);
   }
 
   async getContainer(id: string): Promise<TaskContainer | null> {
     const stmt = this.db.prepare('SELECT * FROM containers WHERE id = ?');
     const row = stmt.get(id) as any;
-    return row || null;
+    return row ? dropNulls(row) : null;
   }
 
   async createContainer(container: Omit<TaskContainer, 'id' | 'createdAt' | 'updatedAt'>): Promise<TaskContainer> {
@@ -821,13 +829,13 @@ export class SQLiteStore implements StorageAdapter {
   async getIterations(projectId: string): Promise<Iteration[]> {
     const stmt = this.db.prepare('SELECT * FROM iterations WHERE projectId = ?');
     const rows = stmt.all(projectId) as any[];
-    return rows;
+    return rows.map(dropNulls);
   }
 
   async getIteration(id: string): Promise<Iteration | null> {
     const stmt = this.db.prepare('SELECT * FROM iterations WHERE id = ?');
     const row = stmt.get(id) as any;
-    return row || null;
+    return row ? dropNulls(row) : null;
   }
 
   async createIteration(iteration: Omit<Iteration, 'id' | 'createdAt'>): Promise<Iteration> {
@@ -883,7 +891,7 @@ export class SQLiteStore implements StorageAdapter {
 
   // --- Comments ---
   private mapComment(row: any): Comment {
-    return {
+    return dropNulls({
       id: row.id,
       taskId: row.taskId,
       authorId: row.authorId,
@@ -895,7 +903,7 @@ export class SQLiteStore implements StorageAdapter {
       metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
       createdAt: row.createdAt,
       updatedAt: row.updatedAt
-    };
+    });
   }
 
   async getComments(taskId: string): Promise<Comment[]> {
@@ -1028,22 +1036,24 @@ export class SQLiteStore implements StorageAdapter {
 
     const stmt = this.db.prepare(sql);
     const rows = stmt.all(...params) as any[];
-    return rows.map((r) => ({
-      ...r,
-      sizeBytes: Number(r.sizeBytes),
-      metadata: r.metadata ? JSON.parse(r.metadata) : undefined
-    }));
+    return rows.map((r) =>
+      dropNulls({
+        ...r,
+        sizeBytes: Number(r.sizeBytes),
+        metadata: r.metadata ? JSON.parse(r.metadata) : undefined
+      })
+    );
   }
 
   async getAttachment(id: string): Promise<Attachment | null> {
     const stmt = this.db.prepare('SELECT * FROM attachments WHERE id = ?');
     const row = stmt.get(id) as any;
     if (!row) return null;
-    return {
+    return dropNulls({
       ...row,
       sizeBytes: Number(row.sizeBytes),
       metadata: row.metadata ? JSON.parse(row.metadata) : undefined
-    };
+    });
   }
 
   async createAttachment(attachment: Omit<Attachment, 'id' | 'createdAt' | 'updatedAt'>): Promise<Attachment> {
@@ -1106,10 +1116,12 @@ export class SQLiteStore implements StorageAdapter {
 
     const stmt = this.db.prepare(sql);
     const rows = stmt.all(...params) as any[];
-    return rows.map((r) => ({
-      ...r,
-      details: r.details ? JSON.parse(r.details) : undefined
-    }));
+    return rows.map((r) =>
+      dropNulls({
+        ...r,
+        details: r.details ? JSON.parse(r.details) : undefined
+      })
+    );
   }
 
   async logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity> {
@@ -1137,7 +1149,7 @@ export class SQLiteStore implements StorageAdapter {
   async getTimeEntries(taskId: string): Promise<TimeEntry[]> {
     const stmt = this.db.prepare('SELECT * FROM time_entries WHERE taskId = ?');
     const rows = stmt.all(taskId) as any[];
-    return rows.map((r) => ({ ...r, isBillable: r.isBillable !== null ? Boolean(r.isBillable) : undefined }));
+    return rows.map((r) => dropNulls({ ...r, isBillable: r.isBillable !== null ? Boolean(r.isBillable) : undefined }));
   }
 
   async logTime(entry: Omit<TimeEntry, 'id' | 'loggedAt'> & { loggedAt?: string }): Promise<TimeEntry> {
@@ -1164,7 +1176,7 @@ export class SQLiteStore implements StorageAdapter {
   // --- Dependencies ---
   async getDependencies(taskId: string): Promise<TaskDependency[]> {
     const stmt = this.db.prepare('SELECT * FROM dependencies WHERE taskId = ? OR dependsOnTaskId = ?');
-    return stmt.all(taskId, taskId) as any[];
+    return (stmt.all(taskId, taskId) as any[]).map(dropNulls);
   }
 
   async addDependency(dep: Omit<TaskDependency, 'id'>): Promise<TaskDependency> {
@@ -1179,6 +1191,19 @@ export class SQLiteStore implements StorageAdapter {
     return newDep;
   }
 
+  async getDependency(id: string): Promise<TaskDependency | null> {
+    const row = this.db.prepare('SELECT * FROM dependencies WHERE id = ?').get(id) as any;
+    return row ? { id: row.id, taskId: row.taskId, dependsOnTaskId: row.dependsOnTaskId, type: row.type } : null;
+  }
+
+  async removeDependency(id: string): Promise<boolean> {
+    return Number(this.db.prepare('DELETE FROM dependencies WHERE id = ?').run(id).changes) > 0;
+  }
+
+  async deleteTimeEntry(id: string): Promise<boolean> {
+    return Number(this.db.prepare('DELETE FROM time_entries WHERE id = ?').run(id).changes) > 0;
+  }
+
   // --- Webhooks ---
   async getWebhooks(): Promise<Webhook[]> {
     const stmt = this.db.prepare('SELECT * FROM webhooks');
@@ -1215,7 +1240,7 @@ export class SQLiteStore implements StorageAdapter {
   }
 
   private mapWebhook(row: any): Webhook {
-    return {
+    return dropNulls({
       id: row.id,
       name: row.name ?? '',
       url: row.url,
@@ -1224,7 +1249,7 @@ export class SQLiteStore implements StorageAdapter {
       active: Boolean(row.active),
       tenantId: row.tenantId ?? undefined,
       createdAt: row.createdAt
-    };
+    });
   }
 
   async addWebhook(webhook: Omit<Webhook, 'id' | 'createdAt'>): Promise<Webhook> {
@@ -1251,7 +1276,7 @@ export class SQLiteStore implements StorageAdapter {
 
   // Helper mappers
   private mapProject(row: any): Project {
-    return {
+    return dropNulls({
       ...row,
       tenantId: row.tenantId ?? undefined,
       workflowId: row.workflowId || undefined,
@@ -1261,30 +1286,30 @@ export class SQLiteStore implements StorageAdapter {
       statusDefinitions: row.statusDefinitions ? JSON.parse(row.statusDefinitions) : [],
       priorityDefinitions: row.priorityDefinitions ? JSON.parse(row.priorityDefinitions) : [],
       customFieldDefinitions: row.customFieldDefinitions ? JSON.parse(row.customFieldDefinitions) : []
-    };
+    });
   }
 
   private mapWorkflow(row: any): Workflow {
-    return {
+    return dropNulls({
       ...row,
       tenantId: row.tenantId ?? undefined,
       statuses: row.statuses ? JSON.parse(row.statuses) : [],
       transitions: row.transitions ? JSON.parse(row.transitions) : [],
       taskTypes: row.taskTypes ? JSON.parse(row.taskTypes) : undefined,
       isDefault: row.isDefault !== null && row.isDefault !== undefined ? Boolean(row.isDefault) : undefined
-    };
+    });
   }
 
   private mapTeam(row: any): Team {
-    return {
+    return dropNulls({
       ...row,
       tenantId: row.tenantId ?? undefined,
       memberIds: row.memberIds ? JSON.parse(row.memberIds) : []
-    };
+    });
   }
 
   private mapTask(row: any): Task {
-    return {
+    return dropNulls({
       ...row,
       actualDurationSeconds: row.actualDurationSeconds ?? undefined,
       inProgressSince: row.inProgressSince || undefined,
@@ -1299,15 +1324,15 @@ export class SQLiteStore implements StorageAdapter {
       tags: row.tags ? JSON.parse(row.tags) : [],
       assignees: row.assignees ? JSON.parse(row.assignees) : undefined,
       customFields: row.customFields ? JSON.parse(row.customFields) : {}
-    };
+    });
   }
 
   private mapDeliverable(row: any): Deliverable {
-    return {
+    return dropNulls({
       ...row,
       specs: row.specs ? JSON.parse(row.specs) : undefined,
       outputUrls: row.outputUrls ? JSON.parse(row.outputUrls) : [],
       customFields: row.customFields ? JSON.parse(row.customFields) : {}
-    };
+    });
   }
 }

package/src/types/index.ts

@@ -88,7 +88,8 @@ export interface CustomFieldDefinition {
   id: string;
   key: string;
   label: string;
-  type: 'text' | 'number' | 'date' | 'boolean' | 'single_select' | 'multi_select' | 'user';
+  /** A built-in type, or a type registered by a plugin's `customFieldTypes`. */
+  type: 'text' | 'number' | 'date' | 'boolean' | 'single_select' | 'multi_select' | 'user' | (string & {});
   options?: string[];
   required?: boolean;
   defaultValue?: unknown;
@@ -448,23 +449,74 @@ export type PublicWebhook = Omit<Webhook, 'secret'> & { hasSecret: boolean };
  */
 export type WebhookEvent = import('../domain/events.js').CriticalPathDomainEvent['name'] | '*';
 
+/**
+ * Lifecycle hooks, run in plugin registration order.
+ *
+ * - `before*` hooks may transform the input or throw to abort the operation. Their output is
+ *   validated (workflow transitions, custom fields) exactly like caller input, and they cannot
+ *   move a task to another project.
+ * - `after*` hooks run once the change is stored. Errors are logged and do not fail the call.
+ */
 export interface PluginHooks {
   beforeTaskCreate?: (task: Partial<Task>) => Promise<Partial<Task>> | Partial<Task>;
   afterTaskCreate?: (task: Task) => Promise<void> | void;
   beforeTaskUpdate?: (id: string, updates: Partial<Task>) => Promise<Partial<Task>> | Partial<Task>;
   afterTaskUpdate?: (task: Task, previousState: Task) => Promise<void> | void;
-  beforeTaskDelete?: (id: string) => Promise<void> | void;
-  afterTaskDelete?: (id: string) => Promise<void> | void;
+  beforeTaskDelete?: (id: string, task: Task) => Promise<void> | void;
+  afterTaskDelete?: (id: string, task: Task) => Promise<void> | void;
+}
+
+/** A custom field type contributed by a plugin, e.g. `url` or `currency`. */
+export interface CustomFieldType {
+  /** The `type` value used in `CustomFieldDefinition`s. Must not clash with a built-in type. */
+  type: string;
+  label?: string;
+  /** Returns an error message for an invalid value, or nothing when valid. Not called for empty values. */
+  validate: (value: unknown, definition: CustomFieldDefinition) => string | null | undefined | void;
+}
+
+/** Context passed to plugin routes and middleware. */
+export interface PluginRequestContext {
+  /** The engine as the calling actor (authorization and tenancy apply). */
+  engine: import('../engine/index.js').CriticalPathEngine;
+  /** The caller resolved by the router's `getContext`, if any. */
+  context?: Record<string, unknown> & { userId?: string };
+  url: URL;
+  /** Path parameters from the route pattern, e.g. `{ projectId: 'p1' }` for `/reports/:projectId`. */
+  params: Record<string, string>;
 }
 
+export interface PluginRoute {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Path below the router's base, with `:name` parameters, e.g. `/reports/:projectId`. */
+  path: string;
+  handler: (request: Request, ctx: PluginRequestContext) => Response | Promise<Response>;
+}
+
+/**
+ * Wraps every routed request (after authentication). Call `next()` to continue, or return a
+ * `Response` to short-circuit (e.g. rate limiting).
+ */
+export type PluginMiddleware = (
+  request: Request,
+  ctx: Omit<PluginRequestContext, 'params'>,
+  next: () => Promise<Response>
+) => Response | Promise<Response>;
+
 export interface CriticalPathPlugin {
   id: string;
   name: string;
   version: string;
   description?: string;
   hooks?: PluginHooks;
-  customFieldTypes?: CustomFieldDefinition[];
-  init?: (engine: unknown) => Promise<void> | void;
+  /** Additional custom field types projects can use in `customFieldDefinitions`. */
+  customFieldTypes?: CustomFieldType[];
+  /** Runs once when the engine starts; `engine.ready` resolves after every plugin's `init`. */
+  init?: (engine: import('../engine/index.js').CriticalPathEngine) => Promise<void> | void;
+  /** HTTP routes served by `@critical-path/server`, matched before built-in routes. */
+  routes?: PluginRoute[];
+  /** Middleware run by `@critical-path/server` around every routed request. */
+  middleware?: PluginMiddleware;
 }
 
 export interface CriticalPathConfig {

package/src/webhooks/webhooks.test.ts

@@ -78,7 +78,8 @@ describe('webhook delivery', () => {
     await engine.createTask({ projectId: project.id, title: 'T' });
     await engine.webhooks.idle();
 
-    expect(deliveries.map((d) => d.body.event)).toEqual(['project.created', 'task.created']);
+    // Deliveries are asynchronous, so arrival order is not guaranteed
+    expect(deliveries.map((d) => d.body.event).sort()).toEqual(['project.created', 'task.created']);
     expect(deliveries.every((d) => d.url.endsWith('/all'))).toBe(true);
   });