@musashishao/folderforge 1.2.0

package/dist/tools/schema-lock.js

@@ -0,0 +1,152 @@
+/**
+ * FolderForge tool-schema lock (1.0 freeze).
+ *
+ * This file is the SOURCE OF TRUTH for the public native tool surface at 1.0. Tool
+ * names and their `mutates` / `risk` contract are frozen here. Any change that
+ * renames a tool, removes one, or alters its mutation/risk classification is a
+ * BREAKING change: it must be a major-version bump and an intentional edit to
+ * this file.
+ *
+ * NOTE: some tools (e.g. `parse_errors`) are internal helpers but still live in
+ * the native registry. They are frozen here because the schema-lock guard is
+ * intentionally strict: CI should catch any accidental changes to the live tool
+ * catalog.
+ *
+ * Adding a brand-new tool is backwards-compatible: register it, then add an
+ * entry here. The guard test (`tests/unit/schema-lock.test.ts`) fails if the
+ * live registry and this lock ever diverge, so accidental renames/removals are
+ * caught in CI.
+ *
+ * DO NOT edit casually. Treat edits to this file as API changes.
+ */
+/**
+ * The frozen 1.0 native tool catalog. Child-MCP adapter tools (namespaced,
+ * e.g. `serena__find_symbol`) are intentionally NOT part of the frozen surface
+ * because they are discovered dynamically from external servers.
+ */
+export const FROZEN_TOOLS = [
+    // --- workspace ---
+    { name: 'workspace_status', mutates: false, risk: 'LOW' },
+    { name: 'workspace_list', mutates: false, risk: 'LOW' },
+    { name: 'workspace_health', mutates: false, risk: 'LOW' },
+    { name: 'workspace_route', mutates: false, risk: 'LOW' },
+    { name: 'workspace_activate', mutates: true, risk: 'MEDIUM' },
+    { name: 'workspace_switch', mutates: true, risk: 'MEDIUM' },
+    { name: 'workspace_deactivate', mutates: true, risk: 'MEDIUM' },
+    { name: 'workspace_onboard', mutates: true, risk: 'MEDIUM' },
+    { name: 'project_detect_commands', mutates: false, risk: 'LOW' },
+    // --- files ---
+    { name: 'file_read', mutates: false, risk: 'LOW' },
+    { name: 'file_read_many', mutates: false, risk: 'LOW' },
+    { name: 'file_write', mutates: true, risk: 'MEDIUM' },
+    { name: 'file_patch', mutates: true, risk: 'MEDIUM' },
+    { name: 'file_edit_block', mutates: true, risk: 'MEDIUM' },
+    { name: 'file_move', mutates: true, risk: 'MEDIUM' },
+    { name: 'file_copy', mutates: true, risk: 'MEDIUM' },
+    { name: 'list_directory', mutates: false, risk: 'LOW' },
+    { name: 'file_delete', mutates: true, risk: 'HIGH' },
+    // --- search ---
+    { name: 'search_files', mutates: false, risk: 'LOW' },
+    { name: 'search_text', mutates: false, risk: 'LOW' },
+    { name: 'search_ast', mutates: false, risk: 'LOW' },
+    // --- terminal ---
+    { name: 'shell_exec', mutates: true, risk: 'MEDIUM' },
+    // --- processes ---
+    { name: 'process_start', mutates: true, risk: 'MEDIUM' },
+    { name: 'process_read', mutates: false, risk: 'LOW' },
+    { name: 'process_tail', mutates: false, risk: 'LOW' },
+    { name: 'process_write', mutates: true, risk: 'MEDIUM' },
+    { name: 'process_stop', mutates: true, risk: 'MEDIUM' },
+    { name: 'process_list', mutates: false, risk: 'LOW' },
+    { name: 'process_kill', mutates: true, risk: 'HIGH' },
+    // --- git ---
+    { name: 'git_status', mutates: false, risk: 'LOW' },
+    { name: 'git_diff', mutates: false, risk: 'LOW' },
+    { name: 'git_log', mutates: false, risk: 'LOW' },
+    { name: 'git_show', mutates: false, risk: 'LOW' },
+    { name: 'git_blame', mutates: false, risk: 'LOW' },
+    { name: 'git_branch', mutates: false, risk: 'LOW' },
+    { name: 'git_fetch', mutates: true, risk: 'MEDIUM' },
+    { name: 'git_pull', mutates: true, risk: 'HIGH' },
+    { name: 'git_stash', mutates: true, risk: 'MEDIUM' },
+    { name: 'git_add', mutates: true, risk: 'MEDIUM' },
+    { name: 'git_checkout', mutates: true, risk: 'MEDIUM' },
+    { name: 'git_commit', mutates: true, risk: 'HIGH' },
+    { name: 'git_push', mutates: true, risk: 'CRITICAL' },
+    { name: 'git_reset', mutates: true, risk: 'CRITICAL' },
+    // --- build / quality ---
+    { name: 'run_test', mutates: false, risk: 'LOW' },
+    { name: 'run_lint', mutates: false, risk: 'LOW' },
+    { name: 'run_typecheck', mutates: false, risk: 'LOW' },
+    { name: 'run_build', mutates: true, risk: 'MEDIUM' },
+    { name: 'run_coverage', mutates: false, risk: 'LOW' },
+    // NOTE: parse_errors is an internal helper tool used by build/quality tooling.
+    // It is part of the native registry and therefore frozen for 1.0.
+    { name: 'parse_errors', mutates: false, risk: 'MEDIUM' },
+    // --- packages (Gap 2) ---
+    { name: 'pkg_list', mutates: false, risk: 'LOW' },
+    { name: 'pkg_outdated', mutates: false, risk: 'LOW' },
+    { name: 'pkg_audit', mutates: false, risk: 'LOW' },
+    { name: 'pkg_run', mutates: true, risk: 'MEDIUM' },
+    { name: 'pkg_add', mutates: true, risk: 'HIGH' },
+    { name: 'pkg_remove', mutates: true, risk: 'HIGH' },
+    // --- formatting (Gap 3) ---
+    { name: 'format_check', mutates: false, risk: 'LOW' },
+    { name: 'format_apply', mutates: true, risk: 'MEDIUM' },
+    // --- memory ---
+    { name: 'memory_list', mutates: false, risk: 'LOW' },
+    { name: 'memory_read', mutates: false, risk: 'LOW' },
+    { name: 'memory_write', mutates: true, risk: 'MEDIUM' },
+    { name: 'memory_update', mutates: true, risk: 'MEDIUM' },
+    // --- code intelligence ---
+    { name: 'code_symbols_overview', mutates: false, risk: 'LOW' },
+    { name: 'code_find_symbol', mutates: false, risk: 'LOW' },
+    { name: 'code_find_references', mutates: false, risk: 'LOW' },
+    { name: 'code_find_definition', mutates: false, risk: 'LOW' },
+    { name: 'code_find_implementations', mutates: false, risk: 'LOW' },
+    { name: 'code_diagnostics', mutates: false, risk: 'LOW' },
+    { name: 'code_replace_symbol_body', mutates: true, risk: 'MEDIUM' },
+    { name: 'code_insert_before_symbol', mutates: true, risk: 'MEDIUM' },
+    { name: 'code_insert_after_symbol', mutates: true, risk: 'MEDIUM' },
+    { name: 'code_rename_symbol', mutates: true, risk: 'MEDIUM' },
+    // --- browser ---
+    { name: 'browser_snapshot', mutates: false, risk: 'LOW' },
+    { name: 'browser_console', mutates: false, risk: 'LOW' },
+    { name: 'browser_network', mutates: false, risk: 'LOW' },
+    { name: 'browser_open', mutates: true, risk: 'MEDIUM' },
+    { name: 'browser_click', mutates: true, risk: 'MEDIUM' },
+    { name: 'browser_type', mutates: true, risk: 'MEDIUM' },
+    { name: 'browser_screenshot', mutates: true, risk: 'MEDIUM' },
+    { name: 'browser_close', mutates: true, risk: 'MEDIUM' },
+    { name: 'browser_eval', mutates: true, risk: 'HIGH' },
+    // --- database ---
+    { name: 'db_list_connections', mutates: false, risk: 'LOW' },
+    { name: 'db_list_tables', mutates: false, risk: 'LOW' },
+    { name: 'db_describe_table', mutates: false, risk: 'LOW' },
+    { name: 'db_query_readonly', mutates: false, risk: 'LOW' },
+    { name: 'db_explain', mutates: false, risk: 'LOW' },
+    { name: 'db_connect', mutates: true, risk: 'MEDIUM' },
+    { name: 'db_run_migration', mutates: true, risk: 'HIGH' },
+    { name: 'db_write', mutates: true, risk: 'HIGH' },
+    // --- security ---
+    { name: 'secret_scan', mutates: false, risk: 'LOW' },
+    // --- policy / audit / approvals ---
+    { name: 'policy_get', mutates: false, risk: 'LOW' },
+    { name: 'policy_explain', mutates: false, risk: 'LOW' },
+    { name: 'policy_ratelimits', mutates: false, risk: 'LOW' },
+    { name: 'policy_set_mode', mutates: true, risk: 'MEDIUM' },
+    { name: 'audit_recent', mutates: false, risk: 'LOW' },
+    // NOTE: audit_export and approval_request are not in TOOL_RISK, so they fall
+    // back to the defineTool default of MEDIUM. They are frozen here at their
+    // ACTUAL runtime risk to keep the lock truthful. Reclassifying them to LOW is
+    // a deliberate, separate change (see docs/roadmap.md post-1.0 notes).
+    { name: 'audit_export', mutates: false, risk: 'MEDIUM' },
+    { name: 'approval_status', mutates: false, risk: 'LOW' },
+    { name: 'approval_request', mutates: false, risk: 'MEDIUM' },
+];
+/** Set of frozen tool names for O(1) membership checks. */
+export const FROZEN_TOOL_NAMES = new Set(FROZEN_TOOLS.map((t) => t.name));
+/** Lookup the frozen contract for a tool name. */
+export function frozenTool(name) {
+    return FROZEN_TOOLS.find((t) => t.name === name);
+}

package/dist/tools/search-tools.js

@@ -0,0 +1,176 @@
+import { readFileSync, statSync } from 'node:fs';
+import { relative } from 'node:path';
+import fg from 'fast-glob';
+import { defineTool } from './registry.js';
+export function searchTools() {
+    return [
+        defineTool({
+            name: 'search_files',
+            description: 'Find files by name or glob pattern inside the workspace.',
+            group: 'search',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    glob: { type: 'string', description: 'Glob, e.g. src/**/*.ts' },
+                    limit: { type: 'number' },
+                },
+                required: ['glob'],
+            },
+            handler: async (args, ctx) => {
+                const pattern = String(args.glob);
+                const matches = await fg(pattern, {
+                    cwd: ctx.projectRoot,
+                    dot: false,
+                    ignore: ['**/node_modules/**', '**/.git/**'],
+                    onlyFiles: true,
+                });
+                const limit = Number(args.limit ?? 200);
+                return { ok: true, data: { matches: matches.slice(0, limit), total: matches.length } };
+            },
+        }),
+        defineTool({
+            name: 'search_text',
+            description: 'Search text/regex across files (ripgrep-style, native).',
+            group: 'search',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string' },
+                    glob: { type: 'string' },
+                    caseSensitive: { type: 'boolean' },
+                    limit: { type: 'number' },
+                },
+                required: ['query'],
+            },
+            handler: async (args, ctx) => {
+                const glob = String(args.glob ?? '**/*');
+                const limit = Number(args.limit ?? 200);
+                const flags = args.caseSensitive ? 'g' : 'gi';
+                let re;
+                try {
+                    re = new RegExp(String(args.query), flags);
+                }
+                catch {
+                    // Treat as literal if invalid regex.
+                    re = new RegExp(escapeRegExp(String(args.query)), flags);
+                }
+                const files = await fg(glob, {
+                    cwd: ctx.projectRoot,
+                    ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+                    onlyFiles: true,
+                    absolute: true,
+                });
+                const results = [];
+                for (const file of files) {
+                    if (results.length >= limit)
+                        break;
+                    try {
+                        if (statSync(file).size > 2_000_000)
+                            continue;
+                        const content = readFileSync(file, 'utf8');
+                        const lines = content.split('\n');
+                        for (let i = 0; i < lines.length; i++) {
+                            re.lastIndex = 0;
+                            if (re.test(lines[i])) {
+                                results.push({
+                                    file: relative(ctx.projectRoot, file),
+                                    line: i + 1,
+                                    text: ctx.container.policy.secret.redact(lines[i].slice(0, 300)),
+                                });
+                                if (results.length >= limit)
+                                    break;
+                            }
+                        }
+                    }
+                    catch {
+                        // skip unreadable/binary
+                    }
+                }
+                return { ok: true, data: { matches: results, count: results.length } };
+            },
+        }),
+        defineTool({
+            name: 'search_ast',
+            description: 'Structural search for code declarations (functions, classes, methods, ' +
+                'interfaces, types, consts) by name across the workspace. Lightweight, ' +
+                'regex-backed structural matching - no language server required.',
+            group: 'search',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Symbol name or partial name to find.' },
+                    kind: {
+                        type: 'string',
+                        description: 'Restrict to one kind: function | class | method | interface | type | const',
+                        enum: ['function', 'class', 'method', 'interface', 'type', 'const'],
+                    },
+                    glob: { type: 'string', description: 'File glob to limit the search (default common source files).' },
+                    limit: { type: 'number' },
+                },
+                required: ['name'],
+            },
+            handler: async (args, ctx) => {
+                const name = String(args.name);
+                const kindFilter = args.kind === undefined ? null : String(args.kind);
+                const glob = String(args.glob ?? '**/*.{ts,tsx,js,jsx,mjs,cjs,py,go,rs,java,rb,c,h,cpp,cs}');
+                const limit = Number(args.limit ?? 200);
+                const escaped = escapeRegExp(name);
+                // Structural declaration patterns. Each entry maps a kind to a regex whose
+                // match indicates a declaration of `name`.
+                const patterns = [
+                    { kind: 'function', re: new RegExp(`\\b(?:async\\s+)?function\\s+(${escaped})\\b`) },
+                    { kind: 'function', re: new RegExp(`\\b(?:export\\s+)?(?:const|let|var)\\s+(${escaped})\\s*=\\s*(?:async\\s*)?\\(`) },
+                    { kind: 'function', re: new RegExp(`\\bdef\\s+(${escaped})\\s*\\(`) }, // python
+                    { kind: 'function', re: new RegExp(`\\bfunc\\s+(${escaped})\\s*\\(`) }, // go
+                    { kind: 'class', re: new RegExp(`\\bclass\\s+(${escaped})\\b`) },
+                    { kind: 'interface', re: new RegExp(`\\binterface\\s+(${escaped})\\b`) },
+                    { kind: 'type', re: new RegExp(`\\btype\\s+(${escaped})\\b`) },
+                    { kind: 'const', re: new RegExp(`\\b(?:export\\s+)?(?:const|let|var)\\s+(${escaped})\\b`) },
+                    { kind: 'method', re: new RegExp(`^\\s*(?:public|private|protected|static|async|\\s)*\\b(${escaped})\\s*\\(`) },
+                ].filter((p) => !kindFilter || p.kind === kindFilter);
+                const files = await fg(glob, {
+                    cwd: ctx.projectRoot,
+                    ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+                    onlyFiles: true,
+                    absolute: true,
+                });
+                const results = [];
+                for (const file of files) {
+                    if (results.length >= limit)
+                        break;
+                    try {
+                        if (statSync(file).size > 2_000_000)
+                            continue;
+                        const lines = readFileSync(file, 'utf8').split('\n');
+                        for (let i = 0; i < lines.length; i++) {
+                            const line = lines[i];
+                            for (const { kind, re } of patterns) {
+                                if (re.test(line)) {
+                                    results.push({
+                                        file: relative(ctx.projectRoot, file),
+                                        line: i + 1,
+                                        kind,
+                                        text: line.trim().slice(0, 300),
+                                    });
+                                    break; // one hit per line is enough
+                                }
+                            }
+                            if (results.length >= limit)
+                                break;
+                        }
+                    }
+                    catch {
+                        // skip unreadable/binary
+                    }
+                }
+                return { ok: true, data: { matches: results, count: results.length } };
+            },
+        }),
+    ];
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/tools/security-tools.js

@@ -0,0 +1,147 @@
+import { defineTool } from './registry.js';
+import { readFileSync } from 'node:fs';
+export function securityTools() {
+    return [
+        defineTool({
+            name: 'policy_get',
+            description: 'Return the current policy: mode, approval rules, blocked commands, allowed dirs.',
+            group: 'security',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => ({ ok: true, data: ctx.container.policy.describe() }),
+        }),
+        defineTool({
+            name: 'policy_explain',
+            description: 'Dry-run a tool call and explain the policy decision (allow | deny | approval) ' +
+                'and why, without executing the tool or creating an approval request.',
+            group: 'security',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tool: { type: 'string', description: 'Name of the tool to evaluate.' },
+                    args: { type: 'object', description: 'Args the call would use (used for risk classification).' },
+                },
+                required: ['tool'],
+            },
+            handler: async (args, ctx) => {
+                const toolName = String(args.tool);
+                const callArgs = args.args ?? {};
+                const registry = ctx.container.registry;
+                const def = registry?.get(toolName);
+                if (!def) {
+                    return { ok: false, error: `Unknown tool: ${toolName}` };
+                }
+                // Mirror the per-call risk reclassification done in ToolRegistry.call:
+                // shell_exec risk depends on the actual command.
+                let risk = def.risk;
+                if (toolName === 'shell_exec' && typeof callArgs.command === 'string') {
+                    risk = ctx.container.policy.command.classify(callArgs.command).risk;
+                }
+                const explanation = ctx.container.policy.explain(toolName, risk, def.mutates, callArgs);
+                return { ok: true, data: { tool: toolName, ...explanation } };
+            },
+        }),
+        defineTool({
+            name: 'policy_set_mode',
+            description: 'Set the policy mode: readonly | safe | dev | danger.',
+            group: 'security',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { mode: { type: 'string', enum: ['readonly', 'safe', 'dev', 'danger'] } },
+                required: ['mode'],
+            },
+            handler: async (args, ctx) => {
+                const mode = String(args.mode);
+                if (!['readonly', 'safe', 'dev', 'danger'].includes(mode)) {
+                    return { ok: false, error: `Invalid mode: ${mode}` };
+                }
+                ctx.container.policy.setMode(mode);
+                return { ok: true, data: { mode } };
+            },
+        }),
+        defineTool({
+            name: 'audit_recent',
+            description: 'Return recent audit events.',
+            group: 'security',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { limit: { type: 'number' } } },
+            handler: async (args, ctx) => ({ ok: true, data: { events: ctx.container.audit.recent(Number(args.limit ?? 50)) } }),
+        }),
+        defineTool({
+            name: 'audit_export',
+            description: 'Return the path and contents of the JSONL audit log.',
+            group: 'security',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => ({
+                ok: true,
+                data: { path: ctx.container.audit.exportPath(), jsonl: ctx.container.audit.exportRaw() },
+            }),
+        }),
+        defineTool({
+            name: 'approval_status',
+            description: 'Check the status of an approval request, or list pending ones.',
+            group: 'security',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { id: { type: 'string' } } },
+            handler: async (args, ctx) => {
+                if (args.id) {
+                    const req = ctx.container.policy.approvals.get(String(args.id));
+                    return req ? { ok: true, data: req } : { ok: false, error: 'Approval not found.' };
+                }
+                return { ok: true, data: { pending: ctx.container.policy.approvals.pending() } };
+            },
+        }),
+        defineTool({
+            name: 'approval_request',
+            description: 'Create a manual approval request for a tool action.',
+            group: 'security',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: { tool: { type: 'string' }, reason: { type: 'string' } },
+                required: ['tool'],
+            },
+            handler: async (args, ctx) => {
+                const req = ctx.container.policy.approvals.create(String(args.tool), {}, 'HIGH', String(args.reason ?? 'manual'));
+                return { ok: true, data: req };
+            },
+        }),
+        defineTool({
+            name: 'policy_ratelimits',
+            description: 'Show per-tool rate-limit usage: configured window/quota and how many ' +
+                'calls have been used in the current window and rolling 24h.',
+            group: 'security',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => ({
+                ok: true,
+                data: {
+                    enabled: ctx.config.rateLimit.enabled,
+                    default: ctx.config.rateLimit.default,
+                    usage: ctx.container.rateLimiter.snapshot(),
+                },
+            }),
+        }),
+        defineTool({
+            name: 'secret_scan',
+            description: 'Scan a file or text for potential secrets.',
+            group: 'security',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: { path: { type: 'string' }, text: { type: 'string' } },
+            },
+            handler: async (args, ctx) => {
+                let text = String(args.text ?? '');
+                if (args.path) {
+                    const abs = ctx.container.policy.path.resolveSafe(String(args.path), ctx.projectRoot);
+                    text = readFileSync(abs, 'utf8');
+                }
+                return { ok: true, data: { findings: ctx.container.policy.secret.scan(text) } };
+            },
+        }),
+    ];
+}

package/dist/tools/terminal-tools.js

@@ -0,0 +1,57 @@
+import { execa } from 'execa';
+import { defineTool } from './registry.js';
+export function terminalTools() {
+    return [
+        defineTool({
+            name: 'shell_exec',
+            description: 'Run a single shell command in the workspace with timeout, blocklist, and output limits.',
+            group: 'terminal',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string' },
+                    cwd: { type: 'string' },
+                    timeoutMs: { type: 'number' },
+                },
+                required: ['command'],
+            },
+            handler: async (args, ctx) => {
+                const command = String(args.command);
+                const cls = ctx.container.policy.command.classify(command);
+                if (cls.risk === 'CRITICAL' && ctx.container.policy.getMode() !== 'danger') {
+                    return { ok: false, error: `Blocked destructive command: ${cls.blockedReason ?? command}` };
+                }
+                const cwd = args.cwd
+                    ? ctx.container.policy.path.resolveSafe(String(args.cwd), ctx.projectRoot)
+                    : ctx.projectRoot;
+                const timeout = Number(args.timeoutMs ?? ctx.config.terminal.defaultTimeoutMs);
+                const maxBytes = ctx.config.terminal.maxOutputBytes;
+                const started = Date.now();
+                try {
+                    const sub = await execa(ctx.config.terminal.shell, ['-lc', command], {
+                        cwd,
+                        timeout,
+                        reject: false,
+                        all: false,
+                        maxBuffer: maxBytes * 4,
+                    });
+                    const redact = (s) => ctx.container.policy.secret.redact((s ?? '').slice(0, maxBytes));
+                    return {
+                        ok: sub.exitCode === 0,
+                        data: {
+                            exitCode: sub.exitCode,
+                            stdout: redact(sub.stdout),
+                            stderr: redact(sub.stderr),
+                            durationMs: Date.now() - started,
+                            risk: cls.risk,
+                        },
+                    };
+                }
+                catch (err) {
+                    return { ok: false, error: `Execution failed: ${String(err)}` };
+                }
+            },
+        }),
+    ];
+}