octie-cli 1.0.0

package/dist/core/graph/traversal.js

@@ -0,0 +1,336 @@
+/**
+ * Graph traversal algorithms
+ *
+ * Implements BFS and DFS traversal methods for path finding and
+ * reachable node discovery.
+ * Time complexity: O(V + E) where V = vertices, E = edges
+ *
+ * @module core/graph/traversal
+ */
+import { TaskNotFoundError } from '../../types/index.js';
+/**
+ * Breadth-First Search traversal
+ *
+ * Explores nodes layer by layer, finding all reachable nodes from a start node.
+ * Useful for finding all descendants (forward) or ancestors (backward).
+ *
+ * Time Complexity: O(V + E) in worst case
+ * Space Complexity: O(V) for visited set and queue
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param direction - Traversal direction: 'forward' (outgoing) or 'backward' (incoming)
+ * @returns Array of reachable task IDs in order of discovery
+ * @throws {TaskNotFoundError} If start node doesn't exist
+ *
+ * @example
+ * ```ts
+ * // Find all tasks that depend on the start task
+ * const descendants = bfsTraversal(graph, 'task-001', 'forward');
+ *
+ * // Find all tasks that the start task depends on
+ * const ancestors = bfsTraversal(graph, 'task-001', 'backward');
+ * ```
+ */
+export function bfsTraversal(graph, startId, direction = 'forward') {
+    // Validate start node exists
+    if (!graph.hasNode(startId)) {
+        throw new TaskNotFoundError(startId);
+    }
+    const visited = new Set();
+    const queue = [startId];
+    const result = [];
+    /**
+     * Get neighbors based on traversal direction
+     * @param id - Task ID
+     * @returns Array of neighbor task IDs
+     */
+    const getNeighbors = (id) => {
+        return direction === 'forward'
+            ? graph.getOutgoingEdges(id)
+            : graph.getIncomingEdges(id);
+    };
+    while (queue.length > 0) {
+        // Dequeue next node
+        const nodeId = queue.shift();
+        // Skip if already visited
+        if (visited.has(nodeId)) {
+            continue;
+        }
+        // Mark as visited and add to result
+        visited.add(nodeId);
+        result.push(nodeId);
+        // Enqueue all unvisited neighbors
+        const neighbors = getNeighbors(nodeId);
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Depth-First Search to find path between two nodes
+ *
+ * Attempts to find a path from start to end using DFS with backtracking.
+ * Returns the first path found, or null if no path exists.
+ *
+ * Time Complexity: O(V + E) in worst case
+ * Space Complexity: O(V) for recursion stack and visited set
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param endId - Target task ID
+ * @param direction - Search direction: 'forward' (follow outgoing) or 'backward' (follow incoming)
+ * @returns Path array from start to end, or null if no path exists
+ * @throws {TaskNotFoundError} If either node doesn't exist
+ *
+ * @example
+ * ```ts
+ * // Find path from task-001 to task-005
+ * const path = dfsFindPath(graph, 'task-001', 'task-005');
+ * if (path) {
+ *   console.log('Path:', path.join(' -> '));
+ *   // Output: Path: task-001 -> task-002 -> task-004 -> task-005
+ * }
+ * ```
+ */
+export function dfsFindPath(graph, startId, endId, direction = 'forward') {
+    // Validate both nodes exist
+    if (!graph.hasNode(startId)) {
+        throw new TaskNotFoundError(startId);
+    }
+    if (!graph.hasNode(endId)) {
+        throw new TaskNotFoundError(endId);
+    }
+    const visited = new Set();
+    const path = [];
+    /**
+     * Get neighbors based on search direction
+     * @param id - Task ID
+     * @returns Array of neighbor task IDs
+     */
+    const getNeighbors = (id) => {
+        return direction === 'forward'
+            ? graph.getOutgoingEdges(id)
+            : graph.getIncomingEdges(id);
+    };
+    /**
+     * Recursive DFS with backtracking
+     * @param currentId - Current node being visited
+     * @returns true if path was found
+     */
+    function dfs(currentId) {
+        // Skip if already visited
+        if (visited.has(currentId)) {
+            return false;
+        }
+        // Mark as visited and add to path
+        visited.add(currentId);
+        path.push(currentId);
+        // Check if we found the target
+        if (currentId === endId) {
+            return true;
+        }
+        // Recursively search neighbors
+        const neighbors = getNeighbors(currentId);
+        for (const neighbor of neighbors) {
+            if (dfs(neighbor)) {
+                return true; // Path found, propagate success
+            }
+        }
+        // Backtrack: remove from path
+        path.pop();
+        return false;
+    }
+    return dfs(startId) ? path : null;
+}
+/**
+ * Find all paths between two nodes
+ *
+ * Uses DFS to find all possible paths from start to end.
+ * Warning: Can be expensive on dense graphs with many paths.
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param endId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @param maxPaths - Maximum number of paths to find (default: 100, prevents explosion)
+ * @returns Array of paths (each path is an array of task IDs)
+ * @throws {TaskNotFoundError} If either node doesn't exist
+ */
+export function findAllPaths(graph, startId, endId, direction = 'forward', maxPaths = 100) {
+    // Validate both nodes exist
+    if (!graph.hasNode(startId)) {
+        throw new TaskNotFoundError(startId);
+    }
+    if (!graph.hasNode(endId)) {
+        throw new TaskNotFoundError(endId);
+    }
+    const allPaths = [];
+    const visited = new Set();
+    const currentPath = [];
+    /**
+     * Get neighbors based on search direction
+     */
+    const getNeighbors = (id) => {
+        return direction === 'forward'
+            ? graph.getOutgoingEdges(id)
+            : graph.getIncomingEdges(id);
+    };
+    /**
+     * Recursive DFS to find all paths
+     */
+    function dfs(currentId) {
+        // Early exit if we found enough paths
+        if (allPaths.length >= maxPaths) {
+            return;
+        }
+        // Mark as visited and add to current path
+        visited.add(currentId);
+        currentPath.push(currentId);
+        // Check if we found the target
+        if (currentId === endId) {
+            allPaths.push([...currentPath]);
+        }
+        else {
+            // Continue searching neighbors
+            for (const neighbor of getNeighbors(currentId)) {
+                if (!visited.has(neighbor)) {
+                    dfs(neighbor);
+                }
+            }
+        }
+        // Backtrack
+        currentPath.pop();
+        visited.delete(currentId);
+    }
+    dfs(startId);
+    return allPaths;
+}
+/**
+ * Get shortest path between two nodes using BFS
+ *
+ * BFS naturally finds the shortest path in unweighted graphs.
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param endId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @returns Shortest path array, or null if no path exists
+ * @throws {TaskNotFoundError} If either node doesn't exist
+ */
+export function findShortestPath(graph, startId, endId, direction = 'forward') {
+    // Validate both nodes exist
+    if (!graph.hasNode(startId)) {
+        throw new TaskNotFoundError(startId);
+    }
+    if (!graph.hasNode(endId)) {
+        throw new TaskNotFoundError(endId);
+    }
+    if (startId === endId) {
+        return [startId];
+    }
+    const visited = new Set([startId]);
+    const queue = [
+        { nodeId: startId, path: [startId] },
+    ];
+    /**
+     * Get neighbors based on search direction
+     */
+    const getNeighbors = (id) => {
+        return direction === 'forward'
+            ? graph.getOutgoingEdges(id)
+            : graph.getIncomingEdges(id);
+    };
+    while (queue.length > 0) {
+        const { nodeId, path } = queue.shift();
+        for (const neighbor of getNeighbors(nodeId)) {
+            if (neighbor === endId) {
+                return [...path, neighbor];
+            }
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                queue.push({ nodeId: neighbor, path: [...path, neighbor] });
+            }
+        }
+    }
+    return null; // No path found
+}
+/**
+ * Check if two nodes are connected (path exists)
+ *
+ * @param graph - Task graph store
+ * @param fromId - Source task ID
+ * @param toId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @returns true if a path exists between the nodes
+ */
+export function areConnected(graph, fromId, toId, direction = 'forward') {
+    try {
+        const path = findShortestPath(graph, fromId, toId, direction);
+        return path !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get distance (number of edges) between two nodes
+ *
+ * @param graph - Task graph store
+ * @param fromId - Source task ID
+ * @param toId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @returns Number of edges in shortest path, or -1 if no path exists
+ */
+export function getDistance(graph, fromId, toId, direction = 'forward') {
+    const path = findShortestPath(graph, fromId, toId, direction);
+    return path ? path.length - 1 : -1;
+}
+/**
+ * Get connected components in the graph
+ *
+ * Identifies groups of nodes that are reachable from each other.
+ * For directed graphs, uses weakly connected components
+ * (treating edges as undirected).
+ *
+ * @param graph - Task graph store
+ * @returns Array of connected components (each is an array of task IDs)
+ */
+export function getConnectedComponents(graph) {
+    const visited = new Set();
+    const components = [];
+    /**
+     * Get all neighbors (both incoming and outgoing) for undirected traversal
+     */
+    const getAllNeighbors = (id) => {
+        const outgoing = graph.getOutgoingEdges(id);
+        const incoming = graph.getIncomingEdges(id);
+        return [...new Set([...outgoing, ...incoming])];
+    };
+    for (const taskId of graph.getAllTaskIds()) {
+        if (!visited.has(taskId)) {
+            // Start a new component
+            const component = [];
+            const queue = [taskId];
+            while (queue.length > 0) {
+                const nodeId = queue.shift();
+                if (visited.has(nodeId)) {
+                    continue;
+                }
+                visited.add(nodeId);
+                component.push(nodeId);
+                for (const neighbor of getAllNeighbors(nodeId)) {
+                    if (!visited.has(neighbor)) {
+                        queue.push(neighbor);
+                    }
+                }
+            }
+            components.push(component);
+        }
+    }
+    return components;
+}
+//# sourceMappingURL=traversal.js.map

package/dist/core/graph/traversal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traversal.js","sourceRoot":"","sources":["../../../src/core/graph/traversal.ts"],"names":[],"mappings":"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"}

package/dist/core/models/task-node.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Task Node Model
+ *
+ * Implements the TaskNode class with:
+ * - Required field validation
+ * - Atomic task validation
+ * - Auto-timestamp management (created_at, updated_at, completed_at)
+ * - Status transition validation
+ * - Success criteria and deliverable tracking
+ *
+ * @module core/models/task-node
+ */
+import type { TaskNode as TaskNodeType, TaskStatus, TaskPriority, SuccessCriterion, Deliverable, C7Verification, FixItem } from '../../types/index.js';
+/**
+ * Validate atomic task requirements
+ *
+ * Atomic tasks MUST be:
+ * - Specific (clear, focused purpose)
+ * - Executable (can be completed in 2-8 hours typical, max 2 days)
+ * - Verifiable (has quantitative success criteria)
+ * - Independent (minimizes dependencies)
+ *
+ * @param taskData - Task data to validate
+ * @throws {AtomicTaskViolationError} If task violates atomic requirements
+ */
+export declare function validateAtomicTask(taskData: {
+    title: string;
+    description: string;
+    success_criteria: SuccessCriterion[];
+    deliverables: Deliverable[];
+}): void;
+/**
+ * Task Node Class
+ *
+ * Represents a single task in the graph with:
+ * - Auto-managed timestamps (created_at, updated_at, completed_at)
+ * - Required field validation at creation
+ * - Atomic task validation
+ * - Status transition validation
+ * - Private setters to prevent manual timestamp manipulation
+ */
+export declare class TaskNode implements TaskNodeType {
+    readonly id: string;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    priority: TaskPriority;
+    success_criteria: SuccessCriterion[];
+    deliverables: Deliverable[];
+    /** Blocking issues that must be resolved before review (equal importance to criteria/deliverables) */
+    need_fix: FixItem[];
+    /** Optional agent/session that owns this task (decoupled from status) */
+    assignee: string | null;
+    blockers: string[];
+    /** Explanatory text describing WHY this task depends on its blockers */
+    dependencies: string;
+    sub_items: string[];
+    related_files: string[];
+    notes: string;
+    c7_verified: C7Verification[];
+    private _created_at;
+    private _updated_at;
+    private _completed_at;
+    edges: string[];
+    /**
+     * Get the creation timestamp (immutable)
+     */
+    get created_at(): string;
+    /**
+     * Get the last update timestamp (auto-managed)
+     */
+    get updated_at(): string;
+    /**
+     * Get the completion timestamp (auto-managed, null if not complete)
+     */
+    get completed_at(): string | null;
+    /**
+     * Create a new TaskNode
+     *
+     * @param data - Task data (title, description, success_criteria, deliverables are REQUIRED)
+     * @param _skipAtomicValidation - Private: skip atomic validation (used only by fromJSON for deserialization)
+     * @throws {ValidationError} If required fields are missing or invalid
+     * @throws {AtomicTaskViolationError} If task violates atomic requirements
+     */
+    constructor(data: {
+        title?: string;
+        description?: string;
+        status?: TaskStatus;
+        priority?: TaskPriority;
+        success_criteria?: SuccessCriterion[];
+        deliverables?: Deliverable[];
+        need_fix?: FixItem[];
+        assignee?: string | null;
+        blockers?: string[];
+        /** Explanatory text describing WHY this task depends on its blockers */
+        dependencies?: string;
+        sub_items?: string[];
+        related_files?: string[];
+        notes?: string;
+        c7_verified?: C7Verification[];
+        id?: string;
+        edges?: string[];
+        created_at?: string;
+        updated_at?: string;
+        completed_at?: string | null;
+        _skipAtomicValidation?: boolean;
+    });
+    /**
+     * Update the task title
+     * @param title - New title
+     */
+    setTitle(title: string): void;
+    /**
+     * Update the task description
+     * @param description - New description
+     */
+    setDescription(description: string): void;
+    /**
+     * Update the task status
+     * @param status - New status
+     */
+    setStatus(status: TaskStatus): void;
+    /**
+     * Update the task priority
+     * @param priority - New priority
+     */
+    setPriority(priority: TaskPriority): void;
+    /**
+     * Add a success criterion
+     * @param criterion - Success criterion to add
+     */
+    addSuccessCriterion(criterion: SuccessCriterion): void;
+    /**
+     * Mark a success criterion as complete
+     * @param criterionId - ID of the criterion to mark complete
+     */
+    completeCriterion(criterionId: string): void;
+    /**
+     * Unmark a success criterion as complete
+     * @param criterionId - ID of the criterion to unmark
+     * @throws {ImmutabilityViolationError} If criterion is already completed (immutable)
+     */
+    uncompleteCriterion(criterionId: string): void;
+    /**
+     * Add a deliverable
+     * @param deliverable - Deliverable to add
+     */
+    addDeliverable(deliverable: Deliverable): void;
+    /**
+     * Mark a deliverable as complete
+     * @param deliverableId - ID of the deliverable to mark complete
+     */
+    completeDeliverable(deliverableId: string): void;
+    /**
+     * Unmark a deliverable as complete
+     * @param deliverableId - ID of the deliverable to unmark
+     * @throws {ImmutabilityViolationError} If deliverable is already completed (immutable)
+     */
+    uncompleteDeliverable(deliverableId: string): void;
+    /**
+     * Add a need_fix item
+     * Need_fix items are blocking issues that must be resolved before review
+     * @param text - Description of what needs to be fixed
+     * @param options - Optional file_path and source
+     */
+    addNeedFix(text: string, options?: {
+        file_path?: string;
+        source?: FixItem['source'];
+    }): void;
+    /**
+     * Mark a need_fix item as complete
+     * @param fixId - ID of the need_fix item to mark complete
+     */
+    completeNeedFix(fixId: string): void;
+    /**
+     * Set the assignee for this task
+     * Assignee is decoupled from status - just a placeholder for future team management
+     * @param agentId - Agent/session ID, or null to clear
+     */
+    setAssignee(agentId: string | null): void;
+    /**
+     * Add a blocker task ID
+     * @param blockerId - Task ID that blocks this task
+     */
+    addBlocker(blockerId: string): void;
+    /**
+     * Remove a blocker task ID
+     * @param blockerId - Task ID to remove from blockers
+     */
+    removeBlocker(blockerId: string): void;
+    /**
+     * Set the dependencies explanation text (twin to blockers)
+     * @param explanation - Explanatory text describing WHY this task depends on its blockers
+     */
+    setDependencies(explanation: string): void;
+    /**
+     * Clear the dependencies explanation text
+     * Typically called when removing the last blocker
+     */
+    clearDependencies(): void;
+    /**
+     * Remove a success criterion
+     * @param criterionId - ID of the criterion to remove
+     * @throws {ValidationError} If criterion not found or removal would leave no criteria
+     * @throws {ImmutabilityViolationError} If criterion is completed (immutable)
+     */
+    removeSuccessCriterion(criterionId: string): void;
+    /**
+     * Remove a deliverable
+     * @param deliverableId - ID of the deliverable to remove
+     * @throws {ValidationError} If deliverable not found or removal would leave no deliverables
+     * @throws {ImmutabilityViolationError} If deliverable is completed (immutable)
+     */
+    removeDeliverable(deliverableId: string): void;
+    /**
+     * Remove a related file path
+     * @param filePath - File path to remove
+     */
+    removeRelatedFile(filePath: string): void;
+    /**
+     * Remove a C7 verification entry
+     * @param libraryId - Library ID to remove from C7 verifications
+     */
+    removeC7Verification(libraryId: string): void;
+    /**
+     * Add a related file path
+     * @param filePath - File path relative to project root
+     */
+    addRelatedFile(filePath: string): void;
+    /**
+     * Append notes
+     * @param notes - Notes to append
+     */
+    appendNotes(notes: string): void;
+    /**
+     * Add C7 verification
+     * @param verification - C7 verification entry
+     */
+    addC7Verification(verification: C7Verification): void;
+    /**
+     * Add an outgoing edge
+     * @param taskId - Task ID this task points to
+     */
+    addEdge(taskId: string): void;
+    /**
+     * Remove an outgoing edge
+     * @param taskId - Task ID to remove from edges
+     */
+    removeEdge(taskId: string): void;
+    /**
+     * Add a sub-item task ID
+     * @param subItemId - Child task ID
+     */
+    addSubItem(subItemId: string): void;
+    /**
+     * Remove a sub-item task ID
+     * @param subItemId - Child task ID to remove
+     */
+    removeSubItem(subItemId: string): void;
+    /**
+     * Check if the task is complete (ready for review)
+     * All three must be complete: success_criteria, deliverables, and need_fix
+     * @returns True if all success criteria, deliverables, and need_fix items are complete
+     * @private
+     */
+    private _isComplete;
+    /**
+     * Update completed_at timestamp and status based on completion state
+     * Called automatically after any change to success_criteria, deliverables, or need_fix
+     * @private
+     */
+    private _checkCompletion;
+    /**
+     * Update the updated_at timestamp
+     * Called automatically after any field change
+     * @private
+     */
+    private _touch;
+    /**
+     * Calculate the derived status based on task state
+     *
+     * Status is DERIVED from state, not set directly:
+     * Priority order: blocked > in_review > in_progress > ready
+     *
+     * Rules:
+     * 1. Has unresolved blockers → 'blocked'
+     * 2. All criteria + deliverables + need_fix complete → 'in_review'
+     * 3. Any item checked OR need_fix exists → 'in_progress'
+     * 4. Default → 'ready'
+     *
+     * NOTE: This is a pure calculation function. It does NOT modify status.
+     * Use recalculateStatus() to apply the calculated status.
+     *
+     * @returns The calculated status based on current task state
+     */
+    calculateStatus(): TaskStatus;
+    /**
+     * Recalculate and update status based on task state
+     * This is the main method to call when task state changes
+     *
+     * Special cases:
+     * - completed tasks with new need_fix items → in_progress (regression)
+     * - completed tasks with new blockers → blocked (regression)
+     * - Otherwise, completed status is preserved (requires manual approve())
+     *
+     * @returns The new status (may be same as current)
+     */
+    recalculateStatus(): TaskStatus;
+    /**
+     * Approve a task that is in review
+     * This is the ONLY manual status transition in the new system
+     *
+     * @throws {ValidationError} If task is not in 'in_review' status
+     */
+    approve(): void;
+    /**
+     * Serialize the task node to plain object
+     * Useful for JSON serialization
+     */
+    toJSON(): TaskNodeType;
+    /**
+     * Create a TaskNode from plain object
+     * Useful for JSON deserialization
+     * Skips atomic validation since task was already validated when created
+     */
+    static fromJSON(data: TaskNodeType): TaskNode;
+}
+//# sourceMappingURL=task-node.d.ts.map

package/dist/core/models/task-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-node.d.ts","sourceRoot":"","sources":["../../../src/core/models/task-node.ts"],"names":[],"mappings":"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"}