@critical-path/core 0.13.3 → 0.15.0

package/src/storage/firebase-storage.ts

@@ -52,6 +52,11 @@ export class InMemoryFirebaseStorageMock implements FirebaseStorageBucketInterfa
       async delete() {
         files.delete(path);
       },
+      async download(): Promise<[Uint8Array]> {
+        const file = files.get(path);
+        if (!file) throw new Error(`File not found: ${path}`);
+        return [file.data];
+      },
       async getMetadata(): Promise<[any]> {
         const file = files.get(path);
         return [{
@@ -146,6 +151,21 @@ export class FirebaseStorageAdapter implements FileStorageAdapter {
     }
   }
 
+  async download(storageKey: string): Promise<Buffer | Uint8Array> {
+    const fileRef = this.bucket.file(storageKey);
+    if (typeof (fileRef as any).download === 'function') {
+      const [buf] = await (fileRef as any).download();
+      return buf;
+    }
+    const url = await this.getDownloadUrl(storageKey);
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(`Failed to download file from "${url}": ${res.statusText}`);
+    }
+    const arrayBuffer = await res.arrayBuffer();
+    return new Uint8Array(arrayBuffer);
+  }
+
   async getDownloadUrl(storageKey: string): Promise<string> {
     const fileRef = this.bucket.file(storageKey);
     if (typeof (fileRef as any).getMetadata === 'function') {

package/src/storage/storage.test.ts

@@ -172,5 +172,45 @@ describe('Storage Adapters', () => {
       expect(storedUri?.sizeBytes).toBe(Buffer.from(rawText).length);
       expect(new TextDecoder().decode(storedUri?.data)).toBe(rawText);
     });
+
+    it('downloads file bytes and reads text content from attachments via engine', async () => {
+      const mockStorage = new InMemoryFirebaseStorageMock();
+      const storageAdapter = new FirebaseStorageAdapter({ bucket: mockStorage, bucketName: 'test-bucket' });
+      const engine = new CriticalPathEngine({ fileStorage: storageAdapter });
+
+      const project = await engine.createProject({ name: 'Attachment Reading Test' });
+      const task = await engine.createTask({ projectId: project.id, title: 'Document Task' });
+
+      const planMarkdown = '# Project Roadmap\n\nPhase 1: Research\nPhase 2: Execution';
+      const attachment = await engine.uploadAttachmentFile({
+        filename: 'Roadmap.md',
+        data: planMarkdown,
+        mimeType: 'text/markdown',
+        taskId: task.id,
+        projectId: project.id,
+        uploaderId: 'agent_planner',
+        uploaderType: 'agent',
+        artifactType: 'plan'
+      });
+
+      expect(attachment.id).toBeDefined();
+      expect(attachment.artifactType).toBe('plan');
+
+      // Test download method on adapter
+      const downloadedBytes = await storageAdapter.download(attachment.storageKey!);
+      expect(new TextDecoder().decode(downloadedBytes)).toBe(planMarkdown);
+
+      // Test engine readAttachmentText
+      const readText = await engine.readAttachmentText(attachment.id);
+      expect(readText).toBe(planMarkdown);
+
+      // Test filtering by artifactType
+      const planAttachments = await engine.getAttachments({ taskId: task.id, artifactType: 'plan' });
+      expect(planAttachments.length).toBe(1);
+      expect(planAttachments[0].id).toBe(attachment.id);
+
+      const reviewAttachments = await engine.getAttachments({ taskId: task.id, artifactType: 'review' });
+      expect(reviewAttachments.length).toBe(0);
+    });
   });
 });

package/src/store/firebase.test.ts

@@ -62,7 +62,7 @@ describe('FirebaseStore', () => {
       name: 'Firebase Workflow',
       isDefault: false,
       defaultStatusKey: 'backlog',
-      statuses: [{ key: 'backlog', label: 'Backlog', completionState: 'not_done', executionState: 'inactive' }],
+      statuses: [{ key: 'backlog', label: 'Backlog', category: 'not_started' }],
       transitions: []
     });
 

package/src/store/sqlite.test.ts

@@ -155,7 +155,7 @@ describe('SQLiteStore', () => {
       name: 'SQLite Workflow',
       isDefault: true,
       defaultStatusKey: 'todo',
-      statuses: [{ key: 'todo', label: 'To Do', completionState: 'not_done', executionState: 'inactive' }],
+      statuses: [{ key: 'todo', label: 'To Do', category: 'not_started' }],
       transitions: []
     });
 

package/src/types/index.ts

@@ -4,17 +4,33 @@ export type Priority = DefaultPriority | (string & {});
 export type DefaultTaskStatus = 'backlog' | 'todo' | 'in_progress' | 'in_review' | 'done' | 'canceled';
 export type TaskStatus = DefaultTaskStatus | (string & {});
 
-export type CompletionState = 'done' | 'not_done';
-export type ExecutionState = 'active' | 'inactive';
+export type SemanticStatus = 'not_started' | 'in_progress' | 'completed' | 'canceled';
 
 export interface StatusDefinition {
   key: string;
   label: string;
-  completionState: CompletionState;
-  executionState: ExecutionState;
-  isCancelled?: boolean;
+  category: SemanticStatus;
 }
 
+export interface TaskDerivedStatus {
+  semanticStatus: SemanticStatus;
+  isReady: boolean;
+  isBlocked: boolean;
+  blockingTaskIds: string[];
+  isOverdue: boolean;
+  isUpcoming: boolean;
+  isUnplanned: boolean;
+  isUnassigned: boolean;
+  isStalled: boolean;
+  isOverEstimate: boolean;
+  isPaceWarning: boolean;
+  isDone: boolean;
+  isActive: boolean;
+  isCancelled: boolean;
+}
+
+export type TaskLifecycleState = TaskDerivedStatus;
+
 export type Role = 'admin' | 'project_manager' | 'contributor' | 'viewer';
 
 export interface User {
@@ -142,6 +158,7 @@ export interface Task {
   title: string;
   description?: string;
   status: TaskStatus;
+  semanticStatus?: SemanticStatus;
   priority: Priority;
   taskType?: string; // e.g. "bug", "feature", "task", "epic"
   assigneeId?: string;
@@ -271,6 +288,7 @@ export interface Attachment {
   sizeBytes: number;
   url: string;
   storageKey?: string;
+  artifactType?: 'plan' | 'spec' | 'deliverable' | 'review' | 'general';
   metadata?: Record<string, unknown>;
   createdAt: string;
   updatedAt: string;
@@ -309,6 +327,7 @@ export interface PresignedUploadResult {
 export interface FileStorageAdapter {
   upload(input: UploadFileInput): Promise<UploadFileResult>;
   delete(storageKey: string): Promise<boolean>;
+  download?(storageKey: string): Promise<Buffer | Uint8Array>;
   getDownloadUrl?(storageKey: string): Promise<string>;
   getPresignedUploadUrl?(options: PresignedUrlOptions): Promise<PresignedUploadResult>;
 }

package/src/use-case-validation.test.ts

@@ -138,7 +138,7 @@ describe('Critical Path Use Case Validation Suite', () => {
       // Check Lifecycle State
       const lifecycle = await engine.getTaskLifecycleState(featureTask.id);
       expect(lifecycle?.isDone).toBe(true);
-      expect(lifecycle?.completionState).toBe('done');
+      expect(lifecycle?.semanticStatus).toBe('completed');
     });
   });
 

package/src/utils/status.ts

@@ -1,27 +1,24 @@
 import type {
   Task,
   StatusDefinition,
-  CompletionState,
-  ExecutionState
+  SemanticStatus,
+  TaskDerivedStatus,
 } from '../types/index.js';
 
 export const DEFAULT_STATUS_DEFINITIONS: Record<string, StatusDefinition> = {
-  backlog: { key: 'backlog', label: 'Backlog', completionState: 'not_done', executionState: 'inactive' },
-  todo: { key: 'todo', label: 'To Do', completionState: 'not_done', executionState: 'inactive' },
-  in_progress: { key: 'in_progress', label: 'In Progress', completionState: 'not_done', executionState: 'active' },
-  in_review: { key: 'in_review', label: 'In Review', completionState: 'not_done', executionState: 'active' },
-  done: { key: 'done', label: 'Done', completionState: 'done', executionState: 'inactive' },
-  canceled: { key: 'canceled', label: 'Canceled', completionState: 'done', executionState: 'inactive', isCancelled: true }
+  backlog: { key: 'backlog', label: 'Backlog', category: 'not_started' },
+  todo: { key: 'todo', label: 'To Do', category: 'not_started' },
+  in_progress: { key: 'in_progress', label: 'In Progress', category: 'in_progress' },
+  in_review: { key: 'in_review', label: 'In Review', category: 'in_progress' },
+  done: { key: 'done', label: 'Done', category: 'completed' },
+  canceled: { key: 'canceled', label: 'Canceled', category: 'canceled' }
 };
 
-export interface TaskLifecycleState {
-  completionState: CompletionState;
-  executionState: ExecutionState;
-  isDone: boolean;
-  isActive: boolean;
-  isCancelled: boolean;
-  isOverdue: boolean;
-  isUpcoming: boolean;
+export interface DeriveTaskLifecycleOptions {
+  customDefinitions?: StatusDefinition[];
+  referenceDate?: Date;
+  upstreamTasks?: Task[];
+  stalledThresholdDays?: number;
 }
 
 export function resolveStatusDefinition(
@@ -35,28 +32,66 @@ export function resolveStatusDefinition(
   if (DEFAULT_STATUS_DEFINITIONS[statusKey]) {
     return DEFAULT_STATUS_DEFINITIONS[statusKey];
   }
+
   // Fallback heuristic for unknown custom statuses:
-  const isDoneKey = ['done', 'completed', 'finished', 'closed', 'canceled', 'cancelled', 'approved', 'final'].includes(statusKey.toLowerCase());
-  const isActiveKey = ['in_progress', 'active', 'working', 'in_review', 'review'].includes(statusKey.toLowerCase());
+  const lower = statusKey.toLowerCase();
+  let category: SemanticStatus = 'not_started';
+  if (['canceled', 'cancelled', 'rejected', 'abandoned', 'void', 'dropped'].some((k) => lower.includes(k))) {
+    category = 'canceled';
+  } else if (['done', 'completed', 'finished', 'closed', 'approved', 'final', 'delivered', 'shipped'].some((k) => lower.includes(k))) {
+    category = 'completed';
+  } else if (['in_progress', 'active', 'working', 'in_review', 'review', 'testing', 'qa', 'building', 'editing'].some((k) => lower.includes(k))) {
+    category = 'in_progress';
+  }
+
   return {
     key: statusKey,
     label: statusKey,
-    completionState: isDoneKey ? 'done' : 'not_done',
-    executionState: isActiveKey ? 'active' : 'inactive',
-    isCancelled: statusKey.toLowerCase().includes('cancel')
+    category
   };
 }
 
 export function deriveTaskLifecycleState(
   task: Task,
-  customDefinitions?: StatusDefinition[],
-  referenceDate: Date = new Date()
-): TaskLifecycleState {
+  customDefinitionsOrOptions?: StatusDefinition[] | DeriveTaskLifecycleOptions,
+  legacyReferenceDate?: Date
+): TaskDerivedStatus {
+  let customDefinitions: StatusDefinition[] | undefined;
+  let referenceDate = legacyReferenceDate ?? new Date();
+  let upstreamTasks: Task[] = [];
+  let stalledThresholdDays = 5;
+
+  if (Array.isArray(customDefinitionsOrOptions)) {
+    customDefinitions = customDefinitionsOrOptions;
+  } else if (customDefinitionsOrOptions) {
+    customDefinitions = customDefinitionsOrOptions.customDefinitions;
+    if (customDefinitionsOrOptions.referenceDate) {
+      referenceDate = customDefinitionsOrOptions.referenceDate;
+    }
+    if (customDefinitionsOrOptions.upstreamTasks) {
+      upstreamTasks = customDefinitionsOrOptions.upstreamTasks;
+    }
+    if (customDefinitionsOrOptions.stalledThresholdDays !== undefined) {
+      stalledThresholdDays = customDefinitionsOrOptions.stalledThresholdDays;
+    }
+  }
+
   const def = resolveStatusDefinition(task.status, customDefinitions);
-  const isDone = def.completionState === 'done';
-  const isActive = def.executionState === 'active';
-  const isCancelled = Boolean(def.isCancelled);
+  const semanticStatus: SemanticStatus = def.category;
+  const isDone = semanticStatus === 'completed' || semanticStatus === 'canceled';
+  const isActive = semanticStatus === 'in_progress';
+  const isCancelled = semanticStatus === 'canceled';
 
+  // Dependency & Flow Indicators
+  const blockingTasks = upstreamTasks.filter((t) => {
+    const upstreamDef = resolveStatusDefinition(t.status, customDefinitions);
+    return upstreamDef.category !== 'completed';
+  });
+  const blockingTaskIds = blockingTasks.map((t) => t.id);
+  const isBlocked = !isDone && blockingTaskIds.length > 0;
+  const isReady = semanticStatus === 'not_started' && blockingTaskIds.length === 0;
+
+  // Time & Schedule Indicators
   let isOverdue = false;
   if (!isDone && task.dueDate) {
     const due = new Date(task.dueDate);
@@ -66,20 +101,71 @@ export function deriveTaskLifecycleState(
   }
 
   let isUpcoming = false;
-  if (!isDone && !isActive && task.plannedStartDate) {
+  if (semanticStatus === 'not_started' && task.plannedStartDate) {
     const plannedStart = new Date(task.plannedStartDate);
     if (!isNaN(plannedStart.getTime()) && plannedStart > referenceDate) {
       isUpcoming = true;
     }
   }
 
+  const isUnplanned = semanticStatus === 'not_started' && !task.iterationId && !task.plannedStartDate && !task.dueDate;
+
+  // Resource & Activity Indicators
+  const hasAssignee = Boolean(task.assigneeId || (task.assignees && task.assignees.length > 0));
+  const isUnassigned = !isDone && !hasAssignee;
+
+  let isStalled = false;
+  if (semanticStatus === 'in_progress') {
+    const lastActivity = task.updatedAt ? new Date(task.updatedAt) : (task.createdAt ? new Date(task.createdAt) : null);
+    if (lastActivity && !isNaN(lastActivity.getTime())) {
+      const thresholdMs = stalledThresholdDays * 24 * 60 * 60 * 1000;
+      if (referenceDate.getTime() - lastActivity.getTime() > thresholdMs) {
+        isStalled = true;
+      }
+    }
+  }
+
+  // Effort & Estimate Indicators
+  let isOverEstimate = false;
+  const loggedH = task.loggedHours ?? task.actualHours;
+  const estimatedH = task.estimatedHours;
+  if (estimatedH !== undefined && estimatedH > 0 && loggedH !== undefined && loggedH > estimatedH) {
+    isOverEstimate = true;
+  }
+  const actualM = task.actualDurationMinutes;
+  const estimatedM = task.estimatedDurationMinutes;
+  if (estimatedM !== undefined && estimatedM > 0 && actualM !== undefined && actualM > estimatedM) {
+    isOverEstimate = true;
+  }
+
+  let isPaceWarning = false;
+  if (semanticStatus === 'in_progress' && task.actualStartDate) {
+    const start = new Date(task.actualStartDate);
+    if (!isNaN(start.getTime())) {
+      const elapsedMs = referenceDate.getTime() - start.getTime();
+      const elapsedHours = elapsedMs / (1000 * 60 * 60);
+      if (estimatedH !== undefined && estimatedH > 0 && elapsedHours > estimatedH) {
+        isPaceWarning = true;
+      } else if (estimatedM !== undefined && estimatedM > 0 && (elapsedMs / (1000 * 60)) > estimatedM) {
+        isPaceWarning = true;
+      }
+    }
+  }
+
   return {
-    completionState: def.completionState,
-    executionState: def.executionState,
+    semanticStatus,
+    isReady,
+    isBlocked,
+    blockingTaskIds,
+    isOverdue,
+    isUpcoming,
+    isUnplanned,
+    isUnassigned,
+    isStalled,
+    isOverEstimate,
+    isPaceWarning,
     isDone,
     isActive,
-    isCancelled,
-    isOverdue,
-    isUpcoming
+    isCancelled
   };
 }

package/src/utils/workflow.ts

@@ -90,13 +90,13 @@ export const DEFAULT_VFX_WORKFLOW: Workflow = {
   name: 'VFX Production Workflow',
   description: 'Visual effects production pipeline from bidding and drafting to internal lead review and client supervisor approval.',
   statuses: [
-    { key: 'bidding', label: 'Bidding & Draft', completionState: 'not_done', executionState: 'inactive' },
-    { key: 'awarded', label: 'Awarded / Ready', completionState: 'not_done', executionState: 'inactive' },
-    { key: 'in_production', label: 'In Production', completionState: 'not_done', executionState: 'active' },
-    { key: 'internal_review', label: 'Internal Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'client_review', label: 'Client Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'revision_requested', label: 'Revision Requested', completionState: 'not_done', executionState: 'active' },
-    { key: 'approved', label: 'Approved (Final)', completionState: 'done', executionState: 'inactive' },
+    { key: 'bidding', label: 'Bidding & Draft', category: 'not_started' },
+    { key: 'awarded', label: 'Awarded / Ready', category: 'not_started' },
+    { key: 'in_production', label: 'In Production', category: 'in_progress' },
+    { key: 'internal_review', label: 'Internal Review', category: 'in_progress' },
+    { key: 'client_review', label: 'Client Review', category: 'in_progress' },
+    { key: 'revision_requested', label: 'Revision Requested', category: 'in_progress' },
+    { key: 'approved', label: 'Approved (Final)', category: 'completed' },
     DEFAULT_STATUS_DEFINITIONS.canceled
   ],
   transitions: [
@@ -126,14 +126,14 @@ export const DEFAULT_CREATIVE_WORKFLOW: Workflow = {
   name: 'Creative Production Workflow',
   description: 'Production pipeline for creative deliverables from briefing and concepts to internal review, client feedback, and final delivery.',
   statuses: [
-    { key: 'briefing', label: 'Briefing & Scoping', completionState: 'not_done', executionState: 'inactive' },
-    { key: 'concept', label: 'Concept & Storyboarding', completionState: 'not_done', executionState: 'active' },
-    { key: 'in_production', label: 'In Production', completionState: 'not_done', executionState: 'active' },
-    { key: 'internal_review', label: 'Internal Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'client_review', label: 'Client Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'revision_requested', label: 'Revision Requested', completionState: 'not_done', executionState: 'active' },
-    { key: 'approved', label: 'Approved', completionState: 'done', executionState: 'inactive' },
-    { key: 'delivered', label: 'Delivered', completionState: 'done', executionState: 'inactive' },
+    { key: 'briefing', label: 'Briefing & Scoping', category: 'not_started' },
+    { key: 'concept', label: 'Concept & Storyboarding', category: 'in_progress' },
+    { key: 'in_production', label: 'In Production', category: 'in_progress' },
+    { key: 'internal_review', label: 'Internal Review', category: 'in_progress' },
+    { key: 'client_review', label: 'Client Review', category: 'in_progress' },
+    { key: 'revision_requested', label: 'Revision Requested', category: 'in_progress' },
+    { key: 'approved', label: 'Approved', category: 'completed' },
+    { key: 'delivered', label: 'Delivered', category: 'completed' },
     DEFAULT_STATUS_DEFINITIONS.canceled
   ],
   transitions: [

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/use-case-validation.test.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/use-case-validation.test.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}