@musashishao/folderforge 1.2.0

package/dist/tools/pkg-tools.js

@@ -0,0 +1,260 @@
+import { execa } from 'execa';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineTool } from './registry.js';
+import { detectProject } from '../workspace/project-detector.js';
+import { parseErrors } from './error-parser.js';
+/** Detect the package manager for a project root (lockfile-first). */
+export function detectPackageManager(root) {
+    if (existsSync(join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(join(root, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(root, 'package-lock.json')))
+        return 'npm';
+    if (existsSync(join(root, 'package.json')))
+        return 'npm';
+    if (existsSync(join(root, 'Cargo.toml')))
+        return 'cargo';
+    if (existsSync(join(root, 'go.mod')))
+        return 'go';
+    if (existsSync(join(root, 'pyproject.toml')) || existsSync(join(root, 'requirements.txt')))
+        return 'pip';
+    return null;
+}
+/** Map a package manager to its CLI verbs. `null` = unsupported for that op. */
+function commandsFor(pm) {
+    switch (pm) {
+        case 'npm':
+            return {
+                list: ['npm', 'ls', '--depth=0'],
+                outdated: ['npm', 'outdated', '--json'],
+                audit: ['npm', 'audit', '--json'],
+                add: (p, dev) => ['npm', 'install', dev ? '--save-dev' : '--save', p],
+                remove: (p) => ['npm', 'uninstall', p],
+                run: (s) => ['npm', 'run', s],
+            };
+        case 'pnpm':
+            return {
+                list: ['pnpm', 'list', '--depth=0'],
+                outdated: ['pnpm', 'outdated', '--format', 'json'],
+                audit: ['pnpm', 'audit', '--json'],
+                add: (p, dev) => ['pnpm', 'add', ...(dev ? ['-D'] : []), p],
+                remove: (p) => ['pnpm', 'remove', p],
+                run: (s) => ['pnpm', 'run', s],
+            };
+        case 'yarn':
+            return {
+                list: ['yarn', 'list', '--depth=0'],
+                outdated: ['yarn', 'outdated', '--json'],
+                audit: ['yarn', 'audit', '--json'],
+                add: (p, dev) => ['yarn', 'add', ...(dev ? ['-D'] : []), p],
+                remove: (p) => ['yarn', 'remove', p],
+                run: (s) => ['yarn', 'run', s],
+            };
+        case 'pip':
+            return {
+                list: ['pip', 'list'],
+                outdated: ['pip', 'list', '--outdated'],
+                audit: ['pip-audit'], // optional tool; reports unavailable if missing
+                add: (p) => ['pip', 'install', p],
+                remove: (p) => ['pip', 'uninstall', '-y', p],
+                run: null,
+            };
+        case 'cargo':
+            return {
+                list: ['cargo', 'tree', '--depth', '1'],
+                outdated: ['cargo', 'outdated'],
+                audit: ['cargo', 'audit'],
+                add: (p, dev) => ['cargo', 'add', ...(dev ? ['--dev'] : []), p],
+                remove: (p) => ['cargo', 'remove', p],
+                run: null,
+            };
+        case 'go':
+            return {
+                list: ['go', 'list', '-m', 'all'],
+                outdated: ['go', 'list', '-m', '-u', 'all'],
+                audit: ['govulncheck', './...'],
+                add: (p) => ['go', 'get', p],
+                remove: (p) => ['go', 'get', `${p}@none`],
+                run: null,
+            };
+        default:
+            return null;
+    }
+}
+/** A package spec must look like a dependency name/version, not a shell payload. */
+function validatePkgSpec(spec) {
+    // Allow scoped names, versions, extras, and git/url-free specs.
+    // Reject shell metacharacters to prevent argument-injection via the spec.
+    if (!spec || spec.length > 214)
+        return 'Package spec is empty or too long.';
+    if (/[;&|`$(){}<>\n\r\\]/.test(spec))
+        return 'Package spec contains illegal characters.';
+    if (/^\s|\s$/.test(spec))
+        return 'Package spec has leading/trailing whitespace.';
+    return null;
+}
+async function runPm(ctx, argv) {
+    const [bin, ...rest] = argv;
+    const sub = await execa(bin, rest, {
+        cwd: ctx.projectRoot,
+        timeout: ctx.config.terminal.defaultTimeoutMs,
+        reject: false,
+        maxBuffer: ctx.config.terminal.maxOutputBytes * 4,
+    });
+    if (sub.exitCode === undefined && sub.failed && /ENOENT/.test(String(sub.shortMessage ?? ''))) {
+        return { ok: false, error: `Command not found: ${bin}. Install it or pick another package manager.` };
+    }
+    const max = ctx.config.terminal.maxOutputBytes;
+    const redact = ctx.container.policy.secret.redact;
+    const stdout = redact((sub.stdout ?? '').slice(0, max));
+    const stderr = redact((sub.stderr ?? '').slice(0, max));
+    return {
+        ok: sub.exitCode === 0,
+        data: { command: argv.join(' '), exitCode: sub.exitCode ?? null, stdout, stderr },
+    };
+}
+function withPm(build) {
+    return async (ctx) => {
+        const pm = detectPackageManager(ctx.projectRoot);
+        if (!pm) {
+            return { ok: false, error: 'No package manager detected (no package.json/pyproject/Cargo/go.mod).' };
+        }
+        const cmds = commandsFor(pm);
+        if (!cmds)
+            return { ok: false, error: `Unsupported package manager: ${pm}` };
+        const argv = build(cmds, pm);
+        if (!argv)
+            return { ok: false, error: `Operation not supported for ${pm}.` };
+        return { argv };
+    };
+}
+export function pkgTools() {
+    return [
+        defineTool({
+            name: 'pkg_list',
+            description: 'List installed top-level dependencies (auto-detects the package manager).',
+            group: 'pkg',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => {
+                const r = await withPm((c) => c.list)(ctx);
+                if ('ok' in r)
+                    return r;
+                return runPm(ctx, r.argv);
+            },
+        }),
+        defineTool({
+            name: 'pkg_outdated',
+            description: 'Report dependencies that have newer versions available.',
+            group: 'pkg',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => {
+                const r = await withPm((c) => c.outdated)(ctx);
+                if ('ok' in r)
+                    return r;
+                return runPm(ctx, r.argv);
+            },
+        }),
+        defineTool({
+            name: 'pkg_audit',
+            description: 'Scan dependencies for known vulnerabilities.',
+            group: 'pkg',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => {
+                const r = await withPm((c) => c.audit)(ctx);
+                if ('ok' in r)
+                    return r;
+                return runPm(ctx, r.argv);
+            },
+        }),
+        defineTool({
+            name: 'pkg_run',
+            description: 'Run a script defined in the project manifest (e.g. package.json scripts).',
+            group: 'pkg',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { script: { type: 'string', description: 'Script name as declared in the manifest.' } },
+                required: ['script'],
+            },
+            handler: async (args, ctx) => {
+                const script = String(args.script ?? '');
+                const bad = validatePkgSpec(script);
+                if (bad)
+                    return { ok: false, error: bad };
+                // Guard: only allow scripts that actually exist in package.json.
+                const proj = detectProject(ctx.projectRoot);
+                if (proj.packageManagers.some((p) => ['npm', 'pnpm', 'yarn'].includes(p))) {
+                    try {
+                        const pkg = JSON.parse(readFileSync(join(ctx.projectRoot, 'package.json'), 'utf8'));
+                        if (!pkg.scripts || !(script in pkg.scripts)) {
+                            return { ok: false, error: `Script "${script}" is not defined in package.json.` };
+                        }
+                    }
+                    catch {
+                        /* fall through to attempt run */
+                    }
+                }
+                const r = await withPm((c) => (c.run ? c.run(script) : null))(ctx);
+                if ('ok' in r)
+                    return r;
+                const res = await runPm(ctx, r.argv);
+                if (res.ok && res.data) {
+                    const d = res.data;
+                    res.data.errors = parseErrors(`${d.stdout ?? ''}\n${d.stderr ?? ''}`);
+                }
+                return res;
+            },
+        }),
+        defineTool({
+            name: 'pkg_add',
+            description: 'Add a dependency. HIGH risk; mutates the dependency tree (requires approval per policy).',
+            group: 'pkg',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    package: { type: 'string', description: 'Dependency spec, e.g. "lodash" or "lodash@4".' },
+                    dev: { type: 'boolean', description: 'Install as a dev dependency.' },
+                },
+                required: ['package'],
+            },
+            handler: async (args, ctx) => {
+                const spec = String(args.package ?? '');
+                const bad = validatePkgSpec(spec);
+                if (bad)
+                    return { ok: false, error: bad };
+                const dev = Boolean(args.dev);
+                const r = await withPm((c) => c.add(spec, dev))(ctx);
+                if ('ok' in r)
+                    return r;
+                return runPm(ctx, r.argv);
+            },
+        }),
+        defineTool({
+            name: 'pkg_remove',
+            description: 'Remove a dependency. HIGH risk; mutates the dependency tree (requires approval per policy).',
+            group: 'pkg',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { package: { type: 'string' } },
+                required: ['package'],
+            },
+            handler: async (args, ctx) => {
+                const spec = String(args.package ?? '');
+                const bad = validatePkgSpec(spec);
+                if (bad)
+                    return { ok: false, error: bad };
+                const r = await withPm((c) => c.remove(spec))(ctx);
+                if ('ok' in r)
+                    return r;
+                return runPm(ctx, r.argv);
+            },
+        }),
+    ];
+}

package/dist/tools/process-tools.js

@@ -0,0 +1,128 @@
+import { defineTool } from './registry.js';
+export function processTools() {
+    return [
+        defineTool({
+            name: 'process_start',
+            description: 'Start a long-running process (dev server, watcher) and return a session id.',
+            group: 'process',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { command: { type: 'string' }, cwd: { type: 'string' } },
+                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 session = ctx.container.processes.start(command, cwd, ctx.config.terminal.shell);
+                ctx.container.audit.record({ type: 'process_event', summary: `start ${session.sessionId}: ${command}` });
+                return { ok: true, data: session };
+            },
+        }),
+        defineTool({
+            name: 'process_read',
+            description: 'Read new output from a process session since the last cursor.',
+            group: 'process',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { sessionId: { type: 'string' } }, required: ['sessionId'] },
+            handler: async (args, ctx) => {
+                const out = ctx.container.processes.read(String(args.sessionId));
+                return { ok: true, data: { ...out, output: ctx.container.policy.secret.redact(out.output) } };
+            },
+        }),
+        defineTool({
+            name: 'process_tail',
+            description: 'Stream output from a process session: blocks until new output arrives, the ' +
+                'process exits, or timeoutMs elapses (default 2000ms). Call repeatedly to ' +
+                'follow a long-running command. `done` is true once the process has exited ' +
+                'and all output has been drained.',
+            group: 'process',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string' },
+                    timeoutMs: { type: 'number', description: 'Max ms to wait for new output (default 2000).' },
+                },
+                required: ['sessionId'],
+            },
+            handler: async (args, ctx) => {
+                const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 2000), 0), 30000);
+                const signal = ctx.control?.signal;
+                const out = await ctx.container.processes.readUntil(String(args.sessionId), timeoutMs, signal);
+                // P4 - progress: report a tick each tail cycle so a client following a
+                // long-running command sees liveness without parsing the buffer. The
+                // total is unknown for an open-ended stream, so we omit it and send a
+                // status message instead.
+                await ctx.control?.reportProgress?.(out.cursor, undefined, out.done ? 'process exited' : `streaming (${out.status})`);
+                if (signal?.aborted && !out.done) {
+                    return {
+                        ok: true,
+                        data: {
+                            ...out,
+                            output: ctx.container.policy.secret.redact(out.output),
+                            cancelled: true,
+                        },
+                    };
+                }
+                return { ok: true, data: { ...out, output: ctx.container.policy.secret.redact(out.output) } };
+            },
+        }),
+        defineTool({
+            name: 'process_write',
+            description: 'Send a line of input to a running process session.',
+            group: 'process',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { sessionId: { type: 'string' }, input: { type: 'string' } },
+                required: ['sessionId', 'input'],
+            },
+            handler: async (args, ctx) => {
+                ctx.container.processes.write(String(args.sessionId), String(args.input));
+                return { ok: true, data: { sent: true } };
+            },
+        }),
+        defineTool({
+            name: 'process_stop',
+            description: 'Stop a process session gracefully (SIGTERM).',
+            group: 'process',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { sessionId: { type: 'string' } }, required: ['sessionId'] },
+            handler: async (args, ctx) => {
+                const s = ctx.container.processes.stop(String(args.sessionId));
+                ctx.container.audit.record({ type: 'process_event', summary: `stop ${s.sessionId}` });
+                return { ok: true, data: s };
+            },
+        }),
+        defineTool({
+            name: 'process_kill',
+            description: 'Force-kill a process session (SIGKILL). HIGH risk; requires approval.',
+            group: 'process',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { sessionId: { type: 'string' } }, required: ['sessionId'] },
+            handler: async (args, ctx) => {
+                const id = String(args.sessionId);
+                if (!ctx.container.processes.isManaged(id)) {
+                    return { ok: false, error: 'Refusing to kill a process not started by FolderForge.' };
+                }
+                const s = ctx.container.processes.kill(id);
+                return { ok: true, data: s };
+            },
+        }),
+        defineTool({
+            name: 'process_list',
+            description: 'List process sessions managed by FolderForge.',
+            group: 'process',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_args, ctx) => ({ ok: true, data: { sessions: ctx.container.processes.list() } }),
+        }),
+    ];
+}

package/dist/tools/registry.js

@@ -0,0 +1,194 @@
+import { TOOL_RISK, RISK_ORDER } from '../policy/risk.js';
+import { ApprovalRequiredError, PolicyDeniedError } from '../core/errors.js';
+import { logger } from '../core/logger.js';
+/**
+ * Derive MCP tool annotations from the existing `mutates` / `risk` contract.
+ *
+ * This is intentionally a pure mapping so annotations stay in lock-step with
+ * the frozen schema and never need to be hand-maintained:
+ *   - `mutates === false`        => readOnlyHint: true
+ *   - risk HIGH or CRITICAL      => destructiveHint: true (mutating only)
+ *   - read-only tools            => idempotentHint: true
+ * `openWorldHint` is opt-in per tool (e.g. web/http/browser) since most tools
+ * act only on the local workspace; callers may pass an override.
+ */
+export function deriveAnnotations(name, mutates, risk, override) {
+    const destructive = mutates && RISK_ORDER[risk] >= RISK_ORDER.HIGH;
+    const annotations = {
+        title: titleCase(name),
+        readOnlyHint: !mutates,
+        destructiveHint: destructive,
+        idempotentHint: !mutates,
+        openWorldHint: false,
+        ...override,
+    };
+    return annotations;
+}
+function titleCase(name) {
+    return name
+        .split('_')
+        .map((p) => (p ? (p[0] ?? '').toUpperCase() + p.slice(1) : p))
+        .join(' ');
+}
+/**
+ * Helper to declare a tool with sensible defaults.
+ */
+export function defineTool(def) {
+    const risk = def.risk ?? TOOL_RISK[def.name] ?? 'MEDIUM';
+    return {
+        name: def.name,
+        description: def.description,
+        inputSchema: def.inputSchema,
+        ...(def.outputSchema !== undefined ? { outputSchema: def.outputSchema } : {}),
+        group: def.group,
+        mutates: def.mutates,
+        risk,
+        annotations: deriveAnnotations(def.name, def.mutates, risk, def.annotations),
+        handler: def.handler,
+    };
+}
+/**
+ * Central registry. Holds every tool, computes the curated active subset,
+ * and wraps each call with policy evaluation + audit.
+ */
+export class ToolRegistry {
+    container;
+    tools = new Map();
+    activeSet = null;
+    constructor(container) {
+        this.container = container;
+    }
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    registerAll(tools) {
+        for (const t of tools)
+            this.register(t);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** Restrict the visible tool set (routing). Pass null to show all. */
+    setActive(names) {
+        this.activeSet = names ? new Set(names) : null;
+    }
+    listActive() {
+        const all = [...this.tools.values()];
+        if (!this.activeSet)
+            return all;
+        return all.filter((t) => this.activeSet.has(t.name));
+    }
+    listAll() {
+        return [...this.tools.values()];
+    }
+    /** Execute a tool through the policy + audit pipeline. */
+    async call(name, rawArgs, control) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return { ok: false, error: `Unknown tool: ${name}` };
+        }
+        const args = rawArgs ?? {};
+        const started = Date.now();
+        // P6 - cancellation: if the client already cancelled before we start (or
+        // cancels during the synchronous policy/rate-limit checks below), refuse
+        // early instead of doing work the caller no longer wants.
+        if (control?.signal?.aborted) {
+            return { ok: false, error: 'Tool call cancelled before execution.' };
+        }
+        // Determine per-call risk (shell can be re-classified by the handler later,
+        // but we evaluate the base risk here too).
+        let risk = tool.risk;
+        if (name === 'shell_exec' && typeof args.command === 'string') {
+            const cls = this.container.policy.command.classify(args.command);
+            risk = cls.risk;
+        }
+        this.container.audit.record({
+            type: 'tool_call',
+            tool: name,
+            risk,
+            summary: summarizeArgs(name, args),
+        });
+        const decision = this.container.policy.evaluate(name, risk, tool.mutates, args);
+        if (decision.kind === 'deny') {
+            this.container.audit.record({ type: 'policy_deny', tool: name, risk, summary: decision.reason });
+            return { ok: false, error: `Denied: ${decision.reason}` };
+        }
+        if (decision.kind === 'approval') {
+            this.container.audit.record({
+                type: 'approval_request',
+                tool: name,
+                risk,
+                summary: decision.reason,
+                detail: { approvalId: decision.approvalId },
+            });
+            return {
+                ok: false,
+                approvalId: decision.approvalId,
+                error: `Approval required (${risk}). Resolve in the dashboard or via approval tools. id=${decision.approvalId}`,
+            };
+        }
+        // Rate limit / quota: applied only to calls that policy would actually
+        // run. Denied or approval-gated calls never consume quota.
+        const rl = this.container.rateLimiter.hit(name);
+        if (!rl.allowed) {
+            this.container.audit.record({
+                type: 'rate_limited',
+                tool: name,
+                risk,
+                summary: rl.reason ?? 'rate limited',
+                detail: { retryAfterMs: rl.retryAfterMs, windowCount: rl.windowCount, dailyCount: rl.dailyCount },
+            });
+            return {
+                ok: false,
+                error: `${rl.reason} Retry in ~${Math.ceil((rl.retryAfterMs ?? 0) / 1000)}s.`,
+            };
+        }
+        try {
+            const result = await tool.handler(args, {
+                config: this.container.config,
+                projectRoot: this.container.projectRoot(),
+                ...(control !== undefined ? { control } : {}),
+                container: this.container,
+            });
+            this.container.audit.record({
+                type: result.ok ? 'tool_result' : 'tool_error',
+                tool: name,
+                risk,
+                ok: result.ok,
+                durationMs: Date.now() - started,
+                summary: result.ok ? 'ok' : result.error ?? 'error',
+            });
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof ApprovalRequiredError
+                ? `Approval required: ${err.message} (id=${err.approvalId})`
+                : err instanceof PolicyDeniedError
+                    ? `Denied: ${err.message}`
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+            logger.error({ tool: name, err: message }, 'tool error');
+            this.container.audit.record({
+                type: 'tool_error',
+                tool: name,
+                risk,
+                ok: false,
+                durationMs: Date.now() - started,
+                summary: message,
+            });
+            return { ok: false, error: message };
+        }
+    }
+}
+function summarizeArgs(name, args) {
+    const keys = Object.keys(args);
+    if (keys.length === 0)
+        return name;
+    const parts = keys.slice(0, 4).map((k) => {
+        const v = args[k];
+        const s = typeof v === 'string' ? v.slice(0, 60) : JSON.stringify(v);
+        return `${k}=${s}`;
+    });
+    return parts.join(' ');
+}