@critical-path/core 0.10.0 → 0.12.0

package/src/domain/entities.ts

@@ -8,7 +8,10 @@ import type {
   TaskTodoItem,
   CustomFieldDefinition,
   CreateTaskInput,
-  CreateProjectInput
+  CreateProjectInput,
+  Deliverable,
+  DeliverableStatus,
+  CreateDeliverableInput
 } from '../types/index.js';
 import type {
   DomainEvent,
@@ -16,7 +19,10 @@ import type {
   TaskStatusChangedEvent,
   TaskUpdatedEvent,
   TimeLoggedEvent,
-  ProjectCreatedEvent
+  ProjectCreatedEvent,
+  DeliverableCreatedEvent,
+  DeliverableUpdatedEvent,
+  DeliverableStatusChangedEvent
 } from './events.js';
 import { validateTransition, WorkflowValidationError } from '../utils/workflow.js';
 import { resolveStatusDefinition } from '../utils/status.js';
@@ -67,6 +73,7 @@ export class TaskEntity extends BaseEntity {
   public iterationId?: string;
   public teamId?: string;
   public containerId?: string;
+  public deliverableId?: string;
   public plannedStartDate?: string;
   public actualStartDate?: string;
   public actualEndDate?: string;
@@ -99,6 +106,7 @@ export class TaskEntity extends BaseEntity {
     this.iterationId = data.iterationId;
     this.teamId = data.teamId;
     this.containerId = data.containerId;
+    this.deliverableId = data.deliverableId;
     this.plannedStartDate = data.plannedStartDate;
     this.actualStartDate = data.actualStartDate;
     this.actualEndDate = data.actualEndDate;
@@ -365,6 +373,7 @@ export class TaskEntity extends BaseEntity {
       iterationId: this.iterationId,
       teamId: this.teamId,
       containerId: this.containerId,
+      deliverableId: this.deliverableId,
       plannedStartDate: this.plannedStartDate,
       actualStartDate: this.actualStartDate,
       actualEndDate: this.actualEndDate,
@@ -471,6 +480,180 @@ export class ProjectEntity extends BaseEntity {
   }
 }
 
+export class DeliverableEntity extends BaseEntity {
+  public projectId: string;
+  public title: string;
+  public description?: string;
+  public status: DeliverableStatus;
+  public format?: string;
+  public specs?: Record<string, unknown>;
+  public leadId?: string;
+  public reviewerId?: string;
+  public dueDate?: string;
+  public deliveredAt?: string;
+  public outputUrls?: string[];
+  public customFields?: Record<string, unknown>;
+
+  constructor(data: Deliverable) {
+    super(data.id, data.createdAt, data.updatedAt);
+    this.projectId = data.projectId;
+    this.title = data.title;
+    this.description = data.description;
+    this.status = data.status;
+    this.format = data.format;
+    this.specs = data.specs ? { ...data.specs } : undefined;
+    this.leadId = data.leadId;
+    this.reviewerId = data.reviewerId;
+    this.dueDate = data.dueDate;
+    this.deliveredAt = data.deliveredAt;
+    this.outputUrls = data.outputUrls ? [...data.outputUrls] : [];
+    this.customFields = data.customFields ? { ...data.customFields } : {};
+  }
+
+  public static create(
+    input: CreateDeliverableInput,
+    options?: { id?: string; customFieldDefs?: CustomFieldDefinition[] }
+  ): DeliverableEntity {
+    const id = options?.id || `deliv_${Math.random().toString(36).substring(2, 9)}`;
+    const now = new Date().toISOString();
+
+    if (options?.customFieldDefs) {
+      validateCustomFieldValues(options.customFieldDefs, input.customFields);
+    }
+
+    const deliverable = new DeliverableEntity({
+      ...input,
+      id,
+      createdAt: now,
+      updatedAt: now,
+      status: input.status || 'planned',
+      outputUrls: input.outputUrls ?? [],
+      customFields: input.customFields ?? {}
+    });
+
+    const createdEvent: DeliverableCreatedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'deliverable.created',
+      aggregateId: deliverable.id,
+      aggregateType: 'Deliverable',
+      occurredAt: now,
+      payload: { deliverable: deliverable.toPlain() }
+    };
+    deliverable.raiseEvent(createdEvent);
+
+    return deliverable;
+  }
+
+  public transitionTo(newStatus: DeliverableStatus): this {
+    if (this.status === newStatus) return this;
+
+    const previousStatus = this.status;
+    this.status = newStatus;
+    const now = new Date().toISOString();
+
+    if (newStatus === 'delivered' && !this.deliveredAt) {
+      this.deliveredAt = now;
+    }
+
+    this.markUpdated();
+
+    const event: DeliverableStatusChangedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'deliverable.status_changed',
+      aggregateId: this.id,
+      aggregateType: 'Deliverable',
+      occurredAt: now,
+      payload: {
+        deliverable: this.toPlain(),
+        previousStatus,
+        newStatus
+      }
+    };
+    this.raiseEvent(event);
+
+    return this;
+  }
+
+  public addOutputUrl(url: string): this {
+    if (!this.outputUrls) {
+      this.outputUrls = [];
+    }
+    if (!this.outputUrls.includes(url)) {
+      const previous = this.toPlain();
+      this.outputUrls.push(url);
+      this.markUpdated();
+
+      const event: DeliverableUpdatedEvent = {
+        id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+        name: 'deliverable.updated',
+        aggregateId: this.id,
+        aggregateType: 'Deliverable',
+        occurredAt: new Date().toISOString(),
+        payload: {
+          deliverable: this.toPlain(),
+          previous
+        }
+      };
+      this.raiseEvent(event);
+    }
+    return this;
+  }
+
+  public update(updates: Partial<Deliverable>, customFieldDefs?: CustomFieldDefinition[]): this {
+    const previous = this.toPlain();
+
+    if (updates.customFields && customFieldDefs) {
+      validateCustomFieldValues(customFieldDefs, {
+        ...this.customFields,
+        ...updates.customFields
+      });
+    }
+
+    if (updates.status && updates.status !== this.status) {
+      this.transitionTo(updates.status);
+      delete updates.status;
+    }
+
+    Object.assign(this, updates);
+    this.markUpdated();
+
+    const event: DeliverableUpdatedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'deliverable.updated',
+      aggregateId: this.id,
+      aggregateType: 'Deliverable',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        deliverable: this.toPlain(),
+        previous
+      }
+    };
+    this.raiseEvent(event);
+
+    return this;
+  }
+
+  public toPlain(): Deliverable {
+    return {
+      id: this.id,
+      projectId: this.projectId,
+      title: this.title,
+      description: this.description,
+      status: this.status,
+      format: this.format,
+      specs: this.specs ? { ...this.specs } : undefined,
+      leadId: this.leadId,
+      reviewerId: this.reviewerId,
+      dueDate: this.dueDate,
+      deliveredAt: this.deliveredAt,
+      outputUrls: this.outputUrls ? [...this.outputUrls] : [],
+      customFields: this.customFields ? { ...this.customFields } : {},
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt
+    };
+  }
+}
+
 export class AttachmentValidationError extends Error {
   constructor(message: string) {
     super(message);

package/src/domain/events.ts

@@ -9,14 +9,15 @@ import type {
   TimeEntry,
   Comment,
   CommentReaction,
-  Attachment
+  Attachment,
+  Deliverable
 } from '../types/index.js';
 
 export interface DomainEvent<TPayload = Record<string, unknown>> {
   readonly id: string;
   readonly name: string;
   readonly aggregateId: string;
-  readonly aggregateType: 'Task' | 'Project' | 'Workflow' | 'Iteration' | 'Team' | 'Container' | 'Dependency' | 'Comment' | 'Attachment';
+  readonly aggregateType: 'Task' | 'Project' | 'Workflow' | 'Iteration' | 'Team' | 'Container' | 'Dependency' | 'Comment' | 'Attachment' | 'Deliverable';
   readonly occurredAt: string;
   readonly payload: TPayload;
 }
@@ -136,6 +137,26 @@ export interface ContainerCreatedEvent extends DomainEvent<{ container: TaskCont
   readonly aggregateType: 'Container';
 }
 
+export interface DeliverableCreatedEvent extends DomainEvent<{ deliverable: Deliverable }> {
+  readonly name: 'deliverable.created';
+  readonly aggregateType: 'Deliverable';
+}
+
+export interface DeliverableUpdatedEvent extends DomainEvent<{ deliverable: Deliverable; previous: Deliverable }> {
+  readonly name: 'deliverable.updated';
+  readonly aggregateType: 'Deliverable';
+}
+
+export interface DeliverableStatusChangedEvent extends DomainEvent<{ deliverable: Deliverable; previousStatus: string; newStatus: string }> {
+  readonly name: 'deliverable.status_changed';
+  readonly aggregateType: 'Deliverable';
+}
+
+export interface DeliverableDeletedEvent extends DomainEvent<{ deliverableId: string; projectId: string }> {
+  readonly name: 'deliverable.deleted';
+  readonly aggregateType: 'Deliverable';
+}
+
 export type CriticalPathDomainEvent =
   | TaskCreatedEvent
   | TaskUpdatedEvent
@@ -158,7 +179,11 @@ export type CriticalPathDomainEvent =
   | IterationStartedEvent
   | IterationCompletedEvent
   | TeamCreatedEvent
-  | ContainerCreatedEvent;
+  | ContainerCreatedEvent
+  | DeliverableCreatedEvent
+  | DeliverableUpdatedEvent
+  | DeliverableStatusChangedEvent
+  | DeliverableDeletedEvent;
 
 export type DomainEventHandler<T extends DomainEvent = DomainEvent> = (event: T) => Promise<void> | void;
 

package/src/engine/index.ts

@@ -17,7 +17,10 @@ import type {
   WebhookEvent,
   Workflow,
   CreateTaskInput,
-  CreateProjectInput
+  CreateProjectInput,
+  Deliverable,
+  DeliverableSummary,
+  CreateDeliverableInput
 } from '../types/index.js';
 import { StorageAdapter, InMemoryStore } from '../store/index.js';
 import { PluginRegistry } from '../plugins/index.js';
@@ -28,6 +31,7 @@ import {
   WorkflowValidationError,
   DEFAULT_SOFTWARE_WORKFLOW
 } from '../utils/workflow.js';
+import { extractMentions } from '../utils/mentions.js';
 import {
   DomainEventBus,
   TaskCreatedEvent,
@@ -43,6 +47,10 @@ import {
   IterationCompletedEvent,
   TeamCreatedEvent,
   ContainerCreatedEvent,
+  DeliverableCreatedEvent,
+  DeliverableUpdatedEvent,
+  DeliverableStatusChangedEvent,
+  DeliverableDeletedEvent,
   TaskDependencyAddedEvent,
   TimeLoggedEvent,
   CommentAddedEvent,
@@ -62,6 +70,7 @@ export class CriticalPathEngine {
   public readonly fileStorage?: FileStorageAdapter;
   public readonly plugins: PluginRegistry;
   public readonly events: DomainEventBus;
+  public readonly ready: Promise<void> = Promise.resolve();
 
   constructor(config: CriticalPathConfig = {}) {
     this.store = typeof config.store === 'object' && config.store !== null
@@ -79,7 +88,7 @@ export class CriticalPathEngine {
     }
 
     if (config.initialData) {
-      this.seedInitialData(config.initialData);
+      this.ready = this.seedInitialData(config.initialData);
     }
   }
 
@@ -104,6 +113,11 @@ export class CriticalPathEngine {
         await this.store.createContainer(c);
       }
     }
+    if (data.deliverables) {
+      for (const d of data.deliverables) {
+        await this.store.createDeliverable(d);
+      }
+    }
     if (data.iterations) {
       for (const it of data.iterations) {
         await this.store.createIteration(it);
@@ -331,6 +345,7 @@ export class CriticalPathEngine {
       iterationId: processedInput.iterationId ?? taskInput.iterationId,
       teamId: processedInput.teamId ?? taskInput.teamId,
       containerId: processedInput.containerId ?? taskInput.containerId,
+      deliverableId: processedInput.deliverableId ?? taskInput.deliverableId,
       plannedStartDate: processedInput.plannedStartDate ?? taskInput.plannedStartDate,
       actualStartDate,
       actualEndDate,
@@ -624,7 +639,8 @@ export class CriticalPathEngine {
   }
 
   async addComment(comment: Omit<Comment, 'id' | 'createdAt' | 'updatedAt'>): Promise<Comment> {
-    const created = await this.store.addComment(comment);
+    const mentions = comment.mentions ?? extractMentions(comment.content);
+    const created = await this.store.addComment({ ...comment, mentions });
     const now = new Date().toISOString();
 
     const event: CommentAddedEvent = {
@@ -645,7 +661,10 @@ export class CriticalPathEngine {
     const existing = await this.store.getComment(id);
     if (!existing) return null;
 
-    const updated = await this.store.updateComment(id, updates);
+    const mentions = updates.mentions ?? (updates.content ? extractMentions(updates.content) : undefined);
+    const toUpdate = mentions !== undefined ? { ...updates, mentions } : updates;
+
+    const updated = await this.store.updateComment(id, toUpdate);
     if (!updated) return null;
 
     const now = new Date().toISOString();
@@ -932,6 +951,178 @@ export class CriticalPathEngine {
     return this.store.deleteContainer(id);
   }
 
+  // --- Deliverables ---
+  async getDeliverables(projectId: string): Promise<Deliverable[]> {
+    return this.store.getDeliverables(projectId);
+  }
+
+  async getDeliverable(id: string): Promise<Deliverable | null> {
+    return this.store.getDeliverable(id);
+  }
+
+  async createDeliverable(input: CreateDeliverableInput): Promise<Deliverable> {
+    const project = await this.store.getProject(input.projectId);
+    if (project?.customFieldDefinitions && input.customFields) {
+      validateCustomFieldValues(project.customFieldDefinitions, input.customFields);
+    }
+
+    const created = await this.store.createDeliverable({
+      ...input,
+      status: input.status || 'planned',
+      outputUrls: input.outputUrls ?? [],
+      customFields: input.customFields ?? {}
+    });
+    const now = new Date().toISOString();
+
+    const event: DeliverableCreatedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'deliverable.created',
+      aggregateId: created.id,
+      aggregateType: 'Deliverable',
+      occurredAt: now,
+      payload: { deliverable: created }
+    };
+    await this.events.publish(event);
+
+    await this.store.logActivity({
+      projectId: created.projectId,
+      actorId: 'system',
+      action: 'deliverable.created',
+      details: { title: created.title, format: created.format }
+    });
+    this.dispatchWebhook('deliverable.created', { deliverable: created });
+    return created;
+  }
+
+  async updateDeliverable(id: string, updates: Partial<Deliverable>): Promise<Deliverable | null> {
+    const existing = await this.store.getDeliverable(id);
+    if (!existing) return null;
+
+    if (updates.status && updates.status === 'delivered' && !existing.deliveredAt && !updates.deliveredAt) {
+      updates.deliveredAt = new Date().toISOString();
+    }
+
+    const updated = await this.store.updateDeliverable(id, updates);
+    if (updated) {
+      const now = new Date().toISOString();
+
+      if (updates.status && updates.status !== existing.status) {
+        const statusEvent: DeliverableStatusChangedEvent = {
+          id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+          name: 'deliverable.status_changed',
+          aggregateId: updated.id,
+          aggregateType: 'Deliverable',
+          occurredAt: now,
+          payload: {
+            deliverable: updated,
+            previousStatus: existing.status,
+            newStatus: updated.status
+          }
+        };
+        await this.events.publish(statusEvent);
+        this.dispatchWebhook('deliverable.status_changed', {
+          deliverable: updated,
+          previousStatus: existing.status,
+          newStatus: updated.status
+        });
+      }
+
+      const updateEvent: DeliverableUpdatedEvent = {
+        id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+        name: 'deliverable.updated',
+        aggregateId: updated.id,
+        aggregateType: 'Deliverable',
+        occurredAt: now,
+        payload: { deliverable: updated, previous: existing }
+      };
+      await this.events.publish(updateEvent);
+
+      await this.store.logActivity({
+        projectId: updated.projectId,
+        actorId: 'system',
+        action: 'deliverable.updated',
+        details: { title: updated.title, status: updated.status }
+      });
+      this.dispatchWebhook('deliverable.updated', { deliverable: updated });
+    }
+    return updated;
+  }
+
+  async deleteDeliverable(id: string): Promise<boolean> {
+    const existing = await this.store.getDeliverable(id);
+    if (!existing) return false;
+
+    const deleted = await this.store.deleteDeliverable(id);
+    if (deleted) {
+      const now = new Date().toISOString();
+      const event: DeliverableDeletedEvent = {
+        id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+        name: 'deliverable.deleted',
+        aggregateId: id,
+        aggregateType: 'Deliverable',
+        occurredAt: now,
+        payload: { deliverableId: id, projectId: existing.projectId }
+      };
+      await this.events.publish(event);
+
+      await this.store.logActivity({
+        projectId: existing.projectId,
+        actorId: 'system',
+        action: 'deliverable.deleted',
+        details: { title: existing.title }
+      });
+      this.dispatchWebhook('deliverable.deleted', { deliverableId: id, projectId: existing.projectId });
+    }
+    return deleted;
+  }
+
+  async getDeliverableSummary(deliverableId: string): Promise<DeliverableSummary | null> {
+    const deliverable = await this.store.getDeliverable(deliverableId);
+    if (!deliverable) return null;
+
+    const project = await this.store.getProject(deliverable.projectId);
+    const workflow = await this.resolveProjectWorkflow(deliverable.projectId);
+    const allTasks = await this.store.getTasks(deliverable.projectId);
+    const tasks = allTasks.filter((t) => t.deliverableId === deliverableId);
+
+    const totalTasks = tasks.length;
+    let completedTasks = 0;
+    let activeTasks = 0;
+    let estimatedHours = 0;
+    let loggedHours = 0;
+    let totalProgress = 0;
+
+    for (const task of tasks) {
+      const statusDef = resolveStatusDefinition(task.status, project?.statusDefinitions || workflow?.statuses);
+      if (statusDef.completionState === 'done') {
+        completedTasks++;
+      } else if (statusDef.executionState === 'active') {
+        activeTasks++;
+      }
+
+      if (task.estimatedHours) estimatedHours += task.estimatedHours;
+      if (task.loggedHours) loggedHours += task.loggedHours;
+
+      if (typeof task.progress === 'number') {
+        totalProgress += task.progress;
+      } else {
+        totalProgress += statusDef.completionState === 'done' ? 100 : 0;
+      }
+    }
+
+    const progressPercentage = totalTasks > 0 ? Math.round(totalProgress / totalTasks) : 0;
+
+    return {
+      deliverable,
+      totalTasks,
+      completedTasks,
+      activeTasks,
+      progressPercentage,
+      estimatedHours,
+      loggedHours
+    };
+  }
+
   // --- Iterations ---
   async getIterations(projectId: string): Promise<Iteration[]> {
     return this.store.getIterations(projectId);

package/src/index.test.ts

@@ -310,5 +310,35 @@ describe('CriticalPathEngine Core Tests', () => {
     expect(afterRemoval?.reactions?.[0].emoji).toBe('🚀');
     expect(receivedEvents).toContain('comment.reaction.removed');
   });
+
+  it('supports mentions in comments with auto-extraction and explicit override', async () => {
+    const engine = new CriticalPathEngine();
+    const proj = await engine.createProject({ key: 'MNT', name: 'Mentions Project' });
+    const task = await engine.createTask({ projectId: proj.id, title: 'Mentions Task', status: 'todo' });
+
+    // Auto-extracted mentions
+    const comment1 = await engine.addComment({
+      taskId: task.id,
+      authorId: 'user_1',
+      content: 'Hey @planner and @user_2, please check with @"Supervisor Agent"!'
+    });
+    expect(comment1.mentions).toEqual(['planner', 'user_2', 'Supervisor Agent']);
+
+    // Explicit mentions passed
+    const comment2 = await engine.addComment({
+      taskId: task.id,
+      authorId: 'user_1',
+      content: 'Custom mention assignment',
+      mentions: ['custom_agent_id']
+    });
+    expect(comment2.mentions).toEqual(['custom_agent_id']);
+
+    // Update comment content updates mentions
+    const updated = await engine.updateComment(comment1.id, {
+      content: 'Now calling only @coordinator'
+    });
+    expect(updated?.mentions).toEqual(['coordinator']);
+  });
 });
 
+

package/src/store/firebase.ts

@@ -11,7 +11,9 @@ import type {
   Activity,
   Webhook,
   TaskDependency,
-  Workflow
+  Workflow,
+  Deliverable,
+  CreateDeliverableInput
 } from '../types/index.js';
 import { generateProjectKey } from '../utils/key.js';
 
@@ -283,6 +285,50 @@ export class FirebaseStore implements StorageAdapter {
     return true;
   }
 
+  // --- Deliverables ---
+  async getDeliverables(projectId: string): Promise<Deliverable[]> {
+    const snap = await this.db.collection('deliverables').where('projectId', '==', projectId).get();
+    return snap.docs.map((doc) => ({ ...doc.data(), id: doc.id }));
+  }
+
+  async getDeliverable(id: string): Promise<Deliverable | null> {
+    const snap = await this.db.collection('deliverables').doc(id).get();
+    if (!snap.exists) return null;
+    return { ...snap.data(), id: snap.id };
+  }
+
+  async createDeliverable(deliverable: CreateDeliverableInput): Promise<Deliverable> {
+    const docRef = this.db.collection('deliverables').doc();
+    const now = new Date().toISOString();
+    const newDeliverable: Deliverable = {
+      ...deliverable,
+      id: docRef.id,
+      status: deliverable.status || 'planned',
+      outputUrls: deliverable.outputUrls ? [...deliverable.outputUrls] : [],
+      customFields: deliverable.customFields ? { ...deliverable.customFields } : {},
+      createdAt: now,
+      updatedAt: now
+    };
+    await docRef.set(sanitizeFirestoreData(newDeliverable));
+    return newDeliverable;
+  }
+
+  async updateDeliverable(id: string, updates: Partial<Deliverable>): Promise<Deliverable | null> {
+    const existing = await this.getDeliverable(id);
+    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 });
+    return updated;
+  }
+
+  async deleteDeliverable(id: string): Promise<boolean> {
+    const existing = await this.getDeliverable(id);
+    if (!existing) return false;
+    await this.db.collection('deliverables').doc(id).delete();
+    return true;
+  }
+
   // --- Tasks ---
   async getTasks(projectId?: string): Promise<Task[]> {
     let snap;