@fnclaude/cli 1.1.0 → 2.0.0

package/src/mcp/dispatch.ts

@@ -0,0 +1,240 @@
+/**
+ * MCP subcommand dispatch. fnc's first arg of "mcp" routes to the embedded
+ * JSON-RPC subprocess (the one claude invokes via the injected
+ * --mcp-config; see docs/design.mcp.md §2).
+ *
+ * §2.7 contributed the routing wrapper. §7.5 (here) wires the entry point:
+ *   - Read $FNC_SOCKET from env; fatal exit 2 if absent.
+ *   - Build the four tool handlers, each of which dials the parent over
+ *     the AF_UNIX socket using §7.6's dialAndCall.
+ *   - Read line-delimited JSON-RPC requests from stdin until EOF, route
+ *     `tools/call` requests to the appropriate handler, and write JSON
+ *     responses to stdout. (Full JSON-RPC scaffolding — initialize,
+ *     tools/list, notifications — lands in §7.3.)
+ *
+ * Matches Go canonical's dispatch shape (src/main.go:879-887): mcp
+ * subcommand recognized ONLY at argv[0], '--noop' is the sole flag that
+ * affects server behavior, anything else is ignored.
+ */
+
+import { dialAndCall, type WireOp, type WireRequest, type WireResponse } from './wire.ts';
+
+const SUBCOMMAND = 'mcp';
+const NOOP_FLAG = '--noop';
+
+export function isMcpSubcommand(args: readonly string[]): boolean {
+  return args.length > 0 && args[0] === SUBCOMMAND;
+}
+
+export interface McpFlags {
+  noop: boolean;
+}
+
+export function parseMcpFlags(tail: readonly string[]): McpFlags {
+  return { noop: tail.includes(NOOP_FLAG) };
+}
+
+/**
+ * The four tool names exposed by the subprocess, per design.mcp.md §4.
+ * Order matches the spec table; consumers should not depend on order
+ * but `tools/list` rendering is deterministic if they do.
+ */
+export const MCP_TOOL_NAMES = [
+  'fnc_restart',
+  'fnc_switch_project',
+  'fnc_spawn_session',
+  'fnc_copy_to_clipboard',
+] as const;
+
+export type McpToolName = (typeof MCP_TOOL_NAMES)[number];
+
+/**
+ * Mapping from the MCP-visible tool name to the wire `op` value the
+ * parent dispatcher routes on. See design.mcp.md §4.
+ */
+const TOOL_TO_OP: Record<McpToolName, WireOp> = {
+  fnc_restart: 'restart',
+  fnc_switch_project: 'switch',
+  fnc_spawn_session: 'spawn',
+  fnc_copy_to_clipboard: 'copy_to_clipboard',
+};
+
+export interface McpTool {
+  name: McpToolName;
+  handler: (args: unknown) => Promise<WireResponse>;
+}
+
+export interface BuildToolsArgs {
+  socketPath: string;
+  /** Injectable for tests; defaults to the real {@link dialAndCall}. */
+  dialAndCall?: (a: {
+    socketPath: string;
+    request: WireRequest;
+  }) => Promise<WireResponse>;
+}
+
+/**
+ * Construct the four tool handlers. Each handler accepts an MCP tool-args
+ * payload (object literal from the model's `tools/call`), wraps it in a
+ * WireRequest with the matching `op`, and forwards through `dialAndCall`.
+ *
+ * §8 will add per-tool input validation in front of `dialAndCall`. This
+ * function ships the wiring shape; the validation hooks in beside the
+ * `op:` field assignment without changing the call-graph.
+ */
+export function buildTools(args: BuildToolsArgs): McpTool[] {
+  const dialer = args.dialAndCall ?? dialAndCall;
+  return MCP_TOOL_NAMES.map((name) => ({
+    name,
+    handler: async (payload: unknown): Promise<WireResponse> => {
+      const op = TOOL_TO_OP[name];
+      const request: WireRequest = { op };
+      if (payload !== null && payload !== undefined && typeof payload === 'object') {
+        for (const [k, v] of Object.entries(payload as Record<string, unknown>)) {
+          // Don't let a caller-supplied `op` field override our routing.
+          if (k === 'op') continue;
+          (request as Record<string, unknown>)[k] = v;
+        }
+      }
+      return dialer({ socketPath: args.socketPath, request });
+    },
+  }));
+}
+
+/**
+ * Entry point for `fnc mcp [--noop]`.
+ *
+ * Returns the process exit code. The launcher (main.ts) calls
+ * `process.exit(exitCode)` with the return value.
+ */
+export async function runMcpServer(_flags: McpFlags): Promise<number> {
+  const socketPath = process.env.FNC_SOCKET;
+  if (socketPath === undefined || socketPath === '') {
+    process.stderr.write(
+      'fnc mcp: FNC_SOCKET not set; subprocess must be invoked by fnclaude launcher.\n',
+    );
+    return 2;
+  }
+
+  const tools = buildTools({ socketPath });
+  const toolsByName = new Map(tools.map((t) => [t.name, t]));
+
+  await runStdinLoop({ toolsByName });
+  return 0;
+}
+
+interface StdinLoopArgs {
+  toolsByName: Map<string, McpTool>;
+}
+
+/**
+ * Placeholder JSON-RPC loop until §7.3 lands. Reads newline-delimited
+ * JSON from stdin; for each `tools/call` request, calls the matching
+ * handler and writes a minimal JSON-RPC 2.0 response. For everything
+ * else (including the eventual `initialize` / `tools/list`) writes a
+ * method-not-found error.
+ *
+ * The shape here is just enough to surface a real tool-call to the
+ * parent over the wire; §7.3 replaces this with the full scaffold.
+ */
+async function runStdinLoop(args: StdinLoopArgs): Promise<void> {
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+
+  // Read raw bytes from stdin; node:process exposes stdin as an async
+  // iterable of Uint8Array chunks.
+  for await (const chunk of process.stdin) {
+    buffer += decoder.decode(chunk as Uint8Array, { stream: true });
+    let nl: number;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line === '') continue;
+      await handleLine({ line, toolsByName: args.toolsByName });
+    }
+  }
+  // Flush whatever bytes remain after EOF.
+  const tail = buffer.trim();
+  if (tail !== '') {
+    await handleLine({ line: tail, toolsByName: args.toolsByName });
+  }
+}
+
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: number | string | null;
+  method?: string;
+  params?: unknown;
+}
+
+async function handleLine(args: {
+  line: string;
+  toolsByName: Map<string, McpTool>;
+}): Promise<void> {
+  let req: JsonRpcRequest;
+  try {
+    req = JSON.parse(args.line) as JsonRpcRequest;
+  } catch (err) {
+    writeRpcError(null, -32700, `parse error: ${(err as Error).message}`);
+    return;
+  }
+
+  // Notifications (no `id`) get no response, even on error.
+  const id = req.id ?? null;
+  const isNotification = req.id === undefined;
+
+  if (req.method === 'tools/call') {
+    const params = (req.params ?? {}) as { name?: string; arguments?: unknown };
+    const tool = params.name !== undefined ? args.toolsByName.get(params.name) : undefined;
+    if (tool === undefined) {
+      if (!isNotification) {
+        writeRpcError(id, -32601, `unknown tool: ${params.name ?? '<missing>'}`);
+      }
+      return;
+    }
+    try {
+      const result = await tool.handler(params.arguments);
+      if (!isNotification) writeRpcToolResult(id, result);
+    } catch (err) {
+      if (!isNotification) {
+        writeRpcError(id, -32000, `tool error: ${(err as Error).message}`);
+      }
+    }
+    return;
+  }
+
+  // Full method dispatch (initialize, tools/list, etc.) lands with §7.3.
+  if (!isNotification) {
+    writeRpcError(id, -32601, `method not implemented yet (§7.3): ${req.method ?? '<missing>'}`);
+  }
+}
+
+function writeRpcToolResult(
+  id: number | string | null,
+  result: WireResponse,
+): void {
+  // Per design.mcp.md §2.3: marshal the Response JSON as a single text
+  // content item. The model reads `action` / `message` / `command` /
+  // `clipboard_ok` out of the embedded JSON string.
+  const envelope = {
+    jsonrpc: '2.0',
+    id,
+    result: {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    },
+  };
+  process.stdout.write(JSON.stringify(envelope) + '\n');
+}
+
+function writeRpcError(
+  id: number | string | null,
+  code: number,
+  message: string,
+): void {
+  const envelope = {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  };
+  process.stdout.write(JSON.stringify(envelope) + '\n');
+}

package/src/mcp/handlers/clipboard-backends.ts

@@ -0,0 +1,176 @@
+/**
+ * §8.4 — Clipboard backend detection + invocation (pure module).
+ *
+ * Backend priority per design.md §25 + design.mcp.md §4.4:
+ *
+ *   1. `wl-copy`   (Wayland)
+ *   2. `xclip`     (X11 — preferred over xsel)
+ *   3. `xsel`      (X11 fallback)
+ *   4. `pbcopy`    (macOS)
+ *   5. `clip.exe`  (Windows / WSL — reachable on WSL via PATH)
+ *
+ * Detection here is by `which`-style PATH lookup, not by the GOOS+env
+ * gating the Go canonical uses. That's intentional for the rewrite: a
+ * Linux box without WAYLAND_DISPLAY but with `xclip` on PATH will still
+ * work; on WSL `clip.exe` is reachable from a "linux" runtime; on macOS
+ * only `pbcopy` is in PATH by default. The injected `which` keeps tests
+ * pure.
+ *
+ * Each backend takes the clipboard payload via stdin and writes nothing
+ * useful to stdout. Exit 0 = success. The handler never throws — spawn
+ * failures, exec failures, non-zero exits all flow back as `false` so
+ * the caller can report `clipboard_ok: false` without lighting up an
+ * error path the model doesn't expect.
+ */
+
+/** Locate an executable on PATH, returning its absolute path or null. */
+export type WhichFn = (name: string) => string | null;
+
+/**
+ * Minimal spawn surface we exercise from this module. The real
+ * implementation is a thin adapter over `Bun.spawn` (see {@link defaultSpawn}).
+ * Tests inject a fake to avoid touching real processes.
+ */
+export interface SpawnedProc {
+  stdin: {
+    write(chunk: string | Uint8Array): void;
+    end(): void;
+  };
+  exited: Promise<number>;
+  kill(): void;
+}
+
+export type SpawnFn = (
+  args: readonly string[],
+  opts: { stdin: 'pipe' },
+) => SpawnedProc;
+
+export interface Backend {
+  name: 'wl-copy' | 'xclip' | 'xsel' | 'pbcopy' | 'clip.exe';
+  command: string;
+}
+
+const PRIORITY: ReadonlyArray<Backend['name']> = [
+  'wl-copy',
+  'xclip',
+  'xsel',
+  'pbcopy',
+  'clip.exe',
+];
+
+/**
+ * Walk the priority list and return the first backend whose executable
+ * `which` finds. Returns null if nothing is installed.
+ */
+export function detectBackend(args: { which: WhichFn }): Backend | null {
+  for (const name of PRIORITY) {
+    const command = args.which(name);
+    if (command !== null && command !== '') {
+      return { name, command };
+    }
+  }
+  return null;
+}
+
+function backendArgs(name: Backend['name']): readonly string[] {
+  // Selection flags matter for X11 — without `-selection clipboard` xclip
+  // writes to the PRIMARY selection (middle-click paste), not the
+  // clipboard the user reaches via Ctrl-V. Same shape for xsel's `-ib`.
+  switch (name) {
+    case 'xclip':
+      return ['-selection', 'clipboard'];
+    case 'xsel':
+      return ['-ib'];
+    case 'wl-copy':
+    case 'pbcopy':
+    case 'clip.exe':
+      return [];
+  }
+}
+
+export interface RunBackendArgs {
+  backend: Backend;
+  text: string;
+  spawn: SpawnFn;
+}
+
+/**
+ * Invoke the chosen backend, piping `text` to its stdin. Returns true on
+ * clean exit (code 0), false on any failure: spawn throwing, stdin write
+ * throwing, non-zero exit, or the exited promise rejecting.
+ *
+ * Crucially, this function never throws. The caller relies on the
+ * boolean return to populate `clipboard_ok`.
+ */
+export async function runBackend(args: RunBackendArgs): Promise<boolean> {
+  const argv = [args.backend.command, ...backendArgs(args.backend.name)];
+  let proc: SpawnedProc;
+  try {
+    proc = args.spawn(argv, { stdin: 'pipe' });
+  } catch {
+    return false;
+  }
+
+  try {
+    proc.stdin.write(args.text);
+    proc.stdin.end();
+  } catch {
+    // stdin closed early or the process died before we could write.
+    // Make sure the spawned process isn't lingering, then report
+    // failure. Some backends (xclip on Wayland-only boxes, for one)
+    // exit immediately on EPIPE and we shouldn't wait on exited
+    // forever; the kill is best-effort.
+    try {
+      proc.kill();
+    } catch {
+      // ignore
+    }
+    return false;
+  }
+
+  let exitCode: number;
+  try {
+    exitCode = await proc.exited;
+  } catch {
+    return false;
+  }
+  return exitCode === 0;
+}
+
+/**
+ * Production `which`: thin wrapper around Bun.which. Returns null when
+ * the name isn't on PATH; both `null` and `undefined` from Bun.which are
+ * treated as "not found".
+ */
+export const defaultWhich: WhichFn = (name) => {
+  const r = Bun.which(name);
+  return r === null || r === undefined ? null : r;
+};
+
+/**
+ * Production `spawn`: adapter that yields the minimal SpawnedProc shape
+ * over Bun.spawn. We pipe stdin (for the text payload), ignore stdout
+ * (no useful output from these backends), and inherit stderr so a real
+ * misconfiguration surfaces in the parent's terminal during development.
+ */
+export const defaultSpawn: SpawnFn = (args, _opts) => {
+  const proc = Bun.spawn([...args], {
+    stdin: 'pipe',
+    stdout: 'ignore',
+    stderr: 'inherit',
+  });
+  return {
+    stdin: {
+      write(chunk: string | Uint8Array) {
+        proc.stdin.write(chunk);
+      },
+      end() {
+        proc.stdin.end();
+      },
+    },
+    exited: proc.exited,
+    kill() {
+      proc.kill();
+    },
+  };
+};

package/src/mcp/handlers/clipboard.ts

@@ -0,0 +1,62 @@
+/**
+ * §8.4 — `fnc_copy_to_clipboard` handler.
+ *
+ * Spec (design.mcp.md §4.4):
+ *   - Required arg: `text: string`
+ *   - Returns `{ action: 'done', clipboard_ok: boolean }`
+ *   - NEVER errors — clipboard absence flows through the boolean flag,
+ *     not an error response. Same shape on every failure mode: no
+ *     backend on PATH, backend exits non-zero, spawn throws, text arg
+ *     is missing or wrong type.
+ *
+ * Wave 1 (this PR) ships the pure module only. §7.7's parent
+ * dispatcher will route `op: 'copy_to_clipboard'` to this handler in
+ * Wave 2.
+ */
+
+import type { WireRequest, WireResponse } from '../wire.ts';
+import {
+  defaultSpawn,
+  defaultWhich,
+  detectBackend,
+  runBackend,
+  type SpawnFn,
+  type WhichFn,
+} from './clipboard-backends.ts';
+
+export interface HandleCopyToClipboardDeps {
+  which?: WhichFn;
+  spawn?: SpawnFn;
+}
+
+/**
+ * Process a `copy_to_clipboard` request. Always resolves to a `done`
+ * response; the `clipboard_ok` flag carries the actual outcome.
+ *
+ * Deps are injected for tests; production callers omit them and get the
+ * Bun.which / Bun.spawn defaults.
+ */
+export async function handleCopyToClipboard(
+  req: WireRequest,
+  deps: HandleCopyToClipboardDeps = {},
+): Promise<WireResponse> {
+  const which = deps.which ?? defaultWhich;
+  const spawn = deps.spawn ?? defaultSpawn;
+
+  const text = req.text;
+  if (typeof text !== 'string') {
+    return done(false);
+  }
+
+  const backend = detectBackend({ which });
+  if (backend === null) {
+    return done(false);
+  }
+
+  const ok = await runBackend({ backend, text, spawn });
+  return done(ok);
+}
+
+function done(clipboardOk: boolean): WireResponse {
+  return { action: 'done', clipboard_ok: clipboardOk };
+}

package/src/mcp/handlers/restart.ts

@@ -0,0 +1,156 @@
+/**
+ * §8.1 — `fnc_restart` handler.
+ *
+ * Ports the Go canonical `handleRestart` from
+ * `fnclaude@fnrhombus/src/socket_listener.go` lines 221-256. The
+ * restart flow rebuilds the launch argv with the same magic prefix the
+ * user originally typed, swaps in `--resume <session_id>` immediately
+ * after the cwd positional, applies MCP-supplied overrides, then stashes
+ * the result + fires the handoff trigger so §8.5's awaiter can SIGTERM
+ * claude and re-exec fnc with the new argv.
+ *
+ * Algorithm (matches Go canonical):
+ *   1. Validate session_id present + UUID 8-4-4-4-12 hex.
+ *   2. `preserveArgs(origArgs, ∅, ∅)` — restart uses NO denylist.
+ *   3. `applyOverrides(preserved, req)` — splices in MCP overrides.
+ *   4. If no caller-supplied permission_mode AND no preserved
+ *      `--permission-mode`, ask the injected `livePermissionModeReader`
+ *      for the value claude wrote into the session JSONL. The reader is
+ *      optional; production wiring stubs it out for now (TODO file IO).
+ *   5. Split the leading magic-word run; rebuild argv as:
+ *        `[...magic, launchCWD, '--resume', sid, ...rest]`
+ *   6. `trigger.stashArgv(argv)` (first-stash-wins).
+ *   7. `trigger.fire()` to wake §8.5's awaiter.
+ *   8. Respond `{ action: 'done' }`.
+ *
+ * Design: docs/design.mcp.md §4.1, §5; docs/design.md §12-13.
+ */
+
+import {
+  applyOverrides,
+  preserveArgs,
+  splitLeadingMagic,
+  type OverrideRequest,
+} from '../../argv/preserve-args.ts';
+import type { HandoffTrigger } from '../../handoff/trigger.ts';
+import type { ParentDispatchHandler } from '../parent-dispatch.ts';
+import type { WireRequest, WireResponse } from '../wire.ts';
+
+const SESSION_ID_RE =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+const EMPTY_DENY: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Reader for the live permission-mode value claude persists in the
+ * session JSONL (`~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`).
+ * `launchCWD` is bound at construction time in main.ts, so the reader
+ * only takes the per-call `sessionID`. Returns `null` when no value is
+ * available (file missing, no matching record, etc.) — the auto-capture
+ * append is skipped in that case. Same shape as switch.ts uses, so a
+ * single closure can be wired into both handlers.
+ */
+export type LivePermissionModeReader = (sessionID: string) => string | null;
+
+export interface CreateRestartHandlerArgs {
+  /** The user's original argv as fnc saw it at startup (post-readArgv). */
+  origArgs: readonly string[];
+  /** The directory fnc launched claude into — emitted as the first positional. */
+  launchCWD: string;
+  /** Shared handoff trigger; first-stash-wins for argv. */
+  trigger: HandoffTrigger;
+  /** Optional injected reader. Omit to disable live-capture entirely. */
+  livePermissionModeReader?: LivePermissionModeReader;
+}
+
+/**
+ * Build the restart handler with all collaborators bound. Returned
+ * function plugs straight into `createParentDispatcher({ handlers: { restart, ... } })`.
+ */
+export function createRestartHandler(args: CreateRestartHandlerArgs): ParentDispatchHandler {
+  const { origArgs, launchCWD, trigger, livePermissionModeReader } = args;
+
+  return async (req: WireRequest): Promise<WireResponse> => {
+    const sessionID = req.session_id;
+    if (typeof sessionID !== 'string' || sessionID === '') {
+      return {
+        action: 'error',
+        error:
+          'restart requires a session id; pass it as the fnc_restart session_id argument (read $CLAUDE_CODE_SESSION_ID via Bash).',
+      };
+    }
+    if (!SESSION_ID_RE.test(sessionID)) {
+      return {
+        action: 'error',
+        error: `session_id ${JSON.stringify(sessionID)} is not a valid UUID; expected the 8-4-4-4-12 hex form.`,
+      };
+    }
+
+    // Preserve user flags (no denylist for restart — everything carries).
+    const preserved = preserveArgs(origArgs, EMPTY_DENY, EMPTY_DENY);
+
+    // Apply MCP-supplied overrides. Wire snake_case → OverrideRequest camelCase.
+    const overrides = wireToOverrideRequest(req);
+    let withOverrides = applyOverrides(preserved, overrides);
+
+    // Auto-capture live permission-mode when no override was passed AND
+    // no preserved flag carries one. Mirrors Go canonical — runs only
+    // when an injected reader is available.
+    const permissionModeFromReq = req.permission_mode;
+    const callerSuppliedPermissionMode =
+      typeof permissionModeFromReq === 'string' && permissionModeFromReq !== '';
+    if (
+      !callerSuppliedPermissionMode &&
+      !flagPresent(withOverrides, '--permission-mode') &&
+      livePermissionModeReader !== undefined
+    ) {
+      const live = livePermissionModeReader(sessionID);
+      if (live !== null && live !== '') {
+        withOverrides = [...withOverrides, '--permission-mode', live];
+      }
+    }
+
+    const { magic, rest } = splitLeadingMagic(withOverrides);
+    const argv: string[] = [...magic, launchCWD, '--resume', sessionID, ...rest];
+
+    trigger.stashArgv(argv);
+    trigger.fire();
+    return { action: 'done' };
+  };
+}
+
+/**
+ * Translate the wire request's snake_case override fields into the
+ * `OverrideRequest` shape `applyOverrides` consumes. Fields not present
+ * (or of the wrong type) are silently omitted — the caller's MCP layer
+ * validates shapes; defensive typing here just keeps applyOverrides safe.
+ */
+function wireToOverrideRequest(req: WireRequest): OverrideRequest {
+  const out: OverrideRequest = {};
+  if (typeof req.model === 'string' && req.model !== '') out.model = req.model;
+  if (typeof req.effort === 'string' && req.effort !== '') out.effort = req.effort;
+  if (typeof req.permission_mode === 'string' && req.permission_mode !== '') {
+    out.permissionMode = req.permission_mode;
+  }
+  if (typeof req.allowed_tools === 'string' && req.allowed_tools !== '') {
+    out.allowedTools = req.allowed_tools;
+  }
+  if (typeof req.agent === 'string' && req.agent !== '') out.agent = req.agent;
+  if (typeof req.brief === 'boolean') out.brief = req.brief;
+  if (typeof req.chrome === 'boolean') out.chrome = req.chrome;
+  if (typeof req.ide === 'boolean') out.ide = req.ide;
+  if (typeof req.verbose === 'boolean') out.verbose = req.verbose;
+  return out;
+}
+
+/**
+ * Returns true when `args` contains `flag` as a standalone token or in
+ * `--flag=value` form. Mirrors Go canonical's `flagPresent`.
+ */
+function flagPresent(args: readonly string[], flag: string): boolean {
+  const eqPrefix = `${flag}=`;
+  for (const tok of args) {
+    if (tok === flag || tok.startsWith(eqPrefix)) return true;
+  }
+  return false;
+}