db-mcp 2.0.0 → 3.0.1

package/dist/{chunk-645ZEFLA.js → chunk-L552U3QS.js}

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
 // src/filtering/tool-constants.ts
 var ALL_TOOL_GROUPS = [
   "core",
@@ -27,7 +29,14 @@ var TOOL_GROUPS = {
     "batch_insert",
     "count",
     "exists",
-    "truncate"
+    "truncate",
+    "list_triggers",
+    "create_trigger",
+    "drop_trigger",
+    "list_constraints",
+    "date_add",
+    "date_diff",
+    "alter_table"
   ],
   json: [
     // CRUD + Query + Collection (8: crud.ts, query.ts, write.ts)
@@ -57,7 +66,9 @@ var TOOL_GROUPS = {
     "json_storage_info",
     "json_normalize_column",
     // Security (1: security.ts)
-    "json_security_scan"
+    "json_security_scan",
+    // Diff (1: diff.ts)
+    "json_diff"
   ],
   text: [
     // Text Tools (14 WASM)
@@ -107,7 +118,9 @@ var TOOL_GROUPS = {
     "window_lag_lead",
     "window_running_total",
     "window_moving_avg",
-    "window_ntile"
+    "window_ntile",
+    // Sampling (1 WASM)
+    "stats_sample"
   ],
   vector: [
     "vector_create_table",
@@ -123,7 +136,7 @@ var TOOL_GROUPS = {
     "vector_distance"
   ],
   admin: [
-    // Admin Tools (13: backup.ts, verify.ts, pragma.ts)
+    // Admin Tools (15: backup.ts, verify.ts, pragma.ts, reindex.ts, wal.ts)
     "backup",
     "analyze",
     "integrity_check",
@@ -150,7 +163,14 @@ var TOOL_GROUPS = {
     "create_csv_table",
     "analyze_csv_schema",
     "create_rtree_table",
-    "create_series_table"
+    "create_series_table",
+    // Database management (5: pragma.ts, backup/create.ts, reindex.ts, wal.ts)
+    "attach_database",
+    "detach_database",
+    "vacuum_into",
+    "dump",
+    "reindex",
+    "wal"
   ],
   transactions: [
     // Transaction Tools (8 Native-only)
@@ -181,8 +201,9 @@ var TOOL_GROUPS = {
     "dependency_graph",
     "topological_sort",
     "cascade_simulator",
-    // Schema Analysis (3 from introspection/analysis.ts)
+    // Schema Analysis (4 from introspection/analysis.ts)
     "schema_snapshot",
+    "schema_diff",
     "constraint_analysis",
     "migration_risks",
     // Diagnostics (3 from introspection/diagnostics.ts)
@@ -202,19 +223,19 @@ var TOOL_GROUPS = {
   codemode: ["execute_code"]
 };
 var META_GROUPS = {
-  // General development - Core + JSON + Text + Codemode (53 WASM / 58 Native)
+  // General development - Core + JSON + Text (60 WASM / 65 Native)
   starter: ["core", "json", "text", "codemode"],
-  // Data analysis - Core + JSON + Stats + Codemode (55 WASM / 61 Native)
+  // Data analysis - Core + JSON + Stats (63 WASM / 69 Native)
   analytics: ["core", "json", "stats", "codemode"],
-  // Search workloads - Core + Text + Vector + Codemode (40 WASM / 45 Native)
+  // Search workloads - Core + Text + Vector (46 WASM / 51 Native)
   search: ["core", "text", "vector", "codemode"],
-  // Geospatial workloads - Core + Geo + Vector + Codemode (30 WASM / 37 Native)
+  // Geospatial workloads - Core + Geo + Vector (36 WASM / 43 Native)
   spatial: ["core", "geo", "vector", "codemode"],
-  // Schema development - Core + Introspection + Migration + Codemode (30 tools)
+  // Schema development - Core + Introspection + Migration (37 tools)
   "dev-schema": ["core", "introspection", "migration", "codemode"],
-  // Bare minimum - Core + Codemode (15 tools)
+  // Bare minimum - Core (21 tools)
   minimal: ["core", "codemode"],
-  // All tools enabled (125 WASM / 151 Native)
+  // All group tools enabled (166 Native / 139 WASM — see TOOL COUNT TAXONOMY above)
   full: [
     "core",
     "json",
@@ -335,14 +356,6 @@ function parseToolFilter(filterString) {
       }
     }
   }
-  if (!startsWithExclude && enabledGroups.size > 0) {
-    const codemodeExplicitlyExcluded = parts.some(
-      (p) => p === "-codemode" || p === "-sqlite_execute_code"
-    );
-    if (!codemodeExplicitlyExcluded) {
-      enabledGroups.add("codemode");
-    }
-  }
   return {
     raw: filterString,
     rules,
@@ -362,6 +375,14 @@ function isToolEnabled(tool, config) {
   if (config.includedTools.has(tool.name) || config.includedTools.has(baseName)) {
     return true;
   }
+  if (tool.group === "codemode") {
+    const explicitlyExcludedGroup = config.rules.some(
+      (r) => r.type === "exclude" && r.target === "codemode"
+    );
+    if (!explicitlyExcludedGroup) {
+      return true;
+    }
+  }
   return config.enabledGroups.has(tool.group);
 }
 function filterTools(tools, config) {
@@ -397,296 +418,40 @@ function getFilterSummary(config) {
   return lines.join("\n");
 }
 
-// src/utils/errors/suggestions.ts
-var ERROR_SUGGESTIONS = [
-  // Validation errors
-  {
-    pattern: /invalid table name/i,
-    suggestion: "Table names must start with a letter or underscore, followed by letters, numbers, or underscores only.",
-    category: "validation" /* VALIDATION */
-  },
-  {
-    pattern: /invalid column name/i,
-    suggestion: "Column names must start with a letter or underscore, followed by letters, numbers, or underscores only.",
-    category: "validation" /* VALIDATION */
-  },
-  {
-    pattern: /invalid (view|index) name/i,
-    suggestion: "Names must start with a letter or underscore, followed by alphanumeric characters only.",
-    category: "validation" /* VALIDATION */
-  },
-  {
-    pattern: /json path must start with \$/i,
-    suggestion: "JSON paths use $ as the root. Example: $.name, $.items[0], $.nested.property",
-    category: "validation" /* VALIDATION */
-  },
-  {
-    pattern: /vector dimensions must match/i,
-    suggestion: "All vectors in comparison must have the same number of dimensions.",
-    category: "validation" /* VALIDATION */
-  },
-  {
-    pattern: /insufficient data/i,
-    suggestion: "Not enough data points for the requested analysis. Add more data or reduce the degree.",
-    category: "validation" /* VALIDATION */
-  },
-  // Resource errors — specific codes for table/column not found
-  {
-    pattern: /no such table[:\s]*(['"]?)(\w+)\1/i,
-    suggestion: "Table not found. Run sqlite_list_tables to see available tables.",
-    category: "resource" /* RESOURCE */,
-    code: "TABLE_NOT_FOUND"
-  },
-  {
-    pattern: /no such column[:\s]*(['"]?)(\w+)\1/i,
-    suggestion: "Column not found. Use sqlite_describe_table to see available columns.",
-    category: "resource" /* RESOURCE */,
-    code: "COLUMN_NOT_FOUND"
-  },
-  {
-    pattern: /has no column named/i,
-    suggestion: "Column not found in target table. Use sqlite_describe_table to verify column names before INSERT or UPDATE.",
-    category: "resource" /* RESOURCE */,
-    code: "COLUMN_NOT_FOUND"
-  },
-  {
-    pattern: /no such view[:\s]*(['"]?)(\w+)\1/i,
-    suggestion: "View not found. Run sqlite_list_views to see available views.",
-    category: "resource" /* RESOURCE */,
-    code: "VIEW_NOT_FOUND"
-  },
-  {
-    pattern: /filename.*does not exist/i,
-    suggestion: "File not found. Verify the absolute path exists and is readable.",
-    category: "resource" /* RESOURCE */,
-    code: "FILE_NOT_FOUND"
-  },
-  {
-    pattern: /table .* already exists/i,
-    suggestion: "Table already exists. Use CREATE TABLE IF NOT EXISTS or drop the existing table first.",
-    category: "resource" /* RESOURCE */,
-    code: "TABLE_ALREADY_EXISTS"
-  },
-  {
-    pattern: /index .* already exists/i,
-    suggestion: "Index already exists. Use CREATE INDEX IF NOT EXISTS or drop the existing index first.",
-    category: "resource" /* RESOURCE */,
-    code: "INDEX_ALREADY_EXISTS"
-  },
-  // JSON-specific errors — often caused by wrong column name
-  {
-    pattern: /malformed JSON/i,
-    suggestion: "The JSON data is malformed. This commonly occurs when the column name is incorrect \u2014 SQLite treats the unresolved identifier as a literal string. Verify the column exists with sqlite_describe_table.",
-    category: "query" /* QUERY */,
-    code: "MALFORMED_JSON"
-  },
-  // Query errors
-  {
-    pattern: /syntax error/i,
-    suggestion: "Check SQL syntax. Common issues: missing quotes, commas, parentheses, or reserved word conflicts.",
-    category: "query" /* QUERY */
-  },
-  {
-    pattern: /UNIQUE constraint failed/i,
-    suggestion: "A row with this value already exists. Use UPDATE to modify existing data or check for duplicates.",
-    category: "query" /* QUERY */,
-    code: "CONSTRAINT_VIOLATION"
-  },
-  {
-    pattern: /FOREIGN KEY constraint failed/i,
-    suggestion: "The referenced row does not exist. Ensure the parent record exists before inserting.",
-    category: "query" /* QUERY */,
-    code: "CONSTRAINT_VIOLATION"
-  },
-  {
-    pattern: /NOT NULL constraint failed/i,
-    suggestion: "A required column is missing a value. Provide a value or set a default.",
-    category: "query" /* QUERY */,
-    code: "CONSTRAINT_VIOLATION"
-  },
-  {
-    pattern: /CHECK constraint failed/i,
-    suggestion: "The value does not meet the column's check constraint requirements.",
-    category: "query" /* QUERY */,
-    code: "CONSTRAINT_VIOLATION"
-  },
-  {
-    pattern: /incomplete input/i,
-    suggestion: "SQL statement is incomplete. Check for missing clauses, closing parentheses, or semicolons.",
-    category: "query" /* QUERY */
-  },
-  {
-    pattern: /more than one statement/i,
-    suggestion: "Only one SQL statement per call is allowed. Split multiple statements into separate calls or use sqlite_execute_code for multi-step operations.",
-    category: "query" /* QUERY */
-  },
-  {
-    pattern: /too few parameter/i,
-    suggestion: "Not enough parameter values provided for the prepared statement placeholders (?). Ensure params array matches the number of ? placeholders in the query.",
-    category: "query" /* QUERY */
-  },
-  // Connection errors
-  {
-    pattern: /not connected/i,
-    suggestion: "Database connection not established. Ensure the database is configured and connected.",
-    category: "connection" /* CONNECTION */
-  },
-  {
-    pattern: /cannot start a transaction within a transaction/i,
-    suggestion: "A transaction is already active. Commit or rollback the current transaction first, or use sqlite_transaction_execute for atomic multi-statement operations.",
-    category: "query" /* QUERY */,
-    code: "TRANSACTION_CONFLICT"
-  },
-  {
-    pattern: /no transaction is active/i,
-    suggestion: "No transaction is active. Start a transaction using sqlite_transaction_begin first.",
-    category: "query" /* QUERY */,
-    code: "TRANSACTION_NOT_ACTIVE"
-  },
-  {
-    pattern: /no such savepoint/i,
-    suggestion: "The specified savepoint does not exist. Verify the savepoint name and ensure it hasn't already been released or rolled back.",
-    category: "query" /* QUERY */,
-    code: "SAVEPOINT_NOT_FOUND"
-  },
-  {
-    pattern: /database is locked/i,
-    suggestion: "Database is being used by another process. Wait and retry, or check for long-running transactions.",
-    category: "connection" /* CONNECTION */
-  },
-  // Permission errors
-  {
-    pattern: /readonly database/i,
-    suggestion: "Database is in read-only mode. Check file permissions or connection settings.",
-    category: "permission" /* PERMISSION */
-  },
-  {
-    pattern: /attempt to write a readonly/i,
-    suggestion: "Write operations are not allowed. Check database configuration.",
-    category: "permission" /* PERMISSION */
-  },
-  // Codemode errors
-  {
-    pattern: /code validation failed/i,
-    suggestion: "Check for blocked patterns: require(), process., eval(), Function(), import(). Use sqlite.* API instead.",
-    category: "validation" /* VALIDATION */
-  },
-  {
-    pattern: /rate limit exceeded/i,
-    suggestion: "Wait before retrying. Combine multiple operations into fewer execute_code calls.",
-    category: "permission" /* PERMISSION */
-  },
-  {
-    pattern: /execution timed out/i,
-    suggestion: "Reduce code complexity or increase timeout (max 30s). Break into smaller operations.",
-    category: "query" /* QUERY */
+// src/utils/logger/error-codes.ts
+function createErrorCode(module, code) {
+  return {
+    module: module.toUpperCase(),
+    code: code.toUpperCase(),
+    full: `${module.toUpperCase()}_${code.toUpperCase()}`
+  };
+}
+var ERROR_CODES = {
+  // Auth module
+  AUTH: {
+    TOKEN_INVALID: createErrorCode("AUTH", "TOKEN_INVALID"),
+    TOKEN_EXPIRED: createErrorCode("AUTH", "TOKEN_EXPIRED"),
+    TOKEN_MISSING: createErrorCode("AUTH", "TOKEN_MISSING"),
+    SIGNATURE_INVALID: createErrorCode("AUTH", "SIGNATURE_INVALID"),
+    SCOPE_DENIED: createErrorCode("AUTH", "SCOPE_DENIED"),
+    DISCOVERY_FAILED: createErrorCode("AUTH", "DISCOVERY_FAILED"),
+    JWKS_FETCH_FAILED: createErrorCode("AUTH", "JWKS_FETCH_FAILED"),
+    REGISTRATION_FAILED: createErrorCode("AUTH", "REGISTRATION_FAILED")
   },
-  {
-    pattern: /sandbox.*not initialized/i,
-    suggestion: "Internal sandbox error. Retry the operation.",
-    category: "internal" /* INTERNAL */
+  // Server module
+  SERVER: {
+    START_FAILED: createErrorCode("SERVER", "START_FAILED"),
+    SHUTDOWN_FAILED: createErrorCode("SERVER", "SHUTDOWN_FAILED"),
+    TRANSPORT_ERROR: createErrorCode("SERVER", "TRANSPORT_ERROR")
   },
-  // Extension errors
-  {
-    pattern: /extension.*not (available|installed|loaded|found)/i,
-    suggestion: "Extension is not available. Check CLI flags, environment variables, or platform compatibility.",
-    category: "config" /* CONFIGURATION */,
-    code: "EXTENSION_MISSING"
-  }
-];
-function findSuggestion(message) {
-  for (const entry of ERROR_SUGGESTIONS) {
-    if (entry.pattern.test(message)) {
-      return {
-        suggestion: entry.suggestion,
-        category: entry.category,
-        code: entry.code
-      };
-    }
+  // Database module
+  DB: {
+    CONNECT_FAILED: createErrorCode("DB", "CONNECT_FAILED"),
+    QUERY_FAILED: createErrorCode("DB", "QUERY_FAILED"),
+    DISCONNECT_FAILED: createErrorCode("DB", "DISCONNECT_FAILED"),
+    ADAPTER_NOT_FOUND: createErrorCode("DB", "ADAPTER_NOT_FOUND")
   }
-  return null;
-}
-
-// src/utils/errors/base.ts
-var REFINABLE_CODES = /* @__PURE__ */ new Set([
-  "DB_QUERY_FAILED",
-  "DB_WRITE_FAILED",
-  "QUERY_ERROR",
-  "RESOURCE_ERROR",
-  "UNKNOWN_ERROR"
-]);
-var DbMcpError = class extends Error {
-  /** Error category for classification */
-  category;
-  /** Module-prefixed error code (e.g., DB_QUERY_FAILED) */
-  code;
-  /** Actionable suggestion for resolving the error */
-  suggestion;
-  /** Additional error details */
-  details;
-  /** Whether the error is recoverable (can retry) */
-  recoverable;
-  constructor(message, code, category, options) {
-    super(message, { cause: options?.cause });
-    this.name = this.constructor.name;
-    this.category = category;
-    this.recoverable = options?.recoverable ?? false;
-    this.details = options?.details;
-    const match = findSuggestion(message);
-    this.suggestion = options?.suggestion ?? match?.suggestion;
-    this.code = match?.code && REFINABLE_CODES.has(code) ? match.code : code;
-    Error.captureStackTrace?.(this, this.constructor);
-  }
-  /**
-   * Convert to structured response object
-   */
-  toResponse() {
-    return {
-      success: false,
-      error: this.message,
-      code: this.code,
-      category: this.category,
-      suggestion: this.suggestion,
-      recoverable: this.recoverable,
-      details: this.details
-    };
-  }
-};
-
-// src/utils/logger/error-codes.ts
-function createErrorCode(module, code) {
-  return {
-    module: module.toUpperCase(),
-    code: code.toUpperCase(),
-    full: `${module.toUpperCase()}_${code.toUpperCase()}`
-  };
-}
-var ERROR_CODES = {
-  // Auth module
-  AUTH: {
-    TOKEN_INVALID: createErrorCode("AUTH", "TOKEN_INVALID"),
-    TOKEN_EXPIRED: createErrorCode("AUTH", "TOKEN_EXPIRED"),
-    TOKEN_MISSING: createErrorCode("AUTH", "TOKEN_MISSING"),
-    SIGNATURE_INVALID: createErrorCode("AUTH", "SIGNATURE_INVALID"),
-    SCOPE_DENIED: createErrorCode("AUTH", "SCOPE_DENIED"),
-    DISCOVERY_FAILED: createErrorCode("AUTH", "DISCOVERY_FAILED"),
-    JWKS_FETCH_FAILED: createErrorCode("AUTH", "JWKS_FETCH_FAILED"),
-    REGISTRATION_FAILED: createErrorCode("AUTH", "REGISTRATION_FAILED")
-  },
-  // Server module
-  SERVER: {
-    START_FAILED: createErrorCode("SERVER", "START_FAILED"),
-    SHUTDOWN_FAILED: createErrorCode("SERVER", "SHUTDOWN_FAILED"),
-    TRANSPORT_ERROR: createErrorCode("SERVER", "TRANSPORT_ERROR")
-  },
-  // Database module
-  DB: {
-    CONNECT_FAILED: createErrorCode("DB", "CONNECT_FAILED"),
-    QUERY_FAILED: createErrorCode("DB", "QUERY_FAILED"),
-    DISCONNECT_FAILED: createErrorCode("DB", "DISCONNECT_FAILED"),
-    ADAPTER_NOT_FOUND: createErrorCode("DB", "ADAPTER_NOT_FOUND")
-  }
-};
+};
 
 // src/utils/logger/module-logger.ts
 var ModuleLogger = class {
@@ -977,4 +742,817 @@ if (envLevel && envLevel in LEVEL_PRIORITY_CHECK) {
   logger.setLevel(envLevel);
 }
 
-export { ALL_TOOL_GROUPS, DbMcpError, ERROR_CODES, META_GROUPS, TOOL_GROUPS, createModuleLogger, filterTools, findSuggestion, getFilterSummary, getToolFilterFromEnv, isToolEnabled, logger, parseToolFilter };
+// src/utils/errors/suggestions.ts
+var ERROR_SUGGESTIONS = [
+  // Validation errors
+  {
+    pattern: /invalid table name/i,
+    suggestion: "Table names must start with a letter or underscore, followed by letters, numbers, or underscores only.",
+    category: "validation" /* VALIDATION */
+  },
+  {
+    pattern: /invalid column name/i,
+    suggestion: "Column names must start with a letter or underscore, followed by letters, numbers, or underscores only.",
+    category: "validation" /* VALIDATION */
+  },
+  {
+    pattern: /invalid (view|index) name/i,
+    suggestion: "Names must start with a letter or underscore, followed by alphanumeric characters only.",
+    category: "validation" /* VALIDATION */
+  },
+  {
+    pattern: /json path must start with \$/i,
+    suggestion: "JSON paths use $ as the root. Example: $.name, $.items[0], $.nested.property",
+    category: "validation" /* VALIDATION */
+  },
+  {
+    pattern: /vector dimensions must match/i,
+    suggestion: "All vectors in comparison must have the same number of dimensions.",
+    category: "validation" /* VALIDATION */
+  },
+  {
+    pattern: /insufficient data/i,
+    suggestion: "Not enough data points for the requested analysis. Add more data or reduce the degree.",
+    category: "validation" /* VALIDATION */
+  },
+  // Resource errors — specific codes for table/column not found
+  {
+    pattern: /no such table[:\s]*(['"]?)([\w.]+)\1/i,
+    suggestion: "Table not found. Run sqlite_list_tables to see available tables.",
+    category: "resource" /* RESOURCE */,
+    code: "TABLE_NOT_FOUND"
+  },
+  {
+    pattern: /no such column[:\s]*(['"]?)([\w.]+)\1/i,
+    suggestion: "Column not found. Use sqlite_describe_table to see available columns.",
+    category: "resource" /* RESOURCE */,
+    code: "COLUMN_NOT_FOUND"
+  },
+  {
+    pattern: /has no column named/i,
+    suggestion: "Column not found in target table. Use sqlite_describe_table to verify column names before INSERT or UPDATE.",
+    category: "resource" /* RESOURCE */,
+    code: "COLUMN_NOT_FOUND"
+  },
+  {
+    pattern: /no such view[:\s]*(['"]?)([\w.]+)\1/i,
+    suggestion: "View not found. Run sqlite_list_views to see available views.",
+    category: "resource" /* RESOURCE */,
+    code: "VIEW_NOT_FOUND"
+  },
+  {
+    pattern: /filename.*does not exist/i,
+    suggestion: "File not found. Verify the absolute path exists and is readable.",
+    category: "resource" /* RESOURCE */,
+    code: "FILE_NOT_FOUND"
+  },
+  {
+    pattern: /table .* already exists/i,
+    suggestion: "Table already exists. Use CREATE TABLE IF NOT EXISTS or drop the existing table first.",
+    category: "resource" /* RESOURCE */,
+    code: "TABLE_ALREADY_EXISTS"
+  },
+  {
+    pattern: /index .* already exists/i,
+    suggestion: "Index already exists. Use CREATE INDEX IF NOT EXISTS or drop the existing index first.",
+    category: "resource" /* RESOURCE */,
+    code: "INDEX_ALREADY_EXISTS"
+  },
+  // JSON-specific errors — often caused by wrong column name
+  {
+    pattern: /malformed JSON/i,
+    suggestion: "The JSON data is malformed. This commonly occurs when the column name is incorrect \u2014 SQLite treats the unresolved identifier as a literal string. Verify the column exists with sqlite_describe_table.",
+    category: "query" /* QUERY */,
+    code: "MALFORMED_JSON"
+  },
+  // Query errors
+  {
+    pattern: /syntax error/i,
+    suggestion: "Check SQL syntax. Common issues: missing quotes, commas, parentheses, or reserved word conflicts.",
+    category: "query" /* QUERY */
+  },
+  {
+    pattern: /UNIQUE constraint failed/i,
+    suggestion: "A row with this value already exists. Use UPDATE to modify existing data or check for duplicates.",
+    category: "query" /* QUERY */,
+    code: "CONSTRAINT_VIOLATION"
+  },
+  {
+    pattern: /FOREIGN KEY constraint failed/i,
+    suggestion: "The referenced row does not exist. Ensure the parent record exists before inserting.",
+    category: "query" /* QUERY */,
+    code: "CONSTRAINT_VIOLATION"
+  },
+  {
+    pattern: /NOT NULL constraint failed/i,
+    suggestion: "A required column is missing a value. Provide a value or set a default.",
+    category: "query" /* QUERY */,
+    code: "CONSTRAINT_VIOLATION"
+  },
+  {
+    pattern: /CHECK constraint failed/i,
+    suggestion: "The value does not meet the column's check constraint requirements.",
+    category: "query" /* QUERY */,
+    code: "CONSTRAINT_VIOLATION"
+  },
+  {
+    pattern: /incomplete input/i,
+    suggestion: "SQL statement is incomplete. Check for missing clauses, closing parentheses, or semicolons.",
+    category: "query" /* QUERY */
+  },
+  {
+    pattern: /more than one statement/i,
+    suggestion: "Only one SQL statement per call is allowed. Split multiple statements into separate calls or use sqlite_execute_code for multi-step operations.",
+    category: "query" /* QUERY */
+  },
+  {
+    pattern: /too few parameter/i,
+    suggestion: "Not enough parameter values provided for the prepared statement placeholders (?). Ensure params array matches the number of ? placeholders in the query.",
+    category: "query" /* QUERY */
+  },
+  // Connection errors
+  {
+    pattern: /not connected/i,
+    suggestion: "Database connection not established. Ensure the database is configured and connected.",
+    category: "connection" /* CONNECTION */
+  },
+  {
+    pattern: /cannot start a transaction within a transaction/i,
+    suggestion: "A transaction is already active. Commit or rollback the current transaction first, or use sqlite_transaction_execute for atomic multi-statement operations.",
+    category: "query" /* QUERY */,
+    code: "TRANSACTION_CONFLICT"
+  },
+  {
+    pattern: /no transaction is active/i,
+    suggestion: "No transaction is active. Start a transaction using sqlite_transaction_begin first.",
+    category: "query" /* QUERY */,
+    code: "TRANSACTION_NOT_ACTIVE"
+  },
+  {
+    pattern: /no such savepoint/i,
+    suggestion: "The specified savepoint does not exist. Verify the savepoint name and ensure it hasn't already been released or rolled back.",
+    category: "query" /* QUERY */,
+    code: "SAVEPOINT_NOT_FOUND"
+  },
+  {
+    pattern: /database is locked/i,
+    suggestion: "Database is being used by another process. Wait and retry, or check for long-running transactions.",
+    category: "connection" /* CONNECTION */
+  },
+  // Permission errors
+  {
+    pattern: /readonly database/i,
+    suggestion: "Database is in read-only mode. Check file permissions or connection settings.",
+    category: "permission" /* PERMISSION */
+  },
+  {
+    pattern: /attempt to write a readonly/i,
+    suggestion: "Write operations are not allowed. Check database configuration.",
+    category: "permission" /* PERMISSION */
+  },
+  // Codemode errors
+  {
+    pattern: /code validation failed/i,
+    suggestion: "Check for blocked patterns: require(), process., eval(), Function(), import(). Use sqlite.* API instead.",
+    category: "validation" /* VALIDATION */
+  },
+  {
+    pattern: /rate limit exceeded/i,
+    suggestion: "Wait before retrying. Combine multiple operations into fewer execute_code calls.",
+    category: "permission" /* PERMISSION */
+  },
+  {
+    pattern: /execution timed out/i,
+    suggestion: "Reduce code complexity or increase timeout (max 30s). Break into smaller operations.",
+    category: "query" /* QUERY */
+  },
+  {
+    pattern: /sandbox.*not initialized/i,
+    suggestion: "Internal sandbox error. Retry the operation.",
+    category: "internal" /* INTERNAL */
+  },
+  // Extension errors
+  {
+    pattern: /extension.*not (available|installed|loaded|found)/i,
+    suggestion: "Extension is not available. Check CLI flags, environment variables, or platform compatibility.",
+    category: "config" /* CONFIGURATION */,
+    code: "EXTENSION_MISSING"
+  },
+  // Custom JS errors mapped from tools
+  {
+    pattern: /invalid identifier/i,
+    suggestion: "Identifiers must start with a letter or underscore and contain only alphanumeric characters or underscores. Ensure the name follows SQLite identifier rules.",
+    category: "validation" /* VALIDATION */,
+    code: "INVALID_IDENTIFIER"
+  },
+  {
+    pattern: /(expected property name|unexpected token|in JSON at position|Expected double-quoted property name)/i,
+    suggestion: "The JSON data provided is malformed. Ensure the input string is valid JSON.",
+    category: "validation" /* VALIDATION */,
+    code: "MALFORMED_JSON"
+  }
+];
+function findSuggestion(message) {
+  for (const entry of ERROR_SUGGESTIONS) {
+    if (entry.pattern.test(message)) {
+      return {
+        suggestion: entry.suggestion,
+        category: entry.category,
+        code: entry.code
+      };
+    }
+  }
+  return null;
+}
+
+// src/utils/errors/base.ts
+var REFINABLE_CODES = /* @__PURE__ */ new Set([
+  "DB_QUERY_FAILED",
+  "DB_WRITE_FAILED",
+  "QUERY_ERROR",
+  "RESOURCE_ERROR",
+  "UNKNOWN_ERROR"
+]);
+var DbMcpError = class extends Error {
+  /** Error category for classification */
+  category;
+  /** Module-prefixed error code (e.g., DB_QUERY_FAILED) */
+  code;
+  /** Actionable suggestion for resolving the error */
+  suggestion;
+  /** Additional error details */
+  details;
+  /** Whether the error is recoverable (can retry) */
+  recoverable;
+  constructor(message, code, category, options) {
+    super(message, { cause: options?.cause });
+    this.name = this.constructor.name;
+    this.category = category;
+    this.recoverable = options?.recoverable ?? false;
+    this.details = options?.details;
+    const match = findSuggestion(message);
+    this.suggestion = options?.suggestion ?? match?.suggestion;
+    this.code = match?.code && REFINABLE_CODES.has(code) ? match.code : code;
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+  /**
+   * Convert to structured response object
+   */
+  toResponse() {
+    return {
+      success: false,
+      error: this.message,
+      code: this.code,
+      category: this.category,
+      suggestion: this.suggestion,
+      recoverable: this.recoverable,
+      details: this.details
+    };
+  }
+};
+
+// src/utils/errors/classes.ts
+var ValidationError = class extends DbMcpError {
+  constructor(message, code = "VALIDATION_ERROR", options) {
+    super(message, code, "validation" /* VALIDATION */, {
+      ...options,
+      recoverable: false
+    });
+  }
+};
+var ConnectionError = class extends DbMcpError {
+  constructor(message, code = "CONNECTION_ERROR", options) {
+    super(message, code, "connection" /* CONNECTION */, {
+      ...options,
+      recoverable: true
+      // Connection errors are often transient
+    });
+  }
+};
+var QueryError = class extends DbMcpError {
+  constructor(message, code = "QUERY_ERROR", options) {
+    super(message, code, "query" /* QUERY */, {
+      ...options,
+      details: {
+        ...options?.details,
+        sql: options?.sql
+      },
+      recoverable: false
+    });
+  }
+};
+var ResourceNotFoundError = class extends DbMcpError {
+  constructor(message, code = "RESOURCE_NOT_FOUND", options) {
+    super(message, code, "resource" /* RESOURCE */, {
+      ...options,
+      details: {
+        ...options?.details,
+        resourceType: options?.resourceType,
+        resourceName: options?.resourceName
+      },
+      recoverable: false
+    });
+  }
+};
+var ConfigurationError = class extends DbMcpError {
+  constructor(message, code = "CONFIG_ERROR", options) {
+    super(message, code, "config" /* CONFIGURATION */, {
+      ...options,
+      recoverable: false
+    });
+  }
+};
+var AuthenticationError = class extends DbMcpError {
+  constructor(message, code = "AUTHENTICATION_ERROR", options) {
+    super(message, code, "authentication" /* AUTHENTICATION */, {
+      ...options,
+      recoverable: false
+    });
+  }
+};
+var AuthorizationError = class extends DbMcpError {
+  constructor(message, code = "AUTHORIZATION_ERROR", options) {
+    super(message, code, "authorization" /* AUTHORIZATION */, {
+      ...options,
+      recoverable: false
+    });
+  }
+};
+var ExtensionNotAvailableError = class extends DbMcpError {
+  constructor(extensionName, options) {
+    const isWasm = options?.wasmLimitation ?? options?.details?.["wasmLimitation"] ?? false;
+    const baseMessage = `Extension '${extensionName}' is not installed or available`;
+    const message = isWasm === true ? `${baseMessage} in WASM mode` : baseMessage;
+    super(message, "EXTENSION_MISSING", "config" /* CONFIGURATION */, {
+      suggestion: options?.suggestion ?? `Install or enable the '${extensionName}' extension. Check environment variable or CLI flag configuration.`,
+      details: {
+        extension: extensionName,
+        ...options?.details,
+        ...isWasm === true ? { wasmLimitation: true } : {}
+      },
+      recoverable: false,
+      cause: options?.cause
+    });
+  }
+};
+
+// src/utils/errors/format.ts
+function sanitizeErrorMessage(msg) {
+  if (!msg || typeof msg !== "string") return msg;
+  return msg.replace(/[a-zA-Z]:\\[^:\n]*\\/g, "<redacted_path>\\").replace(/(file:|sqlite:|\/)[^:\s]+(\/[^:\s]*)/g, "<redacted_path>").replace(
+    /([a-zA-Z0-9+.-]+:\/\/[^:]+:)[^@\s]+(@)/g,
+    "$1<redacted_credential>$2"
+  ).replace(
+    /([?&](?:password|secret|key|token)=)[^&\s]+/gi,
+    "$1<redacted_credential>"
+  ).replace(
+    /(password|secret|key|token)[=:]\s*["']?[^"'\s,;]+["']?/gi,
+    "$1=<redacted_credential>"
+  );
+}
+var CATEGORY_DEFAULT_CODES = {
+  ["validation" /* VALIDATION */]: "VALIDATION_ERROR",
+  ["connection" /* CONNECTION */]: "CONNECTION_ERROR",
+  ["query" /* QUERY */]: "QUERY_ERROR",
+  ["permission" /* PERMISSION */]: "PERMISSION_ERROR",
+  ["config" /* CONFIGURATION */]: "CONFIG_ERROR",
+  ["resource" /* RESOURCE */]: "RESOURCE_ERROR",
+  ["authentication" /* AUTHENTICATION */]: "AUTHENTICATION_ERROR",
+  ["authorization" /* AUTHORIZATION */]: "AUTHORIZATION_ERROR",
+  ["internal" /* INTERNAL */]: "UNKNOWN_ERROR"
+};
+function formatZodError(error) {
+  if (!("issues" in error) || !Array.isArray(error["issues"])) {
+    return null;
+  }
+  const issues = error["issues"];
+  return issues.map((issue) => {
+    const pathStr = Array.isArray(issue.path) && issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+    return `${pathStr}${issue.message ?? "Unknown validation error"}`;
+  }).join("; ");
+}
+function formatHandlerError(error, _context) {
+  if (error instanceof DbMcpError) {
+    const res = error.toResponse();
+    res.error = sanitizeErrorMessage(res.error);
+    return res;
+  }
+  if (error instanceof Error) {
+    const zodMessage = formatZodError(error);
+    if (zodMessage !== null) {
+      return {
+        success: false,
+        error: sanitizeErrorMessage(zodMessage),
+        code: "VALIDATION_ERROR",
+        category: "validation" /* VALIDATION */,
+        suggestion: void 0,
+        recoverable: false,
+        details: void 0
+      };
+    }
+  }
+  if (error instanceof Error) {
+    const match = findSuggestion(error.message);
+    const category = match?.category ?? "internal" /* INTERNAL */;
+    return {
+      success: false,
+      error: sanitizeErrorMessage(error.message),
+      code: match?.code ?? CATEGORY_DEFAULT_CODES[category],
+      category,
+      suggestion: match?.suggestion,
+      recoverable: false,
+      details: void 0
+    };
+  }
+  return {
+    success: false,
+    error: sanitizeErrorMessage(String(error)),
+    code: "UNKNOWN_ERROR",
+    category: "internal" /* INTERNAL */,
+    suggestion: void 0,
+    recoverable: false,
+    details: void 0
+  };
+}
+var authContextStorage = new AsyncLocalStorage();
+function runWithAuthContext(context, fn) {
+  return authContextStorage.run(context, fn);
+}
+function getAuthContext() {
+  return authContextStorage.getStore();
+}
+
+// src/auth/scopes/constants.ts
+var SCOPES = {
+  /** Read-only access to all databases */
+  READ: "read",
+  /** Read and write access to all databases */
+  WRITE: "write",
+  /** Administrative access */
+  ADMIN: "admin",
+  /** Unrestricted access to all operations */
+  FULL: "full"
+};
+var BASE_SCOPES = ["read", "write", "admin", "full"];
+var SUPPORTED_SCOPES = ["read", "write", "admin", "full"];
+function parseScopes(scopeString) {
+  return scopeString.split(/\s+/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// src/auth/scopes/mapping.ts
+var TOOL_GROUP_SCOPES = {
+  core: SCOPES.READ,
+  json: SCOPES.READ,
+  text: SCOPES.READ,
+  stats: SCOPES.READ,
+  vector: SCOPES.READ,
+  geo: SCOPES.READ,
+  introspection: SCOPES.READ,
+  migration: SCOPES.WRITE,
+  transactions: SCOPES.WRITE,
+  admin: SCOPES.ADMIN,
+  codemode: SCOPES.ADMIN
+};
+var groupsForScope = (maxScope) => {
+  const hierarchy = {
+    read: 0,
+    write: 1,
+    admin: 2,
+    full: 3
+  };
+  const maxLevel = hierarchy[maxScope];
+  return Object.entries(TOOL_GROUP_SCOPES).filter(([, scope]) => hierarchy[scope] <= maxLevel).map(([group]) => group);
+};
+groupsForScope(SCOPES.READ);
+groupsForScope(SCOPES.WRITE);
+groupsForScope(SCOPES.ADMIN);
+function withSqlitePrefix(names) {
+  const set = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    set.add(name);
+    set.add(`sqlite_${name}`);
+  }
+  return set;
+}
+var adminToolNames = [];
+for (const [group, scope] of Object.entries(TOOL_GROUP_SCOPES)) {
+  if (scope === SCOPES.ADMIN) {
+    const tools = TOOL_GROUPS[group];
+    adminToolNames.push(...tools);
+  }
+}
+adminToolNames.push(
+  "sqlite_audit_list_backups",
+  "sqlite_audit_get_backup",
+  "sqlite_audit_cleanup",
+  "sqlite_audit_diff_backup",
+  "sqlite_audit_restore_backup",
+  "drop_table"
+  // explicitly admin since it is destructive, despite being in core
+);
+withSqlitePrefix(adminToolNames);
+var READ_ONLY_TOOLS = withSqlitePrefix([
+  // Core read operations
+  "read_query",
+  "list_tables",
+  "describe_table",
+  "get_indexes",
+  "count",
+  "exists",
+  "list_triggers",
+  "list_constraints",
+  "date_add",
+  "date_diff",
+  // JSON read operations
+  "json_valid",
+  "json_extract",
+  "json_type",
+  "json_array_length",
+  "json_keys",
+  "json_each",
+  "json_group_array",
+  "json_group_object",
+  "json_pretty",
+  "json_query",
+  "json_select",
+  "json_validate_path",
+  "json_analyze_schema",
+  "json_storage_info",
+  "json_diff",
+  "json_security_scan",
+  // Text read operations
+  "regex_extract",
+  "regex_match",
+  "text_split",
+  "text_concat",
+  "text_replace",
+  "text_trim",
+  "text_case",
+  "text_substring",
+  "fuzzy_match",
+  "phonetic_match",
+  "text_normalize",
+  "text_validate",
+  "advanced_search",
+  "text_sentiment",
+  "fts_search",
+  "fts_match_info",
+  "fts_headline",
+  // Stats (all read-only)
+  "stats_basic",
+  "stats_count",
+  "stats_group_by",
+  "stats_histogram",
+  "stats_percentile",
+  "stats_correlation",
+  "stats_top_n",
+  "stats_distinct",
+  "stats_summary",
+  "stats_frequency",
+  "stats_outliers",
+  "stats_regression",
+  "stats_hypothesis",
+  "stats_detect_anomalies",
+  "stats_detect_bloat",
+  "stats_detect_schema_risks",
+  "stats_sample",
+  "window_row_number",
+  "window_rank",
+  "window_lag_lead",
+  "window_running_total",
+  "window_moving_avg",
+  "window_ntile",
+  // Vector read operations
+  "vector_search",
+  "vector_get",
+  "vector_count",
+  "vector_stats",
+  "vector_dimensions",
+  "vector_normalize",
+  "vector_distance",
+  // Geo read operations
+  "geo_distance",
+  "geo_nearby",
+  "geo_bounding_box",
+  "geo_cluster",
+  // Introspection (all read-only)
+  "dependency_graph",
+  "topological_sort",
+  "cascade_simulator",
+  "schema_snapshot",
+  "schema_diff",
+  "constraint_analysis",
+  "migration_risks",
+  "storage_analysis",
+  "index_audit",
+  "query_plan"
+]);
+var WRITE_TOOLS = withSqlitePrefix([
+  // Core write operations
+  "write_query",
+  "create_table",
+  "create_index",
+  "drop_index",
+  "upsert",
+  "batch_insert",
+  "truncate",
+  "create_trigger",
+  "drop_trigger",
+  "alter_table",
+  // JSON write operations
+  "json_insert",
+  "json_update",
+  "json_set",
+  "json_remove",
+  "json_array_append",
+  "json_merge",
+  "create_json_collection",
+  "jsonb_convert",
+  "json_normalize_column",
+  // Text write operations
+  "fts_create",
+  "fts_rebuild",
+  // Vector write operations
+  "vector_create_table",
+  "vector_store",
+  "vector_batch_store",
+  "vector_delete",
+  // Geo write operations
+  "spatialite_load",
+  "spatialite_create_table",
+  "spatialite_query",
+  "spatialite_analyze",
+  "spatialite_index",
+  "spatialite_transform",
+  "spatialite_import",
+  // Migration (write scope group)
+  "migration_init",
+  "migration_record",
+  "migration_apply",
+  "migration_rollback",
+  "migration_history",
+  "migration_status",
+  // Transactions (write scope group)
+  "transaction_begin",
+  "transaction_status",
+  "transaction_commit",
+  "transaction_rollback",
+  "transaction_savepoint",
+  "transaction_release",
+  "transaction_rollback_to",
+  "transaction_execute"
+]);
+
+// src/auth/scopes/validation.ts
+function hasAdminScope(scopes) {
+  return scopes.includes("admin") || scopes.includes("full");
+}
+function hasWriteScope(scopes) {
+  return scopes.includes("write") || hasAdminScope(scopes);
+}
+function hasReadScope(scopes) {
+  return scopes.includes("read") || hasWriteScope(scopes);
+}
+
+// src/auth/scopes/enforcement.ts
+var toolScopeMap = /* @__PURE__ */ new Map();
+function registerToolScopes(map) {
+  for (const [key, val] of map.entries()) {
+    toolScopeMap.set(key, val);
+  }
+}
+function scopeGrantsToolAccess(scope, toolName) {
+  if (scope === "full" || scope === "admin") {
+    return true;
+  }
+  if (toolScopeMap.size > 0) {
+    const required = toolScopeMap.get(toolName);
+    if (required) {
+      if (required.includes(scope)) {
+        return true;
+      }
+      if (scope === "write" && required.includes("read")) {
+        return true;
+      }
+      return false;
+    }
+    return false;
+  }
+  if (scope === "write") {
+    return WRITE_TOOLS.has(toolName) || READ_ONLY_TOOLS.has(toolName);
+  }
+  if (scope === "read") {
+    return READ_ONLY_TOOLS.has(toolName);
+  }
+  return false;
+}
+function scopesGrantToolAccess(scopes, toolName) {
+  return scopes.some((scope) => scopeGrantsToolAccess(scope, toolName));
+}
+
+// src/auth/errors.ts
+var OAuthError = class extends DbMcpError {
+  /** HTTP status code for this error */
+  httpStatus;
+  /** WWW-Authenticate header value */
+  wwwAuthenticate;
+  constructor(message, code, httpStatus, details, wwwAuthenticate) {
+    super(message, code, "authentication" /* AUTHENTICATION */, { details });
+    this.name = "OAuthError";
+    this.httpStatus = httpStatus;
+    this.wwwAuthenticate = wwwAuthenticate;
+  }
+};
+var TokenMissingError = class extends OAuthError {
+  constructor(realm = "db-mcp") {
+    super(
+      "No access token provided",
+      ERROR_CODES.AUTH.TOKEN_MISSING.full,
+      401,
+      void 0,
+      `Bearer realm="${realm}"`
+    );
+    this.name = "TokenMissingError";
+  }
+};
+var InvalidTokenError = class extends OAuthError {
+  constructor(message = "Invalid access token", details) {
+    super(
+      message,
+      ERROR_CODES.AUTH.TOKEN_INVALID.full,
+      401,
+      details,
+      'Bearer error="invalid_token"'
+    );
+    this.name = "InvalidTokenError";
+  }
+};
+var TokenExpiredError = class extends OAuthError {
+  constructor(expiredAt) {
+    super(
+      "Access token has expired",
+      ERROR_CODES.AUTH.TOKEN_EXPIRED.full,
+      401,
+      expiredAt ? { expiredAt: expiredAt.toISOString() } : void 0,
+      'Bearer error="invalid_token", error_description="Token has expired"'
+    );
+    this.name = "TokenExpiredError";
+  }
+};
+var InvalidSignatureError = class extends OAuthError {
+  constructor(message = "Token signature verification failed") {
+    super(
+      message,
+      ERROR_CODES.AUTH.SIGNATURE_INVALID.full,
+      401,
+      void 0,
+      'Bearer error="invalid_token", error_description="Signature verification failed"'
+    );
+    this.name = "InvalidSignatureError";
+  }
+};
+var InsufficientScopeError = class extends OAuthError {
+  constructor(_requiredScope, _providedScopes) {
+    super(
+      `Insufficient scope.`,
+      ERROR_CODES.AUTH.SCOPE_DENIED.full,
+      403,
+      void 0,
+      `Bearer error="insufficient_scope"`
+    );
+    this.name = "InsufficientScopeError";
+  }
+};
+var AuthServerDiscoveryError = class extends OAuthError {
+  constructor(serverUrl, cause) {
+    super(
+      `Failed to discover authorization server metadata: ${serverUrl}`,
+      ERROR_CODES.AUTH.DISCOVERY_FAILED.full,
+      500,
+      {
+        serverUrl,
+        cause: cause?.message
+      }
+    );
+    this.name = "AuthServerDiscoveryError";
+  }
+};
+var JwksFetchError = class extends OAuthError {
+  constructor(jwksUri, cause) {
+    super(
+      `Failed to fetch JWKS: ${jwksUri}`,
+      ERROR_CODES.AUTH.JWKS_FETCH_FAILED.full,
+      500,
+      {
+        jwksUri,
+        cause: cause?.message
+      }
+    );
+    this.name = "JwksFetchError";
+  }
+};
+function isOAuthError(error) {
+  return error instanceof OAuthError;
+}
+
+export { ALL_TOOL_GROUPS, AuthServerDiscoveryError, AuthenticationError, AuthorizationError, BASE_SCOPES, ConfigurationError, ConnectionError, DbMcpError, ERROR_CODES, ExtensionNotAvailableError, InsufficientScopeError, InvalidSignatureError, InvalidTokenError, JwksFetchError, META_GROUPS, QueryError, ResourceNotFoundError, SCOPES, SUPPORTED_SCOPES, TOOL_GROUPS, TokenExpiredError, TokenMissingError, ValidationError, createModuleLogger, filterTools, findSuggestion, formatHandlerError, getAuthContext, getFilterSummary, getToolFilterFromEnv, hasAdminScope, hasReadScope, isOAuthError, isToolEnabled, logger, parseScopes, parseToolFilter, registerToolScopes, runWithAuthContext, sanitizeErrorMessage, scopesGrantToolAccess };