@a13xu/lucid 1.1.0 → 1.9.0

package/build/index.js

@@ -4,6 +4,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { initDatabase, prepareStatements } from "./database.js";
+import { guardRequest, guardOutput, configureGuard } from "./security/guard.js";
+import { allowHost } from "./security/ssrf.js";
+import { loadConfig } from "./config.js";
 import { remember, RememberSchema } from "./tools/remember.js";
 import { relate, RelateSchema } from "./tools/relate.js";
 import { recall, RecallSchema } from "./tools/recall.js";
@@ -11,15 +14,45 @@ import { recallAll } from "./tools/recall-all.js";
 import { forget, ForgetSchema } from "./tools/forget.js";
 import { memoryStats } from "./tools/stats.js";
 import { handleValidateFile, ValidateFileSchema, handleCheckDrift, CheckDriftSchema, handleGetChecklist, } from "./tools/guardian.js";
+import { handleGrepCode, GrepCodeSchema } from "./tools/grep.js";
+import { handleInitProject, InitProjectSchema } from "./tools/init.js";
+import { handleSyncFile, SyncFileSchema, handleSyncProject, SyncProjectSchema, } from "./tools/sync.js";
+import { handleGetContext, GetContextSchema, handleGetRecent, GetRecentSchema, } from "./tools/context.js";
+import { handleReward, RewardSchema, handlePenalize, PenalizeSchema, handleShowRewards, ShowRewardsSchema, } from "./tools/reward.js";
+import { handleGetCodingRules, handleCheckCodeQuality, CheckCodeQualitySchema, } from "./tools/coding-guard.js";
 // ---------------------------------------------------------------------------
 // Init DB
 // ---------------------------------------------------------------------------
 const db = initDatabase();
 const stmts = prepareStatements(db);
 // ---------------------------------------------------------------------------
+// Security guard — initialize from config + env
+// ---------------------------------------------------------------------------
+const _appCfg = loadConfig();
+configureGuard(_appCfg.security ?? {});
+// Register Qdrant host in SSRF allowlist if configured
+const _qdrantUrl = process.env["QDRANT_URL"] ?? _appCfg.qdrant?.url;
+if (_qdrantUrl) {
+    try {
+        allowHost(_qdrantUrl);
+    }
+    catch { /* ignore invalid URL */ }
+}
+const _embeddingUrl = process.env["EMBEDDING_URL"] ?? _appCfg.qdrant?.embeddingUrl;
+if (_embeddingUrl) {
+    try {
+        allowHost(_embeddingUrl);
+    }
+    catch { /* ignore */ }
+}
+else {
+    // Default embedding endpoint
+    allowHost("https://api.openai.com");
+}
+// ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "lucid", version: "1.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "lucid", version: "1.9.0" }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------
@@ -90,6 +123,140 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Get memory usage statistics.",
             inputSchema: { type: "object", properties: {} },
         },
+        // ── Init / Indexing ──────────────────────────────────────────────────────
+        {
+            name: "init_project",
+            description: "Scan and index a project directory into the knowledge graph. " +
+                "Reads CLAUDE.md (directives, conventions), package.json / pyproject.toml (dependencies, scripts), " +
+                "README.md (description), .mcp.json (MCP servers), logic-guardian.yaml (drift patterns), " +
+                "and source files (exported functions/classes). " +
+                "Call this once when starting work on a project to bootstrap memory with project context.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    directory: {
+                        type: "string",
+                        description: "Absolute path to the project root. Defaults to current working directory.",
+                    },
+                },
+            },
+        },
+        {
+            name: "sync_file",
+            description: "Index or re-index a single source file after it was written or modified. " +
+                "Extracts exports, description, and open TODOs, then updates the knowledge graph. " +
+                "IMPORTANT: call this automatically after every Write or Edit tool call.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute or relative path to the modified file." },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "sync_project",
+            description: "Re-index the entire project directory incrementally. " +
+                "Use this when multiple files have changed (e.g. after a refactor or git pull).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    directory: {
+                        type: "string",
+                        description: "Project root directory. Defaults to current working directory.",
+                    },
+                },
+            },
+        },
+        {
+            name: "grep_code",
+            description: "Search indexed source files using a regex pattern. " +
+                "Decompresses stored binary content and returns only matching lines with context. " +
+                "Token-efficient: returns ~20-50 tokens instead of full file contents. " +
+                "Useful for finding function calls, variable usages, import patterns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    pattern: { type: "string", description: "Regex pattern to search for." },
+                    language: { type: "string", enum: ["python", "javascript", "typescript", "generic"], description: "Filter by language." },
+                    context: { type: "number", description: "Lines of context before/after each match (0-10, default 2)." },
+                },
+                required: ["pattern"],
+            },
+        },
+        // ── Context & Token Optimization ─────────────────────────────────────────
+        {
+            name: "get_context",
+            description: "Retrieve the minimal relevant context for a task or query. " +
+                "Uses TF-IDF scoring (or Qdrant vector search if configured) to rank files by relevance, " +
+                "applies recency boost for recently modified files, and returns skeletons (signatures only) " +
+                "for large files to stay within the token budget. " +
+                "Configure limits in lucid.config.json. Set QDRANT_URL env var for vector search.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "What you are working on or searching for" },
+                    maxTokens: { type: "number", description: "Total token budget (default 4000)" },
+                    dirs: { type: "array", items: { type: "string" }, description: "Whitelist directories (e.g. [\"src\", \"backend\"])" },
+                    recentOnly: { type: "boolean", description: "Only files modified within recentWindowHours" },
+                    recentHours: { type: "number", description: "Override recent window (hours)" },
+                    skeletonOnly: { type: "boolean", description: "Always show skeleton (signatures only)" },
+                    topK: { type: "number", description: "Max files to consider (default 10)" },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "get_recent",
+            description: "Return files modified recently with line-level diffs. " +
+                "Shows what changed in each file since the previous sync. " +
+                "Useful for catching up after a git pull or resuming a session.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    hours: { type: "number", description: "Look back N hours (default 24)" },
+                    withDiffs: { type: "boolean", description: "Include line diffs (default true)" },
+                },
+            },
+        },
+        // ── Reward System ────────────────────────────────────────────────────────
+        {
+            name: "reward",
+            description: "Signal that the last get_context() result was helpful (+1 reward). " +
+                "The files returned in that context will be ranked higher in future similar queries. " +
+                "Call this after a get_context() result led to a correct fix or useful code.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    note: { type: "string", description: "Optional note about what worked (stored for future reference)" },
+                },
+            },
+        },
+        {
+            name: "penalize",
+            description: "Signal that the last get_context() result was unhelpful (-1 reward). " +
+                "The files returned in that context will be ranked lower in future similar queries. " +
+                "Call this after a get_context() result missed important files or was irrelevant.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    note: { type: "string", description: "Optional note about what was missing or wrong" },
+                },
+            },
+        },
+        {
+            name: "show_rewards",
+            description: "Show the top rewarded experiences and most rewarded files. " +
+                "Rewards decay exponentially (half-life ~14 days). " +
+                "Use this to understand which context queries and files have been most valuable.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Filter experiences by query text (optional)" },
+                    topK: { type: "number", description: "Number of top results to show (default 10)" },
+                },
+            },
+        },
         // ── Logic Guardian ───────────────────────────────────────────────────────
         {
             name: "validate_file",
@@ -127,6 +294,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "Call this before marking any implementation task as done.",
             inputSchema: { type: "object", properties: {} },
         },
+        // ── Coding Guard ─────────────────────────────────────────────────────────
+        {
+            name: "coding_rules",
+            description: "Get the 25 Golden Rules coding checklist. Covers clarity, naming, single responsibility, " +
+                "error handling, frontend component size/reuse/props, singleton rules, library selection, " +
+                "and architecture separation. Review before marking any task done.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "check_code_quality",
+            description: "Analyze a file or code snippet against the 25 Golden Rules. " +
+                "Detects: file/function size violations, vague naming, deep nesting, dead code, and — " +
+                "for React/Vue component files — inline styles, prop explosion, fetch-in-component, " +
+                "direct DOM access, mixed styling systems. " +
+                "Complements validate_file (which checks logic correctness).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute or relative path to the file to analyze." },
+                    code: { type: "string", description: "Code snippet to analyze inline." },
+                    language: {
+                        type: "string",
+                        enum: ["python", "javascript", "typescript", "vue", "generic"],
+                        description: "Language hint. Auto-detected from file extension if path is provided.",
+                    },
+                },
+            },
+        },
     ],
 }));
 // ---------------------------------------------------------------------------
@@ -134,6 +329,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 // ---------------------------------------------------------------------------
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    // Security: rate limit + WAF check before any execution
+    const guard = guardRequest(name, args);
+    if (guard.blocked) {
+        return { content: [{ type: "text", text: guard.reason ?? "Request blocked by security guard" }], isError: true };
+    }
     try {
         let text;
         switch (name) {
@@ -156,6 +356,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "memory_stats":
                 text = memoryStats(db, stmts);
                 break;
+            // Init & Sync
+            case "init_project":
+                text = await handleInitProject(stmts, InitProjectSchema.parse(args));
+                break;
+            case "sync_file":
+                text = handleSyncFile(stmts, SyncFileSchema.parse(args));
+                break;
+            case "sync_project":
+                text = handleSyncProject(stmts, SyncProjectSchema.parse(args));
+                break;
+            // Grep
+            case "grep_code":
+                text = handleGrepCode(stmts, GrepCodeSchema.parse(args));
+                break;
+            // Context & Token Optimization
+            case "get_context":
+                text = await handleGetContext(stmts, GetContextSchema.parse(args));
+                break;
+            case "get_recent":
+                text = handleGetRecent(stmts, GetRecentSchema.parse(args));
+                break;
+            // Reward System
+            case "reward":
+                text = handleReward(stmts, RewardSchema.parse(args));
+                break;
+            case "penalize":
+                text = handlePenalize(stmts, PenalizeSchema.parse(args));
+                break;
+            case "show_rewards":
+                text = handleShowRewards(stmts, ShowRewardsSchema.parse(args));
+                break;
             // Logic Guardian
             case "validate_file":
                 text = handleValidateFile(ValidateFileSchema.parse(args));
@@ -166,10 +397,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_checklist":
                 text = handleGetChecklist();
                 break;
+            // Coding Guard
+            case "coding_rules":
+                text = handleGetCodingRules();
+                break;
+            case "check_code_quality":
+                text = handleCheckCodeQuality(CheckCodeQualitySchema.parse(args));
+                break;
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }
-        return { content: [{ type: "text", text }] };
+        // Security: scan output for sensitive data leakage
+        return { content: [{ type: "text", text: guardOutput(name, text) }] };
     }
     catch (err) {
         const message = err instanceof z.ZodError

package/build/indexer/ast.d.ts

@@ -0,0 +1,9 @@
+export interface Skeleton {
+    imports: string[];
+    exports: string[];
+    todos: string[];
+    summary: string;
+}
+export declare function extractSkeleton(source: string, language: string): Skeleton;
+/** Render skeleton as compact text for context assembly. */
+export declare function renderSkeleton(sk: Skeleton, filepath: string): string;

package/build/indexer/ast.js

@@ -0,0 +1,158 @@
+// Structural skeleton extraction — regex-based AST-like parsing
+// Returns only signatures, imports, and TODO comments (no function bodies)
+// Used by get_context when a file exceeds the per-file token budget
+// ---------------------------------------------------------------------------
+// TypeScript / JavaScript
+// ---------------------------------------------------------------------------
+function skeletonTS(source) {
+    const lines = source.split("\n");
+    const imports = [];
+    const exports = [];
+    const todos = [];
+    let summary = "";
+    // Grab first JSDoc comment as summary
+    const jsdoc = source.match(/^\/\*\*([\s\S]*?)\*\//m);
+    if (jsdoc) {
+        summary = jsdoc[1].replace(/\s*\*\s*/g, " ").trim().slice(0, 150);
+    }
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Imports
+        if (/^import\s/.test(trimmed)) {
+            // Multi-line import: collect until ';'
+            let full = line;
+            while (!full.includes(";") && i + 1 < lines.length) {
+                i++;
+                full += " " + lines[i].trim();
+            }
+            imports.push(full.replace(/\s+/g, " ").trim());
+            i++;
+            continue;
+        }
+        // Exported declarations
+        if (/^export\s/.test(trimmed)) {
+            // Grab JSDoc above if present
+            let sig = line;
+            // If it's a function/class/interface, find the signature (up to first '{' or ';')
+            if (/^export\s+(async\s+)?function|^export\s+(abstract\s+)?class|^export\s+interface/.test(trimmed)) {
+                let j = i;
+                let full = "";
+                while (j < lines.length) {
+                    full += lines[j] + "\n";
+                    if (lines[j].includes("{") || lines[j].includes(";"))
+                        break;
+                    j++;
+                }
+                // Show only up to opening brace
+                sig = full.split("{")[0].replace(/\n/g, " ").replace(/\s+/g, " ").trim() + " { … }";
+            }
+            else if (/^export\s+(type|interface)\s/.test(trimmed)) {
+                // Multi-line type — take first line
+                sig = trimmed.split("{")[0].trim() + (trimmed.includes("{") ? " { … }" : "");
+            }
+            else {
+                // const/enum/default — take line
+                sig = trimmed.slice(0, 120);
+            }
+            exports.push(sig);
+            i++;
+            continue;
+        }
+        // TODOs
+        if (/\/\/\s*(TODO|FIXME|HACK)/i.test(trimmed)) {
+            todos.push(trimmed.slice(0, 100));
+        }
+        i++;
+    }
+    return { imports, exports, todos, summary };
+}
+// ---------------------------------------------------------------------------
+// Python
+// ---------------------------------------------------------------------------
+function skeletonPython(source) {
+    const lines = source.split("\n");
+    const imports = [];
+    const exports = [];
+    const todos = [];
+    let summary = "";
+    // Module docstring
+    const docMatch = source.match(/^['"]{3}([\s\S]*?)['"]{3}/m);
+    if (docMatch)
+        summary = docMatch[1].trim().slice(0, 150);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith("import ") || trimmed.startsWith("from ")) {
+            imports.push(trimmed.slice(0, 100));
+            continue;
+        }
+        // Public function/class/async def at top level (no indent)
+        if (/^(def|class|async def)\s+(\w)/.test(trimmed) && !trimmed.startsWith("_")) {
+            // Collect signature (may span multiple lines until ':')
+            let sig = line;
+            let j = i + 1;
+            while (!sig.includes(":") && j < lines.length) {
+                sig += " " + lines[j].trim();
+                j++;
+            }
+            sig = sig.split(":")[0].replace(/\s+/g, " ").trim() + ":";
+            exports.push(sig.slice(0, 120));
+            continue;
+        }
+        if (/^\s*#\s*(TODO|FIXME|HACK)/i.test(line)) {
+            todos.push(trimmed.slice(0, 100));
+        }
+    }
+    return { imports, exports, todos, summary };
+}
+// ---------------------------------------------------------------------------
+// Generic (markdown, yaml, json, etc.)
+// ---------------------------------------------------------------------------
+function skeletonGeneric(source) {
+    const lines = source.split("\n").slice(0, 30);
+    const todos = [];
+    for (const line of source.split("\n")) {
+        if (/(?:\/\/|#)\s*(TODO|FIXME|HACK)/i.test(line)) {
+            todos.push(line.trim().slice(0, 100));
+        }
+    }
+    return {
+        imports: [],
+        exports: [],
+        todos,
+        summary: lines.join("\n").slice(0, 300),
+    };
+}
+// ---------------------------------------------------------------------------
+// Public
+// ---------------------------------------------------------------------------
+export function extractSkeleton(source, language) {
+    switch (language) {
+        case "typescript":
+        case "javascript":
+            return skeletonTS(source);
+        case "python":
+            return skeletonPython(source);
+        default:
+            return skeletonGeneric(source);
+    }
+}
+/** Render skeleton as compact text for context assembly. */
+export function renderSkeleton(sk, filepath) {
+    const parts = [`// ${filepath} [skeleton]`];
+    if (sk.summary)
+        parts.push(`// ${sk.summary}`);
+    if (sk.imports.length > 0)
+        parts.push(sk.imports.slice(0, 8).join("\n"));
+    if (sk.exports.length > 0) {
+        parts.push("// — exports —");
+        parts.push(sk.exports.join("\n"));
+    }
+    if (sk.todos.length > 0) {
+        parts.push("// — TODOs —");
+        parts.push(sk.todos.join("\n"));
+    }
+    return parts.join("\n\n");
+}

package/build/indexer/file.d.ts

@@ -0,0 +1,15 @@
+import type { Statements } from "../database.js";
+export interface FileIndex {
+    module: string;
+    exports: string[];
+    description: string;
+    todos: string[];
+    language: string;
+}
+export declare function indexFile(filepath: string): FileIndex | null;
+export interface UpsertResult {
+    observations: string[];
+    stored: boolean;
+    savedBytes: number;
+}
+export declare function upsertFileIndex(index: FileIndex, source: string, stmts: Statements): UpsertResult;

package/build/indexer/file.js

@@ -0,0 +1,100 @@
+import { readFileSync } from "fs";
+import { extname } from "path";
+import { compress, sha256 } from "../store/content.js";
+function extractTS(source) {
+    const exports = [];
+    const todos = [];
+    // Exported symbols
+    for (const m of source.matchAll(/export\s+(?:async\s+)?(?:function|class|const|type|interface|enum)\s+(\w+)/g)) {
+        exports.push(m[1]);
+    }
+    // First JSDoc / block comment as description
+    const docMatch = source.match(/^\/\*\*([\s\S]*?)\*\//m) ?? source.match(/^\/\/(.*)/m);
+    const description = docMatch
+        ? docMatch[1].replace(/\s*\*\s*/g, " ").trim().slice(0, 200)
+        : "";
+    // TODOs
+    for (const m of source.matchAll(/\/\/\s*(TODO|FIXME|HACK)[:\s]+(.+)/gi)) {
+        todos.push(`${m[1]}: ${m[2].trim()}`);
+    }
+    return { exports, description, todos };
+}
+function extractPython(source) {
+    const exports = [];
+    const todos = [];
+    // Public functions and classes
+    for (const m of source.matchAll(/^(?:def|class|async def)\s+(\w+)/gm)) {
+        if (!m[1].startsWith("_"))
+            exports.push(m[1]);
+    }
+    // Module docstring
+    const docMatch = source.match(/^["']{3}([\s\S]*?)["']{3}/m);
+    const description = docMatch ? docMatch[1].trim().slice(0, 200) : "";
+    // TODOs
+    for (const m of source.matchAll(/#\s*(TODO|FIXME|HACK)[:\s]+(.+)/gi)) {
+        todos.push(`${m[1]}: ${m[2].trim()}`);
+    }
+    return { exports, description, todos };
+}
+function extractGeneric(source) {
+    const todos = [];
+    for (const m of source.matchAll(/(?:\/\/|#)\s*(TODO|FIXME|HACK)[:\s]+(.+)/gi)) {
+        todos.push(`${m[1]}: ${m[2].trim()}`);
+    }
+    return { exports: [], description: "", todos };
+}
+export function indexFile(filepath) {
+    let source;
+    try {
+        source = readFileSync(filepath, { encoding: "utf-8" });
+    }
+    catch {
+        return null;
+    }
+    const ext = extname(filepath).toLowerCase();
+    const module = filepath.replace(/\\/g, "/");
+    let extracted;
+    let language;
+    if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+        extracted = extractTS(source);
+        language = ext.includes("ts") ? "typescript" : "javascript";
+    }
+    else if (ext === ".py") {
+        extracted = extractPython(source);
+        language = "python";
+    }
+    else {
+        extracted = extractGeneric(source);
+        language = "generic";
+    }
+    return { module, language, ...extracted };
+}
+export function upsertFileIndex(index, source, stmts) {
+    const fileHash = sha256(source);
+    // Change detection — skip everything se hash-ul e identic
+    const existing = stmts.getFileByPath.get(index.module);
+    if (existing?.content_hash === fileHash) {
+        return { observations: [], stored: false, savedBytes: 0 };
+    }
+    // Comprimă și stochează conținutul binar
+    const blob = compress(source);
+    stmts.upsertFile.run(index.module, blob, fileHash, Buffer.byteLength(source, "utf-8"), blob.byteLength, index.language);
+    // Index structural în entities (compact, pentru recall)
+    const observations = [];
+    if (index.description)
+        observations.push(`description: ${index.description}`);
+    if (index.exports.length > 0)
+        observations.push(`exports: ${index.exports.join(", ")}`);
+    if (index.todos.length > 0)
+        observations.push(`TODOs: ${index.todos.join(" | ")}`);
+    observations.push(`language: ${index.language}`);
+    const entityRow = stmts.getEntityByName.get(index.module);
+    if (entityRow) {
+        stmts.updateEntity.run(JSON.stringify(observations), entityRow.id);
+    }
+    else {
+        stmts.insertEntity.run(index.module, "pattern", JSON.stringify(observations));
+    }
+    const savedBytes = Buffer.byteLength(source, "utf-8") - blob.byteLength;
+    return { observations, stored: true, savedBytes };
+}

package/build/indexer/project.d.ts

@@ -0,0 +1,8 @@
+import type { Statements } from "../database.js";
+export interface IndexResult {
+    entity: string;
+    type: string;
+    observations: number;
+    source: string;
+}
+export declare function indexProject(directory: string, stmts: Statements): IndexResult[];