@liendev/lien 0.11.0 → 0.12.0

package/CURSOR_RULES_TEMPLATE.md

@@ -114,6 +114,73 @@ list_functions({
 
 ---
 
+## Input Validation & Error Handling
+
+Lien uses Zod schemas for runtime type-safe validation of all tool inputs. This provides:
+- **Automatic validation** of all parameters before tool execution
+- **Rich error messages** with field-level feedback
+- **Type safety** with full TypeScript inference
+- **Consistent error structure** across all tools
+
+### Understanding Validation Errors
+
+When you provide invalid parameters, you'll receive a structured error response:
+
+```json
+{
+  "error": "Invalid parameters",
+  "code": "INVALID_INPUT",
+  "details": [
+    {
+      "field": "query",
+      "message": "Query must be at least 3 characters"
+    },
+    {
+      "field": "limit",
+      "message": "Limit cannot exceed 50"
+    }
+  ]
+}
+```
+
+### Common Validation Rules
+
+**semantic_search:**
+- `query`: 3-500 characters (required)
+- `limit`: 1-50 (default: 5)
+
+**find_similar:**
+- `code`: minimum 10 characters (required)
+- `limit`: 1-20 (default: 5)
+
+**get_file_context:**
+- `filepath`: cannot be empty (required)
+- `includeRelated`: boolean (default: true)
+
+**list_functions:**
+- `pattern`: optional regex string
+- `language`: optional language filter
+
+### Error Codes
+
+Lien uses structured error codes for programmatic error handling:
+
+- `INVALID_INPUT` - Parameter validation failed
+- `FILE_NOT_FOUND` - Requested file doesn't exist in index
+- `INDEX_NOT_FOUND` - No index found (run `lien index`)
+- `INDEX_CORRUPTED` - Index is corrupted (run `lien reindex`)
+- `EMBEDDING_GENERATION_FAILED` - Embedding model failed (retryable)
+- `INTERNAL_ERROR` - Unexpected internal error
+
+### Best Practices
+
+1. **Always provide required fields**: Check tool schemas for required parameters
+2. **Respect validation limits**: Don't exceed max values for `limit` parameters
+3. **Use descriptive queries**: Avoid very short or vague queries
+4. **Handle validation errors gracefully**: Parse error details to understand what went wrong
+
+---
+
 ## Workflow Patterns (FOLLOW THESE)
 
 ### Pattern 1: User Asks "Where is X?"

package/dist/index.js

@@ -210,13 +210,20 @@ var init_migration = __esm({
   }
 });
 
+// src/errors/codes.ts
+var init_codes = __esm({
+  "src/errors/codes.ts"() {
+    "use strict";
+  }
+});
+
 // src/errors/index.ts
 function wrapError(error, context, additionalContext) {
   const message = error instanceof Error ? error.message : String(error);
   const stack = error instanceof Error ? error.stack : void 0;
   const wrappedError = new LienError(
     `${context}: ${message}`,
-    "WRAPPED_ERROR",
+    "INTERNAL_ERROR" /* INTERNAL_ERROR */,
     additionalContext
   );
   if (stack) {
@@ -231,32 +238,61 @@ var LienError, ConfigError, EmbeddingError, DatabaseError;
 var init_errors = __esm({
   "src/errors/index.ts"() {
     "use strict";
+    init_codes();
+    init_codes();
     LienError = class extends Error {
-      constructor(message, code, context) {
+      constructor(message, code, context, severity = "medium", recoverable = true, retryable = false) {
         super(message);
         this.code = code;
         this.context = context;
+        this.severity = severity;
+        this.recoverable = recoverable;
+        this.retryable = retryable;
         this.name = "LienError";
         if (Error.captureStackTrace) {
           Error.captureStackTrace(this, this.constructor);
         }
       }
+      /**
+       * Serialize error to JSON for MCP responses
+       */
+      toJSON() {
+        return {
+          error: this.message,
+          code: this.code,
+          severity: this.severity,
+          recoverable: this.recoverable,
+          context: this.context
+        };
+      }
+      /**
+       * Check if this error is retryable
+       */
+      isRetryable() {
+        return this.retryable;
+      }
+      /**
+       * Check if this error is recoverable
+       */
+      isRecoverable() {
+        return this.recoverable;
+      }
     };
     ConfigError = class extends LienError {
       constructor(message, context) {
-        super(message, "CONFIG_ERROR", context);
+        super(message, "CONFIG_INVALID" /* CONFIG_INVALID */, context, "medium", true, false);
         this.name = "ConfigError";
       }
     };
     EmbeddingError = class extends LienError {
       constructor(message, context) {
-        super(message, "EMBEDDING_ERROR", context);
+        super(message, "EMBEDDING_GENERATION_FAILED" /* EMBEDDING_GENERATION_FAILED */, context, "high", true, true);
         this.name = "EmbeddingError";
       }
     };
     DatabaseError = class extends LienError {
       constructor(message, context) {
-        super(message, "DATABASE_ERROR", context);
+        super(message, "INTERNAL_ERROR" /* INTERNAL_ERROR */, context, "high", true, true);
         this.name = "DatabaseError";
       }
     };
@@ -4082,82 +4118,85 @@ import { createRequire as createRequire3 } from "module";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { dirname as dirname3, join as join3 } from "path";
 
+// src/mcp/utils/zod-to-json-schema.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+function toMCPToolSchema(zodSchema, name, description) {
+  return {
+    name,
+    description,
+    inputSchema: zodToJsonSchema(zodSchema, {
+      target: "jsonSchema7",
+      $refStrategy: "none"
+    })
+  };
+}
+
+// src/mcp/schemas/search.schema.ts
+import { z } from "zod";
+var SemanticSearchSchema = z.object({
+  query: z.string().min(3, "Query must be at least 3 characters").max(500, "Query too long (max 500 characters)").describe(
+    "Natural language description of what you're looking for.\n\nUse full sentences describing functionality, not exact names.\n\nGood examples:\n  - 'handles user authentication'\n  - 'validates email format'\n  - 'processes payment transactions'\n\nBad examples:\n  - 'auth' (too vague)\n  - 'validateEmail' (use grep for exact names)"
+  ),
+  limit: z.number().int().min(1, "Limit must be at least 1").max(50, "Limit cannot exceed 50").default(5).describe(
+    "Number of results to return.\n\nDefault: 5\nIncrease to 10-15 for broad exploration."
+  )
+});
+
+// src/mcp/schemas/similarity.schema.ts
+import { z as z2 } from "zod";
+var FindSimilarSchema = z2.object({
+  code: z2.string().min(10, "Code snippet must be at least 10 characters").describe(
+    "Code snippet to find similar implementations for.\n\nProvide a representative code sample that demonstrates the pattern you want to find similar examples of in the codebase."
+  ),
+  limit: z2.number().int().min(1, "Limit must be at least 1").max(20, "Limit cannot exceed 20").default(5).describe(
+    "Number of similar code blocks to return.\n\nDefault: 5"
+  )
+});
+
+// src/mcp/schemas/file.schema.ts
+import { z as z3 } from "zod";
+var GetFileContextSchema = z3.object({
+  filepath: z3.string().min(1, "Filepath cannot be empty").describe(
+    "Relative path to file from workspace root.\n\nExample: 'src/components/Button.tsx'"
+  ),
+  includeRelated: z3.boolean().default(true).describe(
+    "Include semantically related chunks from nearby code.\n\nDefault: true\n\nWhen enabled, also returns related code from other files that are semantically similar to the target file's contents."
+  )
+});
+
+// src/mcp/schemas/symbols.schema.ts
+import { z as z4 } from "zod";
+var ListFunctionsSchema = z4.object({
+  pattern: z4.string().optional().describe(
+    "Regex pattern to match symbol names.\n\nExamples:\n  - '.*Controller.*' to find all Controllers\n  - 'handle.*' to find handlers\n  - '.*Service$' to find Services\n\nIf omitted, returns all symbols."
+  ),
+  language: z4.string().optional().describe(
+    "Filter by programming language.\n\nExamples: 'typescript', 'python', 'javascript', 'php'\n\nIf omitted, searches all languages."
+  )
+});
+
 // src/mcp/tools.ts
 var tools = [
-  {
-    name: "semantic_search",
-    description: "Search the codebase semantically for relevant code using natural language. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: {
-          type: "string",
-          description: 'Natural language search query (e.g., "authentication logic", "database connection handling")'
-        },
-        limit: {
-          type: "number",
-          description: "Maximum number of results to return",
-          default: 5
-        }
-      },
-      required: ["query"]
-    }
-  },
-  {
-    name: "find_similar",
-    description: "Find code similar to a given code snippet. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        code: {
-          type: "string",
-          description: "Code snippet to find similar implementations"
-        },
-        limit: {
-          type: "number",
-          description: "Maximum number of results to return",
-          default: 5
-        }
-      },
-      required: ["code"]
-    }
-  },
-  {
-    name: "get_file_context",
-    description: "Get all chunks and related context for a specific file. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        filepath: {
-          type: "string",
-          description: "Path to the file (relative to project root)"
-        },
-        includeRelated: {
-          type: "boolean",
-          description: "Include semantically related chunks from other files",
-          default: true
-        }
-      },
-      required: ["filepath"]
-    }
-  },
-  {
-    name: "list_functions",
-    description: "List functions, classes, and interfaces by name pattern and language",
-    inputSchema: {
-      type: "object",
-      properties: {
-        pattern: {
-          type: "string",
-          description: 'Regex pattern to match symbol names (e.g., ".*Service$", "handle.*")'
-        },
-        language: {
-          type: "string",
-          description: 'Language filter (e.g., "typescript", "python", "php")'
-        }
-      }
-    }
-  }
+  toMCPToolSchema(
+    SemanticSearchSchema,
+    "semantic_search",
+    "Search the codebase semantically for relevant code using natural language. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity."
+  ),
+  toMCPToolSchema(
+    FindSimilarSchema,
+    "find_similar",
+    "Find code similar to a given code snippet. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity."
+  ),
+  toMCPToolSchema(
+    GetFileContextSchema,
+    "get_file_context",
+    "Get all chunks and related context for a specific file. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity."
+  ),
+  toMCPToolSchema(
+    ListFunctionsSchema,
+    "list_functions",
+    "List functions, classes, and interfaces by name pattern and language"
+  )
 ];
 
 // src/mcp/server.ts
@@ -4300,6 +4339,64 @@ var FileWatcher = class {
 
 // src/mcp/server.ts
 init_constants();
+
+// src/mcp/utils/tool-wrapper.ts
+init_errors();
+import { ZodError } from "zod";
+function wrapToolHandler(schema, handler) {
+  return async (args) => {
+    try {
+      const validated = schema.parse(args);
+      const result = await handler(validated);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    } catch (error) {
+      if (error instanceof ZodError) {
+        return {
+          isError: true,
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              error: "Invalid parameters",
+              code: "INVALID_INPUT" /* INVALID_INPUT */,
+              details: error.errors.map((e) => ({
+                field: e.path.join("."),
+                message: e.message
+              }))
+            }, null, 2)
+          }]
+        };
+      }
+      if (error instanceof LienError) {
+        return {
+          isError: true,
+          content: [{
+            type: "text",
+            text: JSON.stringify(error.toJSON(), null, 2)
+          }]
+        };
+      }
+      console.error("Unexpected error in tool handler:", error);
+      return {
+        isError: true,
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : "Unknown error",
+            code: "INTERNAL_ERROR" /* INTERNAL_ERROR */
+          }, null, 2)
+        }]
+      };
+    }
+  };
+}
+
+// src/mcp/server.ts
+init_errors();
 var __filename4 = fileURLToPath4(import.meta.url);
 var __dirname4 = dirname3(__filename4);
 var require4 = createRequire3(import.meta.url);
@@ -4364,148 +4461,139 @@ async function startMCPServer(options) {
   }, VERSION_CHECK_INTERVAL_MS);
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    log(`Handling tool call: ${name}`);
     try {
-      log(`Handling tool call: ${name}`);
       switch (name) {
-        case "semantic_search": {
-          const query = args?.query;
-          const limit = args?.limit || 5;
-          log(`Searching for: "${query}"`);
-          await checkAndReconnect();
-          const queryEmbedding = await embeddings.embed(query);
-          const results = await vectorDB.search(queryEmbedding, limit, query);
-          log(`Found ${results.length} results`);
-          const response = {
-            indexInfo: getIndexMetadata(),
-            results
-          };
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(response, null, 2)
-              }
-            ]
-          };
-        }
-        case "find_similar": {
-          const code = args?.code;
-          const limit = args?.limit || 5;
-          log(`Finding similar code...`);
-          await checkAndReconnect();
-          const codeEmbedding = await embeddings.embed(code);
-          const results = await vectorDB.search(codeEmbedding, limit, code);
-          log(`Found ${results.length} similar chunks`);
-          const response = {
-            indexInfo: getIndexMetadata(),
-            results
-          };
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(response, null, 2)
-              }
-            ]
-          };
-        }
-        case "get_file_context": {
-          const filepath = args?.filepath;
-          const includeRelated = args?.includeRelated ?? true;
-          log(`Getting context for: ${filepath}`);
-          await checkAndReconnect();
-          const fileEmbedding = await embeddings.embed(filepath);
-          const allResults = await vectorDB.search(fileEmbedding, 50, filepath);
-          const fileChunks = allResults.filter(
-            (r) => r.metadata.file.includes(filepath) || filepath.includes(r.metadata.file)
-          );
-          let results = fileChunks;
-          if (includeRelated && fileChunks.length > 0) {
-            const relatedEmbedding = await embeddings.embed(fileChunks[0].content);
-            const related = await vectorDB.search(relatedEmbedding, 5, fileChunks[0].content);
-            const relatedOtherFiles = related.filter(
-              (r) => !r.metadata.file.includes(filepath) && !filepath.includes(r.metadata.file)
-            );
-            results = [...fileChunks, ...relatedOtherFiles];
-          }
-          log(`Found ${results.length} chunks`);
-          const response = {
-            indexInfo: getIndexMetadata(),
-            file: filepath,
-            chunks: results
-          };
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(response, null, 2)
+        case "semantic_search":
+          return await wrapToolHandler(
+            SemanticSearchSchema,
+            async (validatedArgs) => {
+              log(`Searching for: "${validatedArgs.query}"`);
+              await checkAndReconnect();
+              const queryEmbedding = await embeddings.embed(validatedArgs.query);
+              const results = await vectorDB.search(queryEmbedding, validatedArgs.limit, validatedArgs.query);
+              log(`Found ${results.length} results`);
+              return {
+                indexInfo: getIndexMetadata(),
+                results
+              };
+            }
+          )(args);
+        case "find_similar":
+          return await wrapToolHandler(
+            FindSimilarSchema,
+            async (validatedArgs) => {
+              log(`Finding similar code...`);
+              await checkAndReconnect();
+              const codeEmbedding = await embeddings.embed(validatedArgs.code);
+              const results = await vectorDB.search(codeEmbedding, validatedArgs.limit, validatedArgs.code);
+              log(`Found ${results.length} similar chunks`);
+              return {
+                indexInfo: getIndexMetadata(),
+                results
+              };
+            }
+          )(args);
+        case "get_file_context":
+          return await wrapToolHandler(
+            GetFileContextSchema,
+            async (validatedArgs) => {
+              log(`Getting context for: ${validatedArgs.filepath}`);
+              await checkAndReconnect();
+              const fileEmbedding = await embeddings.embed(validatedArgs.filepath);
+              const allResults = await vectorDB.search(fileEmbedding, 50, validatedArgs.filepath);
+              const fileChunks = allResults.filter(
+                (r) => r.metadata.file.includes(validatedArgs.filepath) || validatedArgs.filepath.includes(r.metadata.file)
+              );
+              let results = fileChunks;
+              if (validatedArgs.includeRelated && fileChunks.length > 0) {
+                const relatedEmbedding = await embeddings.embed(fileChunks[0].content);
+                const related = await vectorDB.search(relatedEmbedding, 5, fileChunks[0].content);
+                const relatedOtherFiles = related.filter(
+                  (r) => !r.metadata.file.includes(validatedArgs.filepath) && !validatedArgs.filepath.includes(r.metadata.file)
+                );
+                results = [...fileChunks, ...relatedOtherFiles];
               }
-            ]
-          };
-        }
-        case "list_functions": {
-          const pattern = args?.pattern;
-          const language = args?.language;
-          log("Listing functions with symbol metadata...");
-          await checkAndReconnect();
-          let results;
-          let usedMethod = "symbols";
-          try {
-            results = await vectorDB.querySymbols({
-              language,
-              pattern,
-              limit: 50
-            });
-            if (results.length === 0 && (language || pattern)) {
-              log("No symbol results, falling back to content scan...");
-              results = await vectorDB.scanWithFilter({
-                language,
-                pattern,
-                limit: 50
-              });
-              usedMethod = "content";
+              log(`Found ${results.length} chunks`);
+              return {
+                indexInfo: getIndexMetadata(),
+                file: validatedArgs.filepath,
+                chunks: results
+              };
             }
-          } catch (error) {
-            log(`Symbol query failed, falling back to content scan: ${error}`);
-            results = await vectorDB.scanWithFilter({
-              language,
-              pattern,
-              limit: 50
-            });
-            usedMethod = "content";
-          }
-          log(`Found ${results.length} matches using ${usedMethod} method`);
-          const response = {
-            indexInfo: getIndexMetadata(),
-            method: usedMethod,
-            results,
-            note: usedMethod === "content" ? 'Using content search. Run "lien reindex" to enable faster symbol-based queries.' : void 0
-          };
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(response, null, 2)
+          )(args);
+        case "list_functions":
+          return await wrapToolHandler(
+            ListFunctionsSchema,
+            async (validatedArgs) => {
+              log("Listing functions with symbol metadata...");
+              await checkAndReconnect();
+              let results;
+              let usedMethod = "symbols";
+              try {
+                results = await vectorDB.querySymbols({
+                  language: validatedArgs.language,
+                  pattern: validatedArgs.pattern,
+                  limit: 50
+                });
+                if (results.length === 0 && (validatedArgs.language || validatedArgs.pattern)) {
+                  log("No symbol results, falling back to content scan...");
+                  results = await vectorDB.scanWithFilter({
+                    language: validatedArgs.language,
+                    pattern: validatedArgs.pattern,
+                    limit: 50
+                  });
+                  usedMethod = "content";
+                }
+              } catch (error) {
+                log(`Symbol query failed, falling back to content scan: ${error}`);
+                results = await vectorDB.scanWithFilter({
+                  language: validatedArgs.language,
+                  pattern: validatedArgs.pattern,
+                  limit: 50
+                });
+                usedMethod = "content";
               }
-            ]
-          };
-        }
+              log(`Found ${results.length} matches using ${usedMethod} method`);
+              return {
+                indexInfo: getIndexMetadata(),
+                method: usedMethod,
+                results,
+                note: usedMethod === "content" ? 'Using content search. Run "lien reindex" to enable faster symbol-based queries.' : void 0
+              };
+            }
+          )(args);
         default:
-          throw new Error(`Unknown tool: ${name}`);
+          throw new LienError(
+            `Unknown tool: ${name}`,
+            "INVALID_INPUT" /* INVALID_INPUT */,
+            { requestedTool: name, availableTools: tools.map((t) => t.name) },
+            "medium",
+            false,
+            false
+          );
       }
     } catch (error) {
-      console.error(`Error handling tool call ${name}:`, error);
-      return {
-        content: [
-          {
+      if (error instanceof LienError) {
+        return {
+          isError: true,
+          content: [{
             type: "text",
-            text: JSON.stringify({
-              error: String(error),
-              tool: name
-            })
-          }
-        ],
-        isError: true
+            text: JSON.stringify(error.toJSON(), null, 2)
+          }]
+        };
+      }
+      console.error(`Unexpected error handling tool call ${name}:`, error);
+      return {
+        isError: true,
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : "Unknown error",
+            code: "INTERNAL_ERROR" /* INTERNAL_ERROR */,
+            tool: name
+          }, null, 2)
+        }]
       };
     }
   });