maskweaver 0.9.4 → 0.9.6

package/dist/shared-context/storage.d.ts

@@ -1,158 +1,26 @@
-/**
- * Storage Adapter
- *
- * File-based storage with abstraction for future database migration.
- * Implements atomic writes and path traversal prevention.
- *
- * @author Kent Beck's Dummy Human
- */
-/**
- * Options for acquiring a file lock.
- *
- * Distributed lock semantics:
- * - timeout: How long to wait for lock acquisition before giving up
- * - stale: Duration after which an unreleased lock is considered abandoned
- * - retries: Number of acquisition attempts with exponential backoff
- *
- * @example
- * // Conservative settings for critical sections
- * const opts: LockOptions = { timeout: 10000, stale: 60000, retries: 5 };
- */
 export interface LockOptions {
-    /** Lock acquisition timeout in milliseconds (default: 5000) */
     timeout?: number;
-    /** Time after which lock is considered stale and can be stolen (default: 30000) */
     stale?: number;
-    /** Number of retry attempts (default: 3) */
     retries?: number;
 }
-/**
- * Abstract storage interface for data persistence.
- * Enables swapping file storage with database or cloud storage.
- */
 export interface StorageAdapter {
-    /** Read and parse JSON data from the given path */
     read<T>(path: string): Promise<T | null>;
-    /** Write data as JSON to the given path (atomic) */
     write<T>(path: string, data: T): Promise<void>;
-    /** Append a line to the given file */
     append(path: string, line: string): Promise<void>;
-    /** Check if a path exists */
     exists(path: string): boolean;
-    /** Ensure a directory exists, creating it if necessary */
     ensureDir(path: string): Promise<void>;
-    /** Get the absolute path for a relative storage path */
     getFullPath(path: string): string;
-    /**
-     * Acquire an exclusive lock on a file path.
-     * Returns an unlock function that MUST be called to release the lock.
-     *
-     * Correctness guarantees:
-     * - Mutual exclusion: Only one holder at a time
-     * - Stale lock detection: Abandoned locks are automatically reclaimable
-     * - Fencing: Use returned unlock function within try/finally
-     *
-     * @param path - Relative path to lock
-     * @param options - Lock behavior options
-     * @returns Unlock function - call to release the lock
-     * @throws {StorageError} If lock cannot be acquired within timeout
-     *
-     * @example
-     * const unlock = await storage.lock("state.json", { timeout: 5000 });
-     * try {
-     *   const data = await storage.read("state.json");
-     *   await storage.write("state.json", { ...data, updated: true });
-     * } finally {
-     *   await unlock();
-     * }
-     */
     lock(path: string, options?: LockOptions): Promise<() => Promise<void>>;
 }
-/**
- * Validate that a path is within the allowed base directory.
- * Prevents path traversal attacks (e.g., "../../../etc/passwd").
- *
- * @param fullPath - The full path to validate
- * @param baseDir - The base directory that should contain the path
- * @returns True if the path is safe and within baseDir
- *
- * @example
- * validatePath("/data/sessions/abc/file.json", "/data/sessions"); // true
- * validatePath("/data/../etc/passwd", "/data/sessions"); // false
- */
 export declare function validatePath(fullPath: string, baseDir: string): boolean;
-/**
- * File-based implementation of the StorageAdapter interface.
- * All paths are relative to the baseDir and validated for security.
- *
- * @example
- * const storage = new FileStorageAdapter("/data/sessions");
- * await storage.write("session-1/manifest.json", { id: "session-1" });
- * const data = await storage.read("session-1/manifest.json");
- */
 export declare class FileStorageAdapter implements StorageAdapter {
     private readonly baseDir;
-    /**
-     * Create a new file storage adapter.
-     *
-     * @param baseDir - The root directory for all storage operations
-     */
     constructor(baseDir: string);
-    /**
-     * Read and parse a JSON file from storage.
-     *
-     * @param path - Relative path within baseDir
-     * @returns Parsed JSON data, or null if file doesn't exist
-     * @throws {ValidationError} If path escapes baseDir
-     * @throws {StorageError} If file read or parse fails
-     */
     read<T>(path: string): Promise<T | null>;
-    /**
-     * Write data to storage as formatted JSON (atomic operation).
-     *
-     * @param path - Relative path within baseDir
-     * @param data - Data to serialize and write
-     * @throws {ValidationError} If path escapes baseDir
-     * @throws {StorageError} If write fails
-     */
     write<T>(path: string, data: T): Promise<void>;
-    /**
-     * Append a line to a file (for log files).
-     *
-     * @param path - Relative path within baseDir
-     * @param line - Line to append (newline added automatically)
-     * @throws {ValidationError} If path escapes baseDir
-     * @throws {StorageError} If append fails
-     */
     append(path: string, line: string): Promise<void>;
-    /**
-     * Check if a path exists in storage.
-     *
-     * @param path - Relative path within baseDir
-     * @returns True if the path exists
-     */
     exists(path: string): boolean;
-    /**
-     * Get the absolute filesystem path for a relative storage path.
-     *
-     * @param path - Relative path within baseDir
-     * @returns Absolute filesystem path
-     */
     getFullPath(path: string): string;
-    /**
-     * Ensure a directory exists, creating it recursively if necessary.
-     *
-     * @param path - Relative directory path within baseDir
-     */
     ensureDir(path: string): Promise<void>;
-    /**
-     * Acquire an exclusive lock on a file path.
-     * Uses .lock files with PID tracking for stale lock detection.
-     *
-     * @param path - Relative path to lock
-     * @param options - Lock behavior options
-     * @returns Unlock function that MUST be called to release
-     * @throws {StorageError} If lock cannot be acquired within timeout
-     */
     lock(path: string, options?: LockOptions): Promise<() => Promise<void>>;
 }

package/dist/shared-context/storage.js

@@ -1,19 +1,8 @@
-/**
- * Storage Adapter
- *
- * File-based storage with abstraction for future database migration.
- * Implements atomic writes and path traversal prevention.
- *
- * @author Kent Beck's Dummy Human
- */
 import { join, resolve } from "path";
 import { mkdir, rename, readFile, appendFile, writeFile, unlink } from "fs/promises";
 import { existsSync } from "fs";
 import { StorageError, ValidationError } from "../shared/errors.js";
 import { LIMITS } from "./types.js";
-/**
- * Check if a process is still running.
- */
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -23,74 +12,24 @@ function isProcessAlive(pid) {
         return false;
     }
 }
-/**
- * Sleep for specified milliseconds.
- */
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-// ============================================================================
-// Path Validation
-// ============================================================================
-/**
- * Validate that a path is within the allowed base directory.
- * Prevents path traversal attacks (e.g., "../../../etc/passwd").
- *
- * @param fullPath - The full path to validate
- * @param baseDir - The base directory that should contain the path
- * @returns True if the path is safe and within baseDir
- *
- * @example
- * validatePath("/data/sessions/abc/file.json", "/data/sessions"); // true
- * validatePath("/data/../etc/passwd", "/data/sessions"); // false
- */
 export function validatePath(fullPath, baseDir) {
     const resolvedFull = resolve(fullPath);
     const resolvedBase = resolve(baseDir);
     return resolvedFull.startsWith(resolvedBase) && !fullPath.includes("..");
 }
-// ============================================================================
-// Atomic Write Helper
-// ============================================================================
-/**
- * Write data atomically by first writing to a temp file then renaming.
- * Prevents partial writes and data corruption on crash.
- */
 async function atomicWrite(filePath, data) {
     const tempPath = `${filePath}.tmp.${Date.now()}`;
     await writeFile(tempPath, data, "utf-8");
     await rename(tempPath, filePath);
 }
-// ============================================================================
-// File Storage Adapter
-// ============================================================================
-/**
- * File-based implementation of the StorageAdapter interface.
- * All paths are relative to the baseDir and validated for security.
- *
- * @example
- * const storage = new FileStorageAdapter("/data/sessions");
- * await storage.write("session-1/manifest.json", { id: "session-1" });
- * const data = await storage.read("session-1/manifest.json");
- */
 export class FileStorageAdapter {
     baseDir;
-    /**
-     * Create a new file storage adapter.
-     *
-     * @param baseDir - The root directory for all storage operations
-     */
     constructor(baseDir) {
         this.baseDir = baseDir;
     }
-    /**
-     * Read and parse a JSON file from storage.
-     *
-     * @param path - Relative path within baseDir
-     * @returns Parsed JSON data, or null if file doesn't exist
-     * @throws {ValidationError} If path escapes baseDir
-     * @throws {StorageError} If file read or parse fails
-     */
     async read(path) {
         const fullPath = join(this.baseDir, path);
         if (!validatePath(fullPath, this.baseDir)) {
@@ -114,14 +53,6 @@ export class FileStorageAdapter {
             });
         }
     }
-    /**
-     * Write data to storage as formatted JSON (atomic operation).
-     *
-     * @param path - Relative path within baseDir
-     * @param data - Data to serialize and write
-     * @throws {ValidationError} If path escapes baseDir
-     * @throws {StorageError} If write fails
-     */
     async write(path, data) {
         const fullPath = join(this.baseDir, path);
         if (!validatePath(fullPath, this.baseDir)) {
@@ -143,14 +74,6 @@ export class FileStorageAdapter {
             });
         }
     }
-    /**
-     * Append a line to a file (for log files).
-     *
-     * @param path - Relative path within baseDir
-     * @param line - Line to append (newline added automatically)
-     * @throws {ValidationError} If path escapes baseDir
-     * @throws {StorageError} If append fails
-     */
     async append(path, line) {
         const fullPath = join(this.baseDir, path);
         if (!validatePath(fullPath, this.baseDir)) {
@@ -171,44 +94,18 @@ export class FileStorageAdapter {
             });
         }
     }
-    /**
-     * Check if a path exists in storage.
-     *
-     * @param path - Relative path within baseDir
-     * @returns True if the path exists
-     */
     exists(path) {
         return existsSync(join(this.baseDir, path));
     }
-    /**
-     * Get the absolute filesystem path for a relative storage path.
-     *
-     * @param path - Relative path within baseDir
-     * @returns Absolute filesystem path
-     */
     getFullPath(path) {
         return join(this.baseDir, path);
     }
-    /**
-     * Ensure a directory exists, creating it recursively if necessary.
-     *
-     * @param path - Relative directory path within baseDir
-     */
     async ensureDir(path) {
         const fullPath = join(this.baseDir, path);
         if (!existsSync(fullPath)) {
             await mkdir(fullPath, { recursive: true });
         }
     }
-    /**
-     * Acquire an exclusive lock on a file path.
-     * Uses .lock files with PID tracking for stale lock detection.
-     *
-     * @param path - Relative path to lock
-     * @param options - Lock behavior options
-     * @returns Unlock function that MUST be called to release
-     * @throws {StorageError} If lock cannot be acquired within timeout
-     */
     async lock(path, options) {
         const timeout = options?.timeout ?? LIMITS.lockTimeout;
         const staleThreshold = options?.stale ?? LIMITS.lockStale;
@@ -236,7 +133,6 @@ export class FileStorageAdapter {
                 });
             }
             attempt++;
-            // Check if lock file exists
             if (existsSync(fullLockPath)) {
                 try {
                     const content = await readFile(fullLockPath, "utf-8");
@@ -249,7 +145,6 @@ export class FileStorageAdapter {
                             await unlink(fullLockPath);
                         }
                         catch {
-                            // Another process may have removed it
                         }
                     }
                     else {
@@ -274,11 +169,9 @@ export class FileStorageAdapter {
                         await unlink(fullLockPath);
                     }
                     catch {
-                        // Continue - file might have been removed
                     }
                 }
             }
-            // Attempt to create lock file atomically
             const lockContent = {
                 pid: process.pid,
                 createdAt: new Date().toISOString(),
@@ -289,7 +182,6 @@ export class FileStorageAdapter {
                 await writeFile(fullLockPath, JSON.stringify(lockContent, null, 2), {
                     flag: "wx",
                 });
-                // Success - return unlock function
                 let released = false;
                 const unlock = async () => {
                     if (released)
@@ -304,7 +196,6 @@ export class FileStorageAdapter {
                         }
                     }
                     catch {
-                        // Best effort release
                     }
                     finally {
                         released = true;
@@ -335,13 +226,6 @@ export class FileStorageAdapter {
         }
     }
 }
-// ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * Extract directory portion from a path.
- * Works with both forward slashes and backslashes.
- */
 function dirname(path) {
     return path.split(/[/\\]/).slice(0, -1).join("/");
 }

package/dist/shared-context/task.d.ts

@@ -1,131 +1,11 @@
-/**
- * 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 type { CreateTaskOptions, TaskState, Status, TaskResult } from "./types.js";
 import type { Session } from "./session.js";
-/**
- * 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 declare function assignTask(session: Session, squadId: string, options: CreateTaskOptions): Promise<TaskState>;
-/**
- * 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 declare function getTask(session: Session, squadId: string, taskId: string): Promise<TaskState | null>;
-/**
- * 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 declare function updateTask(session: Session, squadId: string, taskId: string, updates: {
     status?: Status;
     startedAt?: string;
     completedAt?: string;
     result?: unknown;
 }): Promise<TaskState>;
-/**
- * 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 declare function completeTask(session: Session, squadId: string, taskId: string, result: TaskResult): Promise<TaskState>;