@musashishao/folderforge 1.2.0

package/README.md

@@ -0,0 +1,181 @@
+# FolderForge
+
+FolderForge turns any local folder into a safe, full-tool MCP workspace for AI agents.
+
+## Installation
+
+FolderForge is a single CLI (`folderforge`) that an AI coding agent launches over
+stdio. It needs **Node.js >= 22**. It runs against any project folder you point
+it at with `--project`; a config file is optional (without one it allows just
+that project directory and applies safe defaults).
+
+### Option 1 - npx (no install, recommended)
+
+The fastest path: let your agent run FolderForge on demand. Nothing to install
+globally. Point any MCP client at it:
+
+```jsonc
+{
+  "mcpServers": {
+    "folderforge": {
+      "command": "npx",
+      "args": ["-y", "folderforge", "--stdio", "--project", "/absolute/path/to/your-project"]
+    }
+  }
+}
+```
+
+Try it in a terminal first:
+
+```bash
+npx -y folderforge --project . --stdio
+```
+
+### Option 2 - global install from npm
+
+Install once, then call `folderforge` from anywhere:
+
+```bash
+npm install -g folderforge
+folderforge --version
+
+# run against any folder
+cd /path/to/your-project
+folderforge --stdio --project .
+```
+
+Agent config when installed globally:
+
+```jsonc
+{
+  "mcpServers": {
+    "folderforge": {
+      "command": "folderforge",
+      "args": ["--stdio", "--project", "/absolute/path/to/your-project"]
+    }
+  }
+}
+```
+
+### Option 3 - from source (Git, for contributors)
+
+Clone and build when you want to hack on FolderForge or run an unreleased
+version:
+
+```bash
+git clone https://github.com/your-org/folderforge.git
+cd folderforge
+npm install
+npm run build        # emits dist/
+
+# optional: expose the `folderforge` command system-wide
+npm link
+
+# or run directly without linking
+node dist/main.js --stdio --project /path/to/your-project
+```
+
+During development you can skip the build step and run the TypeScript source
+directly:
+
+```bash
+npm run dev -- --stdio --project /path/to/your-project
+```
+
+You can also install straight from a Git remote without a published npm release:
+
+```bash
+npm install -g github:your-org/folderforge
+```
+
+### Pointing at a different folder
+
+The folder FolderForge serves is independent of where it is installed. Set the
+working project with `--project` (and, if you use a config file, make sure its
+`workspace.allowedDirectories` includes that folder). To work across several
+projects at once, list them all in `allowedDirectories`.
+
+## What it does
+
+- Activates a local workspace (single or multiple projects at once)
+- Exposes MCP tools over stdio and localhost HTTP
+- Enforces path, command, and secret policy with a four-level risk model
+- Gates sensitive actions behind an approval queue (persisted across restarts)
+- Records every call to an append-only audit log
+- Supports file, search, shell, process, git, build, code-intelligence,
+  memory, browser, and database workflows
+
+## Status (1.0)
+
+FolderForge is at **1.0**. The full stack is in place and frozen for release:
+
+- **Core** - config loader (with aggregated validation errors), dependency
+  container, multi-project workspace activation.
+- **Policy** - path, command, and secret policies + risk model; approval queue
+  (once/session scopes) persisted under `.folderforge/approvals.jsonl`;
+  per-tool rate limits and daily quotas; pluggable secret scanning with
+  Shannon-entropy detection.
+- **Tools** - full native catalog (files, search incl. structural `search_ast`,
+  terminal, processes, git, build/quality, code intelligence, memory, security,
+  policy/audit, approvals, browser, database) plus `workspace_route` for
+  task-preset tool routing. The public tool surface is **frozen** in
+  `src/tools/schema-lock.ts` and guarded by tests.
+- **Adapters** - Serena, Playwright, and Desktop Commander child-MCP servers,
+  proxied with namespacing (`serena__<tool>`).
+- **Server** - MCP `tools/list` / `tools/call` over stdio and a hardened
+  Streamable HTTP transport (constant-time bearer auth, CORS allowlist,
+  idle-session expiry).
+- **Observability** - append-only JSONL audit log + ring buffer, `policy_explain`
+  dry-run tooling, and a local dashboard (`/status`, `/audit`, `/processes`,
+  `/approvals`).
+
+See `docs/roadmap.md` for the detailed milestone history and post-1.0 ideas.
+
+### MCP protocol features (1.2)
+
+Beyond `tools/list` / `tools/call`, FolderForge supports progress
+notifications (P4), cancellation (P6), and elicitation (P8), wired through a
+per-call control object that leaves the frozen tool schema untouched.
+`git_reset`, `git_push`, and `git_pull` confirm interactively before acting when
+the client supports elicitation, and `git_push` / `git_fetch` / `git_pull` /
+`process_tail` emit progress.
+
+## Run
+
+```bash
+npm install
+npm run dev -- --stdio
+```
+
+or
+
+```bash
+npm run dev -- --port 7331 --host 127.0.0.1
+```
+
+## Develop
+
+```bash
+npm test          # unit + integration (vitest)
+npm run typecheck # tsc --noEmit
+npm run build     # emit to dist/
+```
+
+## Design goals
+
+- Safe by default
+- Local-first
+- Auditable
+- MCP-native
+- Production-minded code structure
+
+## Repository structure
+
+- `src/` - server, policy, workspace, tools, audit, dashboard
+- `docs/` - architecture, tools, adapters, security, and roadmap docs
+- `examples/` - sample client configs
+- `tests/` - unit and integration tests (incl. the schema-lock guard)
+
+## License
+
+Apache-2.0

package/dist/adapters/child-mcp/client.js

@@ -0,0 +1,114 @@
+import { spawn } from 'node:child_process';
+import { logger } from '../../core/logger.js';
+/**
+ * Minimal JSON-RPC client over a child MCP server's stdio.
+ * Implements just enough of the MCP wire protocol to initialize,
+ * list tools, and call tools.
+ */
+export class StdioChildClient {
+    command;
+    args;
+    env;
+    child = null;
+    pending = new Map();
+    nextId = 1;
+    buffer = '';
+    initialized = false;
+    constructor(command, args, env = {}) {
+        this.command = command;
+        this.args = args;
+        this.env = env;
+    }
+    async start() {
+        if (this.child)
+            return;
+        this.child = spawn(this.command, this.args, {
+            env: { ...process.env, ...this.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child.stdout.on('data', (chunk) => this.onData(chunk));
+        this.child.stderr.on('data', (chunk) => logger.debug({ child: this.command, msg: chunk.toString() }, 'child stderr'));
+        this.child.on('exit', (code) => {
+            logger.warn({ child: this.command, code }, 'child MCP exited');
+            this.child = null;
+            this.initialized = false;
+            for (const p of this.pending.values())
+                p.reject(new Error('child process exited'));
+            this.pending.clear();
+        });
+        await this.request('initialize', {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: { name: 'folderforge', version: '0.1.0' },
+        });
+        this.notify('notifications/initialized', {});
+        this.initialized = true;
+    }
+    onData(chunk) {
+        this.buffer += chunk.toString('utf8');
+        let idx;
+        while ((idx = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            try {
+                const msg = JSON.parse(line);
+                if (typeof msg.id === 'number' && this.pending.has(msg.id)) {
+                    const p = this.pending.get(msg.id);
+                    this.pending.delete(msg.id);
+                    if (msg.error)
+                        p.reject(new Error(msg.error.message));
+                    else
+                        p.resolve(msg.result);
+                }
+            }
+            catch {
+                // ignore non-JSON lines
+            }
+        }
+    }
+    notify(method, params) {
+        if (!this.child)
+            return;
+        this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+    }
+    request(method, params, timeoutMs = 30000) {
+        if (!this.child)
+            return Promise.reject(new Error('child not started'));
+        const id = this.nextId++;
+        const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`child request timed out: ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.child.stdin.write(payload);
+        });
+    }
+    async listTools() {
+        const res = (await this.request('tools/list', {}));
+        return res.tools ?? [];
+    }
+    async callTool(name, args) {
+        return this.request('tools/call', { name, arguments: args });
+    }
+    isReady() {
+        return this.initialized && this.child !== null;
+    }
+    stop() {
+        this.child?.kill('SIGTERM');
+        this.child = null;
+        this.initialized = false;
+    }
+}

package/dist/adapters/child-mcp/registry.js

@@ -0,0 +1,66 @@
+import { StdioChildClient } from './client.js';
+import { logger } from '../../core/logger.js';
+/**
+ * Lazily spawns and manages child MCP servers (Serena, Playwright, etc.).
+ * Adapters only start on first use to avoid paying their cost upfront.
+ */
+export class ChildMcpRegistry {
+    entries = new Map();
+    constructor(config) {
+        const map = [
+            ['serena', config.serena],
+            ['playwright', config.playwright],
+            ['desktopCommander', config.desktopCommander],
+        ];
+        for (const [name, def] of map) {
+            if (def) {
+                this.entries.set(name, { name, def, client: null, lazyStarted: false });
+            }
+        }
+    }
+    isEnabled(name) {
+        return this.entries.get(name)?.def.enabled ?? false;
+    }
+    async ensure(name) {
+        const entry = this.entries.get(name);
+        if (!entry)
+            throw new Error(`Adapter not configured: ${name}`);
+        if (!entry.def.enabled)
+            throw new Error(`Adapter disabled: ${name}`);
+        if (!entry.client) {
+            entry.client = new StdioChildClient(entry.def.command, entry.def.args, entry.def.env ?? {});
+        }
+        if (!entry.client.isReady()) {
+            logger.info({ adapter: name }, 'Starting child MCP adapter');
+            await entry.client.start();
+            entry.lazyStarted = true;
+        }
+        return entry.client;
+    }
+    async health(name) {
+        const entry = this.entries.get(name);
+        if (!entry)
+            return { enabled: false, ready: false };
+        if (!entry.def.enabled)
+            return { enabled: false, ready: false };
+        try {
+            const client = await this.ensure(name);
+            await client.listTools();
+            return { enabled: true, ready: true };
+        }
+        catch (err) {
+            return { enabled: true, ready: false, error: String(err) };
+        }
+    }
+    status() {
+        return [...this.entries.values()].map((e) => ({
+            name: e.name,
+            enabled: e.def.enabled,
+            started: e.lazyStarted && (e.client?.isReady() ?? false),
+        }));
+    }
+    stopAll() {
+        for (const e of this.entries.values())
+            e.client?.stop();
+    }
+}

package/dist/audit/audit-log.js

@@ -0,0 +1,45 @@
+import { appendFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { logger } from '../core/logger.js';
+/**
+ * Append-only JSONL audit log, also kept in a ring buffer for fast recent reads.
+ */
+export class AuditLog {
+    buffer = [];
+    maxBuffer = 500;
+    filePath;
+    constructor(projectRoot) {
+        this.filePath = join(projectRoot, '.folderforge', 'audit', 'audit.jsonl');
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+        }
+        catch (err) {
+            logger.warn({ err: String(err) }, 'Could not create audit directory');
+        }
+    }
+    record(event) {
+        const full = { ts: new Date().toISOString(), ...event };
+        this.buffer.push(full);
+        if (this.buffer.length > this.maxBuffer)
+            this.buffer.shift();
+        try {
+            appendFileSync(this.filePath, JSON.stringify(full) + '\n', 'utf8');
+        }
+        catch (err) {
+            logger.warn({ err: String(err) }, 'Failed to append audit event');
+        }
+        return full;
+    }
+    recent(limit = 50) {
+        return this.buffer.slice(-limit).reverse();
+    }
+    exportPath() {
+        return this.filePath;
+    }
+    exportRaw() {
+        if (existsSync(this.filePath)) {
+            return readFileSync(this.filePath, 'utf8');
+        }
+        return this.buffer.map((e) => JSON.stringify(e)).join('\n');
+    }
+}

package/dist/audit/event-types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/config.js

@@ -0,0 +1,211 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { logger } from './logger.js';
+const DEFAULT_BLOCKED = [
+    'rm -rf /',
+    'sudo rm',
+    'mkfs',
+    'dd if=',
+    'chmod -R 777 /',
+    'chown -R',
+    'curl * | bash',
+    'wget * | sh',
+    'git reset --hard',
+    'git push --force',
+    'docker system prune',
+    'kubectl delete',
+    'terraform apply',
+];
+const DEFAULT_DENIED_GLOBS = [
+    '**/.env',
+    '**/.env.*',
+    '**/id_rsa',
+    '**/id_ed25519',
+    '**/*.pem',
+    '**/*.key',
+    '**/node_modules/**',
+    '**/.git/objects/**',
+];
+export function defaultConfig(projectRoot) {
+    return {
+        server: {
+            name: 'folderforge',
+            transport: 'stdio',
+            http: { host: '127.0.0.1', port: 7331 },
+            dashboard: { host: '127.0.0.1', port: 7332 },
+        },
+        workspace: {
+            defaultProject: projectRoot,
+            allowedDirectories: [projectRoot],
+            deniedGlobs: [...DEFAULT_DENIED_GLOBS],
+        },
+        policy: {
+            defaultMode: 'safe',
+            requireApproval: [
+                'git_push',
+                'git_commit',
+                'file_delete',
+                'db_write',
+                'shell_high_risk',
+                'docker_prune',
+            ],
+            blockedCommands: [...DEFAULT_BLOCKED],
+        },
+        terminal: {
+            shell: process.platform === 'win32' ? 'cmd.exe' : '/bin/bash',
+            defaultTimeoutMs: 120000,
+            maxOutputBytes: 200000,
+            envPolicy: 'redact',
+        },
+        git: {
+            allowCommit: 'approval',
+            allowPush: 'approval',
+            allowResetHard: false,
+        },
+        rateLimit: {
+            enabled: true,
+            // Generous default: 60 calls / 10s window keeps interactive agents fast
+            // while stopping runaway loops. No daily quota by default.
+            default: { maxCalls: 60, windowMs: 10_000 },
+            overrides: {
+                // Mutating/expensive actions get tighter limits.
+                shell_exec: { maxCalls: 20, windowMs: 10_000, dailyQuota: 1000 },
+                git_commit: { maxCalls: 10, windowMs: 60_000, dailyQuota: 200 },
+                git_push: { maxCalls: 5, windowMs: 60_000, dailyQuota: 50 },
+                file_delete: { maxCalls: 20, windowMs: 60_000, dailyQuota: 500 },
+                db_write: { maxCalls: 20, windowMs: 60_000, dailyQuota: 500 },
+            },
+        },
+        secretScan: {
+            entropyEnabled: true,
+            minEntropy: 4.0,
+            minLength: 20,
+        },
+        adapters: {
+            serena: { enabled: false, command: 'serena', args: [] },
+            playwright: { enabled: false, command: 'npx', args: ['-y', '@playwright/mcp@latest'] },
+            desktopCommander: { enabled: false, command: 'npx', args: ['-y', '@wonderwhy-er/desktop-commander@latest'] },
+        },
+        lsp: {
+            enabled: true,
+            requestTimeoutMs: 15000,
+        },
+    };
+}
+function deepMerge(base, override) {
+    if (override === undefined || override === null)
+        return base;
+    if (Array.isArray(base) || Array.isArray(override)) {
+        return (override ?? base);
+    }
+    if (typeof base === 'object' && typeof override === 'object') {
+        const out = { ...base };
+        for (const [k, v] of Object.entries(override)) {
+            const bv = base[k];
+            if (v && typeof v === 'object' && !Array.isArray(v) && bv && typeof bv === 'object') {
+                out[k] = deepMerge(bv, v);
+            }
+            else if (v !== undefined) {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    return (override ?? base);
+}
+export function loadConfig(opts = {}) {
+    const projectRoot = resolve(opts.projectRoot ?? process.cwd());
+    let cfg = defaultConfig(projectRoot);
+    const candidatePaths = [
+        opts.configPath,
+        process.env.FOLDERFORGE_CONFIG,
+        resolve(projectRoot, 'folderforge.yaml'),
+        resolve(projectRoot, '.folderforge.yaml'),
+        resolve(projectRoot, '.folderforge/config.yaml'),
+    ].filter((p) => Boolean(p));
+    for (const p of candidatePaths) {
+        const abs = isAbsolute(p) ? p : resolve(projectRoot, p);
+        if (existsSync(abs)) {
+            try {
+                const raw = readFileSync(abs, 'utf8');
+                const parsed = parseYaml(raw);
+                cfg = deepMerge(cfg, parsed);
+                logger.info({ configPath: abs }, 'Loaded config file');
+            }
+            catch (err) {
+                logger.warn({ configPath: abs, err: String(err) }, 'Failed to parse config; using defaults');
+            }
+            break;
+        }
+    }
+    // Normalize allowed dirs to absolute.
+    cfg.workspace.allowedDirectories = cfg.workspace.allowedDirectories.map((d) => isAbsolute(d) ? resolve(d) : resolve(projectRoot, d));
+    if (cfg.workspace.defaultProject) {
+        cfg.workspace.defaultProject = resolve(cfg.workspace.defaultProject);
+    }
+    validateConfig(cfg);
+    return cfg;
+}
+/**
+ * Validate a loaded config and throw a single, human-readable error listing
+ * every problem found. Catches the common foot-guns (bad enums, negative
+ * limits, empty allowlists) early instead of failing deep inside a handler.
+ */
+export function validateConfig(cfg) {
+    const errors = [];
+    const modes = ['readonly', 'safe', 'dev', 'danger'];
+    if (!modes.includes(cfg.policy.defaultMode)) {
+        errors.push(`policy.defaultMode must be one of ${modes.join(', ')} (got "${cfg.policy.defaultMode}")`);
+    }
+    if (!['stdio', 'http'].includes(cfg.server.transport)) {
+        errors.push(`server.transport must be "stdio" or "http" (got "${cfg.server.transport}")`);
+    }
+    if (cfg.server.http.port <= 0 || cfg.server.http.port > 65535) {
+        errors.push(`server.http.port must be 1-65535 (got ${cfg.server.http.port})`);
+    }
+    if (cfg.server.dashboard.port <= 0 || cfg.server.dashboard.port > 65535) {
+        errors.push(`server.dashboard.port must be 1-65535 (got ${cfg.server.dashboard.port})`);
+    }
+    if (!cfg.workspace.allowedDirectories.length) {
+        errors.push('workspace.allowedDirectories must list at least one directory');
+    }
+    if (cfg.terminal.maxOutputBytes <= 0) {
+        errors.push(`terminal.maxOutputBytes must be > 0 (got ${cfg.terminal.maxOutputBytes})`);
+    }
+    if (cfg.terminal.defaultTimeoutMs <= 0) {
+        errors.push(`terminal.defaultTimeoutMs must be > 0 (got ${cfg.terminal.defaultTimeoutMs})`);
+    }
+    if (!['redact', 'passthrough'].includes(cfg.terminal.envPolicy)) {
+        errors.push(`terminal.envPolicy must be "redact" or "passthrough" (got "${cfg.terminal.envPolicy}")`);
+    }
+    if (cfg.rateLimit.enabled) {
+        const rules = [
+            ['rateLimit.default', cfg.rateLimit.default],
+            ...Object.entries(cfg.rateLimit.overrides).map(([k, v]) => [`rateLimit.overrides.${k}`, v]),
+        ];
+        for (const [label, rule] of rules) {
+            if (rule.maxCalls <= 0)
+                errors.push(`${label}.maxCalls must be > 0 (got ${rule.maxCalls})`);
+            if (rule.windowMs <= 0)
+                errors.push(`${label}.windowMs must be > 0 (got ${rule.windowMs})`);
+            if (rule.dailyQuota !== undefined && rule.dailyQuota <= 0) {
+                errors.push(`${label}.dailyQuota must be > 0 when set (got ${rule.dailyQuota})`);
+            }
+        }
+    }
+    if (cfg.secretScan.entropyEnabled) {
+        if (cfg.secretScan.minEntropy <= 0) {
+            errors.push(`secretScan.minEntropy must be > 0 (got ${cfg.secretScan.minEntropy})`);
+        }
+        if (cfg.secretScan.minLength <= 0) {
+            errors.push(`secretScan.minLength must be > 0 (got ${cfg.secretScan.minLength})`);
+        }
+    }
+    if (cfg.lsp && cfg.lsp.enabled && cfg.lsp.requestTimeoutMs <= 0) {
+        errors.push(`lsp.requestTimeoutMs must be > 0 (got ${cfg.lsp.requestTimeoutMs})`);
+    }
+    if (errors.length) {
+        throw new Error(`Invalid FolderForge config:\n  - ${errors.join('\n  - ')}`);
+    }
+}

package/dist/core/container.js

@@ -0,0 +1,51 @@
+import { PolicyEngine } from '../policy/policy-engine.js';
+import { RateLimiter } from '../policy/rate-limiter.js';
+import { AuditLog } from '../audit/audit-log.js';
+import { WorkspaceManager } from '../workspace/workspace-manager.js';
+import { ProcessManager } from '../managers/process-manager.js';
+import { ChildMcpRegistry } from '../adapters/child-mcp/registry.js';
+import { DbManager } from '../managers/db-manager.js';
+import { LspManager } from '../managers/lsp-manager.js';
+/**
+ * Dependency container shared by every tool handler.
+ */
+export class Container {
+    config;
+    policy;
+    rateLimiter;
+    audit;
+    workspace;
+    processes;
+    adapters;
+    db;
+    lsp;
+    /**
+     * The tool registry. Assigned by `buildRegistry` right after construction so
+     * that routing tools (e.g. `workspace_route`) can adjust the active tool set.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registry = null;
+    constructor(config) {
+        this.config = config;
+        this.policy = new PolicyEngine(config);
+        this.rateLimiter = new RateLimiter(config.rateLimit);
+        this.workspace = new WorkspaceManager(config.workspace.allowedDirectories);
+        this.audit = new AuditLog(config.workspace.defaultProject);
+        this.processes = new ProcessManager();
+        this.adapters = new ChildMcpRegistry(config.adapters);
+        this.db = new DbManager();
+        this.lsp = new LspManager(config.lsp);
+        // Auto-activate default project if it exists.
+        if (config.workspace.defaultProject) {
+            try {
+                this.workspace.activate(config.workspace.defaultProject);
+            }
+            catch {
+                // Not fatal; the client can call workspace_activate later.
+            }
+        }
+    }
+    projectRoot() {
+        return this.workspace.projectRoot() ?? this.config.workspace.defaultProject;
+    }
+}