@allpepper/task-orchestrator 0.1.0

package/src/tools/query-workflow-state.ts

@@ -0,0 +1,198 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse, uuidSchema } from './registry';
+import { getProject } from '../repos/projects';
+import { getFeature } from '../repos/features';
+import { getTask } from '../repos/tasks';
+import { getDependencies } from '../repos/dependencies';
+import { ProjectStatus, FeatureStatus, TaskStatus } from '../domain/types';
+
+/**
+ * Status transition maps (same as get-next-status.ts)
+ *
+ * Note: CANCELLED and DEFERRED are intentionally non-terminal statuses.
+ * They allow transitions back to earlier workflow stages (BACKLOG/PENDING for tasks,
+ * PLANNING for projects) to support reinstating cancelled or deferred work.
+ */
+const PROJECT_TRANSITIONS: Record<ProjectStatus, ProjectStatus[]> = {
+  [ProjectStatus.PLANNING]: [ProjectStatus.IN_DEVELOPMENT, ProjectStatus.ON_HOLD, ProjectStatus.CANCELLED],
+  [ProjectStatus.IN_DEVELOPMENT]: [ProjectStatus.COMPLETED, ProjectStatus.ON_HOLD, ProjectStatus.CANCELLED],
+  [ProjectStatus.ON_HOLD]: [ProjectStatus.PLANNING, ProjectStatus.IN_DEVELOPMENT, ProjectStatus.CANCELLED],
+  [ProjectStatus.COMPLETED]: [ProjectStatus.ARCHIVED],
+  [ProjectStatus.CANCELLED]: [ProjectStatus.PLANNING], // Non-terminal: allows reinstating cancelled projects
+  [ProjectStatus.ARCHIVED]: []
+};
+
+const FEATURE_TRANSITIONS: Record<FeatureStatus, FeatureStatus[]> = {
+  [FeatureStatus.DRAFT]: [FeatureStatus.PLANNING],
+  [FeatureStatus.PLANNING]: [FeatureStatus.IN_DEVELOPMENT, FeatureStatus.ON_HOLD],
+  [FeatureStatus.IN_DEVELOPMENT]: [FeatureStatus.TESTING, FeatureStatus.BLOCKED, FeatureStatus.ON_HOLD],
+  [FeatureStatus.TESTING]: [FeatureStatus.VALIDATING, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.VALIDATING]: [FeatureStatus.PENDING_REVIEW, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.PENDING_REVIEW]: [FeatureStatus.DEPLOYED, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.BLOCKED]: [FeatureStatus.IN_DEVELOPMENT, FeatureStatus.ON_HOLD],
+  [FeatureStatus.ON_HOLD]: [FeatureStatus.PLANNING, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.DEPLOYED]: [FeatureStatus.COMPLETED],
+  [FeatureStatus.COMPLETED]: [FeatureStatus.ARCHIVED],
+  [FeatureStatus.ARCHIVED]: []
+};
+
+const TASK_TRANSITIONS: Record<TaskStatus, TaskStatus[]> = {
+  [TaskStatus.BACKLOG]: [TaskStatus.PENDING],
+  [TaskStatus.PENDING]: [TaskStatus.IN_PROGRESS, TaskStatus.BLOCKED, TaskStatus.ON_HOLD, TaskStatus.CANCELLED, TaskStatus.DEFERRED],
+  [TaskStatus.IN_PROGRESS]: [TaskStatus.IN_REVIEW, TaskStatus.TESTING, TaskStatus.BLOCKED, TaskStatus.ON_HOLD, TaskStatus.COMPLETED],
+  [TaskStatus.IN_REVIEW]: [TaskStatus.CHANGES_REQUESTED, TaskStatus.COMPLETED],
+  [TaskStatus.CHANGES_REQUESTED]: [TaskStatus.IN_PROGRESS],
+  [TaskStatus.TESTING]: [TaskStatus.READY_FOR_QA, TaskStatus.IN_PROGRESS],
+  [TaskStatus.READY_FOR_QA]: [TaskStatus.INVESTIGATING, TaskStatus.DEPLOYED, TaskStatus.COMPLETED],
+  [TaskStatus.INVESTIGATING]: [TaskStatus.IN_PROGRESS, TaskStatus.BLOCKED],
+  [TaskStatus.BLOCKED]: [TaskStatus.PENDING, TaskStatus.IN_PROGRESS],
+  [TaskStatus.ON_HOLD]: [TaskStatus.PENDING, TaskStatus.IN_PROGRESS],
+  [TaskStatus.DEPLOYED]: [TaskStatus.COMPLETED],
+  [TaskStatus.COMPLETED]: [], // Terminal: no transitions allowed
+  [TaskStatus.CANCELLED]: [TaskStatus.BACKLOG, TaskStatus.PENDING], // Non-terminal: allows reinstating cancelled tasks
+  [TaskStatus.DEFERRED]: [TaskStatus.BACKLOG, TaskStatus.PENDING] // Non-terminal: allows resuming deferred tasks
+};
+
+/**
+ * Register the query_workflow_state MCP tool.
+ *
+ * Returns the full workflow state for a container including current status,
+ * allowed transitions, and dependency information for tasks.
+ *
+ * Note: CANCELLED and DEFERRED statuses can transition back to earlier stages
+ * (BACKLOG/PENDING for tasks, PLANNING for projects) to support work reinstatement.
+ */
+export function registerQueryWorkflowStateTool(server: McpServer): void {
+  server.tool(
+    'query_workflow_state',
+    'Query the full workflow state for a container. Returns current status, allowed transitions, whether the status is terminal, and for tasks also includes dependency information (blocking/blocked-by tasks and whether all blockers are resolved).',
+    {
+      containerType: z.enum(['project', 'feature', 'task']).describe('Type of container (project, feature, or task)'),
+      id: uuidSchema.describe('ID of the container')
+    },
+    async (params: any) => {
+      try {
+        const { containerType, id } = params;
+
+        let currentStatus: string;
+        let allowedTransitions: string[] = [];
+        let dependencies: any = undefined;
+
+        switch (containerType) {
+          case 'project': {
+            const result = getProject(id);
+            if (!result.success) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify(createErrorResponse(result.error, result.code), null, 2)
+                }]
+              };
+            }
+
+            currentStatus = result.data.status;
+            allowedTransitions = PROJECT_TRANSITIONS[currentStatus as ProjectStatus] || [];
+            break;
+          }
+
+          case 'feature': {
+            const result = getFeature(id);
+            if (!result.success) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify(createErrorResponse(result.error, result.code), null, 2)
+                }]
+              };
+            }
+
+            currentStatus = result.data.status;
+            allowedTransitions = FEATURE_TRANSITIONS[currentStatus as FeatureStatus] || [];
+            break;
+          }
+
+          case 'task': {
+            const taskResult = getTask(id);
+            if (!taskResult.success) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify(createErrorResponse(taskResult.error, taskResult.code), null, 2)
+                }]
+              };
+            }
+
+            currentStatus = taskResult.data.status;
+            allowedTransitions = TASK_TRANSITIONS[currentStatus as TaskStatus] || [];
+
+            // Get dependencies for tasks
+            const depsResult = getDependencies(id, 'both');
+            if (depsResult.success) {
+              const blocking = depsResult.data.filter(d => d.fromTaskId === id && d.type === 'BLOCKS');
+              const blockedBy = depsResult.data.filter(d => d.toTaskId === id && d.type === 'BLOCKS');
+
+              // Check if all blockers are resolved
+              const allBlockersResolved = blockedBy.length === 0 || blockedBy.every(dep => {
+                const blockerResult = getTask(dep.fromTaskId);
+                if (!blockerResult.success) return false;
+                const blockerStatus = blockerResult.data.status;
+                return blockerStatus === TaskStatus.COMPLETED || blockerStatus === TaskStatus.CANCELLED;
+              });
+
+              dependencies = {
+                blocking: blocking.map(d => d.toTaskId),
+                blockedBy: blockedBy.map(d => d.fromTaskId),
+                allBlockersResolved
+              };
+            }
+            break;
+          }
+
+          default:
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify(
+                  createErrorResponse(`Invalid container type: ${containerType}`, 'VALIDATION_ERROR'),
+                  null,
+                  2
+                )
+              }]
+            };
+        }
+
+        const workflowState = {
+          id,
+          containerType,
+          currentStatus,
+          allowedTransitions,
+          isTerminal: allowedTransitions.length === 0,
+          ...(dependencies && { dependencies })
+        };
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse('Workflow state retrieved successfully', workflowState),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse('Failed to query workflow state', error.message),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/registry.ts

@@ -0,0 +1,180 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+// --- Shared UUID schemas ---
+// These schemas accept standard dashed UUIDs and transform them to dashless format
+// to match the storage format in the database
+export const uuidSchema = z.string().uuid().transform(v => v.replace(/-/g, '').toLowerCase());
+export const optionalUuidSchema = z.string().uuid().optional().transform(v => v ? v.replace(/-/g, '').toLowerCase() : undefined);
+
+// --- Tool Definition interface ---
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, any>;  // Zod schemas
+  execute: (params: Record<string, any>) => Promise<ToolResponse>;
+}
+
+// --- Standard response format ---
+export interface ToolResponse {
+  success: boolean;
+  message: string;
+  data?: any;
+  error?: string;
+  metadata?: {
+    timestamp: string;
+    version: string;
+  };
+}
+
+export function createSuccessResponse(message: string, data: any): ToolResponse {
+  return {
+    success: true,
+    message,
+    data,
+    metadata: {
+      timestamp: new Date().toISOString(),
+      version: '1.0.0'
+    }
+  };
+}
+
+export function createErrorResponse(message: string, error?: string): ToolResponse {
+  return {
+    success: false,
+    message,
+    error: error || message,
+    metadata: {
+      timestamp: new Date().toISOString(),
+      version: '1.0.0'
+    }
+  };
+}
+
+// --- Parameter validation helpers ---
+
+export function requireString(params: Record<string, any>, key: string): string {
+  const value = params[key];
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`Required string parameter '${key}' is missing or empty`);
+  }
+  return value.trim();
+}
+
+export function optionalString(params: Record<string, any>, key: string): string | undefined {
+  const value = params[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') throw new Error(`Parameter '${key}' must be a string`);
+  return value.trim() || undefined;
+}
+
+export function requireUUID(params: Record<string, any>, key: string): string {
+  const value = requireString(params, key);
+  // Accept both dashed and non-dashed UUID formats
+  const uuidRegex = /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i;
+  if (!uuidRegex.test(value)) {
+    throw new Error(`Parameter '${key}' must be a valid UUID`);
+  }
+  return value.replace(/-/g, '').toLowerCase();
+}
+
+export function optionalUUID(params: Record<string, any>, key: string): string | undefined {
+  const value = params[key];
+  if (value === undefined || value === null) return undefined;
+  return requireUUID(params, key);
+}
+
+export function requireBoolean(params: Record<string, any>, key: string): boolean {
+  const value = params[key];
+  if (typeof value !== 'boolean') {
+    throw new Error(`Required boolean parameter '${key}' is missing`);
+  }
+  return value;
+}
+
+export function optionalBoolean(params: Record<string, any>, key: string, defaultValue?: boolean): boolean | undefined {
+  const value = params[key];
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value !== 'boolean') throw new Error(`Parameter '${key}' must be a boolean`);
+  return value;
+}
+
+export function requireInteger(params: Record<string, any>, key: string): number {
+  const value = params[key];
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new Error(`Required integer parameter '${key}' is missing or not an integer`);
+  }
+  return value;
+}
+
+export function optionalInteger(params: Record<string, any>, key: string, defaultValue?: number): number | undefined {
+  const value = params[key];
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new Error(`Parameter '${key}' must be an integer`);
+  }
+  return value;
+}
+
+export function requireEnum<T extends string>(params: Record<string, any>, key: string, validValues: readonly T[]): T {
+  const value = requireString(params, key).toUpperCase() as T;
+  if (!validValues.includes(value)) {
+    throw new Error(`Parameter '${key}' must be one of: ${validValues.join(', ')}`);
+  }
+  return value;
+}
+
+export function optionalEnum<T extends string>(params: Record<string, any>, key: string, validValues: readonly T[]): T | undefined {
+  const value = optionalString(params, key);
+  if (!value) return undefined;
+  const upper = value.toUpperCase() as T;
+  if (!validValues.includes(upper)) {
+    throw new Error(`Parameter '${key}' must be one of: ${validValues.join(', ')}`);
+  }
+  return upper;
+}
+
+// --- Error codes ---
+export enum ErrorCode {
+  NOT_FOUND = 'NOT_FOUND',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  CONFLICT = 'CONFLICT',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  INVALID_OPERATION = 'INVALID_OPERATION',
+  CIRCULAR_DEPENDENCY = 'CIRCULAR_DEPENDENCY',
+}
+
+// --- Tool registration helper ---
+// This will be used to register tools with the MCP server instance
+export function registerTool(server: McpServer, tool: ToolDefinition): void {
+  server.tool(
+    tool.name,
+    tool.description,
+    tool.parameters,
+    async (params: any) => {
+      try {
+        const response = await tool.execute(params);
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(response, null, 2)
+          }]
+        };
+      } catch (error: any) {
+        const response = createErrorResponse(
+          error.message || 'Internal error',
+          error.name === 'NotFoundError' ? ErrorCode.NOT_FOUND
+            : error.name === 'ValidationError' ? ErrorCode.VALIDATION_ERROR
+            : error.name === 'ConflictError' ? ErrorCode.CONFLICT
+            : ErrorCode.INTERNAL_ERROR
+        );
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(response, null, 2)
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/rename-tag.ts

@@ -0,0 +1,64 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse } from './registry';
+import { renameTag } from '../repos/tags';
+
+/**
+ * Register the rename_tag MCP tool
+ * Renames a tag across all entities, with optional dry-run mode
+ */
+export function registerRenameTagTool(server: McpServer): void {
+  server.tool(
+    'rename_tag',
+    'Rename a tag across all entities',
+    {
+      oldTag: z.string().describe('Current tag name'),
+      newTag: z.string().describe('New tag name'),
+      dryRun: z.boolean().optional().default(false).describe('Preview changes without applying them')
+    },
+    async (params) => {
+      try {
+        const result = renameTag(
+          params.oldTag,
+          params.newTag,
+          { dryRun: params.dryRun ?? false }
+        );
+
+        if (!result.success) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(createErrorResponse(result.error), null, 2)
+            }]
+          };
+        }
+
+        const message = params.dryRun
+          ? `Dry run: Would affect ${result.data.affected} entities`
+          : `Tag renamed successfully, affected ${result.data.affected} entities`;
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse(message, result.data),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse(error.message || 'Failed to rename tag'),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/setup-project.ts

@@ -0,0 +1,189 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse } from './registry';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_CONFIG_YAML = `# Task Orchestrator Configuration
+version: "2.0"
+
+workflows:
+  project:
+    statuses:
+      - PLANNING
+      - IN_DEVELOPMENT
+      - ON_HOLD
+      - CANCELLED
+      - COMPLETED
+      - ARCHIVED
+    transitions:
+      PLANNING: [IN_DEVELOPMENT, ON_HOLD, CANCELLED]
+      IN_DEVELOPMENT: [COMPLETED, ON_HOLD, CANCELLED]
+      ON_HOLD: [PLANNING, IN_DEVELOPMENT, CANCELLED]
+      COMPLETED: [ARCHIVED]
+      CANCELLED: [PLANNING]
+      ARCHIVED: []
+
+  feature:
+    statuses:
+      - DRAFT
+      - PLANNING
+      - IN_DEVELOPMENT
+      - TESTING
+      - VALIDATING
+      - PENDING_REVIEW
+      - BLOCKED
+      - ON_HOLD
+      - DEPLOYED
+      - COMPLETED
+      - ARCHIVED
+    transitions:
+      DRAFT: [PLANNING]
+      PLANNING: [IN_DEVELOPMENT, ON_HOLD]
+      IN_DEVELOPMENT: [TESTING, BLOCKED, ON_HOLD]
+      TESTING: [VALIDATING, IN_DEVELOPMENT]
+      VALIDATING: [PENDING_REVIEW, IN_DEVELOPMENT]
+      PENDING_REVIEW: [DEPLOYED, IN_DEVELOPMENT]
+      BLOCKED: [IN_DEVELOPMENT, ON_HOLD]
+      ON_HOLD: [PLANNING, IN_DEVELOPMENT]
+      DEPLOYED: [COMPLETED]
+      COMPLETED: [ARCHIVED]
+      ARCHIVED: []
+
+  task:
+    statuses:
+      - BACKLOG
+      - PENDING
+      - IN_PROGRESS
+      - IN_REVIEW
+      - CHANGES_REQUESTED
+      - TESTING
+      - READY_FOR_QA
+      - INVESTIGATING
+      - BLOCKED
+      - ON_HOLD
+      - DEPLOYED
+      - COMPLETED
+      - CANCELLED
+      - DEFERRED
+    transitions:
+      BACKLOG: [PENDING]
+      PENDING: [IN_PROGRESS, BLOCKED, ON_HOLD, CANCELLED, DEFERRED]
+      IN_PROGRESS: [IN_REVIEW, TESTING, BLOCKED, ON_HOLD, COMPLETED]
+      IN_REVIEW: [CHANGES_REQUESTED, COMPLETED]
+      CHANGES_REQUESTED: [IN_PROGRESS]
+      TESTING: [READY_FOR_QA, IN_PROGRESS]
+      READY_FOR_QA: [INVESTIGATING, DEPLOYED, COMPLETED]
+      INVESTIGATING: [IN_PROGRESS, BLOCKED]
+      BLOCKED: [PENDING, IN_PROGRESS]
+      ON_HOLD: [PENDING, IN_PROGRESS]
+      DEPLOYED: [COMPLETED]
+      COMPLETED: []
+      CANCELLED: [BACKLOG, PENDING]
+      DEFERRED: [BACKLOG, PENDING]
+`;
+
+/**
+ * Sets up a project with Task Orchestrator configuration
+ * Creates .taskorchestrator/config.yaml with default status workflows
+ * Idempotent - skips if configuration already exists
+ */
+export function registerSetupProjectTool(server: McpServer): void {
+  server.tool(
+    'setup_project',
+    'Set up Task Orchestrator configuration in a project. Creates .taskorchestrator/config.yaml with default workflow definitions for projects, features, and tasks. Idempotent - safely skips if already configured.',
+    {
+      projectPath: z
+        .string()
+        .optional()
+        .describe('Project directory path. Defaults to current working directory.'),
+    },
+    async (params: any) => {
+      try {
+        // Determine project path
+        const projectPath = params.projectPath || process.cwd();
+        const configDir = join(projectPath, '.taskorchestrator');
+        const configFilePath = join(configDir, 'config.yaml');
+
+        // Check if config already exists
+        if (existsSync(configFilePath)) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: JSON.stringify(
+                  createSuccessResponse(
+                    'Project already configured',
+                    {
+                      path: configFilePath,
+                      alreadyExists: true,
+                      message: 'Configuration file already exists. No changes made.',
+                    }
+                  ),
+                  null,
+                  2
+                ),
+              },
+            ],
+          };
+        }
+
+        // Create directory if it doesn't exist
+        if (!existsSync(configDir)) {
+          mkdirSync(configDir, { recursive: true });
+        }
+
+        // Write default configuration
+        writeFileSync(configFilePath, DEFAULT_CONFIG_YAML, 'utf-8');
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                createSuccessResponse('Project configured successfully', {
+                  path: configFilePath,
+                  created: true,
+                  message:
+                    'Created .taskorchestrator/config.yaml with default workflow definitions.',
+                  workflows: {
+                    project: {
+                      statuses: 6,
+                      description: 'Project lifecycle management',
+                    },
+                    feature: {
+                      statuses: 11,
+                      description: 'Feature development workflow',
+                    },
+                    task: {
+                      statuses: 14,
+                      description: 'Task tracking workflow',
+                    },
+                  },
+                }),
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                createErrorResponse(
+                  `Failed to set up project: ${error.message}`,
+                  error.stack
+                ),
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    }
+  );
+}