@eddacraft/anvil-aps 0.1.0

package/dist/state/index.js

@@ -0,0 +1,689 @@
+/**
+ * State module - Task state management and locking functionality
+ *
+ * Manages `.anvil/state.json` for tracking task execution states.
+ * Provides TaskLocker for locking tasks for execution with:
+ * - First-lock-wins concurrent lock handling
+ * - Execution plan JSON generation with hash and provenance
+ * - Lock/unlock/status operations
+ */
+import { promises as fs } from 'node:fs';
+import { dirname, join, isAbsolute, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { z } from 'zod';
+import { TaskStatusSchema } from '../types/index.js';
+import { loadPlan } from '../loader/index.js';
+import { validatePlanningDoc } from '../validator/index.js';
+// ============================================================================
+// Schemas
+// ============================================================================
+/**
+ * Source location of a task in a planning document
+ */
+export const TaskSourceSchema = z.object({
+    /** File path relative to project root */
+    file: z.string(),
+    /** Line number where task starts (1-based) */
+    line: z.number().optional(),
+});
+/**
+ * State of a single task
+ */
+export const TaskStateSchema = z.object({
+    /** Current status */
+    status: TaskStatusSchema,
+    /** ISO timestamp when task was locked */
+    locked_at: z.string().optional(),
+    /** User who locked the task */
+    locked_by: z.string().optional(),
+    /** Path to execution plan JSON file */
+    execution_file: z.string().optional(),
+    /** Source location in planning doc */
+    source: TaskSourceSchema.optional(),
+    /** ISO timestamp when task was completed */
+    completed_at: z.string().optional(),
+    /** ISO timestamp when task was cancelled */
+    cancelled_at: z.string().optional(),
+});
+/**
+ * Full state file schema (.anvil/state.json)
+ */
+export const StateFileSchema = z.object({
+    /** Schema version */
+    version: z.string().default('1.0.0'),
+    /** Map of task ID to task state */
+    tasks: z.record(z.string(), TaskStateSchema),
+});
+/**
+ * Provenance information for execution plans
+ */
+export const ProvenanceSchema = z.object({
+    /** User who locked the task */
+    locked_by: z.string(),
+    /** ISO timestamp when locked */
+    locked_at: z.string(),
+    /** Git commit hash (if available) */
+    git_commit: z.string().optional(),
+    /** Git branch (if available) */
+    git_branch: z.string().optional(),
+    /** Planning doc file path */
+    source_file: z.string(),
+    /** Line number in planning doc */
+    source_line: z.number().optional(),
+});
+/**
+ * Execution plan JSON schema (per-task, written to .anvil/executions/)
+ */
+export const ExecutionPlanSchema = z.object({
+    /** Schema version */
+    version: z.string().default('1.0.0'),
+    /** Task ID */
+    task_id: z.string(),
+    /** Task title */
+    title: z.string(),
+    /** Task intent */
+    intent: z.string(),
+    /** Expected outcome */
+    expected_outcome: z.string().optional(),
+    /** Confidence level */
+    confidence: z.enum(['low', 'medium', 'high']),
+    /** Task scopes */
+    scopes: z.array(z.string()).optional(),
+    /** Task tags */
+    tags: z.array(z.string()).optional(),
+    /** Task dependencies */
+    dependencies: z.array(z.string()).optional(),
+    /** Task inputs */
+    inputs: z.array(z.string()).optional(),
+    /** SHA-256 hash of task content */
+    content_hash: z.string(),
+    /** Provenance information */
+    provenance: ProvenanceSchema,
+});
+// ============================================================================
+// State File Operations
+// ============================================================================
+const STATE_FILE_NAME = 'state.json';
+const EXECUTIONS_DIR = 'executions';
+const ANVIL_DIR = '.anvil';
+/**
+ * Get the path to the state file
+ */
+export function getStateFilePath(projectRoot) {
+    return join(projectRoot, ANVIL_DIR, STATE_FILE_NAME);
+}
+/**
+ * Get the path to the executions directory
+ */
+export function getExecutionsDir(projectRoot) {
+    return join(projectRoot, ANVIL_DIR, EXECUTIONS_DIR);
+}
+/**
+ * Read the state file, returning empty state if it doesn't exist
+ */
+export async function readStateFile(projectRoot) {
+    const statePath = getStateFilePath(projectRoot);
+    try {
+        const content = await fs.readFile(statePath, 'utf-8');
+        const data = JSON.parse(content);
+        return StateFileSchema.parse(data);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { version: '1.0.0', tasks: {} };
+        }
+        throw new StateError(`Failed to read state file: ${error instanceof Error ? error.message : String(error)}`, statePath);
+    }
+}
+/**
+ * Write the state file, creating directories if needed
+ */
+export async function writeStateFile(projectRoot, state) {
+    const statePath = getStateFilePath(projectRoot);
+    const stateDir = dirname(statePath);
+    try {
+        await fs.mkdir(stateDir, { recursive: true });
+        const content = JSON.stringify(state, null, 2);
+        await fs.writeFile(statePath, content, 'utf-8');
+    }
+    catch (error) {
+        throw new StateError(`Failed to write state file: ${error instanceof Error ? error.message : String(error)}`, statePath);
+    }
+}
+/**
+ * Get the state of a specific task
+ */
+export async function getTaskState(projectRoot, taskId) {
+    const state = await readStateFile(projectRoot);
+    return state.tasks[taskId];
+}
+/**
+ * Update the state of a specific task
+ */
+export async function updateTaskState(projectRoot, taskId, taskState) {
+    const state = await readStateFile(projectRoot);
+    state.tasks[taskId] = taskState;
+    await writeStateFile(projectRoot, state);
+}
+// ============================================================================
+// Execution Plan Operations
+// ============================================================================
+/**
+ * Generate execution plan JSON for a task
+ */
+export function createExecutionPlan(task, provenance) {
+    // Compute content hash from task fields
+    const contentHash = computeTaskHash(task);
+    return {
+        version: '1.0.0',
+        task_id: task.id,
+        title: task.title,
+        intent: task.intent,
+        expected_outcome: task.expectedOutcome,
+        confidence: task.confidence,
+        scopes: task.scopes,
+        tags: task.tags,
+        dependencies: task.dependencies,
+        inputs: task.inputs,
+        content_hash: contentHash,
+        provenance,
+    };
+}
+/**
+ * Compute SHA-256 hash of task content
+ */
+export function computeTaskHash(task) {
+    const content = JSON.stringify({
+        id: task.id,
+        title: task.title,
+        intent: task.intent,
+        expectedOutcome: task.expectedOutcome,
+        confidence: task.confidence,
+        scopes: task.scopes,
+        tags: task.tags,
+        dependencies: task.dependencies,
+        inputs: task.inputs,
+    });
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Get execution plan file path for a task
+ */
+export function getExecutionPlanPath(projectRoot, taskId) {
+    return join(getExecutionsDir(projectRoot), `${taskId}.json`);
+}
+/**
+ * Write execution plan to file
+ */
+export async function writeExecutionPlan(projectRoot, plan) {
+    const execPath = getExecutionPlanPath(projectRoot, plan.task_id);
+    const execDir = dirname(execPath);
+    await fs.mkdir(execDir, { recursive: true });
+    await fs.writeFile(execPath, JSON.stringify(plan, null, 2), 'utf-8');
+    return execPath;
+}
+/**
+ * Read execution plan from file.
+ * Verifies the stored content_hash matches the recomputed hash.
+ * If the hash does not match, the plan is still returned but a
+ * `hashMismatch` flag is set on the result.
+ */
+export async function readExecutionPlan(projectRoot, taskId) {
+    const execPath = getExecutionPlanPath(projectRoot, taskId);
+    try {
+        const content = await fs.readFile(execPath, 'utf-8');
+        const data = JSON.parse(content);
+        const plan = ExecutionPlanSchema.parse(data);
+        // Verify content hash integrity
+        const recomputed = recomputeContentHash(plan);
+        if (recomputed !== plan.content_hash) {
+            process.stderr.write(`Warning: execution plan "${taskId}" content_hash mismatch ` +
+                `(stored: ${plan.content_hash.slice(0, 12)}…, computed: ${recomputed.slice(0, 12)}…). ` +
+                `The plan file may have been tampered with.\n`);
+            return { ...plan, hashMismatch: true };
+        }
+        return plan;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw new StateError(`Failed to read execution plan: ${error instanceof Error ? error.message : String(error)}`, execPath);
+    }
+}
+/**
+ * Recompute the content hash for an execution plan using the same
+ * fields that `computeTaskHash` uses when creating the plan.
+ */
+function recomputeContentHash(plan) {
+    const content = JSON.stringify({
+        id: plan.task_id,
+        title: plan.title,
+        intent: plan.intent,
+        expectedOutcome: plan.expected_outcome,
+        confidence: plan.confidence,
+        scopes: plan.scopes,
+        tags: plan.tags,
+        dependencies: plan.dependencies,
+        inputs: plan.inputs,
+    });
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Delete execution plan file
+ */
+export async function deleteExecutionPlan(projectRoot, taskId) {
+    const execPath = getExecutionPlanPath(projectRoot, taskId);
+    try {
+        await fs.unlink(execPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new StateError(`Failed to delete execution plan: ${error instanceof Error ? error.message : String(error)}`, execPath);
+        }
+    }
+}
+// ============================================================================
+// Provenance Helpers
+// ============================================================================
+/**
+ * Get current user name
+ */
+export function getCurrentUser() {
+    return process.env['USER'] || process.env['USERNAME'] || 'unknown';
+}
+/**
+ * Get git commit hash (if in a git repo)
+ */
+export function getGitCommit(projectRoot) {
+    try {
+        return execSync('git rev-parse HEAD', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get git branch name (if in a git repo)
+ */
+export function getGitBranch(projectRoot) {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Create provenance info for a task
+ */
+export function createProvenance(task, projectRoot, user) {
+    return {
+        locked_by: user ?? getCurrentUser(),
+        locked_at: new Date().toISOString(),
+        git_commit: getGitCommit(projectRoot),
+        git_branch: getGitBranch(projectRoot),
+        source_file: task.sourcePath ?? 'unknown',
+        source_line: task.sourceLineNumber,
+    };
+}
+// ============================================================================
+// TaskLocker
+// ============================================================================
+/**
+ * Error thrown by state operations
+ */
+export class StateError extends Error {
+    path;
+    taskId;
+    constructor(message, path, taskId) {
+        super(message);
+        this.path = path;
+        this.taskId = taskId;
+        this.name = 'StateError';
+    }
+}
+/**
+ * TaskLocker - Manages task locking for execution
+ *
+ * @example
+ * ```typescript
+ * const locker = new TaskLocker({
+ *   projectRoot: '/path/to/project',
+ *   planPath: 'docs/planning/APS.md',
+ * });
+ *
+ * // Lock a task
+ * const result = await locker.lock('AUTH-001');
+ * if (result.success) {
+ *   console.log(`Task locked, execution plan: ${result.executionPlanPath}`);
+ * }
+ *
+ * // Check status
+ * const status = await locker.getStatus('AUTH-001');
+ *
+ * // Unlock (cancel) a task
+ * await locker.unlock('AUTH-001');
+ * ```
+ */
+export class TaskLocker {
+    projectRoot;
+    planPath;
+    user;
+    skipValidation;
+    plan = null;
+    constructor(options) {
+        this.projectRoot = isAbsolute(options.projectRoot)
+            ? options.projectRoot
+            : resolve(options.projectRoot);
+        this.planPath = isAbsolute(options.planPath)
+            ? options.planPath
+            : resolve(this.projectRoot, options.planPath);
+        this.user = options.user ?? getCurrentUser();
+        this.skipValidation = options.skipValidation ?? false;
+    }
+    /**
+     * Load the plan (validates first unless skipValidation is true)
+     */
+    async loadPlan() {
+        if (this.plan) {
+            return this.plan;
+        }
+        // Validate first
+        if (!this.skipValidation) {
+            const validationResult = await validatePlanningDoc(this.planPath);
+            if (!validationResult.valid) {
+                const errorMessages = validationResult.errors
+                    .map((e) => `${e.path ?? ''}${e.lineNumber ? `:${e.lineNumber}` : ''}: ${e.message}`)
+                    .join('\n');
+                throw new StateError(`Planning document validation failed:\n${errorMessages}`, this.planPath);
+            }
+        }
+        this.plan = await loadPlan(this.planPath);
+        return this.plan;
+    }
+    /**
+     * Find a task by ID in the loaded plan
+     */
+    async findTask(taskId) {
+        const plan = await this.loadPlan();
+        return plan.allTasks.find((t) => t.id === taskId);
+    }
+    /**
+     * Lock a task for execution
+     *
+     * - Validates planning doc first (unless skipValidation)
+     * - Snapshots task definition
+     * - Generates execution plan JSON with hash and provenance
+     * - Updates state.json
+     * - First lock wins (fails if already locked)
+     */
+    async lock(taskId) {
+        try {
+            // Check if task exists
+            const task = await this.findTask(taskId);
+            if (!task) {
+                return {
+                    success: false,
+                    taskId,
+                    error: `Task "${taskId}" not found in planning document`,
+                };
+            }
+            // Check current state (first lock wins)
+            const currentState = await getTaskState(this.projectRoot, taskId);
+            if (currentState?.status === 'locked') {
+                return {
+                    success: false,
+                    taskId,
+                    error: `Task "${taskId}" is already locked by ${currentState.locked_by} at ${currentState.locked_at}`,
+                };
+            }
+            // Create provenance and execution plan
+            const provenance = createProvenance(task, this.projectRoot, this.user);
+            const executionPlan = createExecutionPlan(task, provenance);
+            // Write execution plan
+            const execPath = await writeExecutionPlan(this.projectRoot, executionPlan);
+            // Update state
+            const relativeExecPath = `.anvil/executions/${taskId}.json`;
+            const taskState = {
+                status: 'locked',
+                locked_at: provenance.locked_at,
+                locked_by: provenance.locked_by,
+                execution_file: relativeExecPath,
+                source: task.sourcePath
+                    ? {
+                        file: task.sourcePath,
+                        line: task.sourceLineNumber,
+                    }
+                    : undefined,
+            };
+            await updateTaskState(this.projectRoot, taskId, taskState);
+            return {
+                success: true,
+                taskId,
+                executionPlanPath: execPath,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                taskId,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Unlock (cancel) a locked task
+     *
+     * - Moves task to 'cancelled' status
+     * - Removes execution plan file
+     */
+    async unlock(taskId) {
+        try {
+            const currentState = await getTaskState(this.projectRoot, taskId);
+            if (!currentState) {
+                return {
+                    success: false,
+                    taskId,
+                    error: `Task "${taskId}" has no state record`,
+                };
+            }
+            if (currentState.status !== 'locked') {
+                return {
+                    success: false,
+                    taskId,
+                    previousStatus: currentState.status,
+                    error: `Task "${taskId}" is not locked (current status: ${currentState.status})`,
+                };
+            }
+            // Delete execution plan file
+            await deleteExecutionPlan(this.projectRoot, taskId);
+            // Update state to cancelled
+            const taskState = {
+                status: 'cancelled',
+                cancelled_at: new Date().toISOString(),
+                source: currentState.source,
+            };
+            await updateTaskState(this.projectRoot, taskId, taskState);
+            return {
+                success: true,
+                taskId,
+                previousStatus: 'locked',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                taskId,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Mark a task as completed
+     */
+    async complete(taskId) {
+        try {
+            const currentState = await getTaskState(this.projectRoot, taskId);
+            if (!currentState) {
+                return {
+                    success: false,
+                    taskId,
+                    error: `Task "${taskId}" has no state record`,
+                };
+            }
+            if (currentState.status !== 'locked') {
+                return {
+                    success: false,
+                    taskId,
+                    previousStatus: currentState.status,
+                    error: `Task "${taskId}" is not locked (current status: ${currentState.status})`,
+                };
+            }
+            // Update state to completed (keep execution plan for audit)
+            const taskState = {
+                ...currentState,
+                status: 'completed',
+                completed_at: new Date().toISOString(),
+            };
+            await updateTaskState(this.projectRoot, taskId, taskState);
+            return {
+                success: true,
+                taskId,
+                previousStatus: 'locked',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                taskId,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Get the status of a specific task
+     */
+    async getStatus(taskId) {
+        const state = await getTaskState(this.projectRoot, taskId);
+        if (!state) {
+            // Task exists in plan but no state record - it's open
+            const task = await this.findTask(taskId);
+            if (task) {
+                return {
+                    taskId,
+                    status: 'open',
+                    source: task.sourcePath
+                        ? {
+                            file: task.sourcePath,
+                            line: task.sourceLineNumber,
+                        }
+                        : undefined,
+                };
+            }
+            return undefined;
+        }
+        return {
+            taskId,
+            status: state.status,
+            lockedAt: state.locked_at,
+            lockedBy: state.locked_by,
+            executionFile: state.execution_file,
+            source: state.source,
+            completedAt: state.completed_at,
+            cancelledAt: state.cancelled_at,
+        };
+    }
+    /**
+     * Get status of all tasks in the plan
+     */
+    async getAllStatus() {
+        const plan = await this.loadPlan();
+        const state = await readStateFile(this.projectRoot);
+        const result = [];
+        for (const task of plan.allTasks) {
+            const taskState = state.tasks[task.id];
+            if (taskState) {
+                result.push({
+                    taskId: task.id,
+                    status: taskState.status,
+                    lockedAt: taskState.locked_at,
+                    lockedBy: taskState.locked_by,
+                    executionFile: taskState.execution_file,
+                    source: taskState.source,
+                    completedAt: taskState.completed_at,
+                    cancelledAt: taskState.cancelled_at,
+                });
+            }
+            else {
+                result.push({
+                    taskId: task.id,
+                    status: 'open',
+                    source: task.sourcePath
+                        ? {
+                            file: task.sourcePath,
+                            line: task.sourceLineNumber,
+                        }
+                        : undefined,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Get summary of task statuses
+     */
+    async getStatusSummary() {
+        const allStatus = await this.getAllStatus();
+        const summary = {
+            open: 0,
+            locked: 0,
+            completed: 0,
+            cancelled: 0,
+        };
+        for (const status of allStatus) {
+            summary[status.status]++;
+        }
+        return summary;
+    }
+}
+/**
+ * Format task status for display
+ */
+export function formatTaskStatus(status) {
+    const parts = [`${status.taskId}: ${status.status}`];
+    if (status.lockedBy && status.lockedAt) {
+        parts.push(`  Locked by: ${status.lockedBy} at ${status.lockedAt}`);
+    }
+    if (status.completedAt) {
+        parts.push(`  Completed: ${status.completedAt}`);
+    }
+    if (status.cancelledAt) {
+        parts.push(`  Cancelled: ${status.cancelledAt}`);
+    }
+    if (status.source) {
+        const loc = status.source.line
+            ? `${status.source.file}:${status.source.line}`
+            : status.source.file;
+        parts.push(`  Source: ${loc}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Format all task statuses for display
+ */
+export function formatAllTaskStatus(statuses) {
+    if (statuses.length === 0) {
+        return 'No tasks found.';
+    }
+    return statuses.map(formatTaskStatus).join('\n\n');
+}