@musashishao/folderforge 1.2.0

package/dist/core/errors.js

@@ -0,0 +1,37 @@
+/**
+ * Structured error types for FolderForge.
+ */
+export class FolderForgeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'FolderForgeError';
+        this.code = code;
+    }
+}
+export class PolicyDeniedError extends FolderForgeError {
+    constructor(message) {
+        super('POLICY_DENIED', message);
+        this.name = 'PolicyDeniedError';
+    }
+}
+export class ApprovalRequiredError extends FolderForgeError {
+    approvalId;
+    constructor(message, approvalId) {
+        super('APPROVAL_REQUIRED', message);
+        this.name = 'ApprovalRequiredError';
+        this.approvalId = approvalId;
+    }
+}
+export class PathEscapeError extends FolderForgeError {
+    constructor(message) {
+        super('PATH_ESCAPE', message);
+        this.name = 'PathEscapeError';
+    }
+}
+export class WorkspaceNotActiveError extends FolderForgeError {
+    constructor() {
+        super('NO_WORKSPACE', 'No active workspace. Call workspace_activate first.');
+        this.name = 'WorkspaceNotActiveError';
+    }
+}

package/dist/core/logger.js

@@ -0,0 +1,8 @@
+import pino from 'pino';
+/**
+ * Logger writes to stderr so it never corrupts the stdio MCP channel (stdout).
+ */
+export const logger = pino({
+    level: process.env.FOLDERFORGE_LOG_LEVEL ?? 'info',
+    base: { service: 'folderforge' },
+}, pino.destination(2));

package/dist/core/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core type definitions shared across FolderForge.
+ */
+export {};

package/dist/dashboard/server.js

@@ -0,0 +1,191 @@
+import { createServer } from 'node:http';
+import { readFileSync, existsSync } from 'node:fs';
+import { timingSafeEqual } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { logger } from '../core/logger.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** True when the bind host is loopback-only and therefore safe without a token. */
+export function isLoopbackHost(host) {
+    return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+}
+/**
+ * Local control-plane dashboard. Read-only views plus approval actions.
+ *
+ * Endpoints:
+ *   GET  /            -> static dashboard (dashboard/static/index.html)
+ *   GET  /status      -> server + workspace + policy snapshot
+ *   GET  /audit       -> recent audit events
+ *   GET  /processes   -> managed long-running processes
+ *   GET  /approvals   -> pending + resolved approval requests
+ *   POST /approvals/:id/approve  -> approve (body: { scope?: 'once'|'session' })
+ *   POST /approvals/:id/deny     -> deny
+ */
+export function startDashboard(container, registry, opts) {
+    // Auth is enforced only when bound to a non-loopback address. A loopback bind
+    // is treated as trusted (same machine), matching the default 127.0.0.1.
+    const requireAuth = !isLoopbackHost(opts.host);
+    if (requireAuth && !opts.token) {
+        throw new Error('Dashboard bound to a non-loopback host requires a token');
+    }
+    const server = createServer((req, res) => {
+        if (requireAuth && !isAuthorized(req, opts.token)) {
+            res.writeHead(401, {
+                'content-type': 'application/json; charset=utf-8',
+                'www-authenticate': 'Bearer realm="folderforge-dashboard"',
+            });
+            res.end(JSON.stringify({ error: 'unauthorized', message: 'Valid bearer token required.' }));
+            return;
+        }
+        handle(req, res, container, registry).catch((err) => {
+            logger.error({ err: String(err) }, 'Dashboard request failed');
+            sendJson(res, 500, { error: 'internal_error', message: String(err) });
+        });
+    });
+    server.listen(opts.port, opts.host, () => {
+        logger.info({ host: opts.host, port: opts.port, authRequired: requireAuth }, 'Dashboard listening');
+    });
+    return server;
+}
+/**
+ * Accept the token via either `Authorization: Bearer <token>` or a `?token=`
+ * query parameter (handy for opening the dashboard in a browser). Comparison is
+ * constant-time to avoid leaking the token length/prefix via timing.
+ */
+function isAuthorized(req, expected) {
+    const header = req.headers['authorization'];
+    let provided;
+    if (typeof header === 'string' && header.startsWith('Bearer ')) {
+        provided = header.slice('Bearer '.length).trim();
+    }
+    if (!provided) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        provided = url.searchParams.get('token') ?? undefined;
+    }
+    if (!provided)
+        return false;
+    return timingSafeEqualStr(provided, expected);
+}
+function timingSafeEqualStr(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+async function handle(req, res, container, registry) {
+    const method = req.method ?? 'GET';
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+    if (method === 'GET' && (path === '/' || path === '/index.html')) {
+        return sendStatic(res);
+    }
+    if (method === 'GET' && path === '/status') {
+        const active = container.workspace.getActive();
+        return sendJson(res, 200, {
+            server: {
+                name: container.config.server.name,
+                transport: container.config.server.transport,
+            },
+            workspace: {
+                active: Boolean(active),
+                projectRoot: container.projectRoot(),
+                name: active?.name ?? null,
+                languageHints: active?.languageHints ?? [],
+                allowedDirectories: container.config.workspace.allowedDirectories,
+            },
+            policy: container.policy.describe(),
+            tools: {
+                active: registry.listActive().length,
+                total: registry.listAll().length,
+            },
+        });
+    }
+    if (method === 'GET' && path === '/audit') {
+        const limit = clampInt(url.searchParams.get('limit'), 50, 1, 500);
+        return sendJson(res, 200, { entries: container.audit.recent(limit) });
+    }
+    if (method === 'GET' && path === '/processes') {
+        return sendJson(res, 200, { processes: container.processes.list() });
+    }
+    if (method === 'GET' && path === '/approvals') {
+        return sendJson(res, 200, {
+            pending: container.policy.approvals.pending(),
+            all: container.policy.approvals.all(),
+        });
+    }
+    // POST /approvals/:id/approve | /approvals/:id/deny
+    const approvalMatch = /^\/approvals\/([^/]+)\/(approve|deny)$/.exec(path);
+    if (method === 'POST' && approvalMatch) {
+        const id = approvalMatch[1];
+        const action = approvalMatch[2];
+        const body = await readJsonBody(req);
+        let result;
+        if (action === 'approve') {
+            const scope = body?.scope === 'session' ? 'session' : 'once';
+            result = container.policy.approvals.approve(id, scope);
+        }
+        else {
+            result = container.policy.approvals.deny(id);
+        }
+        if (!result) {
+            return sendJson(res, 404, { error: 'approval_not_found', id });
+        }
+        container.audit.record({
+            type: 'approval_resolved',
+            tool: result.tool,
+            risk: result.risk,
+            summary: `${action} (${result.state})`,
+            detail: { approvalId: id },
+        });
+        return sendJson(res, 200, { approval: result });
+    }
+    sendJson(res, 404, { error: 'not_found', path });
+}
+function sendStatic(res) {
+    const candidates = [
+        join(__dirname, 'static', 'index.html'),
+        join(process.cwd(), 'src', 'dashboard', 'static', 'index.html'),
+    ];
+    for (const file of candidates) {
+        if (existsSync(file)) {
+            const html = readFileSync(file, 'utf8');
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(html);
+            return;
+        }
+    }
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('Dashboard static asset not found');
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body, null, 2));
+}
+async function readJsonBody(req) {
+    return new Promise((resolveBody) => {
+        let raw = '';
+        req.on('data', (chunk) => {
+            raw += chunk;
+            if (raw.length > 1_000_000)
+                req.destroy();
+        });
+        req.on('end', () => {
+            if (!raw.trim())
+                return resolveBody(null);
+            try {
+                resolveBody(JSON.parse(raw));
+            }
+            catch {
+                resolveBody(null);
+            }
+        });
+        req.on('error', () => resolveBody(null));
+    });
+}
+function clampInt(value, fallback, min, max) {
+    const n = value ? Number(value) : NaN;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+}

package/dist/lsp/protocol.js

@@ -0,0 +1,116 @@
+/**
+ * Minimal Language Server Protocol (LSP) transport primitives.
+ *
+ * LSP runs JSON-RPC 2.0 over a stream framed with HTTP-style headers:
+ *
+ *   Content-Length: <bytes>\r\n
+ *   \r\n
+ *   <utf8 json body>
+ *
+ * This module is intentionally transport-pure: it knows how to *encode* an
+ * outgoing message and how to *incrementally decode* a byte stream into
+ * complete messages. It spawns nothing and touches no filesystem, which keeps
+ * the framing logic unit-testable without a real language server (the spawn /
+ * lifecycle layer lives in `managers/lsp-manager.ts`).
+ */
+/** Encode a JSON-RPC message into a framed LSP buffer (headers + body). */
+export function encodeMessage(message) {
+    const body = Buffer.from(JSON.stringify(message), 'utf8');
+    const header = `Content-Length: ${body.length}\r\n\r\n`;
+    return Buffer.concat([Buffer.from(header, 'ascii'), body]);
+}
+/**
+ * Incremental decoder for the LSP framing. Feed it raw chunks as they arrive on
+ * the language server's stdout; it buffers partial frames and emits each
+ * complete JSON-RPC message via the `onMessage` callback. A single chunk may
+ * contain zero, one, or many messages, and a message may be split across
+ * chunks; both cases are handled.
+ */
+export class MessageBuffer {
+    onMessage;
+    buffer = Buffer.alloc(0);
+    constructor(onMessage) {
+        this.onMessage = onMessage;
+    }
+    append(chunk) {
+        this.buffer = this.buffer.length
+            ? Buffer.concat([this.buffer, chunk])
+            : Buffer.from(chunk);
+        this.drain();
+    }
+    drain() {
+        // Loop because one append may complete several queued frames.
+        for (;;) {
+            const headerEnd = this.buffer.indexOf('\r\n\r\n');
+            if (headerEnd === -1)
+                return; // headers not fully received yet
+            const header = this.buffer.subarray(0, headerEnd).toString('ascii');
+            const length = parseContentLength(header);
+            if (length === null) {
+                // Malformed header block: drop it and resync past the separator so a
+                // single bad frame can't wedge the stream forever.
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            const bodyStart = headerEnd + 4;
+            const bodyEnd = bodyStart + length;
+            if (this.buffer.length < bodyEnd)
+                return; // body not fully received yet
+            const body = this.buffer.subarray(bodyStart, bodyEnd).toString('utf8');
+            this.buffer = this.buffer.subarray(bodyEnd);
+            let parsed = null;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                parsed = null; // skip a non-JSON body but keep draining
+            }
+            if (parsed)
+                this.onMessage(parsed);
+        }
+    }
+}
+/** Parse the `Content-Length` value out of an LSP header block. */
+export function parseContentLength(header) {
+    for (const line of header.split(/\r\n/)) {
+        const m = /^Content-Length:\s*(\d+)\s*$/i.exec(line);
+        if (m) {
+            const n = Number(m[1]);
+            return Number.isFinite(n) && n >= 0 ? n : null;
+        }
+    }
+    return null;
+}
+/** Type guard: a message is a response when it carries an `id` and no `method`. */
+export function isResponse(msg) {
+    return 'id' in msg && !('method' in msg);
+}
+/**
+ * LSP SymbolKind enum (subset we surface). Maps numeric kinds returned by
+ * documentSymbol / workspaceSymbol to human-readable names.
+ */
+export const SYMBOL_KIND = {
+    1: 'file',
+    2: 'module',
+    3: 'namespace',
+    4: 'package',
+    5: 'class',
+    6: 'method',
+    7: 'property',
+    8: 'field',
+    9: 'constructor',
+    10: 'enum',
+    11: 'interface',
+    12: 'function',
+    13: 'variable',
+    14: 'constant',
+    23: 'struct',
+};
+/** LSP DiagnosticSeverity -> our severity vocabulary. */
+export function lspSeverity(n) {
+    if (n === 1)
+        return 'error';
+    if (n === 2)
+        return 'warning';
+    return 'info';
+}

package/dist/main.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { loadConfig } from './core/config.js';
+import { Container } from './core/container.js';
+import { buildRegistry, registerAdapterTools } from './tools/index.js';
+import { createMcpServer } from './server/mcp-server.js';
+import { startStdioTransport } from './server/transports/stdio.js';
+import { startHttpTransport } from './server/transports/http.js';
+import { startDashboard, isLoopbackHost } from './dashboard/server.js';
+import { logger } from './core/logger.js';
+import { randomBytes } from 'node:crypto';
+const VERSION = '1.0.0';
+function parseArgs(argv) {
+    const args = { stdio: false, http: false, dashboard: true };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => argv[++i];
+        switch (a) {
+            case '--project':
+            case '-p': {
+                const v = next();
+                if (v !== undefined)
+                    args.project = v;
+                break;
+            }
+            case '--config':
+            case '-c': {
+                const v = next();
+                if (v !== undefined)
+                    args.config = v;
+                break;
+            }
+            case '--stdio':
+                args.stdio = true;
+                break;
+            case '--http':
+                args.http = true;
+                break;
+            case '--port':
+                args.port = Number(next());
+                break;
+            case '--host': {
+                const v = next();
+                if (v !== undefined)
+                    args.host = v;
+                break;
+            }
+            case '--dashboard-port':
+                args.dashboardPort = Number(next());
+                break;
+            case '--no-dashboard':
+                args.dashboard = false;
+                break;
+            case '--version':
+            case '-v':
+                process.stdout.write(`folderforge ${VERSION}\n`);
+                process.exit(0);
+                break;
+            case '--help':
+            case '-h':
+                printHelp();
+                process.exit(0);
+                break;
+            default:
+                if (a && a.startsWith('-')) {
+                    logger.warn({ arg: a }, 'Unknown argument ignored');
+                }
+        }
+    }
+    return args;
+}
+function printHelp() {
+    process.stdout.write([
+        'FolderForge - local development control plane for AI coding agents',
+        '',
+        'Usage: folderforge [options]',
+        '',
+        'Options:',
+        '  -p, --project <dir>      Project root to activate (default: cwd)',
+        '  -c, --config <file>      Path to a YAML config file',
+        '      --stdio              Serve MCP over stdio (default for agent clients)',
+        '      --http               Serve MCP over Streamable HTTP',
+        '      --port <n>           HTTP MCP port (default 7331)',
+        '      --host <addr>        Bind address (default 127.0.0.1)',
+        '      --dashboard-port <n> Dashboard port (default 7332)',
+        '      --no-dashboard       Disable the local dashboard',
+        '  -v, --version            Print version and exit',
+        '  -h, --help               Show this help',
+        '',
+    ].join('\n'));
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const config = loadConfig({
+        ...(args.config !== undefined ? { configPath: args.config } : {}),
+        ...(args.project !== undefined ? { projectRoot: args.project } : {}),
+    });
+    // CLI overrides for transport/ports.
+    if (args.http)
+        config.server.transport = 'http';
+    if (args.stdio)
+        config.server.transport = 'stdio';
+    if (args.host !== undefined)
+        config.server.http.host = args.host;
+    if (args.port !== undefined)
+        config.server.http.port = args.port;
+    if (args.dashboardPort !== undefined)
+        config.server.dashboard.port = args.dashboardPort;
+    const container = new Container(config);
+    const registry = buildRegistry(container);
+    // Wire enabled child MCP adapters (Serena, Playwright, ...). Each child tool is
+    // exposed namespaced (e.g. serena__find_symbol). Discovery never blocks startup.
+    try {
+        const added = await registerAdapterTools(container, registry);
+        if (added > 0)
+            logger.info({ added }, 'Registered child MCP adapter tools');
+    }
+    catch (err) {
+        logger.warn({ err: String(err) }, 'Adapter tool registration failed; continuing without adapters');
+    }
+    const server = createMcpServer(registry, {
+        name: config.server.name,
+        version: VERSION,
+        roots: config.workspace.allowedDirectories,
+    });
+    container.audit.record({
+        type: 'server_start',
+        summary: `transport=${config.server.transport} tools=${registry.listAll().length}`,
+        detail: { version: VERSION, projectRoot: container.projectRoot() },
+    });
+    // Dashboard is independent of the MCP transport (and is safe to run alongside stdio).
+    if (args.dashboard) {
+        const dashHost = config.server.dashboard.host;
+        // A non-loopback bind exposes the control plane to the network, so it must be
+        // token-protected. Use the configured token or mint one and log it once.
+        let token = config.server.dashboard.token;
+        if (!isLoopbackHost(dashHost) && !token) {
+            token = randomBytes(24).toString('base64url');
+            logger.warn({ host: dashHost, token }, 'Dashboard bound to a non-loopback host; generated an auth token (set server.dashboard.token to pin it)');
+        }
+        startDashboard(container, registry, {
+            host: dashHost,
+            port: config.server.dashboard.port,
+            ...(token ? { token } : {}),
+        });
+    }
+    if (config.server.transport === 'http') {
+        const httpHost = config.server.http.host;
+        // Mirror the dashboard: a non-loopback bind must be token-protected. Use the
+        // configured token or mint one and log it once.
+        let httpToken = config.server.http.token;
+        if (!isLoopbackHost(httpHost) && !httpToken) {
+            httpToken = randomBytes(24).toString('base64url');
+            logger.warn({ host: httpHost, token: httpToken }, 'HTTP transport bound to a non-loopback host; generated an auth token (set server.http.token to pin it)');
+        }
+        await startHttpTransport(server, {
+            host: httpHost,
+            port: config.server.http.port,
+            ...(httpToken ? { token: httpToken } : {}),
+            ...(config.server.http.corsOrigins ? { corsOrigins: config.server.http.corsOrigins } : {}),
+            ...(config.server.http.sessionTtlMs !== undefined
+                ? { sessionTtlMs: config.server.http.sessionTtlMs }
+                : {}),
+        });
+    }
+    else {
+        await startStdioTransport(server);
+    }
+    const shutdown = async (signal) => {
+        logger.info({ signal }, 'Shutting down FolderForge');
+        try {
+            container.adapters.stopAll();
+        }
+        catch {
+            // ignore
+        }
+        try {
+            await server.close();
+        }
+        catch {
+            // ignore
+        }
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+}
+main().catch((err) => {
+    logger.error({ err: err instanceof Error ? err.stack : String(err) }, 'Fatal startup error');
+    process.exit(1);
+});