@critical-path/core 0.17.0 → 0.19.0

package/src/store/sqlite.ts

@@ -132,6 +132,8 @@ export class SQLiteStore implements StorageAdapter {
         actualDurationMinutes REAL,
         billableDurationMinutes REAL,
         progress REAL,
+        isBlocked INTEGER,
+        blockedReason TEXT,
         tags TEXT,
         customFields TEXT,
         parentId TEXT,
@@ -659,8 +661,9 @@ export class SQLiteStore implements StorageAdapter {
         reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate,
         dueDate, estimatedHours, loggedHours, actualHours, billableHours,
         estimatedDurationMinutes, actualDurationMinutes, billableDurationMinutes, progress,
+        isBlocked, blockedReason,
         tags, customFields, parentId, createdAt, updatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTask.id,
@@ -690,6 +693,8 @@ export class SQLiteStore implements StorageAdapter {
       newTask.actualDurationMinutes ?? null,
       newTask.billableDurationMinutes ?? null,
       newTask.progress ?? null,
+      newTask.isBlocked !== undefined ? (newTask.isBlocked ? 1 : 0) : null,
+      newTask.blockedReason ?? null,
       JSON.stringify(newTask.tags || []),
       JSON.stringify(newTask.customFields || {}),
       newTask.parentId || null,
@@ -716,6 +721,7 @@ export class SQLiteStore implements StorageAdapter {
         plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, dueDate = ?,
         estimatedHours = ?, loggedHours = ?, actualHours = ?, billableHours = ?,
         estimatedDurationMinutes = ?, actualDurationMinutes = ?, billableDurationMinutes = ?, progress = ?,
+        isBlocked = ?, blockedReason = ?,
         tags = ?, customFields = ?, parentId = ?, updatedAt = ?
       WHERE id = ?
     `);
@@ -746,6 +752,8 @@ export class SQLiteStore implements StorageAdapter {
       updated.actualDurationMinutes ?? null,
       updated.billableDurationMinutes ?? null,
       updated.progress ?? null,
+      updated.isBlocked !== undefined ? (updated.isBlocked ? 1 : 0) : null,
+      updated.blockedReason ?? null,
       JSON.stringify(updated.tags || []),
       JSON.stringify(updated.customFields || {}),
       updated.parentId || null,
@@ -1188,6 +1196,8 @@ export class SQLiteStore implements StorageAdapter {
   private mapTask(row: any): Task {
     return {
       ...row,
+      isBlocked: row.isBlocked !== null && row.isBlocked !== undefined ? Boolean(row.isBlocked) : undefined,
+      blockedReason: row.blockedReason || undefined,
       taskType: row.taskType || undefined,
       deliverableId: row.deliverableId || undefined,
       tags: row.tags ? JSON.parse(row.tags) : [],

package/src/task-state.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { CriticalPathEngine } from './engine/index.js';
 import { deriveTaskLifecycleState } from './utils/status.js';
-import type { Task, StatusDefinition, TaskUnblockedEvent } from './index.js';
+import type { Task, StatusDefinition, TaskBlockedEvent, TaskUnblockedEvent } from './index.js';
 
 describe('Task State Behaviour & Dependency Validation', () => {
   const baseTask: Task = {
@@ -443,5 +443,64 @@ describe('Task State Behaviour & Dependency Validation', () => {
       expect(lifecycle?.isBlocked).toBe(false);
       expect(lifecycle?.isReady).toBe(true);
     });
+
+    it('manages first-class isBlocked and blockedReason independently of workflow status', async () => {
+      const engine = new CriticalPathEngine();
+      const project = await engine.createProject({ key: 'BLOCK', name: 'First Class Blocking' });
+
+      const blockedEvents: TaskBlockedEvent[] = [];
+      const unblockedEvents: TaskUnblockedEvent[] = [];
+      engine.events.subscribe<TaskBlockedEvent>('task.blocked', (evt) => {
+        blockedEvents.push(evt);
+      });
+      engine.events.subscribe<TaskUnblockedEvent>('task.unblocked', (evt) => {
+        unblockedEvents.push(evt);
+      });
+
+      // 1. Create a task in 'in_progress' status
+      const task = await engine.createTask({
+        projectId: project.id,
+        title: 'Work on feature',
+        status: 'in_progress'
+      });
+
+      let lifecycle = await engine.getTaskLifecycleState(task.id);
+      expect(lifecycle?.isBlocked).toBe(false);
+
+      // 2. Explicitly block the task while keeping status in_progress
+      const blockedTask = await engine.updateTask(task.id, {
+        isBlocked: true,
+        blockedReason: 'Awaiting third-party API key'
+      });
+      expect(blockedTask?.isBlocked).toBe(true);
+      expect(blockedTask?.blockedReason).toBe('Awaiting third-party API key');
+      expect(blockedTask?.status).toBe('in_progress');
+
+      // Verify domain event
+      expect(blockedEvents).toHaveLength(1);
+      expect(blockedEvents[0].aggregateId).toBe(task.id);
+      expect(blockedEvents[0].payload.reason).toBe('Awaiting third-party API key');
+
+      // Verify lifecycle state
+      lifecycle = await engine.getTaskLifecycleState(task.id);
+      expect(lifecycle?.isBlocked).toBe(true);
+      expect(lifecycle?.isReady).toBe(false);
+
+      // 3. Unblock the task
+      const unblockedTask = await engine.updateTask(task.id, {
+        isBlocked: false,
+        blockedReason: null
+      });
+      expect(unblockedTask?.isBlocked).toBe(false);
+      expect(unblockedTask?.blockedReason).toBeNull();
+      expect(unblockedTask?.status).toBe('in_progress');
+
+      // Verify domain event
+      expect(unblockedEvents).toHaveLength(1);
+      expect(unblockedEvents[0].aggregateId).toBe(task.id);
+
+      lifecycle = await engine.getTaskLifecycleState(task.id);
+      expect(lifecycle?.isBlocked).toBe(false);
+    });
   });
 });

package/src/types/index.ts

@@ -33,12 +33,40 @@ export type TaskLifecycleState = TaskDerivedStatus;
 
 export type Role = 'admin' | 'project_manager' | 'contributor' | 'viewer';
 
+export interface WorkingHoursRange {
+  start: string; // "09:00" (HH:MM 24-hour format)
+  end: string;   // "17:00"
+}
+
+export interface DaySchedule {
+  dayOfWeek: number; // 0 = Sunday, 1 = Monday, ..., 6 = Saturday
+  isWorkingDay: boolean;
+  hours?: WorkingHoursRange[];
+}
+
+export interface Holiday {
+  date: string; // "YYYY-MM-DD"
+  name?: string;
+  halfDay?: boolean; // if true, counts as 50% working hours
+}
+
+export interface WorkSchedule {
+  id?: string;
+  name?: string;
+  timezone?: string; // Informational (e.g. "UTC", "America/New_York")
+  defaultHoursPerDay?: number; // Default: 8
+  days: DaySchedule[];
+  holidays?: Holiday[];
+}
+
 export interface User {
   id: string;
   name: string;
   email: string;
   avatarUrl?: string;
   role: Role;
+  weeklyCapacityHours?: number;
+  schedule?: WorkSchedule;
   createdAt: string;
 }
 
@@ -48,6 +76,8 @@ export interface Team {
   description?: string;
   leaderId?: string;
   memberIds: string[];
+  weeklyCapacityHours?: number;
+  schedule?: WorkSchedule;
   createdAt: string;
   updatedAt: string;
 }
@@ -105,6 +135,9 @@ export interface Project {
   statusDefinitions?: StatusDefinition[];
   priorityDefinitions?: Array<{ key: string; label: string; level?: number }>;
   customFieldDefinitions?: CustomFieldDefinition[];
+  schedule?: WorkSchedule;
+  startDate?: string;
+  targetEndDate?: string;
   createdAt: string;
   updatedAt: string;
 }
@@ -183,6 +216,8 @@ export interface Task {
   billableDurationMinutes?: number;
   // Progress (0 to 100 percentage)
   progress?: number;
+  isBlocked?: boolean;
+  blockedReason?: string | null;
   tags?: string[];
   todos?: TaskTodoItem[];
   customFields?: Record<string, unknown>;
@@ -369,6 +404,7 @@ export type WebhookEvent =
   | 'task.updated'
   | 'task.deleted'
   | 'task.status_changed'
+  | 'task.blocked'
   | 'task.unblocked'
   | 'comment.created'
   | 'comment.updated'
@@ -413,6 +449,7 @@ export interface CriticalPathConfig {
   fileStorage?: FileStorageAdapter;
   plugins?: CriticalPathPlugin[];
   webhooks?: Omit<Webhook, 'id' | 'createdAt'>[];
+  defaultSchedule?: WorkSchedule;
   initialData?: {
     projects?: Project[];
     tasks?: Task[];
@@ -481,12 +518,21 @@ export interface TaskCriticalPathSchedule {
   lateFinish: number;
   totalSlack: number;
   isCritical: boolean;
+  durationHours?: number;
+  earlyStartDate?: string;
+  earlyFinishDate?: string;
+  lateStartDate?: string;
+  lateFinishDate?: string;
+  slackWorkingHours?: number;
 }
 
 export interface CriticalPathAnalysis {
   projectId: string;
   calculatedAt: string;
   totalDurationHours: number;
+  totalWorkingHours?: number;
+  projectStartDate?: string;
+  projectEndDate?: string;
   criticalTaskIds: string[];
   tasks: TaskCriticalPathSchedule[];
 }
@@ -521,6 +567,7 @@ export interface RealityDelta {
   effortVarianceHours?: number; // loggedHours - estimatedHours (effort variance)
   durationVarianceHours?: number; // actual duration hours - planned duration hours
   scheduleVarianceDays?: number; // days difference between planned/due vs actual
+  scheduleVarianceWorkingDays?: number; // working days difference between planned/due vs actual
   accuracyRatio?: number; // loggedHours / estimatedHours (estimation accuracy ratio)
   isOverdue: boolean;
   isOverEstimate: boolean;
@@ -630,3 +677,45 @@ export interface TaskLadderView {
   metrics?: TaskMetrics;
 }
 
+export type WorkloadInterval = 'day' | 'week' | 'month';
+export type WorkloadGroupBy = 'assignee' | 'team' | 'taskType' | 'priority' | 'status';
+export type WorkloadMetric = 'scheduled' | 'logged' | 'remaining' | 'blended';
+
+export interface WorkloadBucket {
+  date: string; // ISO date string e.g. "2026-09-14" (start of bucket)
+  timestamp: number; // Unix timestamp in ms
+  totalHours: number;
+  values: Record<string, number>; // Dimension key to hours: { [dimensionKey]: hours }
+  capacity?: Record<string, number>; // Dimension key to available capacity hours: { [dimensionKey]: capacityHours }
+  totalCapacity?: number;
+  utilizationRatio?: number; // totalHours / totalCapacity
+}
+
+export interface WorkloadDistribution {
+  projectId?: string;
+  startDate: string;
+  endDate: string;
+  interval: WorkloadInterval;
+  groupBy: WorkloadGroupBy;
+  metric: WorkloadMetric;
+  seriesKeys: string[]; // Unique series keys sorted across all buckets
+  seriesLabels: Record<string, string>; // Human-readable labels e.g. { [key]: "Alice" }
+  buckets: WorkloadBucket[];
+  totalHours: number;
+  totalCapacity?: number;
+  averageUtilization?: number;
+}
+
+export interface WorkloadDistributionOptions {
+  startDate?: string;
+  endDate?: string;
+  interval?: WorkloadInterval; // default: 'week'
+  groupBy?: WorkloadGroupBy; // default: 'assignee'
+  metric?: WorkloadMetric; // default: 'blended'
+  defaultWeeklyCapacityHours?: number; // default: 40
+  capacityOverrides?: Record<string, number>; // e.g. { [assigneeOrTeamId]: weeklyCapacityHours }
+  schedule?: WorkSchedule;
+  userSchedules?: Record<string, WorkSchedule>;
+  teamSchedules?: Record<string, WorkSchedule>;
+}
+

package/src/utils/status.ts

@@ -88,8 +88,13 @@ export function deriveTaskLifecycleState(
     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;
+  const isExplicitlyBlocked = Boolean(
+    task.isBlocked === true ||
+    task.customFields?.isBlocked === true ||
+    task.status === 'blocked'
+  );
+  const isBlocked = !isDone && (blockingTaskIds.length > 0 || isExplicitlyBlocked);
+  const isReady = semanticStatus === 'not_started' && !isBlocked;
 
   // Time & Schedule Indicators
   let isOverdue = false;

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/cpm.test.ts","./src/domain/cpm.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/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.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/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.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/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/workload.test.ts","./src/domain/workload.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"}