n2-qln 3.4.2 → 4.1.0

package/lib/store.js

@@ -1,217 +0,0 @@
-// QLN — SQLite storage engine (pure JS via sql.js WASM). No native dependencies.
-const fs = require('fs');
-const path = require('path');
-
-/** @type {object|null} sql.js module singleton */
-let _SQL = null;
-/** @type {Promise<object>|null} sql.js init promise */
-let _initPromise = null;
-
-/**
- * Initialize sql.js WASM module (once per process).
- * @returns {Promise<object>} sql.js module with Database constructor
- */
-async function initSqlJs() {
-    if (_SQL) return _SQL;
-    if (_initPromise) return _initPromise;
-    _initPromise = (async () => {
-        const initFn = require('sql.js');
-        _SQL = await initFn();
-        return _SQL;
-    })();
-    return _initPromise;
-}
-
-/**
- * QLN SQLite store.
- * Dedicated tool index DB — separated from Soul KV-Cache.
- *
- * File: {dataDir}/qln-tools.sqlite
- */
-class Store {
-    /**
-     * @param {string} dataDir - Data directory path
-     */
-    constructor(dataDir) {
-        this._dataDir = dataDir;
-        this._db = null;
-        this._dbPath = path.join(dataDir, 'qln-tools.sqlite');
-    }
-
-    /** Async init — load sql.js + open DB + create schema */
-    async init() {
-        await initSqlJs();
-        if (!fs.existsSync(this._dataDir)) {
-            fs.mkdirSync(this._dataDir, { recursive: true });
-        }
-        if (fs.existsSync(this._dbPath)) {
-            const buffer = fs.readFileSync(this._dbPath);
-            this._db = new _SQL.Database(buffer);
-        } else {
-            this._db = new _SQL.Database();
-        }
-        this._createSchema();
-    }
-
-    /** Create tools + providers table schema */
-    _createSchema() {
-        this._db.run(`
-            CREATE TABLE IF NOT EXISTS tools (
-                name TEXT PRIMARY KEY,
-                description TEXT DEFAULT '',
-                source TEXT DEFAULT 'unknown',
-                category TEXT DEFAULT 'misc',
-                provider TEXT DEFAULT '',
-                input_schema TEXT DEFAULT '{}',
-                triggers TEXT DEFAULT '[]',
-                tags TEXT DEFAULT '[]',
-                examples TEXT DEFAULT '[]',
-                endpoint TEXT DEFAULT '',
-                search_text TEXT DEFAULT '',
-                embedding TEXT DEFAULT '',
-                usage_count INTEGER DEFAULT 0,
-                success_rate REAL DEFAULT 1.0,
-                registered_at TEXT DEFAULT (datetime('now')),
-                updated_at TEXT DEFAULT (datetime('now'))
-            )
-        `);
-        this._db.run(`CREATE INDEX IF NOT EXISTS idx_tools_source ON tools(source)`);
-        this._db.run(`CREATE INDEX IF NOT EXISTS idx_tools_category ON tools(category)`);
-
-        this._db.run(`
-            CREATE TABLE IF NOT EXISTS providers (
-                name TEXT PRIMARY KEY,
-                version TEXT DEFAULT '1.0.0',
-                description TEXT DEFAULT '',
-                endpoint TEXT DEFAULT '',
-                tool_count INTEGER DEFAULT 0,
-                registered_at TEXT DEFAULT (datetime('now')),
-                updated_at TEXT DEFAULT (datetime('now'))
-            )
-        `);
-
-        // Safe migration: add new columns if missing (for existing DBs)
-        this._migrateSchema();
-    }
-
-    /** Schema migration — safe ADD COLUMN (ignores if already exists) */
-    _migrateSchema() {
-        const addCol = (table, col, type, dflt) => {
-            try {
-                this._db.run(`ALTER TABLE ${table} ADD COLUMN ${col} ${type} DEFAULT ${dflt}`);
-            } catch { /* column already exists */ }
-        };
-        addCol('tools', 'provider', 'TEXT', "''");
-        addCol('tools', 'examples', 'TEXT', "'[]'");
-        addCol('tools', 'endpoint', 'TEXT', "''");
-        addCol('tools', 'last_used_at', 'TEXT', 'NULL');
-
-        // Copy plugin_name → provider (if old schema has plugin_name)
-        try {
-            const cols = this._db.exec("PRAGMA table_info(tools)");
-            if (cols.length > 0) {
-                const colNames = cols[0].values.map(r => r[1]);
-                if (colNames.includes('plugin_name') && colNames.includes('provider')) {
-                    this._db.run("UPDATE tools SET provider = plugin_name WHERE provider = '' AND plugin_name != ''");
-                }
-            }
-        } catch { /* table doesn't exist yet */ }
-
-        // Create provider index (safe)
-        try {
-            this._db.run(`CREATE INDEX IF NOT EXISTS idx_tools_provider ON tools(provider)`);
-        } catch { /* already exists */ }
-    }
-
-    /**
-     * Upsert a tool entry.
-     * @param {object} entry - Normalized tool entry
-     */
-    upsert(entry) {
-        this._db.run(`
-            INSERT INTO tools (name, description, source, category, provider,
-                input_schema, triggers, tags, examples, endpoint, search_text, embedding,
-                usage_count, success_rate, last_used_at, updated_at)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
-                ?, COALESCE(?, (SELECT embedding FROM tools WHERE name = ?)),
-                ?, ?, ?, datetime('now'))
-            ON CONFLICT(name) DO UPDATE SET
-                description = excluded.description,
-                source = excluded.source,
-                category = excluded.category,
-                provider = excluded.provider,
-                input_schema = excluded.input_schema,
-                triggers = excluded.triggers,
-                tags = excluded.tags,
-                examples = excluded.examples,
-                endpoint = excluded.endpoint,
-                search_text = excluded.search_text,
-                embedding = COALESCE(excluded.embedding, tools.embedding),
-                usage_count = excluded.usage_count,
-                success_rate = excluded.success_rate,
-                last_used_at = excluded.last_used_at,
-                updated_at = excluded.updated_at
-        `, [
-            entry.name, entry.description, entry.source, entry.category, entry.provider,
-            JSON.stringify(entry.inputSchema), JSON.stringify(entry.triggers),
-            JSON.stringify(entry.tags), JSON.stringify(entry.examples), entry.endpoint || '',
-            entry.searchText,
-            entry.embedding ? JSON.stringify(entry.embedding) : null, entry.name,
-            entry.usageCount, entry.successRate, entry.lastUsedAt || null,
-        ]);
-        this._persist();
-    }
-
-    /**
-     * Remove a tool by name.
-     * @param {string} name
-     * @returns {boolean}
-     */
-    remove(name) {
-        this._db.run('DELETE FROM tools WHERE name = ?', [name]);
-        this._persist();
-        return true;
-    }
-
-    /**
-     * Purge all tools by source (for re-sync).
-     * @param {string} source
-     */
-    purgeBySource(source) {
-        this._db.run('DELETE FROM tools WHERE source = ?', [source]);
-        this._persist();
-    }
-
-    /**
-     * Load all tools from DB.
-     * @returns {object[]} Array of SQLite rows
-     */
-    loadAll() {
-        const results = this._db.exec('SELECT * FROM tools ORDER BY name');
-        if (results.length === 0) return [];
-        const cols = results[0].columns;
-        return results[0].values.map(row => {
-            const obj = {};
-            cols.forEach((c, i) => { obj[c] = row[i]; });
-            return obj;
-        });
-    }
-
-    /** Persist DB to disk */
-    _persist() {
-        if (!this._db) return;
-        const data = this._db.export();
-        fs.writeFileSync(this._dbPath, Buffer.from(data));
-    }
-
-    /** Close connection */
-    dispose() {
-        if (this._db) {
-            this._persist();
-            this._db.close();
-            this._db = null;
-        }
-    }
-}
-
-module.exports = { Store, initSqlJs };

package/lib/validator.js

@@ -1,171 +0,0 @@
-// QLN — Tool registration validator (validator.rs pattern)
-// Enforced validation: errors reject registration, warnings pass with message.
-
-/** Valid tool categories */
-const VALID_CATEGORIES = ['web', 'data', 'file', 'dev', 'ai', 'capture', 'misc'];
-
-/** Tool name pattern: verb_target (e.g. read_pdf, take_screenshot) */
-const NAME_PATTERN = /^[a-z]+_[a-z][a-z0-9_]*$/;
-
-/** Minimum description length */
-const MIN_DESCRIPTION_LENGTH = 10;
-
-/**
- * Validate tool entry for registration.
- * Pattern: accumulate errors → reject if any error exists.
- *
- * @param {object} params - Tool creation params
- * @param {import('./registry').Registry} registry - For duplicate check
- * @returns {{ valid: boolean, errors: ValidationError[] }}
- */
-function validateToolEntry(params, registry) {
-    /** @type {ValidationError[]} */
-    const errors = [];
-
-    // Rule 1: name required + verb_target format enforced
-    if (!params.name || params.name.trim() === '') {
-        errors.push({
-            field: 'name',
-            message: 'name은 필수입니다',
-            severity: 'error',
-        });
-    } else if (!NAME_PATTERN.test(params.name)) {
-        errors.push({
-            field: 'name',
-            message: `'${params.name}' → 동사_대상 형식 필수 (예: read_pdf, take_screenshot)`,
-            severity: 'error',
-        });
-    }
-
-    // Rule 2: description required (= first-line comment) + min 10 chars
-    if (!params.description || params.description.trim() === '') {
-        errors.push({
-            field: 'description',
-            message: 'description은 필수입니다 (도구 용도 설명)',
-            severity: 'error',
-        });
-    } else if (params.description.trim().length < MIN_DESCRIPTION_LENGTH) {
-        errors.push({
-            field: 'description',
-            message: `최소 ${MIN_DESCRIPTION_LENGTH}자 이상 설명 필요 (현재: ${params.description.trim().length}자)`,
-            severity: 'error',
-        });
-    }
-
-    // Rule 3: category enum enforced
-    if (params.category && !VALID_CATEGORIES.includes(params.category)) {
-        errors.push({
-            field: 'category',
-            message: `'${params.category}' → ${VALID_CATEGORIES.join('|')} 중 하나`,
-            severity: 'error',
-        });
-    }
-
-    // Rule 4: duplicate name check
-    if (params.name && registry && registry.get(params.name)) {
-        errors.push({
-            field: 'name',
-            message: `'${params.name}' 이미 존재합니다. action: "update" 를 사용하세요`,
-            severity: 'error',
-        });
-    }
-
-    // Warning: no tags (search accuracy may be lower)
-    if (!params.tags || params.tags.length === 0) {
-        errors.push({
-            field: 'tags',
-            message: 'tags 미지정 — 검색 정확도가 낮아질 수 있습니다',
-            severity: 'warning',
-        });
-    }
-
-    const errorCount = errors.filter(e => e.severity === 'error').length;
-    return { valid: errorCount === 0, errors };
-}
-
-/**
- * Validate tool update params.
- * Same rules as create, but no duplicate check (updating existing tool).
- *
- * @param {object} params - Update params (only changed fields)
- * @param {object} existing - Current tool entry from registry
- * @returns {{ valid: boolean, errors: ValidationError[] }}
- */
-function validateUpdateEntry(params, existing) {
-    /** @type {ValidationError[]} */
-    const errors = [];
-
-    // Merge: use existing values as fallback
-    const merged = {
-        name: params.name || existing.name,
-        description: params.description || existing.description,
-        category: params.category || existing.category,
-    };
-
-    // Rule 1: name format (if changed)
-    if (params.name && !NAME_PATTERN.test(params.name)) {
-        errors.push({
-            field: 'name',
-            message: `'${params.name}' → 동사_대상 형식 필수 (예: read_pdf, take_screenshot)`,
-            severity: 'error',
-        });
-    }
-
-    // Rule 2: description min length (if changed)
-    if (params.description && params.description.trim().length < MIN_DESCRIPTION_LENGTH) {
-        errors.push({
-            field: 'description',
-            message: `최소 ${MIN_DESCRIPTION_LENGTH}자 이상 설명 필요 (현재: ${params.description.trim().length}자)`,
-            severity: 'error',
-        });
-    }
-
-    // Rule 3: category enum (if changed)
-    if (params.category && !VALID_CATEGORIES.includes(params.category)) {
-        errors.push({
-            field: 'category',
-            message: `'${params.category}' → ${VALID_CATEGORIES.join('|')} 중 하나`,
-            severity: 'error',
-        });
-    }
-
-    const errorCount = errors.filter(e => e.severity === 'error').length;
-    return { valid: errorCount === 0, errors };
-}
-
-/**
- * Format validation errors as user-readable string.
- * @param {ValidationError[]} errors
- * @returns {string}
- */
-function formatValidationErrors(errors) {
-    const errorCount = errors.filter(e => e.severity === 'error').length;
-    const warnCount = errors.filter(e => e.severity === 'warning').length;
-
-    const lines = errors.map(e => {
-        const icon = e.severity === 'error' ? '❌' : '⚠️';
-        return `  ${icon} [${e.field}] ${e.message}`;
-    });
-
-    const header = errorCount > 0
-        ? `등록 거부 (${errorCount} error${errorCount > 1 ? 's' : ''}${warnCount > 0 ? `, ${warnCount} warning` : ''}):`
-        : `등록 완료 (${warnCount} warning${warnCount > 1 ? 's' : ''}):`;
-
-    return `${header}\n${lines.join('\n')}`;
-}
-
-/**
- * @typedef {object} ValidationError
- * @property {string} field - Field name
- * @property {string} message - Error message
- * @property {'error'|'warning'} severity - Severity level
- */
-
-module.exports = {
-    validateToolEntry,
-    validateUpdateEntry,
-    formatValidationErrors,
-    VALID_CATEGORIES,
-    NAME_PATTERN,
-    MIN_DESCRIPTION_LENGTH,
-};

package/tools/qln-call.js

@@ -1,257 +0,0 @@
-// QLN MCP tool — n2_qln_call (unified tool: search/exec/create/update/delete)
-// Single entry point for all QLN operations. ~200 tokens in AI context.
-const { validateToolEntry, validateUpdateEntry, formatValidationErrors } = require('../lib/validator');
-
-/**
- * Register the unified n2_qln_call MCP tool.
- * @param {object} server - MCP server
- * @param {object} z - Zod validator
- * @param {import('../lib/router').Router} router - L1 search engine
- * @param {import('../lib/executor').Executor} executor - L3 tool executor
- * @param {import('../lib/registry').Registry} registry - L2 tool index
- */
-function registerQlnCall(server, z, router, executor, registry) {
-    server.tool(
-        'n2_qln_call',
-        {
-            title: 'QLN Call',
-            description:
-                'Query Layer Network — unified tool dispatcher. ' +
-                'Search 1000+ tools, execute them, or manage the index. ' +
-                'Actions: search, exec, create, update, delete.',
-            inputSchema: {
-                action: z.enum(['search', 'exec', 'create', 'update', 'delete'])
-                    .describe('Action: search | exec | create | update | delete'),
-                // search
-                query: z.string().optional()
-                    .describe('[search] Natural language query (e.g. "take a screenshot")'),
-                topK: z.number().optional()
-                    .describe('[search] Number of results (default: 5, max: 20)'),
-                // exec
-                tool: z.string().optional()
-                    .describe('[exec/update/delete] Tool name'),
-                args: z.record(z.unknown()).optional()
-                    .describe('[exec] Tool arguments (JSON object)'),
-                // create / update
-                name: z.string().optional()
-                    .describe('[create/update] Tool name (unique identifier)'),
-                description: z.string().optional()
-                    .describe('[create/update] Tool description (used for search matching)'),
-                source: z.string().optional()
-                    .describe('[create/update] Source: mcp, plugin, local (default: local)'),
-                category: z.string().optional()
-                    .describe('[create/update] Category: web, data, file, dev, ai, capture, misc'),
-                toolSchema: z.record(z.unknown()).optional()
-                    .describe('[create/update] JSON Schema for tool input'),
-                tags: z.array(z.string()).optional()
-                    .describe('[create/update] Additional search tags'),
-                provider: z.string().optional()
-                    .describe('[create/update] Provider name (e.g. "n2-browser", "pdf-tools")'),
-                examples: z.array(z.string()).optional()
-                    .describe('[create/update] Usage examples (e.g. ["read this PDF file", "extract text from PDF"])'),
-                endpoint: z.string().optional()
-                    .describe('[create/update] Execution HTTP endpoint'),
-            },
-        },
-        async (params) => {
-            try {
-                switch (params.action) {
-                    case 'search': return await _handleSearch(router, registry, params);
-                    case 'exec':   return await _handleExec(executor, registry, params);
-                    case 'create': return await _handleCreate(registry, router, params);
-                    case 'update': return await _handleUpdate(registry, router, params);
-                    case 'delete': return await _handleDelete(registry, router, params);
-                    default:
-                        return _error(`Unknown action: ${params.action}`);
-                }
-            } catch (err) {
-                return _error(`QLN internal error: ${err.message}. Try the action again or use raw tool calls as fallback.`);
-            }
-        }
-    );
-}
-
-// ── Action Handlers ──
-
-/** Search tools by natural language query */
-async function _handleSearch(router, registry, { query, topK }) {
-    if (!query) return _error('Missing required param: query');
-    try {
-        const k = Math.min(topK || 5, 20);
-        const { results, timing } = await router.route(query, { topK: k });
-
-        if (results.length === 0) {
-            // Blind Spot prevention: show available categories so AI doesn't hallucinate
-            const stats = registry.stats();
-            const categories = Object.entries(stats.byCategory)
-                .map(([cat, count]) => `${cat}(${count})`)
-                .join(', ');
-            return _text(
-                `No tools found for: "${query}" (${timing.total}ms)\n\n` +
-                `Available categories [${stats.total} tools]: ${categories || 'none'}\n` +
-                `→ Try a different keyword, or check available categories above.`
-            );
-        }
-
-        const lines = results.map((r, i) => {
-            const schemaHint = r.inputSchema
-                ? ` | args: ${JSON.stringify(Object.keys(r.inputSchema.properties || r.inputSchema || {}))}`
-                : '';
-            return `${i + 1}. **${r.name}** (${r.score}) [${r.source}/${r.category}]${schemaHint}\n   ${r.description || '(no description)'}`;
-        });
-
-        const top = results[0];
-        const hint = `\n→ Execute: n2_qln_call(action: "exec", tool: "${top.name}", args: {})`;
-
-        return _text(
-            `Route "${query}" (${timing.total}ms, stages: T${timing.stage1}+K${timing.stage2}+S${timing.stage3}ms):\n\n` +
-            `${lines.join('\n\n')}${hint}`
-        );
-    } catch (err) {
-        return _error(`Search failed: ${err.message}`);
-    }
-}
-
-/** Execute a tool by name */
-async function _handleExec(executor, registry, { tool: toolName, args }) {
-    if (!toolName) return _error('Missing required param: tool');
-    try {
-        const { result, source, elapsed } = await executor.exec(toolName, args || {});
-        registry.recordUsage(toolName, true);
-
-        const resultStr = typeof result === 'string'
-            ? result
-            : JSON.stringify(result, null, 2);
-
-        const truncated = resultStr.length > 4000
-            ? resultStr.substring(0, 4000) + '\n... (truncated)'
-            : resultStr;
-
-        return _text(`✅ [${toolName}] (${source}, ${elapsed}ms):\n${truncated}`);
-    } catch (err) {
-        registry.recordUsage(toolName, false);
-        return { content: [{ type: 'text', text: `❌ [${toolName}] failed: ${err.message}` }], isError: true };
-    }
-}
-
-/** Create (register) a new tool — with enforced validation */
-async function _handleCreate(registry, router, params) {
-    // Step 1: Forced validation (validator.rs pattern)
-    const validation = validateToolEntry(params, registry);
-    if (!validation.valid) {
-        return { content: [{ type: 'text', text: formatValidationErrors(validation.errors) }], isError: true };
-    }
-
-    try {
-        // Step 2: Register with auto-enrichment
-        const entry = registry.register({
-            name: params.name,
-            description: params.description,
-            source: params.source || 'local',
-            category: params.category || undefined,
-            provider: params.provider || '',
-            inputSchema: params.toolSchema,
-            tags: params.tags,
-            examples: params.examples || [],
-            endpoint: params.endpoint || '',
-        });
-
-        // Step 3: Rebuild vector index
-        const indexResult = router.buildIndex();
-
-        // Step 4: Return with warnings if any
-        const warnings = validation.errors.filter(e => e.severity === 'warning');
-        const warnMsg = warnings.length > 0
-            ? `\n${formatValidationErrors(warnings)}`
-            : '';
-
-        return _text(
-            `✅ Created: ${entry.name} [${entry.source}/${entry.category}]\n` +
-            `Provider: ${entry.provider || '(none)'}\n` +
-            `Triggers: ${entry.triggers.join(', ')}\n` +
-            `Examples: ${entry.examples.length}\n` +
-            `Index: ${indexResult.indexed} tools, ${indexResult.categories} categories${warnMsg}`
-        );
-    } catch (err) {
-        return _error(`Create failed: ${err.message}`);
-    }
-}
-
-/** Update an existing tool — with validation */
-async function _handleUpdate(registry, router, params) {
-    const toolName = params.tool || params.name;
-    if (!toolName) return _error('Missing required param: tool (or name)');
-
-    const existing = registry.get(toolName);
-    if (!existing) return _error(`Tool not found: ${toolName}`);
-
-    // Validate changed fields
-    const validation = validateUpdateEntry(params, existing);
-    if (!validation.valid) {
-        return { content: [{ type: 'text', text: formatValidationErrors(validation.errors) }], isError: true };
-    }
-
-    try {
-        const entry = registry.register({
-            name: toolName,
-            description: params.description || existing.description,
-            source: params.source || existing.source,
-            category: params.category || existing.category,
-            provider: params.provider || existing.provider,
-            inputSchema: params.toolSchema || existing.inputSchema,
-            tags: params.tags || existing.tags,
-            examples: params.examples || existing.examples,
-            endpoint: params.endpoint || existing.endpoint,
-        });
-
-        const indexResult = router.buildIndex();
-        return _text(
-            `✅ Updated: ${entry.name} [${entry.source}/${entry.category}]\n` +
-            `Provider: ${entry.provider || '(none)'}\n` +
-            `Triggers: ${entry.triggers.join(', ')}\n` +
-            `Index: ${indexResult.indexed} tools, ${indexResult.categories} categories`
-        );
-    } catch (err) {
-        return _error(`Update failed: ${err.message}`);
-    }
-}
-
-/** Delete tool(s) — by name or by provider */
-async function _handleDelete(registry, router, params) {
-    const toolName = params.tool || params.name;
-
-    // Provider-level delete: remove all tools of a provider
-    if (params.provider && !toolName) {
-        const count = registry.removeByProvider(params.provider);
-        if (count === 0) return _error(`No tools found for provider: ${params.provider}`);
-        const indexResult = router.buildIndex();
-        return _text(
-            `✅ Deleted ${count} tools from provider: ${params.provider}\n` +
-            `Index: ${indexResult.indexed} tools, ${indexResult.categories} categories`
-        );
-    }
-
-    // Single tool delete
-    if (!toolName) return _error('Missing required param: tool (or name). For bulk delete, use provider param.');
-
-    const removed = registry.remove(toolName);
-    if (!removed) return _error(`Tool not found: ${toolName}`);
-
-    const indexResult = router.buildIndex();
-    return _text(
-        `✅ Deleted: ${toolName}\n` +
-        `Index: ${indexResult.indexed} tools, ${indexResult.categories} categories`
-    );
-}
-
-// ── Response Helpers ──
-
-function _text(text) {
-    return { content: [{ type: 'text', text }] };
-}
-
-function _error(message) {
-    return { content: [{ type: 'text', text: `⚠️ ${message}` }], isError: true };
-}
-
-module.exports = { registerQlnCall };