@musashishao/folderforge 1.2.0

package/dist/managers/db-manager.js

@@ -0,0 +1,161 @@
+/**
+ * Read-only database manager. MVP supports SQLite via better-sqlite3 if present
+ * and Postgres via 'pg' if present; both are optional peer deps loaded lazily.
+ * If a driver is missing, the tools return a clear, actionable error instead of
+ * crashing the server.
+ */
+const WRITE_KEYWORDS = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE|REPLACE|MERGE|VACUUM)\b/i;
+export function isReadOnlyQuery(sql) {
+    const trimmed = sql.trim().replace(/;+\s*$/, '');
+    if (WRITE_KEYWORDS.test(trimmed))
+        return false;
+    return /^(SELECT|WITH|EXPLAIN|PRAGMA|SHOW)\b/i.test(trimmed);
+}
+const SECRET_COL = /pass(word)?|secret|token|api[_-]?key|private[_-]?key/i;
+export function maskRow(row) {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        out[k] = SECRET_COL.test(k) ? '[MASKED]' : v;
+    }
+    return out;
+}
+export class DbManager {
+    connections = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handles = new Map();
+    list() {
+        return [...this.connections.values()];
+    }
+    require(id) {
+        const conn = this.connections.get(id);
+        const handle = this.handles.get(id);
+        if (!conn || !handle)
+            throw new Error(`Unknown db connection: ${id}`);
+        return { conn, handle };
+    }
+    async connect(id, kind, target) {
+        if (/prod|production/i.test(target)) {
+            throw new Error('Refusing to connect to a production-looking database target.');
+        }
+        if (kind === 'sqlite') {
+            const mod = await this.tryImport('better-sqlite3', 'SQLite');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const Database = mod.default ?? mod;
+            const db = new Database(target, { readonly: true, fileMustExist: true });
+            this.handles.set(id, db);
+        }
+        else {
+            const mod = await this.tryImport('pg', 'Postgres');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const Client = mod.Client;
+            const client = new Client({ connectionString: target });
+            await client.connect();
+            this.handles.set(id, client);
+        }
+        const conn = { id, kind, target, readonly: true };
+        this.connections.set(id, conn);
+        return conn;
+    }
+    async listTables(id) {
+        const { conn, handle } = this.require(id);
+        if (conn.kind === 'sqlite') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const rows = handle
+                .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+                .all();
+            return rows.map((r) => r.name);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await handle.query("SELECT table_name FROM information_schema.tables WHERE table_schema='public' ORDER BY table_name");
+        return res.rows.map((r) => r.table_name);
+    }
+    async describeTable(id, table) {
+        const { conn, handle } = this.require(id);
+        if (!/^[A-Za-z0-9_]+$/.test(table))
+            throw new Error('Invalid table name');
+        if (conn.kind === 'sqlite') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return handle.prepare(`PRAGMA table_info(${table})`).all();
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await handle.query('SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name=$1 ORDER BY ordinal_position', [table]);
+        return res.rows;
+    }
+    async queryReadonly(id, sql, limit = 200) {
+        if (!isReadOnlyQuery(sql))
+            throw new Error('Only read-only queries (SELECT/EXPLAIN/WITH) are allowed.');
+        const { conn, handle } = this.require(id);
+        let rows;
+        if (conn.kind === 'sqlite') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            rows = handle.prepare(sql).all().slice(0, limit);
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const res = await handle.query(sql);
+            rows = res.rows.slice(0, limit);
+        }
+        return rows.map(maskRow);
+    }
+    async explain(id, sql) {
+        const cleaned = sql.trim().replace(/;+\s*$/, '');
+        return this.queryReadonly(id, `EXPLAIN ${cleaned}`);
+    }
+    /**
+     * Execute a single write statement (INSERT/UPDATE/DELETE) against a dev
+     * connection. Refuses read-only-looking statements and DDL; migrations go
+     * through {@link runMigration}. HIGH-risk: gated by policy/approval upstream.
+     */
+    async write(id, sql) {
+        if (isReadOnlyQuery(sql)) {
+            throw new Error('db_write expects a write statement (INSERT/UPDATE/DELETE), not a read-only query.');
+        }
+        const { conn, handle } = this.require(id);
+        if (conn.readonly) {
+            throw new Error(`Connection ${id} is read-only; db_write is not permitted.`);
+        }
+        if (conn.kind === 'sqlite') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const info = handle.prepare(sql).run();
+            return { changes: Number(info.changes ?? 0) };
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await handle.query(sql);
+        return { changes: Number(res.rowCount ?? 0) };
+    }
+    /**
+     * Run a multi-statement migration script in a single transaction. HIGH-risk:
+     * gated by policy/approval upstream.
+     */
+    async runMigration(id, sql) {
+        const { conn, handle } = this.require(id);
+        if (conn.readonly) {
+            throw new Error(`Connection ${id} is read-only; db_run_migration is not permitted.`);
+        }
+        if (conn.kind === 'sqlite') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            handle.exec(sql);
+            return { applied: true };
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const client = handle;
+        try {
+            await client.query('BEGIN');
+            await client.query(sql);
+            await client.query('COMMIT');
+            return { applied: true };
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch(() => undefined);
+            throw err;
+        }
+    }
+    async tryImport(mod, label) {
+        try {
+            return await import(mod);
+        }
+        catch {
+            throw new Error(`${label} driver "${mod}" is not installed. Run: npm install ${mod} (optional dependency).`);
+        }
+    }
+}

package/dist/managers/lsp-manager.js

@@ -0,0 +1,269 @@
+import { spawn } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { MessageBuffer, encodeMessage, isResponse, SYMBOL_KIND, lspSeverity, } from '../lsp/protocol.js';
+/** Built-in language server definitions. Overridable via config. */
+export const DEFAULT_LANGUAGE_SERVERS = [
+    {
+        id: 'typescript',
+        command: 'typescript-language-server',
+        args: ['--stdio'],
+        extensions: ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs'],
+        languageId: 'typescript',
+    },
+    {
+        id: 'python',
+        command: 'pyright-langserver',
+        args: ['--stdio'],
+        extensions: ['py', 'pyi'],
+        languageId: 'python',
+    },
+];
+export const DEFAULT_LSP_CONFIG = {
+    enabled: true,
+    requestTimeoutMs: 15_000,
+};
+/** A live, initialized language-server connection. */
+class LspConnection {
+    def;
+    root;
+    requestTimeoutMs;
+    child;
+    nextId = 1;
+    pending = new Map();
+    buffer;
+    opened = new Set();
+    /** Latest published diagnostics per file URI. */
+    diagnostics = new Map();
+    exited = false;
+    constructor(def, root, requestTimeoutMs) {
+        this.def = def;
+        this.root = root;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.child = spawn(def.command, def.args, { cwd: root });
+        this.buffer = new MessageBuffer((msg) => this.onMessage(msg));
+        this.child.stdout.on('data', (c) => this.buffer.append(c));
+        this.child.stderr.on('data', () => { }); // language servers log noisily; ignore
+        this.child.on('exit', () => {
+            this.exited = true;
+            for (const [, p] of this.pending) {
+                clearTimeout(p.timer);
+                p.reject(new Error(`${this.def.id} language server exited`));
+            }
+            this.pending.clear();
+        });
+        this.child.on('error', () => {
+            this.exited = true;
+        });
+    }
+    onMessage(msg) {
+        if (isResponse(msg)) {
+            const p = this.pending.get(msg.id);
+            if (!p)
+                return;
+            this.pending.delete(msg.id);
+            clearTimeout(p.timer);
+            if (msg.error)
+                p.reject(new Error(msg.error.message));
+            else
+                p.resolve(msg.result);
+            return;
+        }
+        // Notification from the server.
+        if ('method' in msg && msg.method === 'textDocument/publishDiagnostics') {
+            const params = msg.params;
+            if (params?.uri)
+                this.diagnostics.set(params.uri, params.diagnostics ?? []);
+        }
+        // Server->client requests (e.g. workspace/configuration) are answered with
+        // a null result so the server doesn't stall waiting on us.
+        if ('method' in msg && 'id' in msg) {
+            this.send({ jsonrpc: '2.0', id: msg.id, result: null });
+        }
+    }
+    send(msg) {
+        if (this.exited)
+            return;
+        this.child.stdin.write(encodeMessage(msg));
+    }
+    request(method, params) {
+        if (this.exited)
+            return Promise.reject(new Error(`${this.def.id} server not running`));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`LSP request ${method} timed out after ${this.requestTimeoutMs}ms`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+    notify(method, params) {
+        this.send({ jsonrpc: '2.0', method, params });
+    }
+    async initialize() {
+        await this.request('initialize', {
+            processId: process.pid,
+            rootUri: pathToFileURL(this.root).href,
+            capabilities: {
+                textDocument: {
+                    documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+                    definition: {},
+                    references: {},
+                    rename: {},
+                    publishDiagnostics: {},
+                },
+                workspace: { symbol: {}, workspaceFolders: true },
+            },
+            workspaceFolders: [{ uri: pathToFileURL(this.root).href, name: 'root' }],
+        });
+        this.notify('initialized', {});
+    }
+    /** Ensure a file is open on the server (didOpen once per URI). */
+    ensureOpen(relativePath) {
+        const abs = isAbsolute(relativePath) ? relativePath : join(this.root, relativePath);
+        const uri = pathToFileURL(abs).href;
+        if (this.opened.has(uri))
+            return uri;
+        let text = '';
+        try {
+            text = readFileSync(abs, 'utf8');
+        }
+        catch {
+            text = '';
+        }
+        this.notify('textDocument/didOpen', {
+            textDocument: { uri, languageId: this.def.languageId, version: 1, text },
+        });
+        this.opened.add(uri);
+        return uri;
+    }
+    dispose() {
+        try {
+            this.send({ jsonrpc: '2.0', id: this.nextId++, method: 'shutdown', params: null });
+            this.notify('exit', null);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            this.child.kill('SIGTERM');
+        }
+        catch {
+            /* ignore */
+        }
+        this.exited = true;
+    }
+}
+/**
+ * Manages native LSP connections, one per (language, projectRoot). Lazily
+ * spawns and initializes a server on first use, reusing it afterwards. When the
+ * configured binary is not installed, callers get a clear "unavailable" signal
+ * and degrade gracefully (Serena adapter / regex search).
+ */
+export class LspManager {
+    config;
+    connections = new Map();
+    servers;
+    constructor(config = DEFAULT_LSP_CONFIG) {
+        this.config = config;
+        this.config = config ?? DEFAULT_LSP_CONFIG;
+        this.servers = this.config.servers ?? DEFAULT_LANGUAGE_SERVERS;
+    }
+    /** Pick the server definition that handles a given file path, if any. */
+    serverForPath(relativePath) {
+        const ext = relativePath.split('.').pop()?.toLowerCase() ?? '';
+        return this.servers.find((s) => s.extensions.includes(ext));
+    }
+    serverById(id) {
+        return this.servers.find((s) => s.id === id);
+    }
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Get (or lazily create + initialize) a connection for a language at a root.
+     * Returns null if LSP is disabled or the binary cannot be spawned.
+     */
+    async ensure(def, root) {
+        if (!this.config.enabled)
+            return null;
+        const key = `${def.id}::${root}`;
+        const existing = this.connections.get(key);
+        if (existing)
+            return existing;
+        try {
+            const conn = new LspConnection(def, root, this.config.requestTimeoutMs);
+            await conn.initialize();
+            this.connections.set(key, conn);
+            return conn;
+        }
+        catch {
+            return null; // binary missing or init failed -> caller falls back
+        }
+    }
+    disposeAll() {
+        for (const [, c] of this.connections)
+            c.dispose();
+        this.connections.clear();
+    }
+}
+/** Normalize an LSP Location into a {file, line, column} record (1-based line). */
+export function normalizeLocation(loc) {
+    const l = loc;
+    if (!l?.uri || !l.range?.start)
+        return null;
+    let file = l.uri;
+    try {
+        file = fileURLToPath(l.uri);
+    }
+    catch {
+        /* keep raw uri */
+    }
+    return {
+        file,
+        line: (l.range.start.line ?? 0) + 1,
+        column: (l.range.start.character ?? 0) + 1,
+    };
+}
+/** Flatten a documentSymbol tree (hierarchical or flat) into named entries. */
+export function flattenSymbols(symbols) {
+    const out = [];
+    const visit = (nodes) => {
+        for (const n of nodes) {
+            const s = n;
+            if (s?.name) {
+                const line = (s.range?.start?.line ?? s.location?.range?.start?.line ?? 0) + 1;
+                out.push({ name: s.name, kind: SYMBOL_KIND[s.kind ?? 0] ?? 'symbol', line });
+            }
+            if (Array.isArray(s?.children))
+                visit(s.children);
+        }
+    };
+    if (Array.isArray(symbols))
+        visit(symbols);
+    return out;
+}
+/** Convert LSP diagnostics for a file into the shared error-item shape. */
+export function normalizeDiagnostics(uri, diags) {
+    let file = uri;
+    try {
+        file = fileURLToPath(uri);
+    }
+    catch {
+        /* keep raw uri */
+    }
+    return diags.map((d) => {
+        const x = d;
+        return {
+            file,
+            line: (x.range?.start?.line ?? 0) + 1,
+            column: (x.range?.start?.character ?? 0) + 1,
+            severity: lspSeverity(x.severity),
+            message: x.message ?? '',
+            ...(x.code !== undefined ? { code: String(x.code) } : {}),
+        };
+    });
+}

package/dist/managers/process-manager.js

@@ -0,0 +1,140 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+/**
+ * Manages long-running child processes (dev servers, watchers, compose).
+ */
+export class ProcessManager {
+    sessions = new Map();
+    maxBuffer = 1_000_000;
+    start(command, cwd, shell) {
+        const sessionId = `proc_${randomUUID().slice(0, 8)}`;
+        const child = spawn(shell, ['-lc', command], {
+            cwd,
+            env: process.env,
+        });
+        const session = {
+            sessionId,
+            pid: child.pid,
+            command,
+            cwd,
+            status: 'running',
+            exitCode: null,
+            startedAt: Date.now(),
+            child,
+            output: '',
+            cursor: 0,
+            waiters: [],
+        };
+        const wake = () => {
+            const ws = session.waiters;
+            session.waiters = [];
+            for (const w of ws)
+                w();
+        };
+        const append = (chunk) => {
+            session.output += chunk.toString('utf8');
+            if (session.output.length > this.maxBuffer) {
+                session.output = session.output.slice(-this.maxBuffer);
+            }
+            wake();
+        };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        child.on('exit', (code) => {
+            session.status = session.status === 'killed' ? 'killed' : 'exited';
+            session.exitCode = code;
+            wake();
+        });
+        this.sessions.set(sessionId, session);
+        return this.publicView(session);
+    }
+    read(sessionId) {
+        const s = this.require(sessionId);
+        const out = s.output.slice(s.cursor);
+        s.cursor = s.output.length;
+        return { output: out, status: s.status, cursor: s.cursor };
+    }
+    /**
+     * Long-poll read: resolve as soon as new output is available or the process
+     * exits, or after `timeoutMs` with whatever (possibly empty) output arrived.
+     * This backs streaming tails without busy-waiting. `done` is true once the
+     * process has exited and all buffered output has been drained.
+     */
+    readUntil(sessionId, timeoutMs = 2000, signal) {
+        const s = this.require(sessionId);
+        const drain = () => {
+            const output = s.output.slice(s.cursor);
+            s.cursor = s.output.length;
+            const done = s.status !== 'running' && s.cursor >= s.output.length;
+            return { output, status: s.status, cursor: s.cursor, done };
+        };
+        // Immediate return if there is already new output, the process is finished,
+        // or the caller has already cancelled (P6).
+        if (s.output.length > s.cursor || s.status !== 'running' || signal?.aborted) {
+            return Promise.resolve(drain());
+        }
+        return new Promise((resolveOut) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (signal)
+                    signal.removeEventListener('abort', finish);
+                resolveOut(drain());
+            };
+            const timer = setTimeout(finish, timeoutMs);
+            // Wake immediately on cancellation so a long tail does not block the
+            // client after it has cancelled the request.
+            if (signal)
+                signal.addEventListener('abort', finish, { once: true });
+            s.waiters.push(finish);
+        });
+    }
+    write(sessionId, input) {
+        const s = this.require(sessionId);
+        if (s.status !== 'running')
+            throw new Error('Process is not running');
+        s.child.stdin.write(input.endsWith('\n') ? input : input + '\n');
+    }
+    stop(sessionId) {
+        const s = this.require(sessionId);
+        if (s.status === 'running') {
+            s.child.kill('SIGTERM');
+            s.status = 'killed';
+        }
+        return this.publicView(s);
+    }
+    kill(sessionId) {
+        const s = this.require(sessionId);
+        if (s.status === 'running') {
+            s.child.kill('SIGKILL');
+            s.status = 'killed';
+        }
+        return this.publicView(s);
+    }
+    list() {
+        return [...this.sessions.values()].map((s) => this.publicView(s));
+    }
+    isManaged(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    require(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            throw new Error(`Unknown process session: ${sessionId}`);
+        return s;
+    }
+    publicView(s) {
+        return {
+            sessionId: s.sessionId,
+            pid: s.pid,
+            command: s.command,
+            cwd: s.cwd,
+            status: s.status,
+            exitCode: s.exitCode,
+            startedAt: s.startedAt,
+        };
+    }
+}