@task-shepherd/agent 1.0.6 → 1.0.8

package/shared/dist/schema/validation.js

@@ -0,0 +1,282 @@
+/**
+ * Schema Validation System
+ *
+ * This module provides comprehensive validation for GraphQL schema consistency
+ * and MCP tool compatibility across all TasqHub components.
+ */
+import { introspectionFromSchema } from 'graphql';
+import { MCP_TOOL_MAPPINGS, getMCPToolMapping } from './mcp-mappings.js';
+/**
+ * Main schema validator class
+ */
+export class SchemaValidator {
+    constructor(schema) {
+        this.schema = null;
+        this.introspection = null;
+        if (schema) {
+            this.setSchema(schema);
+        }
+    }
+    /**
+     * Set the GraphQL schema to validate against
+     */
+    setSchema(schema) {
+        this.schema = schema;
+        this.introspection = introspectionFromSchema(schema);
+    }
+    /**
+     * Validate all MCP tool mappings against the current schema
+     */
+    validateMCPMappings() {
+        if (!this.schema || !this.introspection) {
+            return {
+                valid: false,
+                errors: [{
+                        type: 'INVALID_MAPPING',
+                        message: 'No GraphQL schema provided for validation',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        const errors = [];
+        const warnings = [];
+        // Validate each tool mapping
+        for (const category of MCP_TOOL_MAPPINGS) {
+            for (const tool of category.tools) {
+                const result = this.validateSingleTool(tool);
+                errors.push(...result.errors);
+                warnings.push(...result.warnings);
+            }
+        }
+        // Check for unused GraphQL operations
+        const usedOperations = new Set(MCP_TOOL_MAPPINGS.flatMap(cat => cat.tools.map(tool => tool.graphqlOperation)));
+        const allOperations = this.getAllGraphQLOperations();
+        for (const operation of allOperations) {
+            if (!usedOperations.has(operation)) {
+                warnings.push({
+                    type: 'UNUSED_OPERATION',
+                    message: `GraphQL operation '${operation}' is not mapped to any MCP tool`,
+                    suggestion: `Consider creating an MCP tool mapping for this operation or removing it if unused`
+                });
+            }
+        }
+        return {
+            valid: errors.filter(e => e.severity === 'error').length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Validate a single MCP tool mapping
+     */
+    validateSingleTool(tool) {
+        const errors = [];
+        const warnings = [];
+        // Check if the GraphQL operation exists
+        const operation = this.findGraphQLOperation(tool.graphqlOperation, tool.operationType);
+        if (!operation) {
+            errors.push({
+                type: 'MISSING_OPERATION',
+                message: `GraphQL ${tool.operationType} '${tool.graphqlOperation}' not found in schema`,
+                toolName: tool.toolName,
+                operationName: tool.graphqlOperation,
+                severity: 'error'
+            });
+            return { errors, warnings };
+        }
+        // Validate input schema compatibility
+        if (tool.inputSchema && operation.args) {
+            const inputValidation = this.validateInputSchema(tool, operation);
+            errors.push(...inputValidation.errors);
+            warnings.push(...inputValidation.warnings);
+        }
+        // Check for deprecated operations
+        if (tool.deprecated) {
+            warnings.push({
+                type: 'DEPRECATED_FIELD',
+                message: `MCP tool '${tool.toolName}' is deprecated: ${tool.deprecationReason || 'No reason provided'}`,
+                suggestion: 'Consider migrating to a newer tool or removing this mapping'
+            });
+        }
+        return { errors, warnings };
+    }
+    /**
+     * Find a GraphQL operation in the schema
+     */
+    findGraphQLOperation(operationName, operationType) {
+        if (!this.introspection)
+            return null;
+        const typeMap = this.introspection.data.__schema.types.reduce((map, type) => {
+            map[type.name] = type;
+            return map;
+        }, {});
+        let rootType;
+        switch (operationType) {
+            case 'query':
+                rootType = this.introspection.data.__schema.queryType.name;
+                break;
+            case 'mutation':
+                rootType = this.introspection.data.__schema.mutationType?.name;
+                break;
+            case 'subscription':
+                rootType = this.introspection.data.__schema.subscriptionType?.name;
+                break;
+            default:
+                return null;
+        }
+        if (!rootType || !typeMap[rootType])
+            return null;
+        const rootTypeFields = typeMap[rootType].fields;
+        return rootTypeFields?.find((field) => field.name === operationName);
+    }
+    /**
+     * Validate input schema compatibility
+     */
+    validateInputSchema(tool, operation) {
+        const errors = [];
+        const warnings = [];
+        // This is a simplified validation - in a real implementation,
+        // we would do deep type checking between JSON Schema and GraphQL types
+        if (tool.inputSchema?.required) {
+            const operationArgs = operation.args?.map((arg) => arg.name) || [];
+            for (const requiredField of tool.inputSchema.required) {
+                if (!operationArgs.includes(requiredField)) {
+                    errors.push({
+                        type: 'TYPE_MISMATCH',
+                        message: `Required field '${requiredField}' in MCP tool '${tool.toolName}' not found in GraphQL operation '${tool.graphqlOperation}'`,
+                        toolName: tool.toolName,
+                        operationName: tool.graphqlOperation,
+                        fieldPath: requiredField,
+                        severity: 'error'
+                    });
+                }
+            }
+        }
+        return { errors, warnings };
+    }
+    /**
+     * Get all GraphQL operations from the schema
+     */
+    getAllGraphQLOperations() {
+        if (!this.introspection)
+            return [];
+        const operations = [];
+        const typeMap = this.introspection.data.__schema.types.reduce((map, type) => {
+            map[type.name] = type;
+            return map;
+        }, {});
+        // Query operations
+        const queryType = this.introspection.data.__schema.queryType?.name;
+        if (queryType && typeMap[queryType]) {
+            operations.push(...typeMap[queryType].fields.map((field) => field.name));
+        }
+        // Mutation operations
+        const mutationType = this.introspection.data.__schema.mutationType?.name;
+        if (mutationType && typeMap[mutationType]) {
+            operations.push(...typeMap[mutationType].fields.map((field) => field.name));
+        }
+        // Subscription operations
+        const subscriptionType = this.introspection.data.__schema.subscriptionType?.name;
+        if (subscriptionType && typeMap[subscriptionType]) {
+            operations.push(...typeMap[subscriptionType].fields.map((field) => field.name));
+        }
+        return operations;
+    }
+    /**
+     * Check compatibility between two schemas (for migration validation)
+     */
+    static compareSchemas(oldSchema, newSchema) {
+        const oldIntrospection = introspectionFromSchema(oldSchema);
+        const newIntrospection = introspectionFromSchema(newSchema);
+        const breakingChanges = [];
+        const safeChanges = [];
+        const deprecations = [];
+        // This is a simplified implementation - in practice, you'd want to use
+        // a library like @graphql-inspector/core for comprehensive schema comparison
+        // Compare query operations
+        const oldQueries = this.getOperationsFromIntrospection(oldIntrospection, 'query');
+        const newQueries = this.getOperationsFromIntrospection(newIntrospection, 'query');
+        // Check for removed operations (breaking change)
+        for (const oldQuery of oldQueries) {
+            if (!newQueries.includes(oldQuery)) {
+                breakingChanges.push(`Removed query operation: ${oldQuery}`);
+            }
+        }
+        // Check for added operations (safe change)
+        for (const newQuery of newQueries) {
+            if (!oldQueries.includes(newQuery)) {
+                safeChanges.push(`Added query operation: ${newQuery}`);
+            }
+        }
+        return {
+            compatible: breakingChanges.length === 0,
+            breakingChanges,
+            safeChanges,
+            deprecations
+        };
+    }
+    /**
+     * Helper to extract operations from introspection
+     */
+    static getOperationsFromIntrospection(introspection, operationType) {
+        const typeMap = introspection.data.__schema.types.reduce((map, type) => {
+            map[type.name] = type;
+            return map;
+        }, {});
+        let rootTypeName;
+        switch (operationType) {
+            case 'query':
+                rootTypeName = introspection.data.__schema.queryType?.name;
+                break;
+            case 'mutation':
+                rootTypeName = introspection.data.__schema.mutationType?.name;
+                break;
+            case 'subscription':
+                rootTypeName = introspection.data.__schema.subscriptionType?.name;
+                break;
+        }
+        if (!rootTypeName || !typeMap[rootTypeName])
+            return [];
+        return typeMap[rootTypeName].fields?.map((field) => field.name) || [];
+    }
+    /**
+     * Validate a specific MCP tool operation
+     */
+    validateToolOperation(toolName, input) {
+        const mapping = getMCPToolMapping(toolName);
+        if (!mapping) {
+            return { valid: false, errors: [`Unknown MCP tool: ${toolName}`] };
+        }
+        const errors = [];
+        // Validate required fields
+        if (mapping.inputSchema?.required) {
+            for (const requiredField of mapping.inputSchema.required) {
+                if (!(requiredField in input)) {
+                    errors.push(`Missing required field: ${requiredField}`);
+                }
+            }
+        }
+        // Validate permissions (if user context is available)
+        // This would be implemented with actual user context in a real application
+        return { valid: errors.length === 0, errors };
+    }
+}
+/**
+ * Utility function to create a schema validator from a GraphQL schema file
+ */
+export async function createSchemaValidatorFromFile(schemaPath) {
+    // This would read the schema file and parse it
+    // For now, returning an empty validator
+    return new SchemaValidator();
+}
+/**
+ * Utility function to validate schema consistency across components
+ */
+export function validateCrossComponentConsistency(schemas) {
+    const validator = new SchemaValidator(schemas.backend);
+    const result = validator.validateMCPMappings();
+    // Additional cross-component validation logic would go here
+    // For example, checking that frontend GraphQL operations match backend schema
+    return result;
+}

package/shared/dist/work-queue/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Work Queue Types - Shared between backend and agent
+ *
+ * Provides consistent contracts for work assignments and AI work operations
+ */
+export * from './types.js';
+export * from './validation.js';

package/shared/dist/work-queue/index.js

@@ -0,0 +1,7 @@
+/**
+ * Work Queue Types - Shared between backend and agent
+ *
+ * Provides consistent contracts for work assignments and AI work operations
+ */
+export * from './types.js';
+export * from './validation.js';

package/shared/dist/work-queue/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Work Queue Types - Shared between backend and agent
+ */
+import { AIWorkStatus } from '../schema/index.js';
+/**
+ * Work Assignment structure passed from backend to agent
+ */
+export interface WorkAssignment {
+    assignmentId: string;
+    workerId: string;
+    workItemType: string;
+    workItemId: string;
+    priority: number;
+    assignedAt: Date;
+    deadline?: Date;
+    workData?: WorkData;
+    organizationId?: string;
+    organizationApiUrl?: string;
+    organizationApiKey?: string;
+}
+/**
+ * Work data structure containing work-specific information
+ */
+export interface WorkData {
+    workType: string;
+    projectId?: string;
+    projectName?: string;
+    project?: ProjectData;
+    storyId?: string;
+    storyTitle?: string;
+    story?: StoryData;
+    reviewId?: string;
+    applicationDetails?: ReviewApplicationDetails;
+    applicationPrompt?: string;
+    focusAreas?: string[];
+    customInstructions?: string;
+    organizationId?: string;
+    organizationApiUrl?: string;
+    organizationApiKey?: string;
+    progress?: WorkProgress;
+    lastError?: string;
+    attemptCount?: number;
+    maxRetryAttempts?: number;
+    createdAt?: string;
+    claimedAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    status?: string;
+    priority?: number;
+    aiWorkerId?: string;
+    metadata?: Record<string, any>;
+    developmentPlanId?: string;
+    originalPlanId?: string;
+    isReprompt?: boolean;
+    repromptContext?: string;
+    previousReviewId?: string;
+}
+/**
+ * Project data structure
+ */
+export interface ProjectData {
+    id: string;
+    name: string;
+    description?: string;
+    repositoryUrl?: string;
+    workspaceConfig?: WorkspaceConfigData;
+    workspaces?: WorkspaceData[];
+}
+/**
+ * Story data structure
+ */
+export interface StoryData {
+    id: string;
+    title: string;
+    description?: string;
+    project?: ProjectData;
+}
+/**
+ * Workspace configuration data
+ */
+export interface WorkspaceConfigData {
+    workspace?: {
+        paths?: {
+            root?: string;
+        };
+    };
+    [key: string]: any;
+}
+/**
+ * Workspace data structure
+ */
+export interface WorkspaceData {
+    id?: string;
+    name?: string;
+    path?: string;
+    [key: string]: any;
+}
+/**
+ * Work progress structure
+ */
+export interface WorkProgress {
+    assignmentId: string;
+    stage: string;
+    progressPercentage: number;
+    currentStep: string;
+    message: string;
+    updatedAt: Date;
+    estimatedCompletion?: Date;
+    metadata?: Record<string, any>;
+}
+/**
+ * Review application details
+ */
+export interface ReviewApplicationDetails {
+    reviewId?: string;
+    applicationPrompt?: string;
+    focusAreas?: string[];
+    customInstructions?: string;
+    [key: string]: any;
+}
+/**
+ * GraphQL UpdateAIWorkInput - matches backend schema exactly
+ */
+export interface UpdateAIWorkInput {
+    workId: string;
+    status?: AIWorkStatus;
+    metadataJson?: string;
+    priority?: number;
+}
+/**
+ * Work validation result
+ */
+export interface WorkValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+export interface ValidationWarning {
+    field: string;
+    message: string;
+    code: string;
+}

package/shared/dist/work-queue/types.js

@@ -0,0 +1,4 @@
+/**
+ * Work Queue Types - Shared between backend and agent
+ */
+export {};

package/shared/dist/work-queue/validation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Work Queue Validation - Shared validation utilities
+ */
+import { WorkAssignment, WorkData, WorkValidationResult } from './types.js';
+/**
+ * Validate work assignment structure
+ */
+export declare function validateWorkAssignment(assignment: WorkAssignment): WorkValidationResult;
+/**
+ * Validate work data structure
+ */
+export declare function validateWorkData(workData: WorkData): WorkValidationResult;
+/**
+ * Check if work assignment is expired based on deadline
+ */
+export declare function isWorkAssignmentExpired(assignment: WorkAssignment): boolean;
+/**
+ * Get work assignment age in milliseconds
+ */
+export declare function getWorkAssignmentAge(assignment: WorkAssignment): number;
+/**
+ * Check if work assignment is considered stale (older than specified duration)
+ */
+export declare function isWorkAssignmentStale(assignment: WorkAssignment, staleThresholdMs?: number): boolean;

package/shared/dist/work-queue/validation.js

@@ -0,0 +1,160 @@
+/**
+ * Work Queue Validation - Shared validation utilities
+ */
+/**
+ * Validate work assignment structure
+ */
+export function validateWorkAssignment(assignment) {
+    const errors = [];
+    const warnings = [];
+    // Required fields validation
+    if (!assignment.assignmentId || assignment.assignmentId.trim() === '') {
+        errors.push({
+            field: 'assignmentId',
+            message: 'Assignment ID is required',
+            code: 'MISSING_ASSIGNMENT_ID'
+        });
+    }
+    if (!assignment.workerId || assignment.workerId.trim() === '') {
+        errors.push({
+            field: 'workerId',
+            message: 'Worker ID is required',
+            code: 'MISSING_WORKER_ID'
+        });
+    }
+    if (!assignment.workItemType || assignment.workItemType.trim() === '') {
+        errors.push({
+            field: 'workItemType',
+            message: 'Work item type is required',
+            code: 'MISSING_WORK_ITEM_TYPE'
+        });
+    }
+    if (!assignment.workItemId || assignment.workItemId.trim() === '') {
+        errors.push({
+            field: 'workItemId',
+            message: 'Work item ID is required',
+            code: 'MISSING_WORK_ITEM_ID'
+        });
+    }
+    if (typeof assignment.priority !== 'number' || assignment.priority < 0) {
+        errors.push({
+            field: 'priority',
+            message: 'Priority must be a non-negative number',
+            code: 'INVALID_PRIORITY'
+        });
+    }
+    if (!assignment.assignedAt || !(assignment.assignedAt instanceof Date)) {
+        errors.push({
+            field: 'assignedAt',
+            message: 'Assigned date is required and must be a Date object',
+            code: 'INVALID_ASSIGNED_DATE'
+        });
+    }
+    // Deadline validation (warning if in the past)
+    if (assignment.deadline && assignment.deadline instanceof Date) {
+        if (assignment.deadline < new Date()) {
+            warnings.push({
+                field: 'deadline',
+                message: 'Deadline is in the past',
+                code: 'PAST_DEADLINE'
+            });
+        }
+    }
+    // Work data validation
+    if (assignment.workData) {
+        const workDataValidation = validateWorkData(assignment.workData);
+        errors.push(...workDataValidation.errors);
+        warnings.push(...workDataValidation.warnings);
+    }
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+/**
+ * Validate work data structure
+ */
+export function validateWorkData(workData) {
+    const errors = [];
+    const warnings = [];
+    // Work type validation
+    if (!workData.workType || workData.workType.trim() === '') {
+        errors.push({
+            field: 'workType',
+            message: 'Work type is required in work data',
+            code: 'MISSING_WORK_TYPE'
+        });
+    }
+    // Organization context validation
+    if (workData.organizationId && !workData.organizationApiUrl) {
+        warnings.push({
+            field: 'organizationApiUrl',
+            message: 'Organization API URL should be provided when organization ID is set',
+            code: 'MISSING_ORG_API_URL'
+        });
+    }
+    if (workData.organizationApiUrl && !workData.organizationApiKey) {
+        warnings.push({
+            field: 'organizationApiKey',
+            message: 'Organization API key should be provided when organization API URL is set',
+            code: 'MISSING_ORG_API_KEY'
+        });
+    }
+    // Progress validation
+    if (workData.progress) {
+        if (workData.progress.progressPercentage < 0 || workData.progress.progressPercentage > 100) {
+            errors.push({
+                field: 'progress.progressPercentage',
+                message: 'Progress percentage must be between 0 and 100',
+                code: 'INVALID_PROGRESS_PERCENTAGE'
+            });
+        }
+    }
+    // Retry validation
+    if (workData.maxRetryAttempts !== undefined && workData.maxRetryAttempts < 0) {
+        errors.push({
+            field: 'maxRetryAttempts',
+            message: 'Max retry attempts must be non-negative',
+            code: 'INVALID_MAX_RETRY_ATTEMPTS'
+        });
+    }
+    if (workData.attemptCount !== undefined && workData.attemptCount < 0) {
+        errors.push({
+            field: 'attemptCount',
+            message: 'Attempt count must be non-negative',
+            code: 'INVALID_ATTEMPT_COUNT'
+        });
+    }
+    if (workData.attemptCount !== undefined && workData.maxRetryAttempts !== undefined &&
+        workData.attemptCount > workData.maxRetryAttempts) {
+        warnings.push({
+            field: 'attemptCount',
+            message: 'Attempt count exceeds maximum retry attempts',
+            code: 'EXCEEDED_MAX_RETRIES'
+        });
+    }
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+/**
+ * Check if work assignment is expired based on deadline
+ */
+export function isWorkAssignmentExpired(assignment) {
+    return assignment.deadline ? assignment.deadline < new Date() : false;
+}
+/**
+ * Get work assignment age in milliseconds
+ */
+export function getWorkAssignmentAge(assignment) {
+    return Date.now() - assignment.assignedAt.getTime();
+}
+/**
+ * Check if work assignment is considered stale (older than specified duration)
+ */
+export function isWorkAssignmentStale(assignment, staleThresholdMs = 3600000) {
+    return getWorkAssignmentAge(assignment) > staleThresholdMs;
+}