@geanatz/cortex-mcp 5.0.1

package/dist/features/task-management/storage/storage.d.ts

@@ -0,0 +1,159 @@
+import { Task, TaskHierarchy, TaskFilters, CreateTaskInput, UpdateTaskInput, Subtask, AddSubtaskInput, UpdateSubtaskInput } from '../models/task.js';
+import { CURRENT_STORAGE_VERSION } from '../models/config.js';
+import { Artifact, CreateArtifactInput, UpdateArtifactInput, ArtifactPhase, TaskArtifacts } from '../models/artifact.js';
+export { CURRENT_STORAGE_VERSION };
+/**
+ * Storage operation result
+ */
+export interface StorageResult<T> {
+    readonly success: boolean;
+    readonly data?: T;
+    readonly error?: string;
+}
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+    readonly taskCount: number;
+    readonly artifactCount: number;
+    readonly cacheHitRate?: number;
+    readonly lastAccessed?: Date;
+}
+/**
+ * Storage interface for the task management system
+ *
+ * Simplified storage model:
+ * - Each parent task has its own folder: .cortex/tasks/{number}-{slug}/
+ * - .task.json contains parent task + subtasks array
+ * - Subtasks are NOT separate folders - they're stored inline
+ * - No dependsOn - simplified model
+ * - Single level nesting only
+ *
+ * Artifacts stored in .cortex/tasks/{number}-{slug}/{phase}.md
+ * Each phase (explore, search, plan, build, test) has its own artifact file
+ * Artifacts belong to the entire task hierarchy (parent + subtasks)
+ */
+export interface Storage {
+    /**
+     * Initialize the storage system
+     * Must be called before any other operations
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if storage is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get all parent tasks
+     */
+    getTasks(): Promise<readonly Task[]>;
+    /**
+     * Get tasks with filters
+     */
+    getTasksFiltered(filters: TaskFilters): Promise<readonly Task[]>;
+    /**
+     * Get a single task by ID
+     */
+    getTask(id: string): Promise<Task | null>;
+    /**
+     * Create a new parent task
+     */
+    createTask(input: CreateTaskInput): Promise<Task>;
+    /**
+     * Update an existing task (parent fields or subtask operations)
+     */
+    updateTask(id: string, updates: UpdateTaskInput): Promise<Task | null>;
+    /**
+     * Delete a task and all its subtasks
+     */
+    deleteTask(id: string): Promise<boolean>;
+    /**
+     * Check if a task exists
+     */
+    taskExists(id: string): Promise<boolean>;
+    /**
+     * Add a subtask to a parent task
+     */
+    addSubtask(taskId: string, input: AddSubtaskInput): Promise<Subtask | null>;
+    /**
+     * Update a subtask
+     */
+    updateSubtask(taskId: string, input: UpdateSubtaskInput): Promise<Subtask | null>;
+    /**
+     * Remove a subtask by ID
+     */
+    removeSubtask(taskId: string, subtaskId: string): Promise<boolean>;
+    /**
+     * Get task hierarchy (parent with subtasks)
+     */
+    getTaskHierarchy(): Promise<readonly TaskHierarchy[]>;
+    /**
+     * Get a single artifact for a task
+     */
+    getArtifact(taskId: string, phase: ArtifactPhase): Promise<Artifact | null>;
+    /**
+     * Get all artifacts for a task
+     */
+    getAllArtifacts(taskId: string): Promise<TaskArtifacts>;
+    /**
+     * Create a new artifact (overwrites existing)
+     */
+    createArtifact(taskId: string, phase: ArtifactPhase, input: CreateArtifactInput): Promise<Artifact>;
+    /**
+     * Update an existing artifact
+     */
+    updateArtifact(taskId: string, phase: ArtifactPhase, input: UpdateArtifactInput): Promise<Artifact | null>;
+    /**
+     * Delete an artifact
+     */
+    deleteArtifact(taskId: string, phase: ArtifactPhase): Promise<boolean>;
+    /**
+     * Check if an artifact exists
+     */
+    artifactExists(taskId: string, phase: ArtifactPhase): Promise<boolean>;
+    /**
+     * Get storage version
+     */
+    getVersion(): string;
+    /**
+     * Get storage statistics
+     */
+    getStats(): Promise<StorageStats>;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get the working directory
+     */
+    getWorkingDirectory(): string;
+}
+/**
+ * Abstract base storage class with common functionality
+ */
+export declare abstract class BaseStorage implements Storage {
+    protected initialized: boolean;
+    abstract initialize(): Promise<void>;
+    abstract getTasks(): Promise<readonly Task[]>;
+    abstract getTask(id: string): Promise<Task | null>;
+    abstract createTask(input: CreateTaskInput): Promise<Task>;
+    abstract updateTask(id: string, updates: UpdateTaskInput): Promise<Task | null>;
+    abstract deleteTask(id: string): Promise<boolean>;
+    abstract addSubtask(taskId: string, input: AddSubtaskInput): Promise<Subtask | null>;
+    abstract updateSubtask(taskId: string, input: UpdateSubtaskInput): Promise<Subtask | null>;
+    abstract removeSubtask(taskId: string, subtaskId: string): Promise<boolean>;
+    abstract getTaskHierarchy(): Promise<readonly TaskHierarchy[]>;
+    abstract getArtifact(taskId: string, phase: ArtifactPhase): Promise<Artifact | null>;
+    abstract getAllArtifacts(taskId: string): Promise<TaskArtifacts>;
+    abstract createArtifact(taskId: string, phase: ArtifactPhase, input: CreateArtifactInput): Promise<Artifact>;
+    abstract updateArtifact(taskId: string, phase: ArtifactPhase, input: UpdateArtifactInput): Promise<Artifact | null>;
+    abstract deleteArtifact(taskId: string, phase: ArtifactPhase): Promise<boolean>;
+    abstract getStats(): Promise<StorageStats>;
+    abstract clearCache(): void;
+    abstract getWorkingDirectory(): string;
+    isInitialized(): boolean;
+    getVersion(): string;
+    getTasksFiltered(filters: TaskFilters): Promise<readonly Task[]>;
+    taskExists(id: string): Promise<boolean>;
+    artifactExists(taskId: string, phase: ArtifactPhase): Promise<boolean>;
+}

package/dist/features/task-management/storage/storage.js

@@ -0,0 +1,37 @@
+import { CURRENT_STORAGE_VERSION } from '../models/config.js';
+// Re-export config types for convenience
+export { CURRENT_STORAGE_VERSION };
+/**
+ * Abstract base storage class with common functionality
+ */
+export class BaseStorage {
+    initialized = false;
+    isInitialized() {
+        return this.initialized;
+    }
+    getVersion() {
+        return CURRENT_STORAGE_VERSION;
+    }
+    async getTasksFiltered(filters) {
+        let tasks = await this.getTasks();
+        if (filters.status) {
+            const statuses = Array.isArray(filters.status) ? filters.status : [filters.status];
+            tasks = tasks.filter(t => statuses.includes(t.status));
+        }
+        if (filters.tags && filters.tags.length > 0) {
+            tasks = tasks.filter(t => t.tags && filters.tags.some(tag => t.tags.includes(tag)));
+        }
+        if (filters.includeDone === false) {
+            tasks = tasks.filter(t => t.status !== 'done');
+        }
+        return tasks;
+    }
+    async taskExists(id) {
+        const task = await this.getTask(id);
+        return task !== null;
+    }
+    async artifactExists(taskId, phase) {
+        const artifact = await this.getArtifact(taskId, phase);
+        return artifact !== null;
+    }
+}

package/dist/features/task-management/tools/artifacts/index.d.ts

@@ -0,0 +1,6 @@
+import { Storage } from '../../storage/storage.js';
+import { StorageConfig } from '../../../../utils/storage-config.js';
+import { ToolDefinition } from '../../tools/base/types.js';
+type StorageFactory = (workingDirectory: string, config: StorageConfig) => Promise<Storage>;
+export declare function createArtifactTools(config: StorageConfig, createStorage: StorageFactory): ToolDefinition[];
+export {};

package/dist/features/task-management/tools/artifacts/index.js

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { getWorkingDirectoryDescription } from '../../../../utils/storage-config.js';
+import { createErrorResponse } from '../../../../utils/response-builder.js';
+import { createLogger } from '../../../../utils/logger.js';
+import { ARTIFACT_PHASES, OPERATION_DESCRIPTIONS, PHASE_DESCRIPTIONS } from '../../models/artifact.js';
+import { withErrorHandling } from '../../tools/base/handlers.js';
+import { workingDirectorySchema, taskIdSchema } from '../../tools/base/schemas.js';
+const logger = createLogger('artifact-tools');
+function createCreateHandler(phase, config, createStorage) {
+    return async (params) => {
+        try {
+            const { workingDirectory, taskId, content, status, retries, error } = params;
+            if (!taskId || taskId.trim().length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: Task ID is required.' }],
+                    isError: true
+                };
+            }
+            if (!content || content.trim().length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: Content is required.' }],
+                    isError: true
+                };
+            }
+            const storage = await createStorage(workingDirectory, config);
+            const artifact = await storage.createArtifact(taskId.trim(), phase, {
+                content: content.trim(),
+                status,
+                retries,
+                error
+            });
+            const phaseUpper = phase.charAt(0).toUpperCase() + phase.slice(1);
+            const truncated = artifact.content.length > 500
+                ? artifact.content.substring(0, 500) + '...\n\n*(truncated - use get_task to see full content)*'
+                : artifact.content;
+            return {
+                content: [{
+                        type: 'text',
+                        text: `**${phaseUpper} artifact created for task "${taskId}"**\n\n**Phase:** ${artifact.metadata.phase}\n**Status:** ${artifact.metadata.status}\n**Created:** ${new Date(artifact.metadata.createdAt).toLocaleString()}\n\n---\n\n${truncated}`
+                    }]
+            };
+        }
+        catch (err) {
+            return createErrorResponse(err);
+        }
+    };
+}
+function createUpdateHandler(phase, config, createStorage) {
+    return async (params) => {
+        try {
+            const { workingDirectory, taskId, content, status, retries, error } = params;
+            if (!taskId || taskId.trim().length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: Task ID is required.' }],
+                    isError: true
+                };
+            }
+            const storage = await createStorage(workingDirectory, config);
+            const artifact = await storage.updateArtifact(taskId.trim(), phase, {
+                content: content?.trim(),
+                status,
+                retries,
+                error
+            });
+            if (!artifact) {
+                const phaseUpper = phase.charAt(0).toUpperCase() + phase.slice(1);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Error: ${phaseUpper} artifact not found for task "${taskId}". Use create_${phase} to create it first.`
+                        }],
+                    isError: true
+                };
+            }
+            const phaseUpper = phase.charAt(0).toUpperCase() + phase.slice(1);
+            const extras = (artifact.metadata.retries !== undefined ? `\n**Retries:** ${artifact.metadata.retries}` : '') + (artifact.metadata.error ? `\n**Error:** ${artifact.metadata.error}` : '');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `**${phaseUpper} artifact updated for task "${taskId}"**\n\n**Phase:** ${artifact.metadata.phase}\n**Status:** ${artifact.metadata.status}\n**Updated:** ${new Date(artifact.metadata.updatedAt).toLocaleString()}${extras}`
+                    }]
+            };
+        }
+        catch (err) {
+            return createErrorResponse(err);
+        }
+    };
+}
+function createDeleteHandler(phase, config, createStorage) {
+    return async (params) => {
+        try {
+            const { workingDirectory, taskId, confirm } = params;
+            if (!taskId || taskId.trim().length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: Task ID is required.' }],
+                    isError: true
+                };
+            }
+            if (!confirm) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Error: Deletion not confirmed. Set confirm=true to delete the ${phase} artifact.`
+                        }],
+                    isError: true
+                };
+            }
+            const storage = await createStorage(workingDirectory, config);
+            const deleted = await storage.deleteArtifact(taskId.trim(), phase);
+            if (!deleted) {
+                const phaseUpper = phase.charAt(0).toUpperCase() + phase.slice(1);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${phaseUpper} artifact not found for task "${taskId}". Nothing to delete.`
+                        }]
+                };
+            }
+            const phaseUpper = phase.charAt(0).toUpperCase() + phase.slice(1);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `**${phaseUpper} artifact deleted from task "${taskId}"**\n\nThe ${phase} phase has been reset and can be re-run.`
+                    }]
+            };
+        }
+        catch (err) {
+            return createErrorResponse(err);
+        }
+    };
+}
+export function createArtifactTools(config, createStorage) {
+    const tools = [];
+    const wdSchema = workingDirectorySchema.describe(getWorkingDirectoryDescription(config));
+    for (const phase of ARTIFACT_PHASES) {
+        tools.push({
+            name: `create_${phase}`,
+            description: OPERATION_DESCRIPTIONS.create[phase],
+            parameters: {
+                workingDirectory: wdSchema,
+                taskId: taskIdSchema.describe('The ID of the task to create the artifact for'),
+                content: z.string().describe(`Markdown content for the ${phase} artifact. ${PHASE_DESCRIPTIONS[phase]}`),
+                status: z.enum(['pending', 'in-progress', 'completed', 'failed', 'skipped']).optional().describe('Status of this phase (defaults to "completed")'),
+                retries: z.number().min(0).optional().describe('Number of retry attempts for this phase'),
+                error: z.string().optional().describe('Error message if status is "failed"')
+            },
+            handler: withErrorHandling(createCreateHandler(phase, config, createStorage))
+        });
+        tools.push({
+            name: `update_${phase}`,
+            description: OPERATION_DESCRIPTIONS.update[phase],
+            parameters: {
+                workingDirectory: wdSchema,
+                taskId: taskIdSchema.describe('The ID of the task to update the artifact for'),
+                content: z.string().optional().describe(`Updated markdown content for the ${phase} artifact`),
+                status: z.enum(['pending', 'in-progress', 'completed', 'failed', 'skipped']).optional().describe('Updated status of this phase'),
+                retries: z.number().min(0).optional().describe('Updated number of retry attempts'),
+                error: z.string().optional().describe('Updated error message')
+            },
+            handler: withErrorHandling(createUpdateHandler(phase, config, createStorage))
+        });
+        tools.push({
+            name: `delete_${phase}`,
+            description: OPERATION_DESCRIPTIONS.delete[phase],
+            parameters: {
+                workingDirectory: wdSchema,
+                taskId: taskIdSchema.describe('The ID of the task to delete the artifact from'),
+                confirm: z.boolean().describe('Must be set to true to confirm deletion (safety measure)')
+            },
+            handler: withErrorHandling(createDeleteHandler(phase, config, createStorage))
+        });
+    }
+    return tools;
+}

package/dist/features/task-management/tools/base/handlers.d.ts

@@ -0,0 +1,7 @@
+import { ToolHandler } from './types.js';
+import { McpToolResponse } from '../../../../types/common.js';
+/**
+ * Wrap a tool handler with top-level error handling.
+ * Any thrown error is converted to an MCP error response.
+ */
+export declare function withErrorHandling<TInput, TOutput extends McpToolResponse>(handler: ToolHandler<TInput, TOutput>): ToolHandler<TInput, TOutput>;

package/dist/features/task-management/tools/base/handlers.js

@@ -0,0 +1,15 @@
+import { createErrorResponse } from '../../../../utils/response-builder.js';
+/**
+ * Wrap a tool handler with top-level error handling.
+ * Any thrown error is converted to an MCP error response.
+ */
+export function withErrorHandling(handler) {
+    return async (input) => {
+        try {
+            return await handler(input);
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    };
+}

package/dist/features/task-management/tools/base/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './schemas.js';
+export * from './handlers.js';

package/dist/features/task-management/tools/base/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './schemas.js';
+export * from './handlers.js';

package/dist/features/task-management/tools/base/schemas.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare const workingDirectorySchema: z.ZodString;
+export declare const taskIdSchema: z.ZodString;

package/dist/features/task-management/tools/base/schemas.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import { ValidationLimits } from '../../../../utils/validation.js';
+export const workingDirectorySchema = z.string().min(1, 'Working directory is required');
+export const taskIdSchema = z.string()
+    .min(1, 'Task ID is required')
+    .max(ValidationLimits.TASK_ID_MAX_LENGTH);

package/dist/features/task-management/tools/base/types.d.ts

@@ -0,0 +1,13 @@
+import { McpToolResponse } from '../../../../types/common.js';
+/**
+ * Definition for a tool that can be registered with the MCP server.
+ * The handler uses a permissive input type because the MCP SDK
+ * validates params against the zod schemas at the protocol layer.
+ */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly handler: (params: any) => Promise<McpToolResponse>;
+}
+export type ToolHandler<TInput = Record<string, unknown>, TOutput = McpToolResponse> = (input: TInput) => Promise<TOutput>;

package/dist/features/task-management/tools/base/types.js

@@ -0,0 +1 @@
+export {};

package/dist/features/task-management/tools/tasks/index.d.ts

@@ -0,0 +1,10 @@
+import { Storage } from '../../storage/storage.js';
+import { ToolDefinition } from '../base/types.js';
+import { StorageConfig } from '../../../../utils/storage-config.js';
+type StorageFactory = (workingDirectory: string, config: StorageConfig) => Promise<Storage>;
+/**
+ * Create all task management tools using the same factory pattern as artifact tools.
+ * Each tool creates its own storage instance per-call using the provided factory.
+ */
+export declare function createTaskTools(config: StorageConfig, createStorage: StorageFactory): ToolDefinition[];
+export {};