@firenet-designs/fnd-cli 2.3.2 → 2.4.0

package/dist/lib/rpc.js

@@ -0,0 +1,313 @@
+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());
+            }),
+        });
+    });
+});

package/dist/lib/workspace.d.ts

@@ -1,3 +1,4 @@
+import type { RpcConfig } from './rpc.js';
 /**
  * Mutagen-backed workspace helpers.
  *
@@ -30,12 +31,15 @@ export interface SshTarget {
     host: string;
     user: string;
 }
-export interface DevtoolsPorts {
-    /** Remote-debugging port of the browser on the caller's LOCAL machine. */
+/** A reverse-tunnel port pair: `ssh -R <remote>:localhost:<local>`. */
+export interface PortPair {
+    /** Port on the caller's LOCAL machine (the tunnel destination). */
     local: number;
-    /** Port opened on the REMOTE (via `ssh -R`) that tunnels back to the local browser. */
+    /** Port opened on the REMOTE (via `ssh -R`) that tunnels back to the local port. */
     remote: number;
 }
+/** For --devtools: `local` is the browser's remote-debugging port on the caller's machine. */
+export type DevtoolsPorts = PortPair;
 /**
  * Which side wins when the same path changed on both ends since the last sync.
  * `remote` = this server (the box where the workspace shell runs); `local` = the
@@ -47,6 +51,8 @@ export type SyncSource = 'local' | 'remote';
 export interface WorkspaceContext {
     /** Chrome DevTools MCP tunnel, when --devtools was passed; undefined otherwise. */
     devtools?: DevtoolsPorts;
+    /** Mutagen ignore patterns derived from the project's .gitignore files (--ignore-vcs); undefined syncs everything. */
+    ignores?: string[];
     /** Absolute path of the current dir on the LOCAL machine (one side of the sync). */
     localCwd: string;
     /** Basename of the local cwd — the leaf of the remote directory path. */
@@ -55,6 +61,8 @@ export interface WorkspaceContext {
     localUser: string;
     /** Where the mirror lives on the REMOTE, e.g. /home/fnd/<localUser>/<localDirName>. */
     remoteDir: string;
+    /** Local-command RPC server + tunnel, when --rpc was passed; undefined otherwise. */
+    rpc?: RpcConfig;
     /** Which endpoint wins conflicts (the Mutagen alpha in two-way-resolved); undefined flags conflicts instead. */
     source?: SyncSource;
     /** Unique Mutagen session name for this workspace. */
@@ -72,18 +80,48 @@ export declare const slugify: (value: string) => string;
 /** A unique Mutagen session name for a workspace on the given local directory. */
 export declare const buildSyncName: (dirName: string) => string;
 /**
- * Parse the --devtools value. Accepts `port` (same port on both ends) or
- * `remote:local`, where `local` is the caller's machine (where the browser runs)
- * and `remote` is the port opened on the workspace host.
+ * Parse a reverse-tunnel port value. Accepts `port` (same port on both ends) or
+ * `remote:local`, where `local` is the caller's machine and `remote` is the
+ * port opened on the workspace host. `flag` names the flag in error messages.
  */
-export declare const parseDevtoolsPort: (raw: string) => DevtoolsPorts;
+export declare const parsePortPair: (raw: string, flag: string) => PortPair;
 /** Build the immutable facts for a workspace session from the local environment + flags. */
 export declare const buildContext: (opts: {
     cwd: string;
     devtools?: DevtoolsPorts;
+    ignoreVcs?: boolean;
     remoteBase: string;
+    rpc?: RpcConfig;
     source?: SyncSource;
 }) => WorkspaceContext;
+/**
+ * Translate one .gitignore line into Mutagen ignore patterns. `base` is the
+ * directory holding the .gitignore, as a posix path relative to the sync root
+ * ('' for the root file). Mutagen's syntax already matches gitignore's for the
+ * pieces that pass through untouched (`*`, `**`, `?`, `[...]`, `!` negation,
+ * trailing `/` for directory-only) — what needs translating is scope:
+ *
+ * - A pattern with a slash is anchored to the .gitignore's own directory, so it
+ *   becomes an absolute pattern under `base` (`/dist` in src/.gitignore →
+ *   `/src/dist`).
+ * - A slashless pattern matches at any depth AT OR BELOW `base`. At the root
+ *   that is exactly Mutagen's unanchored behavior, so it passes through as-is;
+ *   under a subdirectory it becomes `/base/p` plus `/base/**\/p` (both forms, so
+ *   the match doesn't depend on `**` matching zero segments).
+ *
+ * Returns [] for blanks and comments.
+ */
+export declare const translateGitignoreLine: (line: string, base: string) => string[];
+/**
+ * Walk the project and turn every .gitignore into Mutagen ignore patterns, each
+ * resolved relative to the directory of the .gitignore that declared it. Files
+ * are ordered root-first so deeper .gitignore patterns come later — Mutagen
+ * gives later patterns precedence, which mirrors git. `.git` and `node_modules`
+ * are never descended into (git does not consult .gitignore files inside
+ * ignored or metadata directories), and symlinked directories are skipped to
+ * avoid cycles.
+ */
+export declare const collectVcsIgnores: (rootDir: string) => string[];
 /** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
 export declare const shQuote: (value: string) => string;
 /**
@@ -92,15 +130,27 @@ export declare const shQuote: (value: string) => string;
  * optionally wires up the chrome-devtools MCP, and drops into a login shell.
  */
 export declare const buildRemoteScript: (ctx: WorkspaceContext) => string;
-/** Run the remote-side teardown (strip this project's chrome-devtools MCP) over a fresh ssh connection. */
-export declare const runRemoteCleanup: (target: string, remoteDir: string) => Promise<number>;
+/** Options controlling what the remote-side teardown does. */
+export interface RemoteCleanupOptions {
+    /** Delete the workspace dir after cleanup; by default the synced copy is left in place. */
+    deleteRemoteDir?: boolean;
+    /** Strip this project's chrome-devtools MCP entry — only when the workspace registered one (--devtools). */
+    removeDevtoolsMcp?: boolean;
+    /** Strip this project's local-shell MCP entry — only when the workspace registered one (--rpc). */
+    removeRpcMcp?: boolean;
+}
+/** Run the remote-side teardown over a fresh ssh connection. */
+export declare const runRemoteCleanup: (target: string, remoteDir: string, opts?: RemoteCleanupOptions) => Promise<number>;
 /**
- * The remote-side teardown script: strip this project's chrome-devtools MCP via
- * the `claude` CLI. Runs from inside the workspace dir so local scope resolves to
- * the right project. A no-op if there is nothing to undo. The synced files
- * themselves are left in place — they are a real copy, not a mount.
+ * The remote-side teardown script. Runs from inside the workspace dir so the
+ * `claude` CLI's local scope resolves to the right project. The chrome-devtools
+ * and local-shell MCP entries are stripped only when their flags are set — i.e.
+ * when the workspace registered them via --devtools / --rpc; without them we
+ * never touch the user's MCP config. The synced files themselves are left in
+ * place — they are a real copy, not a mount — unless `deleteRemoteDir` is set,
+ * in which case the workspace dir is removed after any MCP config is stripped.
  */
-export declare const buildCleanupScript: (remoteDir: string) => string;
+export declare const buildCleanupScript: (remoteDir: string, opts?: RemoteCleanupOptions) => string;
 /** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
 export declare const hasSshClient: () => boolean;
 /** True if the Mutagen CLI is on PATH and runnable. */
@@ -112,6 +162,8 @@ export declare const hasMutagen: () => boolean;
  * the mode switches to two-way-resolved (alpha always wins conflicts), so
  * `--source remote` puts the server first and `--source local` puts this
  * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ * `ctx.ignores` (from --ignore-vcs) excludes gitignored paths from the sync so
+ * each side keeps its own build artifacts and platform-specific binaries.
  */
 export declare const buildMutagenCreateArgs: (ctx: WorkspaceContext, target: string) => string[];
 /** Arguments for `mutagen sync flush <name>` — block until one full sync completes. */