sqlew 3.6.5 → 3.6.6

package/dist/utils/error-handler.js.map

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

package/dist/utils/parameter-validator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Parameter Validation with Typo Detection for MCP Tools
+ *
+ * Provides comprehensive parameter validation with:
+ * - Missing required parameter detection
+ * - Typo suggestions using Levenshtein distance
+ * - Structured error messages with examples
+ * - Support for all sqlew MCP tools
+ *
+ * Usage:
+ *   validateActionParams('decision', 'set', params);
+ *   // Throws ValidationError with structured details if validation fails
+ */
+import type { DecisionAction, TaskAction, FileAction, ConstraintAction, StatsAction, ConfigAction, MessageAction } from '../types.js';
+/**
+ * Validate action parameters and throw structured error if invalid
+ *
+ * @param tool Tool name (e.g., 'decision', 'task', 'file', 'constraint', 'stats')
+ * @param action Action name (accepts both typed action enums and strings for backward compatibility)
+ * @param params Parameters provided by user
+ * @throws Error with structured ValidationError JSON if validation fails
+ */
+export declare function validateActionParams(tool: string, action: DecisionAction | TaskAction | FileAction | ConstraintAction | StatsAction | ConfigAction | MessageAction | string, params: any): void;
+/**
+ * Validate batch operation parameters
+ * Used by set_batch, record_batch, batch_create actions
+ *
+ * @param tool Tool name
+ * @param batchParamName Name of the batch array parameter (e.g., 'decisions', 'tasks', 'file_changes')
+ * @param items Array of items to validate
+ * @param itemAction Action name for each item (e.g., 'set' for decision items)
+ * @param maxItems Maximum allowed items (default: 50)
+ * @throws Error if batch validation fails
+ */
+export declare function validateBatchParams(tool: string, batchParamName: string, items: any[], itemAction: string, maxItems?: number): void;
+/**
+ * Get all available actions for a tool
+ * Useful for error messages suggesting alternatives
+ *
+ * @param tool Tool name
+ * @returns Array of available action names
+ */
+export declare function getAvailableActions(tool: string): string[];
+/**
+ * Suggest similar action names using Levenshtein distance
+ * Helps users when they misspell an action name
+ *
+ * @param tool Tool name
+ * @param providedAction Action name provided by user
+ * @returns Array of suggested action names (max 3)
+ */
+export declare function suggestSimilarActions(tool: string, providedAction: string): string[];
+//# sourceMappingURL=parameter-validator.d.ts.map

package/dist/utils/parameter-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-validator.d.ts","sourceRoot":"","sources":["../../src/utils/parameter-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAEV,cAAc,EACd,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,EACd,MAAM,aAAa,CAAC;AAgKrB;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,gBAAgB,GAAG,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,MAAM,EACzH,MAAM,EAAE,GAAG,GACV,IAAI,CAmDN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,GAAG,EAAE,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAW,GACpB,IAAI,CAqCN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM1D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CAcpF"}

package/dist/utils/parameter-validator.js

@@ -0,0 +1,286 @@
+/**
+ * Parameter Validation with Typo Detection for MCP Tools
+ *
+ * Provides comprehensive parameter validation with:
+ * - Missing required parameter detection
+ * - Typo suggestions using Levenshtein distance
+ * - Structured error messages with examples
+ * - Support for all sqlew MCP tools
+ *
+ * Usage:
+ *   validateActionParams('decision', 'set', params);
+ *   // Throws ValidationError with structured details if validation fails
+ */
+import { getActionSpec, ACTION_SPECS_BY_TOOL } from './action-specs.js';
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for typo detection (e.g., "context_key" → "key")
+ *
+ * @param a First string
+ * @param b Second string
+ * @returns Edit distance (number of single-character edits needed)
+ */
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    // Initialize matrix
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    // Fill matrix
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                );
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Common abbreviation patterns for AI parameter typos
+ * Maps abbreviated/shortened names to their full parameter names
+ */
+const COMMON_ABBREVIATIONS = {
+    desc: ['description'],
+    val: ['value'],
+    prio: ['priority'],
+    pri: ['priority'],
+    config: ['configuration'],
+    msg: ['message'],
+    crit: ['criteria', 'critical'],
+    req: ['required'],
+    opt: ['optional'],
+    param: ['parameter', 'params'],
+    arg: ['argument', 'args'],
+    attr: ['attribute', 'attributes'],
+    prop: ['property', 'properties'],
+    stat: ['status', 'statistics'],
+    info: ['information'],
+    temp: ['template'],
+    rel: ['related', 'relation'],
+    deps: ['dependencies'],
+    dep: ['dependency'],
+    ref: ['reference'],
+    ctx: ['context'],
+    db: ['database'],
+};
+/**
+ * Check if provided parameter matches any common abbreviation pattern
+ *
+ * @param provided Parameter name provided by user (potentially abbreviated)
+ * @param validParams List of valid parameters to match against
+ * @returns Matched full parameter name, or null if no match
+ */
+function checkAbbreviation(provided, validParams) {
+    const lowerProvided = provided.toLowerCase();
+    // Direct abbreviation match
+    if (COMMON_ABBREVIATIONS[lowerProvided]) {
+        for (const fullForm of COMMON_ABBREVIATIONS[lowerProvided]) {
+            // Check if any valid parameter contains this full form
+            const match = validParams.find(v => v.toLowerCase().includes(fullForm));
+            if (match) {
+                return match;
+            }
+        }
+    }
+    // Check if provided is a prefix abbreviation (e.g., "desc" → "description")
+    for (const valid of validParams) {
+        if (valid.length > provided.length &&
+            valid.toLowerCase().startsWith(lowerProvided) &&
+            provided.length >= 3) { // Minimum 3 chars for prefix matching
+            return valid;
+        }
+    }
+    return null;
+}
+/**
+ * Find typo suggestions for provided parameters
+ * Uses:
+ * 1. Abbreviation dictionary for common AI shortcuts
+ * 2. Prefix matching for partial parameter names
+ * 3. Levenshtein distance ≤ 2 for typos
+ *
+ * @param providedParams Parameters actually provided by user
+ * @param validParams All valid parameters (required + optional)
+ * @returns Map of typo → suggested correction
+ */
+function findTypoSuggestions(providedParams, validParams) {
+    const suggestions = {};
+    for (const provided of providedParams) {
+        // Skip 'action' parameter (always valid)
+        if (provided === 'action') {
+            continue;
+        }
+        // Skip if it's a valid parameter
+        if (validParams.includes(provided)) {
+            continue;
+        }
+        // 1. Check abbreviation dictionary first (highest priority)
+        const abbreviationMatch = checkAbbreviation(provided, validParams);
+        if (abbreviationMatch) {
+            suggestions[provided] = abbreviationMatch;
+            continue;
+        }
+        // 2. Find closest match within Levenshtein distance ≤ 2
+        let bestMatch = null;
+        let bestDistance = Infinity;
+        for (const valid of validParams) {
+            const distance = levenshteinDistance(provided.toLowerCase(), valid.toLowerCase());
+            if (distance <= 2 && distance < bestDistance) {
+                bestDistance = distance;
+                bestMatch = valid;
+            }
+        }
+        if (bestMatch) {
+            suggestions[provided] = bestMatch;
+        }
+    }
+    return suggestions;
+}
+/**
+ * Validate action parameters and throw structured error if invalid
+ *
+ * @param tool Tool name (e.g., 'decision', 'task', 'file', 'constraint', 'stats')
+ * @param action Action name (accepts both typed action enums and strings for backward compatibility)
+ * @param params Parameters provided by user
+ * @throws Error with structured ValidationError JSON if validation fails
+ */
+export function validateActionParams(tool, action, params) {
+    // Skip validation for help actions
+    const helpActions = ['help', 'example', 'use_case', 'help_action', 'help_params',
+        'help_tool', 'help_use_case', 'help_list_use_cases', 'help_next_actions'];
+    if (helpActions.includes(action)) {
+        return;
+    }
+    // Get action specification
+    const spec = getActionSpec(tool, action);
+    if (!spec) {
+        throw new Error(`Unknown action "${action}" for tool "${tool}". Use action: "help" to see available actions, or action: "use_case" for comprehensive scenarios.`);
+    }
+    // Check for missing required parameters
+    const missingParams = [];
+    for (const requiredParam of spec.required) {
+        if (params[requiredParam] === undefined || params[requiredParam] === null || params[requiredParam] === '') {
+            missingParams.push(requiredParam);
+        }
+    }
+    // Get all provided parameters (excluding 'action')
+    const providedParams = Object.keys(params).filter(p => p !== 'action');
+    // All valid parameters for this action
+    const allValidParams = [...spec.required, ...spec.optional];
+    // Find typo suggestions
+    const typoSuggestions = findTypoSuggestions(providedParams, allValidParams);
+    // If validation fails, throw structured error
+    if (missingParams.length > 0 || Object.keys(typoSuggestions).length > 0) {
+        const error = {
+            error: missingParams.length > 0
+                ? `Missing required parameter${missingParams.length > 1 ? 's' : ''} for action '${action}': ${missingParams.join(', ')}`
+                : `Invalid parameter name${Object.keys(typoSuggestions).length > 1 ? 's' : ''} detected`,
+            action: action,
+            missing_params: missingParams.length > 0 ? missingParams : undefined,
+            required_params: spec.required,
+            optional_params: spec.optional,
+            you_provided: providedParams,
+            did_you_mean: Object.keys(typoSuggestions).length > 0 ? typoSuggestions : undefined,
+            example: spec.example,
+            hint: spec.hint,
+            need_help: `For comprehensive scenarios and examples, try: ${tool}({ action: "use_case" })`
+        };
+        // Throw error with JSON-formatted details for easy parsing by AI agents
+        throw new Error(JSON.stringify(error, null, 2));
+    }
+}
+/**
+ * Validate batch operation parameters
+ * Used by set_batch, record_batch, batch_create actions
+ *
+ * @param tool Tool name
+ * @param batchParamName Name of the batch array parameter (e.g., 'decisions', 'tasks', 'file_changes')
+ * @param items Array of items to validate
+ * @param itemAction Action name for each item (e.g., 'set' for decision items)
+ * @param maxItems Maximum allowed items (default: 50)
+ * @throws Error if batch validation fails
+ */
+export function validateBatchParams(tool, batchParamName, items, itemAction, maxItems = 50) {
+    // Check if batch parameter exists and is an array
+    if (!items || !Array.isArray(items)) {
+        throw new Error(`Parameter "${batchParamName}" is required and must be an array`);
+    }
+    // Check array is not empty
+    if (items.length === 0) {
+        // Allow empty arrays (will return empty success response)
+        return;
+    }
+    // Check max items constraint
+    if (items.length > maxItems) {
+        throw new Error(`Parameter "${batchParamName}" must contain at most ${maxItems} items (got ${items.length})`);
+    }
+    // Validate each item in the batch
+    const itemErrors = [];
+    for (let i = 0; i < items.length; i++) {
+        try {
+            validateActionParams(tool, itemAction, items[i]);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            itemErrors.push({
+                index: i,
+                error: message
+            });
+        }
+    }
+    // If any items have validation errors, throw aggregate error
+    if (itemErrors.length > 0) {
+        const errorSummary = itemErrors.map(e => `Item ${e.index}: ${e.error}`).join('\n');
+        throw new Error(`Batch validation failed for ${itemErrors.length} item(s):\n${errorSummary}`);
+    }
+}
+/**
+ * Get all available actions for a tool
+ * Useful for error messages suggesting alternatives
+ *
+ * @param tool Tool name
+ * @returns Array of available action names
+ */
+export function getAvailableActions(tool) {
+    const toolSpecs = ACTION_SPECS_BY_TOOL[tool];
+    if (!toolSpecs) {
+        return [];
+    }
+    return Object.keys(toolSpecs);
+}
+/**
+ * Suggest similar action names using Levenshtein distance
+ * Helps users when they misspell an action name
+ *
+ * @param tool Tool name
+ * @param providedAction Action name provided by user
+ * @returns Array of suggested action names (max 3)
+ */
+export function suggestSimilarActions(tool, providedAction) {
+    const availableActions = getAvailableActions(tool);
+    const scored = availableActions.map(action => ({
+        action,
+        distance: levenshteinDistance(providedAction.toLowerCase(), action.toLowerCase())
+    }));
+    // Sort by distance and return top 3 within distance ≤ 3
+    return scored
+        .filter(item => item.distance <= 3)
+        .sort((a, b) => a.distance - b.distance)
+        .slice(0, 3)
+        .map(item => item.action);
+}
+//# sourceMappingURL=parameter-validator.js.map

package/dist/utils/parameter-validator.js.map

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

package/docs/BEST_PRACTICES.md

@@ -33,11 +33,80 @@
 
 ---
 
+## Parameter Validation Patterns
+
+**NEW in dev branch**: sqlew provides comprehensive parameter validation with helpful error messages.
+
+### How Validation Helps
+
+1. **Catch Typos Early** - Get instant feedback on misspelled parameter names
+2. **Learn by Example** - Every error includes a working example
+3. **Clear Requirements** - Know exactly which parameters are required vs optional
+4. **Visual Markers** - Help responses show 🔴 REQUIRED and ⚪ OPTIONAL
+
+### Common Validation Errors and Fixes
+
+**Missing Required Parameter:**
+```javascript
+// ❌ ERROR: Missing required parameter 'value'
+{ action: "set", key: "auth_method" }
+
+// ✅ FIX: Add required parameter
+{ action: "set", key: "auth_method", value: "JWT authentication chosen" }
+```
+
+**Typo in Parameter Name:**
+```javascript
+// ❌ ERROR: Unknown parameter 'tgas' (did you mean 'tags'?)
+{ action: "set", key: "api/v2", value: "New API", tgas: ["api"] }
+
+// ✅ FIX: Correct the typo
+{ action: "set", key: "api/v2", value: "New API", tags: ["api"] }
+```
+
+**Wrong Action Name:**
+```javascript
+// ❌ ERROR: Unknown action 'create_task' (did you mean 'create'?)
+{ action: "create_task", title: "Implement auth" }
+
+// ✅ FIX: Use correct action name
+{ action: "create", title: "Implement auth" }
+```
+
+**Parameters from Wrong Action:**
+```javascript
+// ❌ ERROR: Unknown parameter 'task_id' for action 'create'
+{ action: "create", task_id: 5, title: "New task" }
+
+// ✅ FIX: Use 'update' action instead
+{ action: "update", task_id: 5, title: "Updated task" }
+```
+
+### Reading Validation Error Messages
+
+Error messages provide structured guidance:
+
+```json
+{
+  "error": "Missing required parameter for action 'set': value",
+  "missing_params": ["value"],              // What you're missing
+  "required_params": ["key", "value"],      // All required fields
+  "optional_params": ["agent", "layer"],    // All optional fields
+  "you_provided": ["key", "layer"],         // What you actually sent
+  "example": { ... },                       // Working example
+  "hint": "Use 'quick_set' for simpler..."  // Helpful tip
+}
+```
+
+---
+
 ## Common Errors
 
 | Error | Cause | Solution |
 |-------|-------|----------|
 | "Unknown action: undefined" | Missing `action` | Always include `action` parameter |
+| "Missing required parameter" | Omitted required field | Check `required_params` in error message |
+| "Unknown parameter" | Typo or wrong action | Check `did_you_mean` suggestions |
 | "Parameter 'value' is required" | Using `defaults` with templates | Pass parameters directly, not in `defaults` |
 | "Invalid layer" | Wrong layer name | Use: presentation, business, data, infrastructure, cross-cutting |
 | "Invalid status" | Wrong status | Use: active, deprecated, draft |

package/docs/CONFIGURATION.md

@@ -613,37 +613,53 @@ stale_hours_in_progress = 200   # ❌ Error: must be <= 168
 
 ## Runtime Configuration
 
-### Update via MCP Tools
+### ⚠️ Config Tool Removed (dev branch)
 
-Use the `config` tool to change settings at runtime:
+**DEPRECATED**: The `config` MCP tool has been removed in the dev branch.
 
-```javascript
-// Get current configuration
-{
-  action: "get"
-}
+**Why removed:**
+- Messaging system deprecated (primary use case eliminated)
+- File-based configuration (`.sqlew/config.toml`) is clearer and more maintainable
+- Runtime updates were confusing (changes lost on restart unless manually synced to file)
+- Configuration drift between `m_config` table and config file
 
-// Update settings (persists to m_config table)
-{
-  action: "update",
-  autodelete_message_hours: 48,
-  autodelete_ignore_weekend: true
-}
+**Migration path:**
+- ✅ **Use `.sqlew/config.toml`** for all configuration (persistent, version-controlled)
+- ✅ **Use CLI arguments** for one-time overrides (`--autodelete-message-hours=48`)
+- ❌ **Do NOT use** `config` tool (removed in dev, will error)
+
+### File-Based Configuration (Recommended)
+
+Edit `.sqlew/config.toml` directly:
+
+```toml
+[database]
+path = ".sqlew/custom.db"
+
+[autodelete]
+ignore_weekend = true
+message_hours = 48  # Messaging system deprecated, but config preserved for backward compatibility
 ```
 
-### Configuration Persistence
+**Benefits:**
+1. **Version control** - Commit config to git, share with team
+2. **No drift** - Single source of truth (no table vs file conflicts)
+3. **Clear documentation** - Config file documents project requirements
+4. **Type safety** - TOML validation catches errors at startup
+
+### Configuration Persistence (Legacy - v3.6.6 and earlier)
 
-**How it works:**
+**How it worked (DEPRECATED):**
 1. Config file loaded on startup
 2. Values merged with CLI arguments
 3. Final config written to `m_config` table
 4. MCP `config` tool updates `m_config` table
 5. Changes persist until next startup (then config file reloads)
 
-**To persist runtime changes:**
-1. Update values via MCP `config` tool
-2. Manually update `.sqlew/config.toml` to match
-3. Or regenerate config file from database (manual export)
+**Migration to file-based:**
+1. Remove all `config` tool calls from workflows
+2. Update `.sqlew/config.toml` directly
+3. Restart MCP server to apply changes
 
 ---