@critical-path/core 0.26.0 → 0.28.0

package/dist/engine/index.js

@@ -5,9 +5,11 @@ import { validateTransition, getAllowedNextStatuses, getAllowedPreviousStatuses,
 import { extractMentions } from '../utils/mentions.js';
 import { DomainEventBus } from '../domain/events.js';
 import { validateAttachmentUrl } from '../domain/entities.js';
-import { validateCustomFieldValues } from '../domain/custom-fields.js';
+import { validateCustomFieldValues, validateCustomFieldDefinitions } from '../domain/custom-fields.js';
 import { detectDependencyCycle, CircularDependencyError } from '../domain/graph.js';
 import { ValidationError, NotFoundError, ForbiddenError } from '../domain/errors.js';
+import { WebhookDispatcher, assertWebhookUrl } from '../webhooks/dispatcher.js';
+import { generateWebhookSecret } from '../webhooks/signature.js';
 import { calculateCPM } from '../domain/cpm.js';
 import { buildTimelineLadder, aggregateConcreteEvidenceForTask } from '../domain/ladder.js';
 import { calculateTaskMetrics, reconstructTaskProgressHistory } from '../domain/metrics.js';
@@ -18,6 +20,8 @@ export class CriticalPathEngine {
     fileStorage;
     plugins;
     events;
+    /** Delivers domain events to registered webhooks. Exposed for custom queues (`deliver`) and tests (`idle`). */
+    webhooks;
     ready = Promise.resolve();
     /** The identity mutations are attributed to. Set only on views returned by `withActor`. */
     actor;
@@ -31,14 +35,19 @@ export class CriticalPathEngine {
         this.fileStorage = config.fileStorage;
         this.plugins = new PluginRegistry();
         this.events = new DomainEventBus();
+        this.webhooks = new WebhookDispatcher({
+            listWebhooks: () => this.listAllWebhooks(),
+            resolveTenant: (event) => this.resolveEventTenant(event)
+        }, config.webhookDelivery);
+        this.events.subscribe('*', (event) => this.webhooks.handle(event));
         if (config.plugins) {
             for (const plugin of config.plugins) {
                 this.plugins.register(plugin);
             }
         }
-        if (config.initialData) {
-            this.ready = this.seedInitialData(config.initialData);
-        }
+        this.ready = this.initialize(config);
+        // Callers that never await `ready` should not crash on an unhandled rejection; awaiting it still throws.
+        this.ready.catch(() => { });
     }
     /**
      * Returns a view of this engine that attributes every mutation to `actor`: activity log
@@ -151,6 +160,14 @@ export class CriticalPathEngine {
         const { tenantId: _ignored, ...rest } = updates;
         return rest;
     }
+    async initialize(config) {
+        if (config.initialData) {
+            await this.seedInitialData(config.initialData);
+        }
+        for (const plugin of this.plugins.getPlugins()) {
+            await plugin.init?.(this);
+        }
+    }
     async seedInitialData(data) {
         if (data.workflows) {
             for (const wf of data.workflows) {
@@ -215,7 +232,6 @@ export class CriticalPathEngine {
             action: 'workflow.created',
             details: { name: created.name }
         });
-        this.dispatchWebhook('workflow.created', { workflow: created });
         return created;
     }
     async updateWorkflow(id, updates) {
@@ -241,7 +257,6 @@ export class CriticalPathEngine {
                 action: 'workflow.updated',
                 details: { name: updated.name }
             });
-            this.dispatchWebhook('workflow.updated', { workflow: updated, previous: existing });
         }
         return updated;
     }
@@ -259,7 +274,7 @@ export class CriticalPathEngine {
                 aggregateId: id,
                 aggregateType: 'Workflow',
                 occurredAt: now,
-                payload: { workflowId: id, name: existing.name }
+                payload: { workflowId: id, name: existing.name, tenantId: existing.tenantId }
             };
             await this.events.publish(event);
             await this.store.logActivity({
@@ -267,7 +282,6 @@ export class CriticalPathEngine {
                 action: 'workflow.deleted',
                 details: { name: existing.name }
             });
-            this.dispatchWebhook('workflow.deleted', { workflowId: id, name: existing.name });
         }
         return deleted;
     }
@@ -322,6 +336,7 @@ export class CriticalPathEngine {
     }
     async createProject(project) {
         await this.requireWorkspaceAccess('project.create');
+        validateCustomFieldDefinitions(project.customFieldDefinitions, this.plugins.getCustomFieldTypes());
         // Views always use the actor's tenant (possibly none); only trusted base-engine calls may set it.
         const input = { ...project, tenantId: this.actor ? this.actor.tenantId : project.tenantId };
         // The creator administers the project they create.
@@ -345,7 +360,6 @@ export class CriticalPathEngine {
             action: 'project.created',
             details: { name: created.name, key: created.key }
         });
-        this.dispatchWebhook('project.created', { project: created });
         return created;
     }
     async updateProject(id, updates) {
@@ -355,6 +369,7 @@ export class CriticalPathEngine {
         await this.requireProjectAccess('project.update', id);
         if ('members' in updates)
             await this.requireProjectAccess('project.manage_members', id);
+        validateCustomFieldDefinitions(updates.customFieldDefinitions, this.plugins.getCustomFieldTypes());
         updates = this.withoutTenant(updates);
         const updated = await this.store.updateProject(id, updates);
         if (updated) {
@@ -374,7 +389,6 @@ export class CriticalPathEngine {
                 action: 'project.updated',
                 details: { name: updated.name }
             });
-            this.dispatchWebhook('project.updated', { project: updated });
         }
         return updated;
     }
@@ -405,7 +419,7 @@ export class CriticalPathEngine {
                 aggregateId: id,
                 aggregateType: 'Project',
                 occurredAt: now,
-                payload: { projectId: id, name: existing.name, deletedTaskIds }
+                payload: { projectId: id, name: existing.name, deletedTaskIds, tenantId: existing.tenantId }
             };
             await this.events.publish(event);
             await this.store.logActivity({
@@ -414,7 +428,6 @@ export class CriticalPathEngine {
                 action: 'project.deleted',
                 details: { name: existing.name, deletedTaskCount: deletedTaskIds.length }
             });
-            this.dispatchWebhook('project.deleted', { projectId: id, name: existing.name, deletedTaskIds });
         }
         return deleted;
     }
@@ -437,13 +450,14 @@ export class CriticalPathEngine {
             taskInput = { ...taskInput, reporterId: this.actor.userId };
         }
         const processedInput = await this.plugins.runBeforeTaskCreate(taskInput);
-        const projectId = processedInput.projectId || taskInput.projectId;
+        if (processedInput.projectId && processedInput.projectId !== taskInput.projectId) {
+            throw new ValidationError('Plugins cannot move a task to another project in beforeTaskCreate.');
+        }
+        const projectId = taskInput.projectId;
         const project = await this.store.getProject(projectId);
         const workflow = await this.resolveProjectWorkflow(projectId);
-        // Validate custom field domain invariants
-        if (project?.customFieldDefinitions && (processedInput.customFields || taskInput.customFields)) {
-            validateCustomFieldValues(project.customFieldDefinitions, processedInput.customFields || taskInput.customFields);
-        }
+        // Validate custom fields on the final (post-plugin) input, including required fields when none are given
+        validateCustomFieldValues(project?.customFieldDefinitions, processedInput.customFields ?? taskInput.customFields, this.plugins.getCustomFieldTypes());
         const defaultStatus = workflow?.defaultStatusKey || 'todo';
         const initialStatus = processedInput.status || taskInput.status || defaultStatus;
         const now = new Date().toISOString();
@@ -514,7 +528,6 @@ export class CriticalPathEngine {
             action: 'task.created',
             details: { title: created.title, status: created.status }
         });
-        this.dispatchWebhook('task.created', { task: created });
         return created;
     }
     async updateTask(id, updates, options) {
@@ -531,21 +544,20 @@ export class CriticalPathEngine {
         const taskUpdates = updates;
         const project = await this.store.getProject(existing.projectId);
         const workflow = await this.resolveProjectWorkflow(existing.projectId);
+        // Plugins run first; their output is then validated like caller input. Identity and
+        // ownership fields are never changed by hooks.
+        const { id: _id, projectId: _projectId, createdAt: _createdAt, ...processedUpdates } = await this.plugins.runBeforeTaskUpdate(id, taskUpdates);
         // Validate workflow transition invariant
-        if (taskUpdates.status && taskUpdates.status !== existing.status) {
-            const isValid = validateTransition(workflow || undefined, existing.status, taskUpdates.status);
+        if (processedUpdates.status && processedUpdates.status !== existing.status) {
+            const isValid = validateTransition(workflow || undefined, existing.status, processedUpdates.status);
             if (!isValid) {
-                throw new WorkflowValidationError(existing.status, taskUpdates.status, workflow?.id);
+                throw new WorkflowValidationError(existing.status, processedUpdates.status, workflow?.id);
             }
         }
         // Validate custom field invariants
-        if (project?.customFieldDefinitions && taskUpdates.customFields) {
-            validateCustomFieldValues(project.customFieldDefinitions, {
-                ...existing.customFields,
-                ...taskUpdates.customFields
-            });
+        if (processedUpdates.customFields) {
+            validateCustomFieldValues(project?.customFieldDefinitions, { ...existing.customFields, ...processedUpdates.customFields }, this.plugins.getCustomFieldTypes());
         }
-        const processedUpdates = await this.plugins.runBeforeTaskUpdate(id, taskUpdates);
         const now = new Date().toISOString();
         const existingStatusDef = resolveStatusDefinition(existing.status, project?.statusDefinitions || workflow?.statuses);
         const newStatusDef = processedUpdates.status
@@ -759,10 +771,6 @@ export class CriticalPathEngine {
                 action: 'task.blocked',
                 details: { reason: blockedReason, ...(actorName ? { actorName } : {}) }
             });
-            this.dispatchWebhook('task.blocked', {
-                task: updated,
-                reason: blockedReason
-            });
         }
         else if (wasBlocked && !isNowBlocked) {
             const unblockedEvent = {
@@ -786,9 +794,6 @@ export class CriticalPathEngine {
                 action: 'task.unblocked',
                 details: { ...(actorName ? { actorName } : {}) }
             });
-            this.dispatchWebhook('task.unblocked', {
-                task: updated
-            });
         }
         await this.store.logActivity({
             projectId: updated.projectId,
@@ -801,10 +806,6 @@ export class CriticalPathEngine {
                 ...(actorName ? { actorName } : {})
             }
         });
-        this.dispatchWebhook(isStatusChange ? 'task.status_changed' : 'task.updated', {
-            task: updated,
-            previous: existing
-        });
         return updated;
     }
     async checkAndUnblockDownstreamTasks(completedTask) {
@@ -866,10 +867,6 @@ export class CriticalPathEngine {
                         action: 'task.unblocked',
                         details: { unblockedByTaskId: completedTask.id }
                     });
-                    this.dispatchWebhook('task.unblocked', {
-                        task: updatedDownstream,
-                        upstreamTaskId: completedTask.id
-                    });
                 }
             }
         }
@@ -882,10 +879,10 @@ export class CriticalPathEngine {
         if (!existing)
             return false;
         await this.requireProjectAccess('task.delete', existing.projectId);
-        await this.plugins.runBeforeTaskDelete(id);
+        await this.plugins.runBeforeTaskDelete(id, existing);
         const deleted = await this.store.deleteTask(id);
         if (deleted) {
-            await this.plugins.runAfterTaskDelete(id);
+            await this.plugins.runAfterTaskDelete(id, existing);
             const now = new Date().toISOString();
             const event = {
                 id: `evt_${Math.random().toString(36).substring(2, 9)}`,
@@ -907,7 +904,6 @@ export class CriticalPathEngine {
                 action: 'task.deleted',
                 details: { title: existing.title }
             });
-            this.dispatchWebhook('task.deleted', { taskId: id, title: existing.title });
         }
         return deleted;
     }
@@ -1090,7 +1086,6 @@ export class CriticalPathEngine {
             payload: { taskId: comment.taskId, comment: created }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('comment.created', { comment: created });
         return created;
     }
     async updateComment(id, updates) {
@@ -1116,7 +1111,6 @@ export class CriticalPathEngine {
             payload: { comment: updated, previous: existing }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('comment.updated', { comment: updated });
         return updated;
     }
     async deleteComment(id) {
@@ -1139,7 +1133,6 @@ export class CriticalPathEngine {
                 payload: { taskId: existing.taskId, commentId: id }
             };
             await this.events.publish(event);
-            this.dispatchWebhook('comment.deleted', { commentId: id, taskId: existing.taskId });
         }
         return deleted;
     }
@@ -1185,7 +1178,6 @@ export class CriticalPathEngine {
             }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('comment.reaction.added', { comment: updated, reaction });
         return updated;
     }
     async removeCommentReaction(commentId, input) {
@@ -1214,7 +1206,6 @@ export class CriticalPathEngine {
             payload: { commentId, reaction, comment: updated }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('comment.reaction.removed', { comment: updated, reaction });
         return updated;
     }
     // --- Attachments ---
@@ -1256,7 +1247,6 @@ export class CriticalPathEngine {
             payload: { attachment: created }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('attachment.created', { attachment: created });
         return created;
     }
     async deleteAttachment(id) {
@@ -1284,10 +1274,14 @@ export class CriticalPathEngine {
                 aggregateId: id,
                 aggregateType: 'Attachment',
                 occurredAt: now,
-                payload: { attachmentId: id, storageKey: existing.storageKey, url: existing.url }
+                payload: {
+                    attachmentId: id,
+                    storageKey: existing.storageKey,
+                    url: existing.url,
+                    projectId: await this.projectIdOfAttachment(existing)
+                }
             };
             await this.events.publish(event);
-            this.dispatchWebhook('attachment.deleted', { attachmentId: id, taskId: existing.taskId, projectId: existing.projectId });
         }
         return deleted;
     }
@@ -1387,7 +1381,6 @@ export class CriticalPathEngine {
             payload: { team: created }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('team.created', { team: created });
         return created;
     }
     async updateTeam(id, updates) {
@@ -1427,7 +1420,6 @@ export class CriticalPathEngine {
             payload: { container: created }
         };
         await this.events.publish(event);
-        this.dispatchWebhook('container.created', { container: created });
         return created;
     }
     async updateContainer(id, updates) {
@@ -1460,7 +1452,7 @@ export class CriticalPathEngine {
         await this.requireProjectAccess('plan.manage', input.projectId);
         const project = await this.store.getProject(input.projectId);
         if (project?.customFieldDefinitions && input.customFields) {
-            validateCustomFieldValues(project.customFieldDefinitions, input.customFields);
+            validateCustomFieldValues(project.customFieldDefinitions, input.customFields, this.plugins.getCustomFieldTypes());
         }
         const created = await this.store.createDeliverable({
             ...input,
@@ -1484,7 +1476,6 @@ export class CriticalPathEngine {
             action: 'deliverable.created',
             details: { title: created.title, format: created.format }
         });
-        this.dispatchWebhook('deliverable.created', { deliverable: created });
         return created;
     }
     async updateDeliverable(id, updates) {
@@ -1512,11 +1503,6 @@ export class CriticalPathEngine {
                     }
                 };
                 await this.events.publish(statusEvent);
-                this.dispatchWebhook('deliverable.status_changed', {
-                    deliverable: updated,
-                    previousStatus: existing.status,
-                    newStatus: updated.status
-                });
             }
             const updateEvent = {
                 id: `evt_${Math.random().toString(36).substring(2, 9)}`,
@@ -1533,7 +1519,6 @@ export class CriticalPathEngine {
                 action: 'deliverable.updated',
                 details: { title: updated.title, status: updated.status }
             });
-            this.dispatchWebhook('deliverable.updated', { deliverable: updated });
         }
         return updated;
     }
@@ -1560,7 +1545,6 @@ export class CriticalPathEngine {
                 action: 'deliverable.deleted',
                 details: { title: existing.title }
             });
-            this.dispatchWebhook('deliverable.deleted', { deliverableId: id, projectId: existing.projectId });
         }
         return deleted;
     }
@@ -1634,7 +1618,6 @@ export class CriticalPathEngine {
                 payload: { iteration: created }
             };
             await this.events.publish(event);
-            this.dispatchWebhook('iteration.started', { iteration: created });
         }
         return created;
     }
@@ -1656,7 +1639,6 @@ export class CriticalPathEngine {
                     payload: { iteration: updated }
                 };
                 await this.events.publish(event);
-                this.dispatchWebhook('iteration.started', { iteration: updated });
             }
             else if (existing.status !== 'completed' && updated.status === 'completed') {
                 const event = {
@@ -1668,7 +1650,6 @@ export class CriticalPathEngine {
                     payload: { iteration: updated }
                 };
                 await this.events.publish(event);
-                this.dispatchWebhook('iteration.completed', { iteration: updated });
             }
         }
         return updated;
@@ -1819,18 +1800,93 @@ export class CriticalPathEngine {
             schedule
         });
     }
-    async dispatchWebhook(event, payload) {
+    // --- Webhooks ---
+    /** Webhooks from `config.webhooks` (static, not editable) plus those in the store. */
+    async listAllWebhooks() {
+        const fromConfig = (this.config.webhooks ?? []).map((w, i) => ({
+            ...w,
+            id: `config_${i}`,
+            createdAt: new Date(0).toISOString()
+        }));
+        return [...fromConfig, ...(await this.store.getWebhooks())];
+    }
+    toPublicWebhook({ secret, ...webhook }) {
+        return { ...webhook, hasSecret: !!secret };
+    }
+    /** Webhooks in the actor's tenant, with secrets redacted. Requires `workspace.manage` on views. */
+    async getWebhooks() {
+        await this.requireWorkspaceAccess('workspace.manage');
         const webhooks = await this.store.getWebhooks();
-        const active = webhooks.filter((w) => w.active && w.events.includes(event));
-        for (const wh of active) {
-            fetch(wh.url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ event, timestamp: new Date().toISOString(), data: payload })
-            }).catch(() => {
-                // Silent catch for webhook errors in dev
-            });
+        return webhooks.filter((w) => this.inActorTenant(w)).map((w) => this.toPublicWebhook(w));
+    }
+    async getWebhook(id) {
+        await this.requireWorkspaceAccess('workspace.manage');
+        const webhook = await this.store.getWebhook(id);
+        return webhook && this.inActorTenant(webhook) ? this.toPublicWebhook(webhook) : null;
+    }
+    /**
+     * Registers a webhook. The signing secret is returned only here; generate one by omitting
+     * `secret`. Deliveries carry `X-CriticalPath-Signature` (see `verifyWebhookSignature`).
+     */
+    async createWebhook(input) {
+        await this.requireWorkspaceAccess('workspace.manage');
+        this.validateWebhookUrl(input.url);
+        const secret = input.secret ?? generateWebhookSecret();
+        const created = await this.store.addWebhook({
+            name: input.name,
+            url: input.url,
+            events: input.events,
+            secret,
+            active: input.active ?? true,
+            tenantId: this.actor?.tenantId
+        });
+        this.webhooks.invalidate();
+        return { webhook: this.toPublicWebhook(created), secret };
+    }
+    async updateWebhook(id, updates) {
+        if (!(await this.getWebhook(id)))
+            return null;
+        if (updates.url)
+            this.validateWebhookUrl(updates.url);
+        const { name, url, events, active, secret } = updates;
+        const updated = await this.store.updateWebhook(id, Object.fromEntries(Object.entries({ name, url, events, active, secret }).filter(([, v]) => v !== undefined)));
+        this.webhooks.invalidate();
+        return updated ? this.toPublicWebhook(updated) : null;
+    }
+    async deleteWebhook(id) {
+        if (!(await this.getWebhook(id)))
+            return false;
+        const deleted = await this.store.deleteWebhook(id);
+        this.webhooks.invalidate();
+        return deleted;
+    }
+    validateWebhookUrl(url) {
+        try {
+            assertWebhookUrl(url, this.config.webhookDelivery?.allowPrivateUrls);
         }
+        catch (err) {
+            throw new ValidationError(err.message);
+        }
+    }
+    /** Finds the tenant an event belongs to, from the entity in its payload or its project. */
+    async resolveEventTenant(event) {
+        const p = event.payload;
+        const owner = p.project ?? p.workflow ?? p.team;
+        if (owner)
+            return owner.tenantId ?? undefined;
+        // Deleted projects and workflows carry their tenant in the payload.
+        if ('tenantId' in p)
+            return p.tenantId ?? undefined;
+        const projectId = p.projectId ??
+            p.task?.projectId ??
+            p.deliverable?.projectId ??
+            p.iteration?.projectId ??
+            p.container?.projectId ??
+            p.attachment?.projectId ??
+            (await this.projectIdOfTask(p.taskId ?? p.comment?.taskId ?? p.attachment?.taskId ?? p.dependency?.taskId ?? p.timeEntry?.taskId));
+        if (!projectId)
+            return undefined;
+        return (await this.store.getProject(projectId))?.tenantId ?? undefined;
     }
 }
 //# sourceMappingURL=index.js.map