@geanatz/cortex-mcp 5.0.1

package/dist/features/task-management/models/artifact.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Artifact types for the orchestration workflow
+ *
+ * Artifacts are phase-specific knowledge files stored alongside .task.json
+ * Each phase (explore, search, plan, build, test) produces an artifact
+ * that subsequent phases can read and build upon.
+ */
+/**
+ * Valid artifact phases in the orchestration workflow
+ */
+export declare const ARTIFACT_PHASES: readonly ["explore", "search", "plan", "build", "test"];
+export type ArtifactPhase = typeof ARTIFACT_PHASES[number];
+/**
+ * Required phases that must be present in every workflow
+ */
+export declare const REQUIRED_PHASES: readonly ArtifactPhase[];
+/**
+ * Optional phases that may be skipped
+ */
+export declare const OPTIONAL_PHASES: readonly ArtifactPhase[];
+/**
+ * Valid artifact status values
+ */
+export declare const ARTIFACT_STATUSES: readonly ["pending", "in-progress", "completed", "failed", "skipped"];
+export type ArtifactStatus = typeof ARTIFACT_STATUSES[number];
+/**
+ * Status display information
+ */
+export declare const ARTIFACT_STATUS_INFO: Record<ArtifactStatus, {
+    label: string;
+    icon: string;
+}>;
+/**
+ * Phase display information
+ */
+export declare const PHASE_INFO: Record<ArtifactPhase, {
+    label: string;
+    icon: string;
+    order: number;
+}>;
+/**
+ * Artifact metadata stored in YAML frontmatter
+ */
+export interface ArtifactMetadata {
+    /** Phase this artifact belongs to */
+    readonly phase: ArtifactPhase;
+    /** Status of this phase */
+    status: ArtifactStatus;
+    /** Timestamp when the artifact was created */
+    readonly createdAt: string;
+    /** Timestamp when the artifact was last updated */
+    updatedAt: string;
+    /** Number of retry attempts for this phase */
+    retries?: number;
+    /** Optional error message if status is 'failed' */
+    error?: string;
+}
+/**
+ * Complete artifact including metadata and content
+ */
+export interface Artifact {
+    /** Artifact metadata */
+    readonly metadata: ArtifactMetadata;
+    /** Markdown content of the artifact */
+    content: string;
+}
+/**
+ * Map of all artifacts for a task
+ */
+export type TaskArtifacts = {
+    readonly [K in ArtifactPhase]?: Artifact;
+};
+/**
+ * Input for creating an artifact
+ */
+export interface CreateArtifactInput {
+    /** Markdown content for the artifact body */
+    content: string;
+    /** Status of the phase (defaults to 'completed') */
+    status?: ArtifactStatus;
+    /** Number of retry attempts */
+    retries?: number;
+    /** Error message if status is 'failed' */
+    error?: string;
+}
+/**
+ * Input for updating an artifact
+ */
+export interface UpdateArtifactInput {
+    /** Markdown content for the artifact body */
+    content?: string;
+    /** Status of the phase */
+    status?: ArtifactStatus;
+    /** Number of retry attempts */
+    retries?: number;
+    /** Error message if status is 'failed' */
+    error?: string;
+}
+/**
+ * Get the filename for an artifact phase
+ */
+export declare function getArtifactFilename(phase: ArtifactPhase): string;
+/**
+ * Check if a phase is valid
+ */
+export declare function isValidPhase(phase: unknown): phase is ArtifactPhase;
+/**
+ * Check if a status is valid
+ */
+export declare function isValidArtifactStatus(status: unknown): status is ArtifactStatus;
+/**
+ * Get phase label
+ */
+export declare function getPhaseLabel(phase: ArtifactPhase): string;
+/**
+ * Get phase icon
+ */
+export declare function getPhaseIcon(phase: ArtifactPhase): string;
+/**
+ * Get status icon
+ */
+export declare function getArtifactStatusIcon(status: ArtifactStatus): string;
+/**
+ * Human-readable descriptions for each phase
+ */
+export declare const PHASE_DESCRIPTIONS: Record<ArtifactPhase, string>;
+/**
+ * Tool descriptions for each operation type
+ */
+export declare const OPERATION_DESCRIPTIONS: {
+    readonly create: {
+        readonly explore: "Create the explore artifact with codebase analysis findings. Use after analyzing the repository to document relevant files, logic entry points, and unknowns.";
+        readonly search: "Create the search artifact with external research findings. Use after web research to document patterns, best practices, and solutions found.";
+        readonly plan: "Create the plan artifact with the implementation approach. Use after designing the solution to document step-by-step implementation plan.";
+        readonly build: "Create the build artifact documenting implementation changes. Use after making code changes to document what was modified and why.";
+        readonly test: "Create the test artifact with verification results. Use after running tests to document results, pass/fail status, and any issues found.";
+    };
+    readonly update: {
+        readonly explore: "Update the explore artifact with additional analysis findings or corrections.";
+        readonly search: "Update the search artifact with additional research findings or corrections.";
+        readonly plan: "Update the plan artifact with revised approach or additional implementation steps.";
+        readonly build: "Update the build artifact with additional changes or corrections to the implementation record.";
+        readonly test: "Update the test artifact with additional test results or corrections.";
+    };
+    readonly delete: {
+        readonly explore: "Delete the explore artifact. Use to reset the exploration phase for re-analysis.";
+        readonly search: "Delete the search artifact. Use to reset the research phase for new research.";
+        readonly plan: "Delete the plan artifact. Use to reset the planning phase for a new approach.";
+        readonly build: "Delete the build artifact. Use to reset the build phase record.";
+        readonly test: "Delete the test artifact. Use to reset the testing phase for re-verification.";
+    };
+};
+/**
+ * Get workflow progress based on artifact statuses
+ */
+export declare function getWorkflowProgress(artifacts: TaskArtifacts): {
+    completed: number;
+    total: number;
+    percentage: number;
+    nextPhase?: ArtifactPhase;
+};
+/**
+ * Check if workflow is complete
+ */
+export declare function isWorkflowComplete(artifacts: TaskArtifacts): boolean;
+/**
+ * Get missing required phases
+ */
+export declare function getMissingRequiredPhases(artifacts: TaskArtifacts): ArtifactPhase[];

package/dist/features/task-management/models/artifact.js

@@ -0,0 +1,155 @@
+/**
+ * Artifact types for the orchestration workflow
+ *
+ * Artifacts are phase-specific knowledge files stored alongside .task.json
+ * Each phase (explore, search, plan, build, test) produces an artifact
+ * that subsequent phases can read and build upon.
+ */
+/**
+ * Valid artifact phases in the orchestration workflow
+ */
+export const ARTIFACT_PHASES = ['explore', 'search', 'plan', 'build', 'test'];
+/**
+ * Required phases that must be present in every workflow
+ */
+export const REQUIRED_PHASES = ['explore', 'plan', 'build'];
+/**
+ * Optional phases that may be skipped
+ */
+export const OPTIONAL_PHASES = ['search', 'test'];
+/**
+ * Valid artifact status values
+ */
+export const ARTIFACT_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'skipped'];
+/**
+ * Status display information
+ */
+export const ARTIFACT_STATUS_INFO = {
+    'pending': { label: 'Pending', icon: '⏳' },
+    'in-progress': { label: 'In Progress', icon: '🔄' },
+    'completed': { label: 'Completed', icon: '✅' },
+    'failed': { label: 'Failed', icon: '❌' },
+    'skipped': { label: 'Skipped', icon: '⏭️' },
+};
+/**
+ * Phase display information
+ */
+export const PHASE_INFO = {
+    explore: { label: 'Explore', icon: '🔍', order: 1 },
+    search: { label: 'Search', icon: '🌐', order: 2 },
+    plan: { label: 'Plan', icon: '📋', order: 3 },
+    build: { label: 'Build', icon: '🔨', order: 4 },
+    test: { label: 'Test', icon: '🧪', order: 5 },
+};
+/**
+ * Get the filename for an artifact phase
+ */
+export function getArtifactFilename(phase) {
+    return `${phase}.md`;
+}
+/**
+ * Check if a phase is valid
+ */
+export function isValidPhase(phase) {
+    return typeof phase === 'string' && ARTIFACT_PHASES.includes(phase);
+}
+/**
+ * Check if a status is valid
+ */
+export function isValidArtifactStatus(status) {
+    return typeof status === 'string' && ARTIFACT_STATUSES.includes(status);
+}
+/**
+ * Get phase label
+ */
+export function getPhaseLabel(phase) {
+    return PHASE_INFO[phase].label;
+}
+/**
+ * Get phase icon
+ */
+export function getPhaseIcon(phase) {
+    return PHASE_INFO[phase].icon;
+}
+/**
+ * Get status icon
+ */
+export function getArtifactStatusIcon(status) {
+    return ARTIFACT_STATUS_INFO[status].icon;
+}
+/**
+ * Human-readable descriptions for each phase
+ */
+export const PHASE_DESCRIPTIONS = {
+    explore: 'Codebase analysis and discovery findings',
+    search: 'External research and documentation findings',
+    plan: 'Implementation approach and step-by-step plan',
+    build: 'Implementation changes and modifications made',
+    test: 'Test execution results and verification status'
+};
+/**
+ * Tool descriptions for each operation type
+ */
+export const OPERATION_DESCRIPTIONS = {
+    create: {
+        explore: 'Create the explore artifact with codebase analysis findings. Use after analyzing the repository to document relevant files, logic entry points, and unknowns.',
+        search: 'Create the search artifact with external research findings. Use after web research to document patterns, best practices, and solutions found.',
+        plan: 'Create the plan artifact with the implementation approach. Use after designing the solution to document step-by-step implementation plan.',
+        build: 'Create the build artifact documenting implementation changes. Use after making code changes to document what was modified and why.',
+        test: 'Create the test artifact with verification results. Use after running tests to document results, pass/fail status, and any issues found.'
+    },
+    update: {
+        explore: 'Update the explore artifact with additional analysis findings or corrections.',
+        search: 'Update the search artifact with additional research findings or corrections.',
+        plan: 'Update the plan artifact with revised approach or additional implementation steps.',
+        build: 'Update the build artifact with additional changes or corrections to the implementation record.',
+        test: 'Update the test artifact with additional test results or corrections.'
+    },
+    delete: {
+        explore: 'Delete the explore artifact. Use to reset the exploration phase for re-analysis.',
+        search: 'Delete the search artifact. Use to reset the research phase for new research.',
+        plan: 'Delete the plan artifact. Use to reset the planning phase for a new approach.',
+        build: 'Delete the build artifact. Use to reset the build phase record.',
+        test: 'Delete the test artifact. Use to reset the testing phase for re-verification.'
+    }
+};
+/**
+ * Get workflow progress based on artifact statuses
+ */
+export function getWorkflowProgress(artifacts) {
+    let completed = 0;
+    let nextPhase;
+    for (const phase of ARTIFACT_PHASES) {
+        const artifact = artifacts[phase];
+        if (artifact?.metadata.status === 'completed') {
+            completed++;
+        }
+        else if (!nextPhase && artifact?.metadata.status !== 'skipped') {
+            nextPhase = phase;
+        }
+    }
+    return {
+        completed,
+        total: ARTIFACT_PHASES.length,
+        percentage: (completed / ARTIFACT_PHASES.length) * 100,
+        nextPhase,
+    };
+}
+/**
+ * Check if workflow is complete
+ */
+export function isWorkflowComplete(artifacts) {
+    return REQUIRED_PHASES.every(phase => {
+        const artifact = artifacts[phase];
+        return artifact?.metadata.status === 'completed';
+    });
+}
+/**
+ * Get missing required phases
+ */
+export function getMissingRequiredPhases(artifacts) {
+    return REQUIRED_PHASES.filter(phase => {
+        const artifact = artifacts[phase];
+        return !artifact || artifact.metadata.status !== 'completed';
+    });
+}

package/dist/features/task-management/models/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Configuration constants for the task management system
+ *
+ * Task ID = folder name (e.g., '001-implement-auth') - serves as the task title
+ * ID generated from details field using intelligent slug extraction
+ * Details can be comprehensive, ID is auto-generated from key parts
+ * No index.json - tasks are discovered by scanning folders
+ *
+ * Artifacts stored in task folders as {phase}.md files
+ * Each phase (explore, search, plan, build, test) has its own artifact
+ */
+/**
+ * Current schema version for the task storage format
+ * v9.0.0 - Simplified model: subtasks inline, no dependsOn, no parentId
+ */
+export declare const CURRENT_STORAGE_VERSION = "9.0.0";
+/**
+ * Storage paths configuration
+ */
+export declare const STORAGE_PATHS: {
+    /** Root directory for cortex data */
+    readonly ROOT_DIR: ".cortex";
+    /** Tasks directory name */
+    readonly TASKS_DIR: "tasks";
+    /** Task metadata filename */
+    readonly TASK_FILE: ".task.json";
+};
+/**
+ * Task numbering configuration
+ */
+export declare const TASK_NUMBERING: {
+    /** Number of digits for task numbers */
+    readonly DIGITS: 3;
+    /** Pattern for matching task folders */
+    readonly PATTERN: RegExp;
+};
+/**
+ * File naming constraints
+ */
+export declare const FILE_NAMING: {
+    /** Maximum length for task slug */
+    readonly MAX_SLUG_LENGTH: 50;
+    /** Maximum length for full task ID */
+    readonly MAX_ID_LENGTH: 100;
+};
+/**
+ * Cache configuration defaults
+ */
+export declare const CACHE_CONFIG: {
+    /** Default TTL in milliseconds */
+    readonly DEFAULT_TTL: number;
+    /** Maximum cache entries */
+    readonly MAX_SIZE: 1000;
+};

package/dist/features/task-management/models/config.js

@@ -0,0 +1,54 @@
+/**
+ * Configuration constants for the task management system
+ *
+ * Task ID = folder name (e.g., '001-implement-auth') - serves as the task title
+ * ID generated from details field using intelligent slug extraction
+ * Details can be comprehensive, ID is auto-generated from key parts
+ * No index.json - tasks are discovered by scanning folders
+ *
+ * Artifacts stored in task folders as {phase}.md files
+ * Each phase (explore, search, plan, build, test) has its own artifact
+ */
+/**
+ * Current schema version for the task storage format
+ * v9.0.0 - Simplified model: subtasks inline, no dependsOn, no parentId
+ */
+export const CURRENT_STORAGE_VERSION = '9.0.0';
+/**
+ * Storage paths configuration
+ */
+export const STORAGE_PATHS = {
+    /** Root directory for cortex data */
+    ROOT_DIR: '.cortex',
+    /** Tasks directory name */
+    TASKS_DIR: 'tasks',
+    /** Task metadata filename */
+    TASK_FILE: '.task.json',
+};
+/**
+ * Task numbering configuration
+ */
+export const TASK_NUMBERING = {
+    /** Number of digits for task numbers */
+    DIGITS: 3,
+    /** Pattern for matching task folders */
+    PATTERN: /^\d{3}-/,
+};
+/**
+ * File naming constraints
+ */
+export const FILE_NAMING = {
+    /** Maximum length for task slug */
+    MAX_SLUG_LENGTH: 50,
+    /** Maximum length for full task ID */
+    MAX_ID_LENGTH: 100,
+};
+/**
+ * Cache configuration defaults
+ */
+export const CACHE_CONFIG = {
+    /** Default TTL in milliseconds */
+    DEFAULT_TTL: 5 * 60 * 1000, // 5 minutes
+    /** Maximum cache entries */
+    MAX_SIZE: 1000,
+};

package/dist/features/task-management/models/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Models index - central exports for all model types
+ */
+export * from './task.js';
+export * from './artifact.js';
+export * from './config.js';

package/dist/features/task-management/models/index.js

@@ -0,0 +1,6 @@
+/**
+ * Models index - central exports for all model types
+ */
+export * from './task.js';
+export * from './artifact.js';
+export * from './config.js';

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

@@ -0,0 +1,173 @@
+/**
+ * Task data model for the task management system
+ * ID = folder name (e.g., '001-implement-auth') - acts as the task title
+ * Details = comprehensive description
+ *
+ * New Structure:
+ * - Each parent task has its own folder
+ * - Subtasks are stored INSIDE the parent .task.json file
+ * - No separate folders for subtasks
+ * - No dependsOn field - simplified dependency model
+ */
+/**
+ * Valid task status values
+ */
+export declare const TASK_STATUSES: readonly ["pending", "in_progress", "done"];
+export type TaskStatus = typeof TASK_STATUSES[number];
+/**
+ * Status display information
+ */
+export declare const TASK_STATUS_INFO: Record<TaskStatus, {
+    label: string;
+    icon: string;
+    description: string;
+}>;
+/**
+ * Subtask - simplified task for organizational purposes
+ * Stored inside parent task's subtasks array
+ * Single level only - subtasks cannot have their own subtasks
+ */
+export interface Subtask {
+    /** Subtask ID (simple incremental number: "1", "2", etc.) */
+    readonly id: string;
+    /** Subtask description */
+    details: string;
+    /** Subtask status */
+    status: TaskStatus;
+}
+/**
+ * Base task interface - parent task with all fields
+ * Each parent task has its own folder with .task.json
+ */
+export interface Task {
+    /** Unique identifier for the task (same as folder name, e.g., '001-implement-auth') */
+    readonly id: string;
+    /** Comprehensive task description with full context and requirements */
+    details: string;
+    /** Timestamp when the task was created */
+    readonly createdAt: string;
+    /** Timestamp when the task was last updated */
+    updatedAt: string;
+    /** Task status (pending, in_progress, done) */
+    status: TaskStatus;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+    /** Actual time spent in hours */
+    actualHours?: number;
+    /** Subtasks for organizational purposes */
+    subtasks: Subtask[];
+}
+/**
+ * Task without readonly fields (for internal updates)
+ */
+export type MutableTask = Omit<Task, 'id' | 'createdAt'> & {
+    id: string;
+    createdAt: string;
+};
+/**
+ * Input data for creating a new parent task
+ */
+export interface CreateTaskInput {
+    /** Task description - used to generate folder name/ID */
+    details: string;
+    /** Task status (defaults to 'pending') */
+    status?: TaskStatus;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+}
+/**
+ * Input for adding a new subtask
+ */
+export interface AddSubtaskInput {
+    /** Subtask description */
+    details: string;
+    /** Subtask status (defaults to 'pending') */
+    status?: TaskStatus;
+}
+/**
+ * Input for updating an existing subtask
+ */
+export interface UpdateSubtaskInput {
+    /** Subtask ID to update */
+    id: string;
+    /** Updated description (optional) */
+    details?: string;
+    /** Updated status (optional) */
+    status?: TaskStatus;
+}
+/**
+ * Input data for updating an existing parent task
+ * Supports updating parent fields and subtask operations
+ */
+export interface UpdateTaskInput {
+    /** Task description (optional) */
+    details?: string;
+    /** Task status */
+    status?: TaskStatus;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+    /** Actual time spent in hours */
+    actualHours?: number;
+    /** Add a new subtask */
+    addSubtask?: AddSubtaskInput;
+    /** Update an existing subtask */
+    updateSubtask?: UpdateSubtaskInput;
+    /** Remove subtask by ID */
+    removeSubtaskId?: string;
+}
+/**
+ * Task hierarchy helper types
+ */
+export interface TaskHierarchy {
+    readonly task: Task;
+    readonly depth: number;
+}
+/**
+ * Task summary for list views
+ */
+export interface TaskSummary {
+    readonly id: string;
+    readonly status: TaskStatus;
+    readonly subtaskCount: number;
+    readonly doneSubtaskCount: number;
+}
+/**
+ * Task filters for querying
+ */
+export interface TaskFilters {
+    readonly status?: TaskStatus | TaskStatus[];
+    readonly tags?: string[];
+    readonly includeDone?: boolean;
+}
+/**
+ * Check if a status is valid
+ */
+export declare function isValidTaskStatus(status: unknown): status is TaskStatus;
+/**
+ * Get status icon
+ */
+export declare function getStatusIcon(status: TaskStatus): string;
+/**
+ * Get status label
+ */
+export declare function getStatusLabel(status: TaskStatus): string;
+/**
+ * Check if task is done (including all subtasks)
+ */
+export declare function isTaskDone(task: Task): boolean;
+/**
+ * Calculate task progress (ratio of done subtasks)
+ */
+export declare function calculateTaskProgress(task: Task): number;
+/**
+ * Generate next subtask ID
+ */
+export declare function generateNextSubtaskId(subtasks: readonly Subtask[]): string;
+/**
+ * Find subtask by ID
+ */
+export declare function findSubtask(task: Task, subtaskId: string): Subtask | undefined;
+/**
+ * Check if all subtasks are done
+ */
+export declare function areAllSubtasksDone(task: Task): boolean;