@firenet-designs/fnd-cli 2.4.0 → 2.7.0

package/dist/lib/rpc.js

@@ -1,313 +0,0 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { createServer } from 'node:http';
-import { z } from 'zod';
-import { kvExample, kvUsage, parseKvFlag } from './kv-flag.js';
-import { parsePortPair } from './workspace.js';
-/**
- * The --rpc local-command server.
- *
- * Topology: this machine (the one that ran `fnd workspace`) runs a tiny MCP
- * server — Streamable HTTP transport, implemented on node:http with no
- * dependencies — bound to 127.0.0.1:<local>. The workspace's `ssh -R` reverse
- * tunnel exposes it on the REMOTE at 127.0.0.1:<remote>, where the `claude` CLI
- * registers it as an HTTP MCP server. When the AI on the remote calls the
- * `run_local_command` tool, the command executes HERE, on the calling machine,
- * under the shell chosen in the flag.
- *
- * The server binds loopback only; the sole way in from outside is the reverse
- * tunnel, which lives exactly as long as the ssh session.
- */
-const ShellSchema = z.enum(['bash', 'batch', 'powershell', 'sh', 'zsh']);
-export const RPC_SHELLS = ShellSchema.options;
-const RpcFlagSchema = z.object({
-    port: z
-        .string()
-        .transform((v) => parsePortPair(v, '--rpc'))
-        .meta({ example: '7777:7700', hint: 'port|remote:local' }),
-    profile: z
-        .stringbool({ falsy: ['false', '0'], truthy: ['true', '1'] })
-        .default(true)
-        .meta({ example: 'false', hint: 'true|1|false|0' }),
-    shell: z
-        .preprocess((v) => String(v).toLowerCase(), ShellSchema)
-        .optional()
-        .meta({ example: 'zsh' }),
-});
-/** Usage and example strings for the --rpc flag, derived from the schema. */
-export const RPC_FLAG_USAGE = kvUsage(RpcFlagSchema);
-export const RPC_FLAG_EXAMPLES = {
-    full: kvExample(RpcFlagSchema),
-    required: kvExample(RpcFlagSchema, { requiredOnly: true }),
-};
-export const RPC_TOOL_NAME = 'run_local_command';
-const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
-const MAX_TIMEOUT_MS = 30 * 60 * 1000;
-const MAX_OUTPUT_CHARS = 200_000;
-const MAX_BODY_BYTES = 4 * 1024 * 1024;
-/** Map a process name or path to a supported shell, if it is one. */
-const asRpcShell = (name) => {
-    if (!name)
-        return undefined;
-    // Basename, minus the login-shell dash ("-zsh") and Windows ".exe" suffix.
-    const base = name
-        .split(/[/\\]/)
-        .pop()
-        .toLowerCase()
-        .replace(/^-/, '')
-        .replace(/\.exe$/, '');
-    if (base === 'cmd')
-        return 'batch';
-    if (base === 'pwsh')
-        return 'powershell';
-    const parsed = ShellSchema.safeParse(base);
-    return parsed.success ? parsed.data : undefined;
-};
-/** Name of the process that spawned us, when discoverable. */
-const parentProcessName = () => {
-    const { ppid } = process;
-    if (!ppid)
-        return undefined;
-    const probe = process.platform === 'win32'
-        ? spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', `(Get-Process -Id ${ppid}).ProcessName`], { encoding: 'utf8', windowsHide: true })
-        : spawnSync('ps', ['-p', String(ppid), '-o', 'comm='], { encoding: 'utf8' });
-    if (probe.error || probe.status !== 0)
-        return undefined;
-    return probe.stdout.trim() || undefined;
-};
-/**
- * The shell `fnd workspace` was called from: the parent process when it is a
- * supported shell, else $SHELL, else undefined (e.g. invoked from a script).
- */
-export const detectCallingShell = () => asRpcShell(parentProcessName()) ?? asRpcShell(process.env.SHELL);
-/**
- * Parse the --rpc value: comma-separated key=value pairs per RpcFlagSchema.
- *   port=<port> | port=<remote>:<local> — required; `local` is this machine
- *     (where commands run), `remote` the port opened on the workspace host.
- *     The single-port form uses the same port on both ends.
- *   shell=<bash|batch|powershell|sh|zsh> — optional, defaults to the shell
- *     `fnd workspace` was called from.
- *   profile=<true|1|false|0> — optional, default true: the shell loads its
- *     startup files (rc/profile), so tools like nvm are available.
- */
-export const parseRpcFlag = (raw) => {
-    const parsed = parseKvFlag('--rpc', raw, RpcFlagSchema);
-    const shell = parsed.shell ?? detectCallingShell();
-    if (!shell) {
-        throw new Error(`--rpc could not detect the calling shell; pass shell=<${RPC_SHELLS.join('|')}> explicitly.`);
-    }
-    return { ports: parsed.port, profile: parsed.profile, shell };
-};
-/** How to invoke the chosen shell for a one-shot command string. */
-const shellInvocation = (shell, command, profile) => {
-    switch (shell) {
-        case 'batch': {
-            // /d skips the AutoRun registry commands — cmd's closest analog to a profile.
-            return { args: [...(profile ? [] : ['/d']), '/s', '/c', command], bin: 'cmd.exe' };
-        }
-        case 'powershell': {
-            return { args: [...(profile ? [] : ['-NoProfile']), '-NonInteractive', '-Command', command], bin: 'powershell' };
-        }
-        default: {
-            // -i: interactive, so rc files (~/.bashrc, ~/.zshrc) are sourced and tools
-            // that hook in there (nvm, rbenv, …) work without manual sourcing.
-            return { args: [...(profile ? ['-i'] : []), '-c', command], bin: shell };
-        }
-    }
-};
-/** True if the chosen shell is runnable on this machine. */
-export const hasLocalShell = (shell, profile) => {
-    const { args, bin } = shellInvocation(shell, 'exit 0', profile);
-    const result = spawnSync(bin, args, { stdio: 'ignore' });
-    return !result.error && result.status === 0;
-};
-/** Append a chunk to captured output unless the cap is already reached. */
-const appendCapped = (current, chunk) => current.length >= MAX_OUTPUT_CHARS ? current : current + chunk.toString();
-/**
- * Interactive bash/dash on a non-TTY stdin print job-control warnings on every
- * run; drop them so they don't clutter the stderr the model sees.
- */
-const stripInteractiveShellNoise = (stderr) => stderr
-    .replaceAll(/^bash: cannot set terminal process group \(-?\d+\):[^\n]*\n?/gm, '')
-    .replaceAll(/^bash: no job control in this shell\n?/gm, '')
-    .replaceAll(/^sh: \d+: can't access tty; job control turned off\n?/gm, '');
-/** Execute a command on this machine under the configured shell, capturing output. */
-const runLocalCommand = (config, command, cwd, timeoutMs) => new Promise((resolve) => {
-    const { args, bin } = shellInvocation(config.shell, command, config.profile);
-    const child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
-    let stdout = '';
-    let stderr = '';
-    let timedOut = false;
-    child.stdout.on('data', (chunk) => {
-        stdout = appendCapped(stdout, chunk);
-    });
-    child.stderr.on('data', (chunk) => {
-        stderr = appendCapped(stderr, chunk);
-    });
-    const timer = setTimeout(() => {
-        timedOut = true;
-        child.kill('SIGKILL');
-    }, timeoutMs);
-    child.once('error', (error) => {
-        clearTimeout(timer);
-        resolve({ exitCode: null, stderr: `Could not spawn ${bin}: ${error.message}`, stdout: '', timedOut: false });
-    });
-    child.once('close', (code) => {
-        clearTimeout(timer);
-        resolve({ exitCode: code, stderr: stripInteractiveShellNoise(stderr), stdout, timedOut });
-    });
-});
-/** Clip captured output at the cap, marking the truncation. */
-const clip = (value) => value.length >= MAX_OUTPUT_CHARS ? `${value.slice(0, MAX_OUTPUT_CHARS)}\n[output truncated]` : value;
-/** Render a command result as the text block returned to the model. */
-const formatResult = (result) => {
-    const status = result.timedOut ? 'killed (timed out)' : `exit code ${result.exitCode ?? 'unknown'}`;
-    return [
-        status,
-        '--- stdout ---',
-        clip(result.stdout) || '(empty)',
-        '--- stderr ---',
-        clip(result.stderr) || '(empty)',
-    ].join('\n');
-};
-/** True for the POSIX shells we run with -i (rc files sourced). */
-const isPosixShell = (shell) => shell !== 'batch' && shell !== 'powershell';
-/** The MCP tool definition advertised to the remote AI. */
-const toolDefinition = (config, cwd) => ({
-    description: `Run a shell command on the LOCAL machine — the computer that launched \`fnd workspace\`, NOT this remote box. ` +
-        `The command runs under ${config.shell}${config.profile && isPosixShell(config.shell) ? ' (interactive, so rc files and tools like nvm are already loaded)' : ''} ` +
-        `with working directory ${cwd}, and the result contains the exit code, stdout, and stderr.`,
-    inputSchema: {
-        properties: {
-            command: { description: `Command line to execute via ${config.shell} on the local machine.`, type: 'string' },
-            timeoutMs: {
-                description: `Optional timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}); the process is killed when it elapses.`,
-                type: 'number',
-            },
-        },
-        required: ['command'],
-        type: 'object',
-    },
-    name: RPC_TOOL_NAME,
-});
-const rpcError = (id, code, message) => ({
-    error: { code, message },
-    id,
-    jsonrpc: '2.0',
-});
-const rpcResult = (id, result) => ({ id, jsonrpc: '2.0', result });
-/**
- * Handle one JSON-RPC message. Returns the response object for requests, or
- * undefined for notifications (which get no response body).
- */
-const handleRpcMessage = async (msg, config, cwd) => {
-    const isRequest = msg.id !== undefined && msg.id !== null;
-    if (msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
-        return isRequest ? rpcError(msg.id, -32_600, 'Invalid request') : undefined;
-    }
-    if (!isRequest)
-        return undefined; // notifications (e.g. notifications/initialized) need no reply
-    const id = msg.id;
-    switch (msg.method) {
-        case 'initialize': {
-            const requested = msg.params?.protocolVersion;
-            return rpcResult(id, {
-                capabilities: { tools: {} },
-                protocolVersion: typeof requested === 'string' ? requested : '2025-03-26',
-                serverInfo: { name: 'fnd-local-shell', version: '1.0.0' },
-            });
-        }
-        case 'ping': {
-            return rpcResult(id, {});
-        }
-        case 'tools/call': {
-            const params = msg.params ?? {};
-            if (params.name !== RPC_TOOL_NAME) {
-                return rpcError(id, -32_602, `Unknown tool: ${String(params.name)}`);
-            }
-            const args = (params.arguments ?? {});
-            if (typeof args.command !== 'string' || args.command.length === 0) {
-                return rpcError(id, -32_602, 'The "command" argument must be a non-empty string');
-            }
-            const timeoutMs = typeof args.timeoutMs === 'number' && args.timeoutMs > 0
-                ? Math.min(args.timeoutMs, MAX_TIMEOUT_MS)
-                : DEFAULT_TIMEOUT_MS;
-            const result = await runLocalCommand(config, args.command, cwd, timeoutMs);
-            return rpcResult(id, {
-                content: [{ text: formatResult(result), type: 'text' }],
-                isError: result.timedOut || result.exitCode !== 0,
-            });
-        }
-        case 'tools/list': {
-            return rpcResult(id, { tools: [toolDefinition(config, cwd)] });
-        }
-        default: {
-            return rpcError(id, -32_601, `Method not found: ${msg.method}`);
-        }
-    }
-};
-/** Read a request body, rejecting when it exceeds the size cap. */
-const readBody = (req) => new Promise((resolve, reject) => {
-    let size = 0;
-    const chunks = [];
-    req.on('data', (chunk) => {
-        size += chunk.length;
-        if (size > MAX_BODY_BYTES) {
-            reject(new Error('request body too large'));
-            req.destroy();
-            return;
-        }
-        chunks.push(chunk);
-    });
-    req.once('end', () => resolve(Buffer.concat(chunks).toString()));
-    req.once('error', reject);
-});
-const handleHttpRequest = async (req, res, config, cwd) => {
-    // Streamable HTTP: clients POST JSON-RPC messages. We don't offer a
-    // server-initiated SSE stream, so GET (and anything else) gets 405.
-    if (req.method !== 'POST') {
-        res.writeHead(405, { allow: 'POST' }).end();
-        return;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(await readBody(req));
-    }
-    catch {
-        res
-            .writeHead(400, { 'content-type': 'application/json' })
-            .end(JSON.stringify(rpcError(null, -32_700, 'Parse error')));
-        return;
-    }
-    const messages = (Array.isArray(parsed) ? parsed : [parsed]);
-    const responses = (await Promise.all(messages.map((m) => handleRpcMessage(m, config, cwd)))).filter((r) => r !== undefined);
-    // A body of nothing but notifications gets 202 Accepted with no content.
-    if (responses.length === 0) {
-        res.writeHead(202).end();
-        return;
-    }
-    const payload = Array.isArray(parsed) ? responses : responses[0];
-    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(payload));
-};
-/**
- * Start the local RPC (MCP) server on 127.0.0.1:<ports.local>. Commands execute
- * with `cwd` as their working directory — the local side of the workspace sync.
- * Resolves once the port is bound; rejects if binding fails (e.g. port in use).
- */
-export const startRpcServer = (config, cwd) => new Promise((resolve, reject) => {
-    const server = createServer((req, res) => {
-        handleHttpRequest(req, res, config, cwd).catch(() => {
-            if (!res.headersSent)
-                res.writeHead(500);
-            res.end();
-        });
-    });
-    server.once('error', reject);
-    server.listen(config.ports.local, '127.0.0.1', () => {
-        resolve({
-            close: () => new Promise((done) => {
-                server.closeAllConnections();
-                server.close(() => done());
-            }),
-        });
-    });
-});