maskweaver 0.9.4 → 0.9.6

package/dist/shared-context/task.js

@@ -1,54 +1,10 @@
-/**
- * Task Management
- *
- * Tasks are the atomic units of work within a squad.
- * "Make the implicit explicit" - Eric Evans
- *
- * This module embodies the Task aggregate, ensuring domain invariants:
- * - A task always belongs to exactly one squad
- * - Task count per squad is bounded (LIMITS.maxTasksPerSquad)
- * - Task identity is immutable once assigned
- *
- * @author Kent Beck's Dummy Human
- */
 import { randomUUID } from "crypto";
 import { LIMITS, validateCreateTaskOptions, validateTaskResult } from "./types.js";
 import { getSquad, updateSquadState } from "./squad.js";
 import { logEvent } from "./logger.js";
 import { ValidationError, StorageError } from "../shared/errors.js";
-// ============================================================================
-// Task Assignment - The heart of work distribution
-// ============================================================================
-/**
- * Assign a new task to an agent within a squad.
- *
- * This is a domain operation that enforces invariants:
- * 1. The target squad must exist
- * 2. The squad's task capacity must not be exceeded
- * 3. Task options must be valid at the boundary
- *
- * The task starts in "pending" status, awaiting execution.
- *
- * @param session - The parent session containing the squad
- * @param squadId - ID of the squad to assign the task to
- * @param options - Task creation options (assignee, description, priority, etc.)
- * @returns The newly created TaskState
- * @throws {StorageError} If the squad doesn't exist
- * @throws {ValidationError} If task limit is exceeded or options are invalid
- *
- * @example
- * const task = await assignTask(session, "squad-a1b2c3d4", {
- *   assignee: "worker-1",
- *   description: "Implement user login form",
- *   priority: "high",
- *   dependencies: ["task-setup"]
- * });
- * console.log(`Assigned task ${task.taskId} to ${task.assignee}`);
- */
 export async function assignTask(session, squadId, options) {
-    // Validate at boundary - Parse, don't validate
     const validatedOptions = validateCreateTaskOptions(options);
-    // Retrieve the squad - domain aggregate root
     const squad = await getSquad(session, squadId);
     if (!squad) {
         throw new StorageError(`Squad not found: ${squadId}`, {
@@ -56,7 +12,6 @@ export async function assignTask(session, squadId, options) {
             sessionId: session.manifest.sessionId,
         });
     }
-    // Enforce domain invariant: task capacity
     if (squad.state.tasks.length >= LIMITS.maxTasksPerSquad) {
         throw new ValidationError("Maximum tasks per squad exceeded", {
             squadId,
@@ -64,7 +19,6 @@ export async function assignTask(session, squadId, options) {
             current: squad.state.tasks.length,
         });
     }
-    // Create the task entity with identity
     const taskId = `task-${randomUUID().slice(0, 8)}`;
     const now = new Date().toISOString();
     const task = {
@@ -76,12 +30,10 @@ export async function assignTask(session, squadId, options) {
         dependencies: validatedOptions.dependencies,
         createdAt: now,
     };
-    // Update squad aggregate - append task to collection
     const updatedTasks = [...squad.state.tasks, task];
     await updateSquadState(session, squadId, {
         tasks: updatedTasks,
     });
-    // Emit domain event for observability
     await logEvent(session, squadId, {
         type: "task_assigned",
         taskId: task.taskId,
@@ -90,29 +42,7 @@ export async function assignTask(session, squadId, options) {
     });
     return task;
 }
-// ============================================================================
-// Task Query - Domain Entity Lookup
-// ============================================================================
-/**
- * Get a specific task from a squad by taskId.
- *
- * "Make implicit concepts explicit" - Eric Evans
- * Task lookup is a first-class domain operation, not hidden in aggregate traversal.
- *
- * @param session - Parent session
- * @param squadId - Squad containing the task
- * @param taskId - Task ID to find
- * @returns TaskState or null if not found (no error thrown for missing task)
- * @throws {StorageError} If the squad doesn't exist
- *
- * @example
- * const task = await getTask(session, "squad-a1b2c3d4", "task-12345678");
- * if (task) {
- *   console.log(`Task ${task.taskId} is ${task.status}`);
- * }
- */
 export async function getTask(session, squadId, taskId) {
-    // Retrieve the squad aggregate
     const squad = await getSquad(session, squadId);
     if (!squad) {
         throw new StorageError(`Squad not found: ${squadId}`, {
@@ -120,45 +50,10 @@ export async function getTask(session, squadId, taskId) {
             sessionId: session.manifest.sessionId,
         });
     }
-    // Search for task within the squad's task collection
     const task = squad.state.tasks.find((t) => t.taskId === taskId);
-    // Return null for not found (expected case, not an error)
     return task ?? null;
 }
-// ============================================================================
-// Task Update - State Transition through Aggregate Root
-// ============================================================================
-/**
- * Update a task's status and optionally record progress.
- * This is the primary way to advance task lifecycle.
- *
- * DDD Principle: All state mutations go through the Aggregate Root (Squad).
- * "Make implicit concepts explicit" - Eric Evans
- *
- * @param session - Parent session
- * @param squadId - Squad containing the task
- * @param taskId - Task to update
- * @param updates - Partial updates (status, result, etc.)
- * @returns Updated TaskState
- * @throws {StorageError} If squad or task not found
- *
- * @example
- * // Start a task
- * const updated = await updateTask(session, squadId, taskId, {
- *   status: "active",
- *   startedAt: new Date().toISOString()
- * });
- *
- * @example
- * // Complete a task with result
- * const completed = await updateTask(session, squadId, taskId, {
- *   status: "completed",
- *   completedAt: new Date().toISOString(),
- *   result: { success: true, output: "Feature implemented" }
- * });
- */
 export async function updateTask(session, squadId, taskId, updates) {
-    // Retrieve the squad aggregate root
     const squad = await getSquad(session, squadId);
     if (!squad) {
         throw new StorageError(`Squad not found: ${squadId}`, {
@@ -166,7 +61,6 @@ export async function updateTask(session, squadId, taskId, updates) {
             sessionId: session.manifest.sessionId,
         });
     }
-    // Find the task within the aggregate
     const taskIndex = squad.state.tasks.findIndex((t) => t.taskId === taskId);
     if (taskIndex === -1) {
         throw new StorageError(`Task not found: ${taskId}`, {
@@ -177,19 +71,15 @@ export async function updateTask(session, squadId, taskId, updates) {
     }
     const existingTask = squad.state.tasks[taskIndex];
     const previousStatus = existingTask.status;
-    // Apply updates via spread - immutable update pattern
     const updatedTask = {
         ...existingTask,
         ...updates,
     };
-    // Update the tasks array immutably
     const updatedTasks = [...squad.state.tasks];
     updatedTasks[taskIndex] = updatedTask;
-    // Persist through aggregate root
     await updateSquadState(session, squadId, {
         tasks: updatedTasks,
     });
-    // Log status change as domain event (only if status actually changed)
     if (updates.status && updates.status !== previousStatus) {
         if (updates.status === "completed") {
             await logEvent(session, squadId, {
@@ -200,8 +90,6 @@ export async function updateTask(session, squadId, taskId, updates) {
             });
         }
         else {
-            // Generic status change - use error event type for now
-            // (Could extend LogEvent union for task_status_changed)
             await logEvent(session, squadId, {
                 type: "error",
                 message: `Task ${taskId} status changed: ${previousStatus} -> ${updates.status}`,
@@ -210,49 +98,9 @@ export async function updateTask(session, squadId, taskId, updates) {
     }
     return updatedTask;
 }
-// ============================================================================
-// Task Completion - Explicit Domain Operation
-// ============================================================================
-/**
- * Complete a task with a result.
- *
- * "Make implicit concepts explicit" - Eric Evans
- * Task completion is a first-class domain operation with its own semantics.
- *
- * This is a convenience wrapper around updateTask() that:
- * - Validates the TaskResult at the boundary
- * - Sets the appropriate status based on result.success
- * - Records completedAt timestamp
- *
- * @param session - Parent session
- * @param squadId - Squad containing the task
- * @param taskId - Task to complete
- * @param result - TaskResult with success/failure info
- * @returns Updated TaskState
- * @throws {StorageError} If squad or task not found
- * @throws {ValidationError} If result is invalid
- *
- * @example
- * // Success case
- * const completed = await completeTask(session, squadId, taskId, {
- *   success: true,
- *   output: { files: ["src/auth/login.ts"] },
- *   metrics: { duration: 45000, tokensUsed: 1500 }
- * });
- *
- * @example
- * // Failure case
- * const failed = await completeTask(session, squadId, taskId, {
- *   success: false,
- *   error: { code: "TIMEOUT", message: "Task exceeded timeout" }
- * });
- */
 export async function completeTask(session, squadId, taskId, result) {
-    // Validate at boundary
     const validatedResult = validateTaskResult(result);
-    // Determine status from result
     const status = validatedResult.success ? "completed" : "failed";
-    // Delegate to updateTask with appropriate fields
     return updateTask(session, squadId, taskId, {
         status,
         completedAt: new Date().toISOString(),

package/dist/shared-context/test/dag.test.js

@@ -1,8 +1,6 @@
-// src/shared-context/test/dag.test.ts
 import { describe, test, expect } from 'vitest';
 import { buildDAG, getReadyTasks, areDependenciesMet, validateDependencies, } from '../dag.js';
 import { ValidationError } from '../../shared/errors.js';
-// Helper to create a TaskState object for tests
 const createTask = (taskId, dependencies = [], status = 'pending', priority = 'medium') => ({
     taskId,
     assignee: 'test-assignee',
@@ -25,7 +23,7 @@ describe('DAG Module', () => {
             expect(dag.waves).toEqual([
                 { waveIndex: 0, taskIds: ['A', 'B', 'C'].sort() },
             ]);
-            expect(dag.criticalPath.length).toBe(1); // Any single task is critical path
+            expect(dag.criticalPath.length).toBe(1);
             expect(dag.parallelismFactor).toBeCloseTo(3);
         });
         test('should correctly build DAG for linear dependencies (A->B->C)', () => {
@@ -58,16 +56,15 @@ describe('DAG Module', () => {
                 { waveIndex: 1, taskIds: ['B', 'C'].sort() },
                 { waveIndex: 2, taskIds: ['D'] },
             ]);
-            // Critical path can be A->B->D or A->C->D, both have length 3
             expect(dag.criticalPath.length).toBe(3);
             expect(dag.criticalPath[0]).toBe('A');
             expect(['B', 'C']).toContain(dag.criticalPath[1]);
             expect(dag.criticalPath[2]).toBe('D');
-            expect(dag.parallelismFactor).toBeCloseTo(4 / 3); // 4 tasks / 3 waves
+            expect(dag.parallelismFactor).toBeCloseTo(4 / 3);
         });
         test('should detect a cycle and throw ValidationError (A->B->C->A)', () => {
             const tasks = [
-                createTask('A', ['C']), // A depends on C
+                createTask('A', ['C']),
                 createTask('B', ['A']),
                 createTask('C', ['B']),
             ];
@@ -100,7 +97,7 @@ describe('DAG Module', () => {
         test('should throw ValidationError for dangling dependencies', () => {
             const tasks = [
                 createTask('A'),
-                createTask('B', ['X']), // X does not exist
+                createTask('B', ['X']),
             ];
             expect(() => buildDAG(tasks)).toThrow(ValidationError);
             expect(() => buildDAG(tasks)).toThrow("Invalid dependencies: Task B depends on non-existent task X");
@@ -120,8 +117,8 @@ describe('DAG Module', () => {
                 { waveIndex: 1, taskIds: ['B', 'D'].sort() },
                 { waveIndex: 2, taskIds: ['E'] },
             ]);
-            expect(dag.criticalPath.length).toBe(3); // A->B->E or C->D->E
-            expect(dag.criticalPath[0]).toBe('A'); // or C
+            expect(dag.criticalPath.length).toBe(3);
+            expect(dag.criticalPath[0]).toBe('A');
             expect(['B', 'D']).toContain(dag.criticalPath[1]);
             expect(dag.criticalPath[2]).toBe('E');
             expect(dag.parallelismFactor).toBeCloseTo(5 / 3);
@@ -216,11 +213,9 @@ describe('DAG Module', () => {
         test('should return false if a dependency does not exist (handled by validateDependencies)', () => {
             const tasks = [
                 createTask('A', [], 'completed'),
-                createTask('C', ['A', 'X']), // X does not exist
+                createTask('C', ['A', 'X']),
             ];
             const taskC = tasks[1];
-            // This function assumes valid dependencies. If a dependency is missing,
-            // find will return undefined, and (undefined && undefined.status === 'completed') will be false.
             expect(areDependenciesMet(taskC, tasks)).toBe(false);
         });
     });
@@ -247,8 +242,8 @@ describe('DAG Module', () => {
         test('should return valid false and errors for tasks with non-existent dependencies', () => {
             const tasks = [
                 createTask('A'),
-                createTask('B', ['A', 'X']), // X does not exist
-                createTask('C', ['Y']), // Y does not exist
+                createTask('B', ['A', 'X']),
+                createTask('C', ['Y']),
             ];
             const result = validateDependencies(tasks);
             expect(result.valid).toBe(false);

package/dist/shared-context/test/logger.test.d.ts

@@ -1,9 +1 @@
-/**
- * Logger Unit Tests
- *
- * Tests for logEvent and readLog functions
- * Following Red-Green-Refactor cycle
- *
- * @author Kent Beck's TDD Approach
- */
 export {};

package/dist/shared-context/test/logger.test.js

@@ -1,11 +1,3 @@
-/**
- * Logger Unit Tests
- *
- * Tests for logEvent and readLog functions
- * Following Red-Green-Refactor cycle
- *
- * @author Kent Beck's TDD Approach
- */
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -14,26 +6,18 @@ import { existsSync } from "fs";
 import { logEvent, readLog } from "../logger.js";
 import { FileStorageAdapter } from "../storage.js";
 import { createSession } from "../session.js";
-// ============================================================================
-// Test Setup
-// ============================================================================
 let tempDir;
 let storage;
 beforeEach(async () => {
-    // Create unique temp directory for each test
     tempDir = join(tmpdir(), `logger-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
     await mkdir(tempDir, { recursive: true });
     storage = new FileStorageAdapter(tempDir);
 });
 afterEach(async () => {
-    // Clean up temp directory
     if (existsSync(tempDir)) {
         await rm(tempDir, { recursive: true, force: true });
     }
 });
-// ============================================================================
-// Helper Functions
-// ============================================================================
 async function createTestSession() {
     return createSession(storage, {
         goal: "Test goal",
@@ -41,35 +25,26 @@ async function createTestSession() {
     });
 }
 async function createSquadDir(session, squadId) {
-    // Use mkdir directly with absolute path to avoid ensureDir's path handling issues
     const fullPath = storage.getFullPath(`${session.sessionPath}/squads/${squadId}`);
     await mkdir(fullPath, { recursive: true });
 }
-// ============================================================================
-// logEvent Tests
-// ============================================================================
 describe("logEvent", () => {
     test("should create log.jsonl file after logging an event", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-001";
         await createSquadDir(session, squadId);
-        // Act
         await logEvent(session, squadId, {
             type: "squad_started",
             squadId,
             operator: "operator-agent",
         });
-        // Assert
         const logPath = storage.getFullPath(`${session.sessionPath}/squads/${squadId}/log.jsonl`);
         expect(existsSync(logPath)).toBe(true);
     });
     test("should append multiple events in order", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-002";
         await createSquadDir(session, squadId);
-        // Act - Log three events
         await logEvent(session, squadId, {
             type: "squad_started",
             squadId,
@@ -87,7 +62,6 @@ describe("logEvent", () => {
             assignee: "worker-agent",
             result: { success: true },
         });
-        // Assert - Read and verify order
         const events = await readLog(session, squadId);
         expect(events).toHaveLength(3);
         expect(events[0].type).toBe("squad_started");
@@ -95,39 +69,32 @@ describe("logEvent", () => {
         expect(events[2].type).toBe("task_completed");
     });
     test("should auto-generate ts field with ISO timestamp", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-003";
         await createSquadDir(session, squadId);
         const beforeTime = new Date().toISOString();
-        // Act
         await logEvent(session, squadId, {
             type: "error",
             message: "Something went wrong",
             source: "test-agent",
         });
         const afterTime = new Date().toISOString();
-        // Assert
         const events = await readLog(session, squadId);
         expect(events).toHaveLength(1);
         expect(events[0].ts).toBeDefined();
         expect(typeof events[0].ts).toBe("string");
-        // Verify ts is between before and after
         expect(events[0].ts >= beforeTime).toBe(true);
         expect(events[0].ts <= afterTime).toBe(true);
     });
     test("should preserve all event properties", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-004";
         await createSquadDir(session, squadId);
-        // Act
         await logEvent(session, squadId, {
             type: "context_updated",
             key: "shared-data",
             updatedBy: "agent-x",
         });
-        // Assert
         const events = await readLog(session, squadId);
         expect(events).toHaveLength(1);
         const event = events[0];
@@ -136,16 +103,11 @@ describe("logEvent", () => {
         expect(event.updatedBy).toBe("agent-x");
     });
 });
-// ============================================================================
-// readLog Tests
-// ============================================================================
 describe("readLog", () => {
     test("should return all logged events", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-005";
         await createSquadDir(session, squadId);
-        // Log events
         await logEvent(session, squadId, {
             type: "squad_started",
             squadId,
@@ -156,42 +118,30 @@ describe("readLog", () => {
             squadId,
             finalStatus: "completed",
         });
-        // Act
         const events = await readLog(session, squadId);
-        // Assert
         expect(events).toHaveLength(2);
         expect(events[0].type).toBe("squad_started");
         expect(events[1].type).toBe("squad_completed");
     });
     test("should return empty array for empty log", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-006";
         await createSquadDir(session, squadId);
-        // Create an empty log file
         const logPath = `${session.sessionPath}/squads/${squadId}/log.jsonl`;
         await writeFile(storage.getFullPath(logPath), "");
-        // Act
         const events = await readLog(session, squadId);
-        // Assert
         expect(events).toEqual([]);
     });
     test("should return empty array when log file does not exist", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "nonexistent-squad";
-        // Intentionally NOT creating the squad directory
-        // Act
         const events = await readLog(session, squadId);
-        // Assert
         expect(events).toEqual([]);
     });
     test("should correctly parse all LogEvent types", async () => {
-        // Arrange
         const session = await createTestSession();
         const squadId = "squad-007";
         await createSquadDir(session, squadId);
-        // Log all event types
         await logEvent(session, squadId, {
             type: "squad_started",
             squadId,
@@ -222,9 +172,7 @@ describe("readLog", () => {
             type: "error",
             message: "Oops",
         });
-        // Act
         const events = await readLog(session, squadId);
-        // Assert
         expect(events).toHaveLength(6);
         expect(events.map((e) => e.type)).toEqual([
             "squad_started",

package/dist/shared-context/test/session.test.d.ts

@@ -1,8 +1 @@
-/**
- * Session Management Tests
- *
- * "Make it work, make it right, make it fast." - Kent Beck
- *
- * Red-Green-Refactor cycle for session.ts
- */
 export {};