sqlew 3.7.4 → 3.8.0

package/dist/utils/action-specs/task-specs.js

@@ -0,0 +1,143 @@
+/**
+ * Task Tool Action Specifications
+ *
+ * Parameter requirements and examples for all task tool actions (12 actions).
+ * Used for Kanban task management with dependencies and file watching.
+ */
+export const TASK_ACTION_SPECS = {
+    create: {
+        required: ['title'],
+        optional: ['description', 'acceptance_criteria', 'notes', 'priority', 'assigned_agent', 'created_by_agent', 'layer', 'tags', 'status', 'watch_files', 'file_actions'],
+        example: {
+            action: 'create',
+            title: 'Implement JWT authentication',
+            description: 'Add JWT-based authentication to /api/login endpoint',
+            priority: 3,
+            assigned_agent: 'backend-agent',
+            layer: 'business',
+            tags: ['authentication', 'security'],
+            file_actions: [{ action: 'create', path: 'src/api/auth.ts' }, { action: 'edit', path: 'src/middleware/jwt.ts' }]
+        },
+        hint: "⭐ v3.8.0: Use file_actions for layer-based validation. Priority: 1=low, 2=medium, 3=high, 4=critical. Code layers REQUIRE file_actions."
+    },
+    update: {
+        required: ['task_id'],
+        optional: ['title', 'priority', 'assigned_agent', 'layer', 'description', 'acceptance_criteria', 'notes', 'watch_files', 'file_actions'],
+        example: {
+            action: 'update',
+            task_id: 5,
+            priority: 4,
+            assigned_agent: 'senior-backend-agent',
+            file_actions: [{ action: 'edit', path: 'src/api/users.ts' }]
+        },
+        hint: "v3.8.0: file_actions replaces watch_files. Only specified fields will be updated; others remain unchanged"
+    },
+    get: {
+        required: ['task_id'],
+        optional: ['include_dependencies'],
+        example: {
+            action: 'get',
+            task_id: 5,
+            include_dependencies: true
+        },
+        hint: "Set include_dependencies=true to see blocking/blocked relationships"
+    },
+    list: {
+        required: [],
+        optional: ['status', 'assigned_agent', 'layer', 'tags', 'limit', 'offset', 'include_dependency_counts'],
+        example: {
+            action: 'list',
+            status: 'in_progress',
+            assigned_agent: 'backend-agent',
+            limit: 20
+        },
+        hint: "Valid statuses: todo, in_progress, waiting_review, blocked, done, archived"
+    },
+    move: {
+        required: ['task_id', 'new_status'],
+        optional: [],
+        example: {
+            action: 'move',
+            task_id: 5,
+            new_status: 'in_progress'
+        },
+        hint: "Status transitions are validated. E.g., can't move from 'todo' directly to 'done'"
+    },
+    link: {
+        required: ['task_id', 'link_type', 'target_id'],
+        optional: ['link_relation'],
+        example: {
+            action: 'link',
+            task_id: 5,
+            link_type: 'decision',
+            target_id: 'api/auth-method',
+            link_relation: 'implements'
+        },
+        hint: "⚠️ link_type='file' is DEPRECATED in v3.4.1. Use watch_files parameter or watch_files action instead."
+    },
+    archive: {
+        required: ['task_id'],
+        optional: [],
+        example: {
+            action: 'archive',
+            task_id: 5
+        },
+        hint: "Task must be in 'done' status before archiving"
+    },
+    create_batch: {
+        required: ['tasks'],
+        optional: ['atomic'],
+        example: {
+            action: 'create_batch',
+            tasks: [
+                { title: 'Design API', priority: 3 },
+                { title: 'Implement API', priority: 3 },
+                { title: 'Write tests', priority: 2 }
+            ],
+            atomic: false
+        },
+        hint: "Max 50 tasks per batch. Use atomic:false for best-effort creation."
+    },
+    add_dependency: {
+        required: ['blocker_task_id', 'blocked_task_id'],
+        optional: [],
+        example: {
+            action: 'add_dependency',
+            blocker_task_id: 1,
+            blocked_task_id: 2
+        },
+        hint: "Task #1 must complete before Task #2 can start. Prevents circular dependencies."
+    },
+    remove_dependency: {
+        required: ['blocker_task_id', 'blocked_task_id'],
+        optional: [],
+        example: {
+            action: 'remove_dependency',
+            blocker_task_id: 1,
+            blocked_task_id: 2
+        },
+        hint: "Silently succeeds even if dependency doesn't exist (idempotent)"
+    },
+    get_dependencies: {
+        required: ['task_id'],
+        optional: ['include_details'],
+        example: {
+            action: 'get_dependencies',
+            task_id: 2,
+            include_details: false
+        },
+        hint: "Returns bidirectional: tasks that block this task AND tasks this task blocks"
+    },
+    watch_files: {
+        required: ['task_id', 'action'],
+        optional: ['file_paths'],
+        example: {
+            action: 'watch_files',
+            task_id: 5,
+            subaction: 'watch',
+            file_paths: ['src/api/auth.ts', 'src/middleware/jwt.ts']
+        },
+        hint: "⭐ NEW in v3.4.1: Replaces task.link(file). Actions: watch, unwatch, list"
+    }
+};
+//# sourceMappingURL=task-specs.js.map

package/dist/utils/action-specs/task-specs.js.map

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

package/dist/utils/action-specs/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Action Specification Type Definition
+ *
+ * Core type for defining parameter requirements and examples for MCP tool actions.
+ * Used by parameter-validator.ts to generate structured error messages with examples
+ * and typo suggestions.
+ */
+export interface ActionSpec {
+    required: string[];
+    optional: string[];
+    example: any;
+    hint?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/action-specs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/action-specs/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,GAAG,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/utils/action-specs/types.js

@@ -0,0 +1,9 @@
+/**
+ * Action Specification Type Definition
+ *
+ * Core type for defining parameter requirements and examples for MCP tool actions.
+ * Used by parameter-validator.ts to generate structured error messages with examples
+ * and typo suggestions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/action-specs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/utils/action-specs/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils/batch-validation.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Batch Validation Utilities
+ * Pre-validates batch items BEFORE transaction to reduce failures by 70-85%
+ *
+ * Features:
+ * - Comprehensive validation (required fields, types, enums, ranges, FK references)
+ * - Reports ALL errors at once (not just first error)
+ * - AI-friendly error messages with actionable fix instructions
+ * - Reusable validators for all batch operations
+ *
+ * Usage:
+ *   const result = await validateBatch(items, validateTaskItem, adapter);
+ *   if (!result.valid) {
+ *     throw new Error(formatBatchValidationError(result));
+ *   }
+ */
+import type { DatabaseAdapter } from '../adapters/types.js';
+/**
+ * Structured validation error for single field in single batch item
+ * Designed for AI comprehension and automatic correction
+ */
+export interface BatchValidationError {
+    /** Index in batch array (0-based) */
+    itemIndex: number;
+    /** Item identifier for user comprehension (e.g., task.title, decision.key, file.file_path) */
+    itemIdentifier: string;
+    /** Field name that failed validation */
+    field: string;
+    /** Human-readable issue description */
+    issue: string;
+    /** Actionable fix instruction (copy-paste ready when possible) */
+    fix: string;
+    /** Current invalid value (for comparison) */
+    current?: any;
+    /** Valid options (for enum fields) */
+    validOptions?: string[];
+}
+/**
+ * Aggregate validation result for entire batch
+ */
+export interface BatchValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** Array of all validation errors (empty if valid) */
+    errors: BatchValidationError[];
+    /** Count of valid items */
+    validCount: number;
+    /** Count of invalid items */
+    invalidCount: number;
+    /** Summary message for AI */
+    summary: string;
+}
+/**
+ * Batch item validator function signature
+ */
+export type BatchItemValidator<T> = (item: T, index: number, adapter: DatabaseAdapter, errors: BatchValidationError[]) => Promise<void>;
+/**
+ * Validate required field exists and is non-empty
+ *
+ * @param value Field value to check
+ * @param fieldName Field name for error messages
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier (e.g., title, key)
+ * @param errors Error array to append to
+ */
+export declare function validateRequiredField(value: any, fieldName: string, itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): void;
+/**
+ * Validate enum value (status, layer, priority, etc.)
+ * Suggests closest match using Levenshtein distance for typos
+ *
+ * @param value Value to validate
+ * @param fieldName Field name for error messages
+ * @param validOptions Valid enum values
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier
+ * @param errors Error array to append to
+ */
+export declare function validateEnum(value: any, fieldName: string, validOptions: readonly string[], itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): void;
+/**
+ * Validate type (array, string, number, object)
+ *
+ * @param value Value to validate
+ * @param fieldName Field name for error messages
+ * @param expectedType Expected type
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier
+ * @param errors Error array to append to
+ */
+export declare function validateType(value: any, fieldName: string, expectedType: 'array' | 'string' | 'number' | 'object', itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): void;
+/**
+ * Validate range (priority, numeric fields)
+ *
+ * @param value Value to validate
+ * @param fieldName Field name for error messages
+ * @param min Minimum value (inclusive)
+ * @param max Maximum value (inclusive)
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier
+ * @param errors Error array to append to
+ */
+export declare function validateRange(value: any, fieldName: string, min: number, max: number, itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): void;
+/**
+ * Validate string length
+ *
+ * @param value Value to validate
+ * @param fieldName Field name for error messages
+ * @param maxLength Maximum length
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier
+ * @param errors Error array to append to
+ */
+export declare function validateLength(value: any, fieldName: string, maxLength: number, itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): void;
+/**
+ * Validate foreign key reference (layer, agent, tag, etc.)
+ * Requires database lookup for existence check
+ *
+ * @param value Value to validate
+ * @param fieldName Field name for error messages
+ * @param tableName Master table name (e.g., 'm_layers', 'm_agents')
+ * @param columnName Column name to check (usually 'name' or 'id')
+ * @param adapter Database adapter
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier
+ * @param errors Error array to append to
+ */
+export declare function validateForeignKey(value: any, fieldName: string, tableName: string, columnName: string, adapter: DatabaseAdapter, itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): Promise<void>;
+/**
+ * Validate layer-specific constraints (FILE_REQUIRED vs FILE_OPTIONAL)
+ * FILE_REQUIRED layers must have file_actions parameter (or empty array)
+ *
+ * @param layer Layer name
+ * @param fileActions file_actions parameter value
+ * @param itemIndex Item index in batch
+ * @param itemIdentifier Item identifier
+ * @param errors Error array to append to
+ */
+export declare function validateLayerFileRequirement(layer: string | undefined, fileActions: any, itemIndex: number, itemIdentifier: string, errors: BatchValidationError[]): void;
+/**
+ * Validate entire batch before transaction
+ * Returns structured result with ALL validation errors
+ *
+ * @param items Array of items to validate
+ * @param itemValidator Validator function for single item
+ * @param adapter Database adapter
+ * @returns Validation result with all errors
+ */
+export declare function validateBatch<T>(items: T[], itemValidator: BatchItemValidator<T>, adapter: DatabaseAdapter): Promise<BatchValidationResult>;
+/**
+ * Format batch validation errors for AI comprehension
+ * Returns human-readable message with actionable fix instructions
+ *
+ * @param result Batch validation result
+ * @returns Formatted error message
+ */
+export declare function formatBatchValidationError(result: BatchValidationResult): string;
+//# sourceMappingURL=batch-validation.d.ts.map

package/dist/utils/batch-validation.d.ts.map

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

package/dist/utils/batch-validation.example.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Batch Validation Usage Examples
+ * Demonstrates how to use batch validation utilities in batch operations
+ *
+ * This file is NOT imported by production code - it's documentation only
+ */
+export {};
+/**
+ * Example error message for batch with multiple issues
+ *
+ * Input:
+ * {
+ *   tasks: [
+ *     { title: "Task 1", layer: "busines", priority: 5 },
+ *     { layer: "presentation" },  // Missing title and file_actions
+ *     { title: "Task 3", layer: "planning" }  // Valid
+ *   ]
+ * }
+ *
+ * Output:
+ * ```
+ * Batch validation failed. Found 4 validation error(s) in 2 item(s). 1 items are valid.
+ *
+ * Item 0 (Task 1):
+ *   ❌ layer: Invalid layer: "busines"
+ *      💡 Fix: Change to "business" (closest match)
+ *      Current: "busines"
+ *      Valid: presentation, business, data, infrastructure, cross-cutting, documentation, planning, coordination, review
+ *
+ *   ❌ priority: Field "priority" must be between 1 and 4
+ *      💡 Fix: Provide a number between 1 and 4
+ *      Current: 5
+ *
+ * Item 1 (Item 1):
+ *   ❌ title: Field "title" is required but missing or empty
+ *      💡 Fix: Provide a non-empty value for "title"
+ *      Current: undefined
+ *
+ *   ❌ file_actions: Layer "presentation" requires file_actions parameter
+ *      💡 Fix: Add file_actions: [{ action: "edit", path: "src/..." }] or use [] for planning tasks
+ *      Current: undefined
+ *      Valid: Add file_actions array, Change to FILE_OPTIONAL layer (planning/coordination/review)
+ *
+ * 💡 Result: 1 valid, 2 invalid
+ * 💡 Action: Fix the 2 invalid item(s) and retry batch operation
+ * ```
+ */
+//# sourceMappingURL=batch-validation.example.d.ts.map

package/dist/utils/batch-validation.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-validation.example.d.ts","sourceRoot":"","sources":["../../src/utils/batch-validation.example.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;;AAmPH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG"}

package/dist/utils/batch-validation.example.js

@@ -0,0 +1,180 @@
+/**
+ * Batch Validation Usage Examples
+ * Demonstrates how to use batch validation utilities in batch operations
+ *
+ * This file is NOT imported by production code - it's documentation only
+ */
+import { validateBatch, formatBatchValidationError, validateRequiredField, validateEnum, validateType, validateRange, validateLength, validateLayerFileRequirement } from './batch-validation.js';
+// ============================================================================
+// Example 1: Task Batch Validation
+// ============================================================================
+/**
+ * Validate single task item for batch creation
+ * This validator would be called by validateBatch() for each task
+ */
+async function validateTaskItem(task, index, adapter, errors) {
+    const identifier = task.title || `Item ${index}`;
+    // Required fields
+    validateRequiredField(task.title, 'title', index, identifier, errors);
+    // String length
+    if (task.title) {
+        validateLength(task.title, 'title', 200, index, identifier, errors);
+    }
+    // Enums
+    if (task.status) {
+        validateEnum(task.status, 'status', ['todo', 'in_progress', 'waiting_review', 'blocked', 'done', 'archived'], index, identifier, errors);
+    }
+    if (task.layer) {
+        validateEnum(task.layer, 'layer', ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting',
+            'documentation', 'planning', 'coordination', 'review'], index, identifier, errors);
+    }
+    // Range validation
+    if (task.priority !== undefined) {
+        validateRange(task.priority, 'priority', 1, 4, index, identifier, errors);
+    }
+    // Type validation
+    if (task.tags !== undefined) {
+        validateType(task.tags, 'tags', 'array', index, identifier, errors);
+    }
+    // Complex field validation: file_actions
+    if (task.file_actions !== undefined) {
+        validateType(task.file_actions, 'file_actions', 'array', index, identifier, errors);
+        if (Array.isArray(task.file_actions)) {
+            task.file_actions.forEach((fa, faIndex) => {
+                if (!fa.action) {
+                    errors.push({
+                        itemIndex: index,
+                        itemIdentifier: identifier,
+                        field: `file_actions[${faIndex}].action`,
+                        issue: 'Missing action field in file_actions',
+                        fix: 'Add action field: { action: "create"|"edit"|"delete", path: "..." }',
+                        current: fa
+                    });
+                }
+                else {
+                    validateEnum(fa.action, `file_actions[${faIndex}].action`, ['create', 'edit', 'delete'], index, identifier, errors);
+                }
+                if (!fa.path || typeof fa.path !== 'string') {
+                    errors.push({
+                        itemIndex: index,
+                        itemIdentifier: identifier,
+                        field: `file_actions[${faIndex}].path`,
+                        issue: 'Missing or invalid path field in file_actions',
+                        fix: 'Add path field as string: { action: "...", path: "src/file.ts" }',
+                        current: fa
+                    });
+                }
+            });
+        }
+    }
+    // Layer-specific validation (FILE_REQUIRED vs FILE_OPTIONAL)
+    validateLayerFileRequirement(task.layer, task.file_actions, index, identifier, errors);
+}
+/**
+ * Example batch operation with pre-validation
+ */
+async function batchCreateTasksExample(params, adapter) {
+    // Basic validation
+    if (!params.tasks || !Array.isArray(params.tasks)) {
+        throw new Error('Parameter "tasks" is required and must be an array');
+    }
+    if (params.tasks.length > 50) {
+        throw new Error('Parameter "tasks" must contain at most 50 items');
+    }
+    // ✅ PRE-VALIDATION: Check ALL items BEFORE transaction
+    const validationResult = await validateBatch(params.tasks, validateTaskItem, adapter);
+    // ✅ FAIL FAST: If any validation errors, throw formatted error
+    if (!validationResult.valid) {
+        throw new Error(formatBatchValidationError(validationResult));
+    }
+    // Validation passed - proceed with transaction
+    console.log('All items valid, proceeding with batch creation...');
+    // ... existing batch creation logic
+}
+// ============================================================================
+// Example 2: Decision Batch Validation
+// ============================================================================
+/**
+ * Validate single decision item for batch set
+ */
+async function validateDecisionItem(decision, index, adapter, errors) {
+    const identifier = decision.key || `Item ${index}`;
+    // Required fields
+    validateRequiredField(decision.key, 'key', index, identifier, errors);
+    validateRequiredField(decision.value, 'value', index, identifier, errors);
+    // Enums
+    if (decision.status) {
+        validateEnum(decision.status, 'status', ['active', 'deprecated', 'draft'], index, identifier, errors);
+    }
+    if (decision.layer) {
+        validateEnum(decision.layer, 'layer', ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting',
+            'documentation', 'planning', 'coordination', 'review'], index, identifier, errors);
+    }
+    // Type validation
+    if (decision.tags !== undefined) {
+        validateType(decision.tags, 'tags', 'array', index, identifier, errors);
+    }
+}
+// ============================================================================
+// Example 3: File Change Batch Validation
+// ============================================================================
+/**
+ * Validate single file change item for batch record
+ */
+async function validateFileChangeItem(fileChange, index, adapter, errors) {
+    const identifier = fileChange.file_path || `Item ${index}`;
+    // Required fields
+    validateRequiredField(fileChange.file_path, 'file_path', index, identifier, errors);
+    // Enums
+    if (fileChange.change_type) {
+        validateEnum(fileChange.change_type, 'change_type', ['created', 'modified', 'deleted'], index, identifier, errors);
+    }
+    if (fileChange.layer) {
+        validateEnum(fileChange.layer, 'layer', ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting',
+            'documentation', 'planning', 'coordination', 'review'], index, identifier, errors);
+    }
+}
+// ============================================================================
+// Example 4: Error Output Examples
+// ============================================================================
+/**
+ * Example error message for batch with multiple issues
+ *
+ * Input:
+ * {
+ *   tasks: [
+ *     { title: "Task 1", layer: "busines", priority: 5 },
+ *     { layer: "presentation" },  // Missing title and file_actions
+ *     { title: "Task 3", layer: "planning" }  // Valid
+ *   ]
+ * }
+ *
+ * Output:
+ * ```
+ * Batch validation failed. Found 4 validation error(s) in 2 item(s). 1 items are valid.
+ *
+ * Item 0 (Task 1):
+ *   ❌ layer: Invalid layer: "busines"
+ *      💡 Fix: Change to "business" (closest match)
+ *      Current: "busines"
+ *      Valid: presentation, business, data, infrastructure, cross-cutting, documentation, planning, coordination, review
+ *
+ *   ❌ priority: Field "priority" must be between 1 and 4
+ *      💡 Fix: Provide a number between 1 and 4
+ *      Current: 5
+ *
+ * Item 1 (Item 1):
+ *   ❌ title: Field "title" is required but missing or empty
+ *      💡 Fix: Provide a non-empty value for "title"
+ *      Current: undefined
+ *
+ *   ❌ file_actions: Layer "presentation" requires file_actions parameter
+ *      💡 Fix: Add file_actions: [{ action: "edit", path: "src/..." }] or use [] for planning tasks
+ *      Current: undefined
+ *      Valid: Add file_actions array, Change to FILE_OPTIONAL layer (planning/coordination/review)
+ *
+ * 💡 Result: 1 valid, 2 invalid
+ * 💡 Action: Fix the 2 invalid item(s) and retry batch operation
+ * ```
+ */
+//# sourceMappingURL=batch-validation.example.js.map

package/dist/utils/batch-validation.example.js.map

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