smart-coding-mcp 2.1.0 → 2.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
 
-An extensible Model Context Protocol (MCP) server that provides intelligent semantic code search for AI assistants. Built with local AI models using Matryoshka Representation Learning (MRL) for flexible embedding dimensions (64-768d), with runtime workspace switching and comprehensive status reporting.
+An extensible Model Context Protocol (MCP) server that provides intelligent semantic code search for AI assistants. Built with local AI models using Matryoshka Representation Learning (MRL) for flexible embedding dimensions (64-768d.
 
 ### Available Tools
 
@@ -90,15 +90,27 @@ npm update -g smart-coding-mcp
 
 ## Configuration
 
-Add to your MCP configuration file. The location depends on your IDE and OS:
+## IDE Integration
 
-| IDE                  | OS      | Config Path                                                       |
-| -------------------- | ------- | ----------------------------------------------------------------- |
-| **Claude Desktop**   | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| **Claude Desktop**   | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
-| **Cascade (Cursor)** | All     | Configured via UI Settings > Features > MCP                       |
-| **Antigravity**      | macOS   | `~/.gemini/antigravity/mcp_config.json`                           |
-| **Antigravity**      | Windows | `%USERPROFILE%\.gemini\antigravity\mcp_config.json`               |
+Detailed setup instructions for your preferred environment:
+
+| IDE / App          | Setup Guide                                        | Supported Variables  |
+| ------------------ | -------------------------------------------------- | -------------------- |
+| **VS Code**        | [**View Guide**](docs/ide-setup/vscode.md)         | `${workspaceFolder}` |
+| **Cursor**         | [**View Guide**](docs/ide-setup/cursor.md)         | `${workspaceFolder}` |
+| **Windsurf**       | [**View Guide**](docs/ide-setup/windsurf.md)       | Absolute paths only  |
+| **Claude Desktop** | [**View Guide**](docs/ide-setup/claude-desktop.md) | Absolute paths only  |
+| **Raycast**        | [**View Guide**](docs/ide-setup/raycast.md)        | Absolute paths only  |
+| **Antigravity**    | [**View Guide**](docs/ide-setup/antigravity.md)    | Absolute paths only  |
+
+### Common Configuration Paths
+
+| IDE                | OS      | Config Path                                                       |
+| ------------------ | ------- | ----------------------------------------------------------------- |
+| **Claude Desktop** | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Claude Desktop** | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
+| **Windsurf**       | macOS   | `~/.codeium/windsurf/mcp_config.json`                             |
+| **Windsurf**       | Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json`                 |
 
 Add the server configuration to the `mcpServers` object in your config file:
 

package/docs/ide-setup/antigravity.md

@@ -0,0 +1,109 @@
+# Antigravity (Gemini IDE) Integration
+
+Antigravity is Google's AI-powered IDE built on VS Code with deep Gemini integration.
+
+## MCP Configuration
+
+Edit your MCP config file:
+
+- **macOS:** `~/.gemini/antigravity/mcp_config.json`
+- **Windows:** `%USERPROFILE%\.gemini\antigravity\mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "smart-coding-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "smart-coding-mcp",
+        "--workspace",
+        "/absolute/path/to/project"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** Antigravity does **NOT** support `${workspaceFolder}`. You must use absolute paths.
+
+---
+
+## Configuring Agent Rules
+
+Antigravity supports powerful agent rules to control AI behavior.
+
+### Rule Locations
+
+| Scope               | Location                                  |
+| ------------------- | ----------------------------------------- |
+| **Global**          | `~/.gemini/GEMINI.md`                     |
+| **Workspace**       | `.agent/rules/*.md`                       |
+| **Project Context** | `GEMINI.md` or `AGENT.md` at project root |
+
+### Creating a Rule to Use Smart Coding MCP
+
+1. **Create the rules directory** in your project:
+
+   ```bash
+   mkdir -p .agent/rules
+   ```
+
+2. **Create a rule file** `.agent/rules/smart-mcp.md`:
+
+   ```markdown
+   ---
+   trigger: always_on
+   description: Mandatory usage of Smart Coding MCP tools for dependencies and search
+   ---
+
+   # Smart Coding MCP Usage Rules
+
+   You must prioritize using the **Smart Coding MCP** tools for the following tasks.
+
+   ## 1. Dependency Management
+
+   **Trigger:** When checking, adding, or updating package versions (npm, python, go, rust, etc.).
+   **Action:**
+
+   - **MUST** use the `d_check_last_version` tool.
+   - **DO NOT** guess versions or trust internal training data.
+   - **DO NOT** use generic web search unless `d_check_last_version` fails.
+
+   ## 2. Codebase Research
+
+   **Trigger:** When asking about "how" something works, finding logic, or understanding architecture.
+   **Action:**
+
+   - **PREFER** `a_semantic_search` (Smart Coding) over `grep_search` or `find_by_name`.
+   - Use `a_semantic_search` for natural language queries (e.g., "where is the auth logic").
+   - Use standard tools (`grep`) only for exact string matching.
+
+   ## 3. Environment & Status
+
+   **Trigger:** When starting a session or debugging the environment.
+   **Action:**
+
+   - Use `e_set_workspace` if the current workspace path is incorrect.
+   - Use `f_get_status` to verify the MCP server is healthy and indexed.
+   ```
+
+### Activation Modes
+
+| Mode             | Description                        |
+| ---------------- | ---------------------------------- |
+| `always_on`      | Rule is always applied             |
+| `manual`         | Activated when mentioned in prompt |
+| `model_decision` | AI decides based on description    |
+| `glob`           | Applied to matching file patterns  |
+
+### Global Rules
+
+For rules that apply to all projects, edit `~/.gemini/GEMINI.md`:
+
+```markdown
+# Global Agent Rules
+
+- Always verify package versions before installing
+- Prefer semantic search when available
+```

package/docs/ide-setup/claude-desktop.md

@@ -0,0 +1,88 @@
+# Claude Desktop Integration
+
+The official Claude Desktop app is the reference implementation for MCP.
+
+## Configuration Location
+
+Edit the configuration file located at:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+## Configuration
+
+Open the file in any text editor (VS Code, TextEdit, Notepad) and add the server:
+
+```json
+{
+  "mcpServers": {
+    "smart-coding-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "smart-coding-mcp",
+        "--workspace",
+        "/absolute/path/to/your/project"
+      ]
+    }
+  }
+}
+```
+
+> **Important:** Claude Desktop does **NOT** support `${workspaceFolder}`. You must provide the absolute path to the directory you want to index.
+
+---
+
+## Configuring Rules (Project Instructions)
+
+Claude Desktop uses **Projects** with custom instructions.
+
+### Creating Project Instructions
+
+1. **Create a new Project** in Claude Desktop
+2. Click **"Set project instructions"**
+3. Add your guidelines:
+
+   ```
+   # Smart Coding MCP Usage Rules
+
+   You must prioritize using the **Smart Coding MCP** tools for the following tasks.
+
+   ## 1. Dependency Management
+
+   **Trigger:** When checking, adding, or updating package versions (npm, python, go, rust, etc.).
+   **Action:**
+
+   - **MUST** use the `d_check_last_version` tool.
+   - **DO NOT** guess versions or trust internal training data.
+   - **DO NOT** use generic web search unless `d_check_last_version` fails.
+
+   ## 2. Codebase Research
+
+   **Trigger:** When asking about "how" something works, finding logic, or understanding architecture.
+   **Action:**
+
+   - **PREFER** `a_semantic_search` (Smart Coding) over `grep_search` or `find_by_name`.
+   - Use `a_semantic_search` for natural language queries (e.g., "where is the auth logic").
+   - Use standard tools (`grep`) only for exact string matching.
+
+   ## 3. Environment & Status
+
+   **Trigger:** When starting a session or debugging the environment.
+   **Action:**
+
+   - Use `e_set_workspace` if the current workspace path is incorrect.
+   - Use `f_get_status` to verify the MCP server is healthy and indexed.
+   ```
+
+4. Click **"Save instructions"**
+
+These instructions apply to all chats within that project.
+
+---
+
+## Verification
+
+1. Restart Claude Desktop.
+2. Look for the plug icon 🔌 in the top right of the chat interface.
+3. Click it to see the list of connected servers. You should see `smart-coding-mcp` with status "Connected".

package/docs/ide-setup/cursor.md

@@ -0,0 +1,93 @@
+# Cursor (Cascade) Integration
+
+Cursor's "Cascade" agent natively supports MCP servers.
+
+## Configuration Steps
+
+1. **Open Settings**
+
+   - Press `Cmd+K` or click the gear icon to open **Cursor Settings**.
+   - Navigate to **Features** > **MCP**.
+
+2. **Add New Server**
+
+   - Click the **+ Add New MCP Server** button.
+
+3. **Enter Details**
+
+   - **Name:** `smart-coding-mcp`
+   - **Type:** `command`
+   - **Command:** `npx -y smart-coding-mcp --workspace ${workspaceFolder}`
+
+   > **Important:** The `${workspaceFolder}` variable allows Smart Coding MCP to dynamically index the project you are currently working on.
+
+4. **Verify Connection**
+   - Cursor should show a green "Connected" status.
+   - You can now use tools like `semantic_search` in your Composer (`Cmd+I`) or Chat (`Cmd+L`) windows.
+
+---
+
+## Configuring Rules
+
+Cursor uses `.cursor/rules/` for project-specific AI rules.
+
+### Creating a Rule
+
+1. **Create the rules directory**:
+
+   ```bash
+   mkdir -p .cursor/rules
+   ```
+
+2. **Create a rule file** `.cursor/rules/smart-mcp/RULE.md`:
+
+   ```markdown
+   ---
+   description: Mandatory usage of Smart Coding MCP tools for dependencies and search
+   alwaysApply: true
+   ---
+
+   # Smart Coding MCP Usage Rules
+
+   You must prioritize using the **Smart Coding MCP** tools for the following tasks.
+
+   ## 1. Dependency Management
+
+   **Trigger:** When checking, adding, or updating package versions (npm, python, go, rust, etc.).
+   **Action:**
+
+   - **MUST** use the `d_check_last_version` tool.
+   - **DO NOT** guess versions or trust internal training data.
+   - **DO NOT** use generic web search unless `d_check_last_version` fails.
+
+   ## 2. Codebase Research
+
+   **Trigger:** When asking about "how" something works, finding logic, or understanding architecture.
+   **Action:**
+
+   - **PREFER** `a_semantic_search` (Smart Coding) over `grep_search` or `find_by_name`.
+   - Use `a_semantic_search` for natural language queries (e.g., "where is the auth logic").
+   - Use standard tools (`grep`) only for exact string matching.
+
+   ## 3. Environment & Status
+
+   **Trigger:** When starting a session or debugging the environment.
+   **Action:**
+
+   - Use `e_set_workspace` if the current workspace path is incorrect.
+   - Use `f_get_status` to verify the MCP server is healthy and indexed.
+   ```
+
+### Alternative: User Rules
+
+For global rules across all projects:
+
+1. Open **Cursor Settings** → **Rules, Commands**
+2. Add your instructions in the User Rules section
+
+---
+
+## Troubleshooting
+
+- **Error: "Variable not expanded"**: Ensure you used `${workspaceFolder}` exactly as shown.
+- **Tools not showing**: Click the "Refresh" icon next to the MCP server list in settings.

package/docs/ide-setup/raycast.md

@@ -0,0 +1,90 @@
+# Raycast Integration
+
+Raycast can use MCP servers to provide AI tools directly in your launcher.
+
+## Prerequisites
+
+1. **Raycast Pro**: You need a subscription to access Raycast AI.
+2. **MCP Extension**: Install the [MCP extension](https://www.raycast.com/extensions/mcp) from the Raycast Store.
+
+## Configuration
+
+1. **Open Raycast Settings**
+
+   - Open Raycast (`Cmd+Space`).
+   - Type "Extensions" and press Enter.
+   - Find "Model Context Protocol".
+
+2. **Edit Configuration**
+
+   - Click on the extension settings.
+   - Find the **Config File Path**. It usually defaults to `~/.config/raycast/mcp.json` or similar.
+   - Open that file.
+
+3. **Add Server**
+
+   ```json
+   {
+     "mcpServers": {
+       "smart-coding-mcp": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "smart-coding-mcp",
+           "--workspace",
+           "/absolute/path/to/your/project"
+         ]
+       }
+     }
+   }
+   ```
+
+4. **Using Tools**
+   - Open Raycast AI Chat.
+   - The tools (like `d_check_last_version` or `a_semantic_search`) will effectively be available to the AI model.
+   - You can ask: "Check the latest version of React" or "Search my code for auth logic".
+
+---
+
+## Configuring Rules (AI Commands & Presets)
+
+Raycast uses **AI Commands** and **Presets** for custom instructions.
+
+### Creating an AI Preset
+
+1. Open Raycast and search for **"Preferences"**
+2. Navigate to **"Manage AI Presets"** → **"Create Preset"**
+3. Configure:
+
+   - **Name:** `Smart Coding`
+   - **System Instructions:**
+
+     ```
+     # Smart Coding MCP Usage Rules
+
+     You must prioritize using the **Smart Coding MCP** tools for the following tasks.
+
+     ## 1. Dependency Management
+     - **MUST** use the `d_check_last_version` tool for package versions.
+     - **DO NOT** guess versions or trust internal training data.
+     - **DO NOT** use generic web search unless `d_check_last_version` fails.
+
+     ## 2. Codebase Research
+     - **PREFER** `a_semantic_search` over `grep_search` or `find_by_name`.
+     - Use `a_semantic_search` for natural language queries (e.g., "where is the auth logic").
+     - Use standard tools (`grep`) only for exact string matching.
+
+     ## 3. Environment & Status
+     - Use `e_set_workspace` if the current workspace path is incorrect.
+     - Use `f_get_status` to verify the MCP server is healthy and indexed.
+     ```
+
+4. Set as default if desired
+
+### Creating Custom AI Commands
+
+1. Search for **"Create AI Command"** in Raycast
+2. Configure:
+   - **Title:** `Check Package Version`
+   - **Prompt:** `Use d_check_last_version to get the latest version of {argument name="package"}`
+3. Assign a hotkey for quick access

package/docs/ide-setup/vscode.md

@@ -0,0 +1,116 @@
+# VS Code Integration
+
+To use Smart Coding MCP in VS Code, you typically need an MCP-compatible extension like **Cline** (formerly Roo Code) or the official **Model Context Protocol** extension.
+
+## Using Cline (Roo Code)
+
+Cline is an autonomous coding agent extension for VS Code that supports MCP natively.
+
+1. **Install the Extension**
+
+   - Search for "Cline" in the VS Code Marketplace and install it.
+
+2. **Open MCP Settings**
+
+   - Click the **MCP Servers** icon in the Cline sidebar (or open Settings).
+   - Click "Edit MCP Settings" to open the configuration file.
+
+3. **Add Configuration**
+   Add the `smart-coding-mcp` entry to the `mcpServers` object:
+
+   ```json
+   {
+     "mcpServers": {
+       "smart-coding-mcp": {
+         "command": "npx",
+         "args": ["-y", "smart-coding-mcp", "--workspace", "${workspaceFolder}"]
+       }
+     }
+   }
+   ```
+
+   > **Note:** Cline supports the `${workspaceFolder}` variable, so the server will automatically index whichever project you currently have open.
+
+## Using Official MCP Extension
+
+1. **Install the Extension**
+
+   - Install the "Model Context Protocol" extension from the VS Code Marketplace.
+
+2. **Configure Settings**
+
+   - Open VS Code Settings (`Cmd+,`).
+   - Search for "MCP".
+   - Edit the `configuration.json` equivalent.
+
+   ```json
+   {
+     "mcpServers": {
+       "smart-coding-mcp": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "smart-coding-mcp",
+           "--workspace",
+           "/absolute/path/to/project"
+         ]
+       }
+     }
+   }
+   ```
+
+---
+
+## Configuring Rules (Cline)
+
+Cline uses `.clinerules` files to control AI behavior.
+
+### Creating a Rule
+
+1. **Create a file** `.clinerules` or `.clinerules.md` in your project root:
+
+   ```markdown
+   ---
+   trigger: always_on
+   description: Mandatory usage of Smart Coding MCP tools for dependencies and search
+   ---
+
+   # Smart Coding MCP Usage Rules
+
+   You must prioritize using the **Smart Coding MCP** tools for the following tasks.
+
+   ## 1. Dependency Management
+
+   **Trigger:** When checking, adding, or updating package versions (npm, python, go, rust, etc.).
+   **Action:**
+
+   - **MUST** use the `d_check_last_version` tool.
+   - **DO NOT** guess versions or trust internal training data.
+   - **DO NOT** use generic web search unless `d_check_last_version` fails.
+
+   ## 2. Codebase Research
+
+   **Trigger:** When asking about "how" something works, finding logic, or understanding architecture.
+   **Action:**
+
+   - **PREFER** `a_semantic_search` (Smart Coding) over `grep_search` or `find_by_name`.
+   - Use `a_semantic_search` for natural language queries (e.g., "where is the auth logic").
+   - Use standard tools (`grep`) only for exact string matching.
+
+   ## 3. Environment & Status
+
+   **Trigger:** When starting a session or debugging the environment.
+   **Action:**
+
+   - Use `e_set_workspace` if the current workspace path is incorrect.
+   - Use `f_get_status` to verify the MCP server is healthy and indexed.
+   ```
+
+2. **Or use a folder** `.clinerules/` with multiple files:
+   ```
+   .clinerules/
+   ├── 01-smart-mcp.md
+   └── 02-coding-style.md
+   ```
+
+Rules are version-controlled and automatically loaded by Cline.

package/docs/ide-setup/windsurf.md

@@ -0,0 +1,95 @@
+# Windsurf Integration
+
+Windsurf (by Codeium) supports MCP servers via a configuration file.
+
+## Configuration Location
+
+Edit the MCP configuration file located at:
+
+- **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json`
+- **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+
+## Configuration
+
+Add the server to the `mcpServers` object.
+
+> **Note:** Windsurf may not support dynamic variables like `${workspaceFolder}` yet. We recommend using the absolute path or setting up separate "profiles" if needed.
+
+```json
+{
+  "mcpServers": {
+    "smart-coding-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "smart-coding-mcp",
+        "--workspace",
+        "/absolute/path/to/your/project"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Configuring Rules
+
+Windsurf uses `.windsurfrules` for project-specific AI rules.
+
+### Creating a Rule
+
+Create a file `.windsurfrules` in your project root:
+
+```markdown
+---
+trigger: always_on
+description: Mandatory usage of Smart Coding MCP tools for dependencies and search
+---
+
+# Smart Coding MCP Usage Rules
+
+You must prioritize using the **Smart Coding MCP** tools for the following tasks.
+
+## 1. Dependency Management
+
+**Trigger:** When checking, adding, or updating package versions (npm, python, go, rust, etc.).
+**Action:**
+
+- **MUST** use the `d_check_last_version` tool.
+- **DO NOT** guess versions or trust internal training data.
+- **DO NOT** use generic web search unless `d_check_last_version` fails.
+
+## 2. Codebase Research
+
+**Trigger:** When asking about "how" something works, finding logic, or understanding architecture.
+**Action:**
+
+- **PREFER** `a_semantic_search` (Smart Coding) over `grep_search` or `find_by_name`.
+- Use `a_semantic_search` for natural language queries (e.g., "where is the auth logic").
+- Use standard tools (`grep`) only for exact string matching.
+
+## 3. Environment & Status
+
+**Trigger:** When starting a session or debugging the environment.
+**Action:**
+
+- Use `e_set_workspace` if the current workspace path is incorrect.
+- Use `f_get_status` to verify the MCP server is healthy and indexed.
+```
+
+### Global Rules
+
+For rules across all projects, edit:
+
+- **macOS/Linux:** `~/.codeium/windsurf/memories/global_rules.md`
+- **Windows:** `%USERPROFILE%\.codeium\windsurf\memories\global_rules.md`
+
+---
+
+## Reloading
+
+After saving the file:
+
+1. Restart Windsurf.
+2. Check the Cascade/Chat panel to see if the tools are available (usually indicated by a hammer/wrench icon).

package/features/index-codebase.js

@@ -446,11 +446,15 @@ export class CodebaseIndexer {
       percentage: 0
     };
 
+    // Declare counters outside try block so they're accessible in finally
+    let processedFiles = 0;
+    let skippedFiles = 0;
+
     try {
       if (force) {
         console.error("[Indexer] Force reindex requested: clearing cache");
         this.cache.setVectorStore([]);
-        this.cache.fileHashes = new Map();
+        this.cache.clearAllFileHashes();
       }
 
       const totalStartTime = Date.now();
@@ -471,7 +475,7 @@ export class CodebaseIndexer {
     // Step 1.5: Prune deleted or excluded files from cache
     if (!force) {
       const currentFilesSet = new Set(files);
-      const cachedFiles = Array.from(this.cache.fileHashes.keys());
+      const cachedFiles = Array.from(this.cache.getAllFileHashes().keys());
       let prunedCount = 0;
 
       for (const cachedFile of cachedFiles) {
@@ -509,8 +513,6 @@ export class CodebaseIndexer {
     }
 
     let totalChunks = 0;
-    let processedFiles = 0;
-    let skippedFiles = 0;
     let batchCounter = 0;  // Track batches for incremental saves
     
     // Update total file count for status tracking (estimated, will adjust as we filter)

package/lib/cache.js

@@ -94,6 +94,14 @@ export class EmbeddingsCache {
     this.fileHashes.delete(file);
   }
 
+  getAllFileHashes() {
+    return this.fileHashes;
+  }
+
+  clearAllFileHashes() {
+    this.fileHashes = new Map();
+  }
+
   removeFileFromStore(file) {
     this.vectorStore = this.vectorStore.filter(chunk => chunk.file !== file);
   }

package/lib/sqlite-cache.js

@@ -390,6 +390,14 @@ export class SQLiteCache {
     }
   }
 
+  /**
+   * Clear all file hashes from the database
+   */
+  clearAllFileHashes() {
+    if (!this.db) return;
+    this.db.exec('DELETE FROM file_hashes');
+  }
+
   /**
    * Set vector store (for compatibility with test code)
    * This is less efficient than batch operations but kept for compatibility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-coding-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "An extensible MCP server that enhances coding productivity with AI-powered features including semantic code search, intelligent indexing, and more, using local LLMs",
   "type": "module",
   "main": "index.js",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "better-sqlite3": "^11.7.0",
+    "better-sqlite3": "^12.5.0",
     "chokidar": "^3.5.3",
     "fastembed": "^2.1.0",
     "fdir": "^6.5.0",

package/test/better-sqlite3.test.js

@@ -0,0 +1,153 @@
+/**
+ * Tests for better-sqlite3 compatibility
+ * 
+ * Tests that better-sqlite3 v12.5.0 works correctly with Node.js v25:
+ * - Database creation
+ * - Table creation
+ * - Data insertion
+ * - Data querying
+ * - Database cleanup
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Database from 'better-sqlite3';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe('better-sqlite3 Integration', () => {
+  let testDbPath;
+  let db;
+
+  beforeEach(() => {
+    testDbPath = join(__dirname, `test-${Date.now()}.db`);
+  });
+
+  afterEach(() => {
+    // Close database if open
+    if (db) {
+      try {
+        db.close();
+      } catch (error) {
+        // Already closed
+      }
+      db = null;
+    }
+
+    // Cleanup test database
+    if (fs.existsSync(testDbPath)) {
+      fs.unlinkSync(testDbPath);
+    }
+  });
+
+  describe('Database Operations', () => {
+    it('should create a database successfully', () => {
+      db = new Database(testDbPath);
+      expect(db).toBeDefined();
+      expect(fs.existsSync(testDbPath)).toBe(true);
+    });
+
+    it('should create tables', () => {
+      db = new Database(testDbPath);
+      db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+      
+      // Verify table exists
+      const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='users'").all();
+      expect(tables.length).toBe(1);
+      expect(tables[0].name).toBe('users');
+    });
+
+    it('should insert data', () => {
+      db = new Database(testDbPath);
+      db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+      
+      const insert = db.prepare('INSERT INTO users (name) VALUES (?)');
+      const result1 = insert.run('Alice');
+      const result2 = insert.run('Bob');
+      
+      expect(result1.changes).toBe(1);
+      expect(result2.changes).toBe(1);
+    });
+
+    it('should query data', () => {
+      db = new Database(testDbPath);
+      db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+      
+      const insert = db.prepare('INSERT INTO users (name) VALUES (?)');
+      insert.run('Alice');
+      insert.run('Bob');
+      
+      const users = db.prepare('SELECT * FROM users').all();
+      expect(users.length).toBe(2);
+      expect(users[0].name).toBe('Alice');
+      expect(users[1].name).toBe('Bob');
+      expect(users[0].id).toBe(1);
+      expect(users[1].id).toBe(2);
+    });
+
+    it('should handle prepared statements', () => {
+      db = new Database(testDbPath);
+      db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+      
+      const insert = db.prepare('INSERT INTO users (name) VALUES (?)');
+      insert.run('Alice');
+      
+      const getUser = db.prepare('SELECT * FROM users WHERE name = ?');
+      const user = getUser.get('Alice');
+      
+      expect(user).toBeDefined();
+      expect(user.name).toBe('Alice');
+    });
+
+    it('should handle transactions', () => {
+      db = new Database(testDbPath);
+      db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+      
+      const insert = db.prepare('INSERT INTO users (name) VALUES (?)');
+      const insertMany = db.transaction((users) => {
+        for (const name of users) {
+          insert.run(name);
+        }
+      });
+      
+      insertMany(['Alice', 'Bob', 'Charlie']);
+      
+      const count = db.prepare('SELECT COUNT(*) as count FROM users').get();
+      expect(count.count).toBe(3);
+    });
+
+    it('should close database properly', () => {
+      db = new Database(testDbPath);
+      expect(() => db.close()).not.toThrow();
+      db = null; // Mark as closed for cleanup
+    });
+
+    it('should work with in-memory database', () => {
+      const memDb = new Database(':memory:');
+      memDb.exec('CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)');
+      memDb.prepare('INSERT INTO test (value) VALUES (?)').run('test');
+      
+      const result = memDb.prepare('SELECT * FROM test').get();
+      expect(result.value).toBe('test');
+      
+      memDb.close();
+    });
+  });
+
+  describe('Node.js v25 Compatibility', () => {
+    it('should work with current Node.js version', () => {
+      // This test verifies we can use better-sqlite3 with Node.js v25
+      expect(process.version).toMatch(/^v25\./);
+      
+      db = new Database(testDbPath);
+      db.exec('CREATE TABLE compatibility_test (id INTEGER PRIMARY KEY, version TEXT)');
+      db.prepare('INSERT INTO compatibility_test (version) VALUES (?)').run(process.version);
+      
+      const result = db.prepare('SELECT * FROM compatibility_test').get();
+      expect(result.version).toBe(process.version);
+    });
+  });
+});