codeatlas-mcp-server 2.20.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 giauphan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+<div align="center">
+
+# CodeAtlas MCP Enterprise
+
+**Enterprise-Grade, Local-First MCP Server for AI-Powered Code Intelligence**
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/typescript-%5E5.4-blue)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io)
+[![npm](https://img.shields.io/npm/v/codeatlas-enterprise)](https://www.npmjs.com/package/codeatlas-enterprise)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/giauphan/codeatlas-mcp-server/pulls)
+
+**CodeAtlas MCP Enterprise** is an ultra-lightweight, local-first [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that securely indexes your codebase, performs deep AST-based analysis, and provides 20+ intelligent tools for AI code assistants. **Your source code never leaves your machine.**
+
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [Why CodeAtlas MCP?](#-why-codeatlas-mcp)
+- [Features](#-features)
+- [Architecture Overview](#-architecture-overview)
+- [Quick Start](#-quick-start)
+- [Authentication](#-authentication)
+- [AI Editor Integration](#-ai-editor-integration)
+  - [Cursor](#cursor)
+  - [Claude Desktop](#claude-desktop)
+  - [VS Code / Windsurf / Copilot](#vs-code--windsurf--copilot)
+- [MCP Tools Reference](#-mcp-tools-reference)
+  - [Analysis & Indexing](#analysis--indexing)
+  - [Code Exploration](#code-exploration)
+  - [Dependency & Impact Analysis](#dependency--impact-analysis)
+  - [Visualization & Diagrams](#visualization--diagrams)
+  - [Memory & Persistence](#memory--persistence)
+  - [Security & Architecture](#security--architecture)
+  - [Project Operations](#project-operations)
+- [Security Model](#-security-model)
+- [Multi-Tenant Mode](#-multi-tenant-mode)
+- [Environment Configuration](#-environment-configuration)
+- [How It Works](#-how-it-works)
+- [License](#-license)
+
+---
+
+## 🎯 Why CodeAtlas MCP?
+
+AI code assistants are powerful — but they work best with **context**. CodeAtlas gives them X-ray vision into your codebase by:
+
+- 🔍 **Deep parsing** — Understands JavaScript, TypeScript, Python, and PHP at the AST level
+- 🧠 **Persistent memory** — Retains insights across conversations via Dreaming Memory
+- 🔒 **Zero data leakage** — All parsing happens locally, no source code ever transmitted
+- ⚡ **Blazing fast** — Full codebase analysis in seconds, incremental re-indexing
+- 🔌 **Universal compatibility** — Works with any MCP-compatible editor (Cursor, Claude, VS Code, Windsurf, Copilot)
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔒 **Local-First Parsing** | AST analysis runs entirely on your machine — zero code uploaded |
+| 🔌 **MCP Protocol** | Works with all MCP-compatible AI editors |
+| 📁 **Auto Workspace Discovery** | Automatically finds projects in your workspace |
+| 🔍 **Multi-Language AST** | JavaScript, TypeScript, Python, PHP with deep dependency resolution |
+| 🧠 **Dreaming Memory** | Persistent AI memory with vector search for cross-session context |
+| 🏠 **Multi-Tenant Isolation** | Isolate projects by workspace with sandbox boundaries |
+| 🔐 **API Key Auth** | Secure communication via cryptographic hash verification |
+| ⚡ **Incremental Indexing** | Only re-parses changed files for near-instant updates |
+| 🏗️ **Knowledge Graph** | Visualize modules, classes, and functions as an interactive graph |
+| 🌐 **Remote Sync** | Optionally sync metadata to CodeAtlas Enterprise via HTTPS |
+| 📊 **Code Metrics** | LOC, complexity scores, function counts per project |
+| 🛡️ **Security Scanner** | Detect hardcoded secrets, unsafe functions, SQL injection |
+| 🔄 **Real-time Watching** | Auto re-index on file changes via chokidar |
+
+---
+
+## 🏗 Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Your Local Machine                     │
+│                                                           │
+│   ┌──────────┐    ┌────────────┐    ┌────────────────┐   │
+│   │  Source   │───▶│    AST     │───▶│   MCP Server   │   │
+│   │  Code     │    │   Parser   │    │  (this tool)   │───┼──▶ AI Editor
+│   │  (JS/TS/  │    │  (local)   │    └───────┬────────┘   │
+│   │   PY/PHP)│    └────────────┘            │            │
+│   └──────────┘                               │            │
+│                                              ▼            │
+│                                  ┌──────────────────┐     │
+│                                  │  Dreaming Memory  │     │
+│                                  │  (optional: sync) │     │
+│                                  └────────┬─────────┘     │
+└───────────────────────────────────────────┼───────────────┘
+                                            │ HTTPS (optional)
+                                            ▼
+                               CodeAtlas Enterprise Server
+```
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Node.js** v18.0.0 or higher (v20+ recommended)
+
+### Install Globally
+
+```bash
+npm install -g codeatlas-enterprise
+```
+
+### Run
+
+```bash
+# Scan current directory and start MCP server
+codeatlas-mcp
+
+# With API key for remote sync
+codeatlas-mcp --apiKey="your_api_key_here"
+
+# Point to a specific project directory
+codeatlas-mcp --projectDir="/path/to/your/project"
+```
+
+That's it! Your AI editor can now connect to the MCP server running on stdio.
+
+---
+
+## 🔑 Authentication
+
+Provide your API Key in one of these ways:
+
+1. **Environment Variable**:
+   ```bash
+   export CODEATLAS_API_KEY="your_api_key_here"
+   ```
+
+2. **CLI Argument**:
+   ```bash
+   codeatlas-mcp --apiKey="your_api_key_here"
+   ```
+
+3. **Local `.env` File** (in the directory where you run the command):
+   ```env
+   CODEATLAS_API_KEY=your_api_key_here
+   ```
+
+---
+
+## 🔌 AI Editor Integration
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` or project-level `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "codeatlas-mcp",
+      "args": ["--apiKey", "YOUR_API_KEY_HERE"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "codeatlas-mcp",
+      "args": ["--apiKey", "YOUR_API_KEY_HERE"]
+    }
+  }
+}
+```
+
+### VS Code / Windsurf / Copilot
+
+For any MCP-compatible editor, use the same JSON structure:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "codeatlas-mcp",
+      "args": ["--apiKey", "YOUR_API_KEY_HERE"]
+    }
+  }
+}
+```
+
+> **Note:** If you're running without a remote server, omit the `--apiKey` argument. The local MCP tools (analysis, search, graph) work fully offline.
+
+---
+
+## 🛠 MCP Tools Reference
+
+CodeAtlas MCP exposes **20+ tools** organized into categories:
+
+### Analysis & Indexing
+| Tool | Description |
+|------|-------------|
+| `analyze` | Trigger full AST analysis of the current project |
+| `get_project_structure` | Get entities tree (modules, classes, functions, variables) |
+| `get_file_entities` | List all entities defined in a specific file |
+
+### Code Exploration
+| Tool | Description |
+|------|-------------|
+| `search_entities` | Search for functions, classes, modules by name (fuzzy) |
+| `code_search` | Search source file contents for any text or regex |
+| `get_file_content` | Read file contents with line numbers |
+
+### Dependency & Impact Analysis
+| Tool | Description |
+|------|-------------|
+| `get_callers` | Find all functions/callers that reference a symbol |
+| `get_callees` | Find everything a function/module imports or calls |
+| `impact_analysis` | Full blast radius: callers + callees + test files |
+| `get_dependencies` | Get import/call/containment/implements relationships |
+
+### Visualization & Diagrams
+| Tool | Description |
+|------|-------------|
+| `generate_system_flow` | Mermaid flowchart of module architecture |
+| `generate_feature_flow_diagram` | Mermaid sequence/flow diagram for a feature |
+| `trace_feature_flow` | Ordered call chain from entry point to database |
+
+### Memory & Persistence
+| Tool | Description |
+|------|-------------|
+| `query_dream_memories` | Semantic vector search across past AI memories |
+| `save_dream_memory` | Persist an AI insight or observation for future sessions |
+| `get_system_memory` | Retrieve business rules and change logs |
+| `sync_system_memory` | Save business rules or change descriptions |
+
+### Security & Architecture
+| Tool | Description |
+|------|-------------|
+| `scan_enterprise_vulnerabilities` | Scan all projects for hardcoded secrets, unsafe functions, SQL injection |
+| `detect_architectural_smells` | Detect circular dependencies, God objects, dead code |
+
+### Project Operations
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all discovered and indexed projects |
+| `refresh_projects` | Re-scan directories for new or removed projects |
+| `get_project_insights` | AI-generated refactoring and maintainability suggestions |
+
+---
+
+## 🔒 Security Model
+
+### 🔐 Local-First by Design
+
+CodeAtlas MCP Enterprise follows a **zero-trust, local-first architecture**:
+
+1. **Parsing is local** — All source file reading, AST generation, and relationship mapping happens on your machine. No source code is ever uploaded.
+
+2. **No credentials embedded** — The package contains zero database passwords, Firebase configs, or private server keys. All remote communication uses standard HTTPS with Bearer token auth.
+
+3. **Encrypted sync** — If you enable remote sync, metadata is transmitted over HTTPS. The server authenticates via cryptographic hash of your API key.
+
+### 🔒 What Gets Sent (When Sync is Enabled)
+
+Only **structural metadata** is transmitted:
+- File paths and names (relative to project root)
+- Function/class/module names and line numbers
+- Import/export relationships
+- Analysis statistics (file count, LOC, complexity)
+
+**Raw source code, credentials, and proprietary logic are never transmitted.**
+
+### 🏠 Multi-Tenant Isolation
+
+When multi-tenant mode is enabled:
+- Each tenant's projects are isolated in separate sandbox directories
+- Path traversal attacks are blocked by strict boundary validation
+- Memory and analysis data are scoped per-tenant
+
+---
+
+## 🏠 Multi-Tenant Mode
+
+Enable tenant isolation via environment variables:
+
+```env
+CODEATLAS_MULTI_TENANT=true
+CODEATLAS_PROJECTS_ROOT=./tenants
+```
+
+Each tenant's projects live in `./tenants/{tenantId}/`, with strict path-boundary enforcement.
+
+---
+
+## 🌍 Environment Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEATLAS_API_KEY` | — | API key for authenticating with remote server |
+| `CODEATLAS_API_URL` | `https://your-server.com/api` | Remote CodeAtlas server URL |
+| `CODEATLAS_MULTI_TENANT` | `false` | Enable multi-tenant isolation |
+| `CODEATLAS_PROJECTS_ROOT` | `./tenants` | Root directory for tenant sandboxes |
+| `CODEATLAS_PROJECT_DIR` | `process.cwd()` | Default project path |
+| `NODE_ENV` | `production` | Environment mode |
+
+---
+
+## ⚙️ How It Works
+
+1. **Start** — Run `codeatlas-mcp` in your project directory or point it with `--projectDir`
+2. **Auto-Discover** — The server scans for projects by detecting `package.json`, `pyproject.toml`, `composer.json`
+3. **AST Parse** — Each source file is parsed into an Abstract Syntax Tree
+4. **Build Graph** — Modules, classes, functions, and their relationships form a Knowledge Graph
+5. **Serve MCP** — AI editors query the graph through 20+ MCP tools
+6. **Dream** — Insights persist across sessions via Dreaming Memory (optional remote vector store)
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 Giau Phan
+
+---
+
+## 🔗 Related Projects
+
+- [CodeAtlas AI](https://github.com/giauphan/codeatlas-ai) — Full enterprise server with Oracle 26ai memory, dashboard, security scanner
+- [npm package](https://www.npmjs.com/package/codeatlas-enterprise) — Install via npm

package/dist/index.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as dotenv from "dotenv";
+import { fileURLToPath } from "url";
+import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+// Configure centralized log file in ~/.codeatlas/mcp.log
+const homeDir = os.homedir();
+const logDir = path.join(homeDir, ".codeatlas");
+const logFilePath = path.join(logDir, "mcp.log");
+const pidFilePath = path.join(logDir, "mcp.pid");
+try {
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+}
+catch (err) {
+    // Ignore directory creation errors
+}
+// ── Single-instance PID guard ──────────────────────────────────────────
+// Prevents duplicate MCP server processes from consuming excessive memory.
+// But allow --version and --help flags to pass through.
+// Handle --version before PID guard
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    // Try both relative locations (source: index.ts, dist: dist/index.js)
+    let pkg;
+    for (const p of ['./package.json', '../package.json']) {
+        try {
+            pkg = JSON.parse(fs.readFileSync(new URL(p, import.meta.url), 'utf-8'));
+            break;
+        }
+        catch { }
+    }
+    if (pkg)
+        console.log(pkg.version);
+    process.exit(0);
+}
+if (!process.argv.includes('--help') && !process.argv.includes('-h')) {
+    try {
+        if (fs.existsSync(pidFilePath)) {
+            const existingPid = parseInt(fs.readFileSync(pidFilePath, "utf-8").trim(), 10);
+            if (!isNaN(existingPid) && existingPid > 0) {
+                try {
+                    process.kill(existingPid, 0); // Check if alive
+                    // Another instance is already running. Exit immediately to avoid duplicates.
+                    // DO NOT kill the old instance — that would break the active MCP connection
+                    // and cause Hermes to reconnect in an infinite kill-restart loop.
+                    console.error(`[PID-Guard] 🔒 Instance already running (PID: ${existingPid}). New instance exiting.`);
+                    process.exit(0);
+                }
+                catch (e) {
+                    if (e?.code === 'ESRCH') {
+                        console.error(`[PID-Guard] 🗑️ Stale PID ${existingPid} — old instance is gone. Starting fresh.`);
+                    }
+                    else {
+                        console.error(`[PID-Guard] ⚠️ Cannot verify PID ${existingPid}. Will overwrite.`);
+                    }
+                }
+            }
+        }
+        fs.writeFileSync(pidFilePath, String(process.pid));
+        console.error(`[PID-Guard] 🔒 Lock acquired (PID: ${process.pid})`);
+    }
+    catch (err) {
+        console.error(`[PID-Guard] ⚠️ Could not write PID file — running without guard: ${err}`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────────
+// ⚠️ NOTE: API key must be set via CODEATLAS_API_KEY environment variable or .env file.
+// Passing API keys via command-line arguments is NOT supported — they are visible
+// to all users on the system via `ps aux`. Use environment variables instead.
+// Parse command line arguments for projectDir (safe directory path, not a secret)
+const projectDirArgIndex = process.argv.findIndex(arg => arg.startsWith('--projectDir'));
+if (projectDirArgIndex !== -1) {
+    const arg = process.argv[projectDirArgIndex];
+    let val = '';
+    if (arg.includes('=')) {
+        val = arg.split('=')[1];
+    }
+    else if (projectDirArgIndex + 1 < process.argv.length) {
+        val = process.argv[projectDirArgIndex + 1];
+    }
+    if (val) {
+        process.env.CODEATLAS_PROJECT_DIR = val;
+    }
+}
+// Async logging queue to prevent blocking the Event Loop on console.error
+const logQueue = [];
+let isWritingLogs = false;
+async function flushLogQueue() {
+    if (isWritingLogs || logQueue.length === 0)
+        return;
+    isWritingLogs = true;
+    while (logQueue.length > 0) {
+        const message = logQueue.shift();
+        if (message) {
+            try {
+                await fs.promises.appendFile(logFilePath, message);
+            }
+            catch (err) {
+                // Ignore write errors
+            }
+        }
+    }
+    isWritingLogs = false;
+}
+const originalConsoleError = console.error;
+console.error = (...args) => {
+    originalConsoleError(...args);
+    try {
+        const message = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+        const timestamp = new Date().toISOString();
+        // Cap log queue at 1000 entries to prevent unbounded memory growth
+        if (logQueue.length >= 1000) {
+            logQueue.shift();
+        }
+        logQueue.push(`[${timestamp}] ${message}\n`);
+        flushLogQueue().catch(() => { });
+    }
+    catch (err) {
+        // Ignore queue errors
+    }
+};
+// Import Presentation Adapters
+import { server } from "./src/presentation/mcpServer.js";
+// Import Domain / Application Services
+import { checkAuth } from "./src/services/authService.js";
+import { getStats, discoverProjects, loadAnalysis, discoverProjectsAsync, loadAnalysisAsync, getWorkspaceFromAncestors, isSystemIdeDirectory, discoverGitSubProjects } from "./src/services/projectService.js";
+import { startWatcher, stopWatcher, isIndexingEnabledForProject } from "./src/services/watcherService.js";
+// Load environment variables
+dotenv.config();
+// Start server
+async function main() {
+    startWatcher();
+    // Function to scan workspace roots from the client
+    async function scanRoots() {
+        let succeeded = false;
+        try {
+            const result = await server.server.listRoots();
+            if (result && result.roots && result.roots.length > 0) {
+                succeeded = true;
+                console.error(`[Auto-Scan] 📂 Discovered ${result.roots.length} workspace root(s) from client.`);
+                for (const root of result.roots) {
+                    if (root.uri.startsWith("file://")) {
+                        const workspacePath = fileURLToPath(root.uri).trim();
+                        if (isSystemIdeDirectory(workspacePath)) {
+                            console.error(`[Auto-Scan] 🛡️ Ignored IDE system/extensions directory: ${workspacePath}`);
+                            continue;
+                        }
+                        // Scan subdirectories for .git projects
+                        const subProjects = await discoverGitSubProjects(workspacePath, true);
+                        if (subProjects.length > 0) {
+                            console.error(`[Auto-Scan] 📦 Found ${subProjects.length} project(s) with .git and open in IDE inside ${path.basename(workspacePath)}`);
+                            for (const subDir of subProjects) {
+                                const subName = path.basename(subDir);
+                                isIndexingEnabledForProject(subName).then((enabled) => {
+                                    if (!enabled) {
+                                        console.error(`[Auto-Scan] ⏸️  Auto-indexing disabled for [${subName}]. Skipping.`);
+                                        return;
+                                    }
+                                    console.error(`[Auto-Scan] 🔄 Indexing sub-project: ${subDir}`);
+                                    loadAnalysisAsync(subDir, true).then((loaded) => {
+                                        if (loaded)
+                                            console.error(`[Auto-Scan] ✅ Indexed: ${subDir}`);
+                                        else
+                                            console.error(`[Auto-Scan] ⚠️ Skipped: ${subDir}`);
+                                    }).catch((err) => {
+                                        console.error(`[Auto-Scan] ❌ Failed: ${subDir}: ${err}`);
+                                    });
+                                }).catch(() => { });
+                            }
+                        }
+                        else {
+                            console.error(`[Auto-Scan] ℹ️ No .git projects found under container root: ${workspacePath}`);
+                        }
+                    }
+                    else {
+                        console.error(`[Auto-Scan] ⚠️ Ignored non-file URI root: ${root.uri}`);
+                    }
+                }
+            }
+            else {
+                console.error("[Auto-Scan] ℹ️ No workspace roots returned by client. Falling back to active workspace.");
+            }
+        }
+        catch (err) {
+            console.error(`[Auto-Scan] ⚠️ Failed to list workspace roots: ${err}. Falling back to active workspace.`);
+        }
+        if (!succeeded) {
+            const activeWorkspace = process.env.CODEATLAS_PROJECT_DIR || getWorkspaceFromAncestors() || process.env.GEMINI_CLI_IDE_WORKSPACE_PATH || process.cwd();
+            if (isSystemIdeDirectory(activeWorkspace)) {
+                console.error(`[Auto-Scan] 🛡️ Ignored IDE system directory fallback: ${activeWorkspace}`);
+                return;
+            }
+            const subProjects = await discoverGitSubProjects(activeWorkspace, true);
+            if (subProjects.length > 0) {
+                console.error(`[Auto-Scan] 📦 Fallback: found ${subProjects.length} IDE-open .git project(s) in ${activeWorkspace}`);
+                for (const subDir of subProjects) {
+                    const subName = path.basename(subDir);
+                    isIndexingEnabledForProject(subName).then((enabled) => {
+                        if (!enabled)
+                            return;
+                        loadAnalysisAsync(subDir, true).catch(() => { });
+                    }).catch(() => { });
+                }
+            }
+            else {
+                console.error(`[Auto-Scan] ℹ️ No .git projects found in workspace fallback: ${activeWorkspace}`);
+            }
+        }
+    }
+    // Hook into client initialized event to fetch and index workspace roots
+    server.server.oninitialized = () => {
+        console.error("[Auto-Scan] 🔌 MCP Client connection initialized. Checking workspace roots...");
+        scanRoots();
+    };
+    // Listen for changes to workspace roots
+    server.server.setNotificationHandler(RootsListChangedNotificationSchema, (notification) => {
+        console.error("[Auto-Scan] 🔔 Received roots/list_changed notification from client. Re-scanning workspace roots...");
+        scanRoots();
+    });
+    // Stdio Mode - for local use (e.g. Claude Desktop, Cursor)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("CodeAtlas MCP server running on stdio");
+}
+main().catch(console.error);
+// ── Graceful shutdown handlers ─────────────────────────────────────────
+// Prevent zombie processes by cleaning up watchers, cache, and PID file.
+function cleanup(signal) {
+    console.error(`[Cleanup] 🧹 Received ${signal}. Shutting down...`);
+    try {
+        stopWatcher();
+    }
+    catch (e) {
+        console.error(`[Cleanup] ⚠️ Watcher cleanup error: ${e}`);
+    }
+    try {
+        if (fs.existsSync(pidFilePath)) {
+            fs.unlinkSync(pidFilePath);
+            console.error(`[Cleanup] 🗑️ PID file removed.`);
+        }
+    }
+    catch (e) {
+        console.error(`[Cleanup] ⚠️ PID file cleanup error: ${e}`);
+    }
+    process.exit(0);
+}
+process.on("SIGTERM", () => cleanup("SIGTERM"));
+process.on("SIGINT", () => cleanup("SIGINT"));
+process.on("SIGQUIT", () => cleanup("SIGQUIT"));
+process.on("uncaughtException", (err) => {
+    console.error(`[Fatal] 💥 Uncaught exception: ${err}`);
+    cleanup("uncaughtException");
+});
+// ────────────────────────────────────────────────────────────────────────
+// Re-export core modules/helpers to maintain compatibility with test suite
+export { server, checkAuth, getStats, discoverProjects, loadAnalysis, discoverProjectsAsync, loadAnalysisAsync };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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