@fnclaude/cli 1.1.0 → 2.0.0

package/src/mcp/handlers/spawn.ts

@@ -0,0 +1,219 @@
+/**
+ * §8.3 — `fnc_spawn_session` handler.
+ *
+ * Spec (design.mcp.md §4.3 + spawn.go + socket_listener.go.handleSpawn):
+ *
+ *   - Required args: `destination`, `name`, `summary`. **No `session_id`** —
+ *     spawn starts fresh, with no preservation of flags or session state.
+ *   - Optional args: override fields (model / effort / permission_mode /
+ *     allowed_tools / agent / brief / chrome / ide / verbose).
+ *
+ * Algorithm:
+ *
+ *   1. Validate required args. Missing/empty → ActionError.
+ *   2. Write `summary` to a unique 0600 file under XDG_RUNTIME_DIR.
+ *   3. Build override args from `applyOverrides([], req)`. No preservation
+ *      → only override-derived flag tokens appear. Result feeds the spawn
+ *      template's surrounding context AND the paste-flow command string.
+ *   4. Build the cleaned env (`cleanEnvForSpawn` strips FNC_SOCKET,
+ *      FNCLAUDE_HANDOFF, CLAUDE_CODE_SESSION_ID).
+ *   5. Decide launcher: `auto.spawnCommand` → `$TMUX` → paste-flow.
+ *   6. On launcher success → ActionDone. On no-launcher → ActionPasteFlow
+ *      + clipboard write of the rendered relaunch command.
+ *
+ * Unlike §8.1 (restart) and §8.2 (switch), spawn NEVER stashes argv or
+ * fires the handoff trigger — the current session keeps running. The
+ * spawned sibling is its own independent fnclaude (own socket, own MCP
+ * env, own claude). design.mcp.md §4.3.
+ *
+ * Wire-protocol contract: returns a `WireResponse`. The handler never
+ * throws — internal failures (launcher errors, file-write errors,
+ * missing args) flow back as `{ action: 'error', error }`.
+ *
+ * Dependencies are injected via `createSpawnHandler` so tests can
+ * exercise the algorithm without touching real launchers, real
+ * clipboards, or real summary files. Production wiring in main.ts
+ * spreads the deps from the parent's runtime context.
+ */
+
+import {
+  applyOverrides,
+  type OverrideRequest,
+} from '../../argv/preserve-args.ts';
+import { cleanEnvForSpawn } from '../../handoff/clean-env.ts';
+import {
+  chooseAndSpawn,
+  defaultSpawn,
+  renderSpawnCommand,
+  type SpawnFn,
+} from '../../handoff/spawn-launcher.ts';
+import { writeSummaryFile } from '../../handoff/summary-file.ts';
+import type { ParentDispatchHandler } from '../parent-dispatch.ts';
+import type { WireRequest, WireResponse } from '../wire.ts';
+
+export interface SpawnHandlerConfig {
+  /** `cfg.auto.spawnCommand` — undefined or empty = "not configured". */
+  autoSpawnCommand?: string | undefined;
+}
+
+export interface SpawnHandlerDeps {
+  config: SpawnHandlerConfig;
+  /** Env source (test seam). Production passes `process.env`. */
+  processEnv: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  /** Absolute fnclaude bin path for `{bin}` substitution. */
+  fncBinPath: string;
+  /**
+   * Override the launcher spawner (test seam). Production omits this and
+   * gets `defaultSpawn` (a thin `Bun.spawn` adapter).
+   */
+  spawnLauncher?: SpawnFn;
+  /**
+   * Handler used for paste-flow fallback to put the rendered relaunch
+   * command on the clipboard. Same signature as §8.4's `handleCopyToClipboard`.
+   * Production wires §8.4's handler here; tests inject a stub.
+   */
+  handleCopyToClipboard?: (req: WireRequest) => Promise<WireResponse>;
+  /**
+   * Override the summary-file writer (test seam). Production omits this
+   * and gets the real `writeSummaryFile`.
+   */
+  writeSummaryFile?: (args: { content: string }) => Promise<string>;
+}
+
+/**
+ * Build the spawn dispatch handler with injected deps. Returns a
+ * `ParentDispatchHandler` (the shape `createParentDispatcher` expects).
+ */
+export function createSpawnHandler(deps: SpawnHandlerDeps): ParentDispatchHandler {
+  const spawnFn = deps.spawnLauncher ?? defaultSpawn;
+  const copyHandler = deps.handleCopyToClipboard;
+  const writeSummary =
+    deps.writeSummaryFile ?? ((args: { content: string }) => writeSummaryFile({ content: args.content }));
+
+  return async (req: WireRequest): Promise<WireResponse> => {
+    // 1. Validate required args.
+    const dest = typeof req.destination === 'string' ? req.destination : '';
+    const name = typeof req.name === 'string' ? req.name : '';
+    const summary = typeof req.summary === 'string' ? req.summary : '';
+
+    if (dest === '') {
+      return errorResponse('spawn requires a destination');
+    }
+    if (name === '') {
+      return errorResponse('spawn requires a name');
+    }
+    if (summary === '') {
+      return errorResponse('spawn requires a summary');
+    }
+
+    // 2. Persist the summary to disk.
+    let summaryPath: string;
+    try {
+      summaryPath = await writeSummary({ content: summary });
+    } catch (err) {
+      return errorResponse(`write summary: ${(err as Error).message}`);
+    }
+
+    // 3. Build the override flag tokens. No preservation — spawn is a
+    // fresh start, so the input slice is empty and `applyOverrides`
+    // emits ONLY override-derived flags.
+    const extraArgs = applyOverrides([], extractOverrides(req));
+
+    // 4. Build the cleaned spawn env.
+    const spawnEnv = cleanEnvForSpawn(deps.processEnv);
+
+    // 5. Pick launcher and dispatch.
+    let result: ReturnType<typeof chooseAndSpawn>;
+    try {
+      result = chooseAndSpawn({
+        autoSpawnCommand: deps.config.autoSpawnCommand ?? '',
+        env: deps.processEnv,
+        spawnEnv,
+        fncBin: deps.fncBinPath,
+        dest,
+        name,
+        summary: summaryPath,
+        extraArgs,
+        spawn: spawnFn,
+      });
+    } catch (err) {
+      return errorResponse(`spawn: ${(err as Error).message}`);
+    }
+
+    if (result.ok) {
+      return {
+        action: 'done',
+        message: `Spawned sibling fnclaude for ${dest} in a new window.`,
+      };
+    }
+
+    // 6. No launcher resolved — paste-flow fallback. Surface the
+    // auto.spawnCommand config knob so users in unrecognized terminals
+    // discover the customization point without reading source.
+    const command = renderSpawnCommand({
+      dest,
+      name,
+      summary: summaryPath,
+      extraArgs,
+    });
+    const clipboardOk = await tryCopyToClipboard(copyHandler, command);
+    const message = clipboardOk
+      ? 'No spawn launcher configured for this terminal — the relaunch command is on your clipboard; paste it into a new terminal window. Set `auto.spawnCommand` in ~/.config/fnclaude/config.toml to enable auto-spawn (use {bin}, {dest}, {name}, {summary} placeholders).'
+      : 'No spawn launcher configured for this terminal — copy this command and run it in a new terminal window. Set `auto.spawnCommand` in ~/.config/fnclaude/config.toml to enable auto-spawn (use {bin}, {dest}, {name}, {summary} placeholders):';
+
+    return {
+      action: 'paste_flow',
+      message,
+      command,
+      clipboard_ok: clipboardOk,
+    };
+  };
+}
+
+function errorResponse(error: string): WireResponse {
+  return { action: 'error', error };
+}
+
+/**
+ * Pull the override fields off the request envelope and shape them as
+ * an `OverrideRequest` for `applyOverrides`. Non-string / non-bool
+ * values are ignored — the wire is loose by design (§7.6) and any
+ * caller writing the wrong type per field gets the "preserve" branch.
+ */
+function extractOverrides(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;
+}
+
+/**
+ * Best-effort clipboard write for paste-flow Responses. Routes the
+ * command string through the injected §8.4 handler. Any failure
+ * (no handler injected, handler returns non-`done`, handler throws)
+ * collapses to `false` — the response still surfaces, claude just
+ * tells the user to copy manually.
+ */
+async function tryCopyToClipboard(
+  copyHandler: ((req: WireRequest) => Promise<WireResponse>) | undefined,
+  text: string,
+): Promise<boolean> {
+  if (copyHandler === undefined) return false;
+  try {
+    const r = await copyHandler({ op: 'copy_to_clipboard', text });
+    return r.clipboard_ok === true;
+  } catch {
+    return false;
+  }
+}

package/src/mcp/handlers/switch.ts

@@ -0,0 +1,272 @@
+/**
+ * §8.2 — `fnc_switch_project` handler.
+ *
+ * Spec (docs/design.mcp.md §4.2):
+ *   - Required args: `destination`, `name`, `summary`.
+ *   - Optional: override fields (`model`, `effort`, `permission_mode`,
+ *     `allowed_tools`, `agent`, `brief`, `chrome`, `ide`, `verbose`) and
+ *     `session_id` (for live permission-mode capture).
+ *
+ * Algorithm:
+ *   1. Validate the three required strings; missing one → `action: 'error'`.
+ *   2. Write `summary` to `<base>/fnclaude-handoff-content-<16hex>.md`
+ *      (mode 0600) via `writeSummaryFile`.
+ *   3. If `permission_mode === 'never'`: build the relaunch command,
+ *      copy it to the clipboard, return `action: 'paste_flow'`. The
+ *      current session keeps running.
+ *   4. Otherwise:
+ *      - `preserved = preserveArgs(origArgs, TRANSFER_DENY_FLAGS, TRANSFER_DENY_BARE_OK)`
+ *      - `withOverrides = applyOverrides(preserved, req)`
+ *      - If no permission_mode override AND no preserved permission-mode
+ *        AND `session_id` is present → live-capture from session JSONL
+ *        and append `--permission-mode <live>`.
+ *      - `{magic, rest} = splitLeadingMagic(withOverrides)`
+ *      - argv = `[...magic, destination, ...rest, '--name', name, '@' + summaryPath]`
+ *      - `trigger.stashArgv(argv)` + `trigger.fire()`.
+ *      - Return `action: 'done'`.
+ *
+ * Side effects (clipboard exec, file write, trigger fire) all flow
+ * through injected dependencies so unit tests stay hermetic. Production
+ * callers in main.ts wire the real `handoffTrigger` singleton and the
+ * real clipboard / summary-file modules.
+ */
+
+import {
+  applyOverrides,
+  preserveArgs,
+  splitLeadingMagic,
+  TRANSFER_DENY_BARE_OK,
+  TRANSFER_DENY_FLAGS,
+  type OverrideRequest,
+} from '../../argv/preserve-args.ts';
+import { writeSummaryFile, type BaseDirResolver } from '../../handoff/summary-file.ts';
+import type { HandoffTrigger } from '../../handoff/trigger.ts';
+import type { ParentDispatchHandler } from '../parent-dispatch.ts';
+import type { WireRequest, WireResponse } from '../wire.ts';
+import { handleCopyToClipboard } from './clipboard.ts';
+
+/**
+ * Read the most recent live permission-mode value from claude's
+ * per-session JSONL. Returns null when no record exists or the file
+ * isn't reachable. The default factory returns null (live capture is a
+ * Wave-2 §8.1/§8.2 add; the §8.2 commit ships the wiring, the JSONL
+ * reader lands separately).
+ */
+export type LivePermissionModeReader = (sessionId: string) => string | null;
+
+const NULL_LIVE_PERMISSION_READER: LivePermissionModeReader = () => null;
+
+/**
+ * Write-summary seam — defaults to {@link writeSummaryFile}. Tests pass
+ * a stub that records the call and returns a deterministic path.
+ */
+export type WriteSummaryFn = (args: {
+  summary: string;
+  baseDir?: BaseDirResolver;
+}) => Promise<{ path: string }>;
+
+/**
+ * Clipboard seam — defaults to {@link handleCopyToClipboard}. Same
+ * signature as the §8.4 handler so production wiring is a direct
+ * reference, no adapter needed.
+ */
+export type CopyToClipboardFn = (req: WireRequest) => Promise<WireResponse>;
+
+export interface CreateSwitchHandlerArgs {
+  /**
+   * The os.argv[1:] snapshot captured at fnclaude startup. Used to
+   * preserve user-supplied flags across the relaunch (minus the
+   * transfer denylist).
+   */
+  origArgs: readonly string[];
+  /** Shared handoff trigger — receives `stashArgv` + `fire` on success. */
+  trigger: HandoffTrigger;
+  /**
+   * Optional live permission-mode reader (defaults to a null stub).
+   * Production wiring passes the session-JSONL reader from §8.1/§8.2.
+   */
+  livePermissionModeReader?: LivePermissionModeReader;
+  /** Optional summary-file write seam (defaults to `writeSummaryFile`). */
+  writeSummary?: WriteSummaryFn;
+  /** Optional clipboard handler seam (defaults to `handleCopyToClipboard`). */
+  handleCopyToClipboard?: CopyToClipboardFn;
+  /** Optional base-dir resolver — forwarded to the summary-file writer. */
+  baseDirResolver?: BaseDirResolver;
+}
+
+/**
+ * Build a `ParentDispatchHandler` bound to the parent's startup state.
+ * The returned function is what main.ts plugs into
+ * `createParentDispatcher`'s `handlers.switch` slot.
+ */
+export function createSwitchHandler(args: CreateSwitchHandlerArgs): ParentDispatchHandler {
+  const liveReader = args.livePermissionModeReader ?? NULL_LIVE_PERMISSION_READER;
+  const writeSummary = args.writeSummary ?? writeSummaryFile;
+  const copyToClipboard = args.handleCopyToClipboard ?? handleCopyToClipboard;
+  const baseDir = args.baseDirResolver;
+
+  return async (req: WireRequest): Promise<WireResponse> => {
+    const destination = stringField(req, 'destination');
+    const name = stringField(req, 'name');
+    const summary = stringField(req, 'summary');
+
+    if (destination === '' || name === '' || summary === '') {
+      const missing: string[] = [];
+      if (destination === '') missing.push('destination');
+      if (name === '') missing.push('name');
+      if (summary === '') missing.push('summary');
+      return {
+        action: 'error',
+        error: `switch requires ${missing.join(', ')}`,
+      };
+    }
+
+    let summaryPath: string;
+    try {
+      const r = await writeSummary({ summary, baseDir });
+      summaryPath = r.path;
+    } catch (err) {
+      return {
+        action: 'error',
+        error: `write summary: ${(err as Error).message}`,
+      };
+    }
+
+    const overrides = overrideRequestFrom(req);
+    const sessionId = stringField(req, 'session_id');
+
+    // Never-mode paste-flow branch. Render the command, copy it, return
+    // action='paste_flow'. The current session keeps running — no
+    // stashArgv, no fire.
+    //
+    // 'never' is a control signal, not a real permission-mode value:
+    // strip it from the overrides before rendering so the relaunch
+    // command the user pastes is a valid invocation. Go canonical
+    // (which branches on cfg.Auto.Handoff="never" instead) gets the
+    // same result by not having a `--permission-mode never` token to
+    // begin with.
+    if (overrides.permissionMode === 'never') {
+      const pasteOverrides: OverrideRequest = { ...overrides, permissionMode: undefined };
+      const preserved = preserveArgs(args.origArgs, TRANSFER_DENY_FLAGS, TRANSFER_DENY_BARE_OK);
+      const withOverrides = applyOverrides(preserved, pasteOverrides);
+      const { magic, rest } = splitLeadingMagic(withOverrides);
+      const command = renderSwitchCommand(magic, destination, rest, name, summaryPath);
+      const clipResp = await copyToClipboard({
+        op: 'copy_to_clipboard',
+        text: command,
+      });
+      const clipboardOk = clipResp.clipboard_ok === true;
+      const message = clipboardOk
+        ? "I've prepared the handoff command (already on your clipboard)."
+        : 'Copy this command and run it:';
+      return {
+        action: 'paste_flow',
+        message,
+        command,
+        clipboard_ok: clipboardOk,
+      };
+    }
+
+    // Normal switch branch. Preserve user flags from startup (minus
+    // the transfer denylist), apply MCP overrides, auto-capture the
+    // live permission mode when neither side supplied one, then split
+    // magic from rest and build the relaunch argv.
+    const preserved = preserveArgs(args.origArgs, TRANSFER_DENY_FLAGS, TRANSFER_DENY_BARE_OK);
+    let withOverrides = applyOverrides(preserved, overrides);
+
+    const hasPermissionOverride =
+      overrides.permissionMode !== undefined && overrides.permissionMode !== '';
+    if (!hasPermissionOverride && !flagPresent(withOverrides, '--permission-mode') && sessionId !== '') {
+      const live = liveReader(sessionId);
+      if (live !== null && live !== '') {
+        withOverrides = [...withOverrides, '--permission-mode', live];
+      }
+    }
+    const { magic, rest } = splitLeadingMagic(withOverrides);
+
+    const argv: string[] = [
+      ...magic,
+      destination,
+      ...rest,
+      '--name',
+      name,
+      `@${summaryPath}`,
+    ];
+    args.trigger.stashArgv(argv);
+    args.trigger.fire();
+    return { action: 'done' };
+  };
+}
+
+/**
+ * Build the user-visible relaunch command string for paste-flow
+ * responses. Mirrors `renderSwitchCommand` in the Go canonical
+ * (src/socket_listener.go:451). Magic words come first, then the
+ * destination, then the preserved/override flags, then
+ * `--name <name> @<summaryPath>`.
+ *
+ * Each token is shell-safe enough as-is: override values come from a
+ * controlled vocabulary (model aliases, effort levels, permission
+ * modes, allowedTools comma-list, agent names), and the summary path
+ * is `<base>/fnclaude-handoff-content-<hex>.md` — no whitespace, no
+ * metacharacters.
+ */
+function renderSwitchCommand(
+  magic: readonly string[],
+  destination: string,
+  rest: readonly string[],
+  name: string,
+  summaryPath: string,
+): string {
+  const parts: string[] = ['fnclaude', ...magic, destination, ...rest, '--name', name, `@${summaryPath}`];
+  return parts.join(' ');
+}
+
+/**
+ * Coerce wire-request fields into an `OverrideRequest`. Wire keys use
+ * snake_case per the JSON contract; the override struct uses
+ * camelCase. Unknown / missing / wrong-type fields collapse to
+ * undefined so `applyOverrides` falls through to its preserve branch.
+ */
+function overrideRequestFrom(req: WireRequest): OverrideRequest {
+  return {
+    model: stringFieldOrUndef(req, 'model'),
+    effort: stringFieldOrUndef(req, 'effort'),
+    permissionMode: stringFieldOrUndef(req, 'permission_mode'),
+    allowedTools: stringFieldOrUndef(req, 'allowed_tools'),
+    agent: stringFieldOrUndef(req, 'agent'),
+    brief: boolFieldOrUndef(req, 'brief'),
+    chrome: boolFieldOrUndef(req, 'chrome'),
+    ide: boolFieldOrUndef(req, 'ide'),
+    verbose: boolFieldOrUndef(req, 'verbose'),
+  };
+}
+
+function stringField(req: WireRequest, key: string): string {
+  const v = req[key];
+  return typeof v === 'string' ? v : '';
+}
+
+function stringFieldOrUndef(req: WireRequest, key: string): string | undefined {
+  const v = req[key];
+  return typeof v === 'string' ? v : undefined;
+}
+
+function boolFieldOrUndef(req: WireRequest, key: string): boolean | undefined {
+  const v = req[key];
+  return typeof v === 'boolean' ? v : undefined;
+}
+
+/**
+ * Whether `args` carries `flag` as a bare token or as `flag=value`.
+ * Mirrors Go canonical's `flagPresent` (src/socket_listener.go:260).
+ */
+function flagPresent(argsArr: readonly string[], flag: string): boolean {
+  const prefix = `${flag}=`;
+  for (const t of argsArr) {
+    if (t === flag || t.startsWith(prefix)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/mcp/inject-config.ts

@@ -0,0 +1,59 @@
+/**
+ * Self-MCP `--mcp-config` injection (§7.4).
+ *
+ * Builds an inline JSON config that points claude at the fnclaude binary
+ * as an MCP server, then appends `--mcp-config <json>` to the claude argv
+ * the launcher is about to spawn. The subprocess claude spawns from this
+ * config dials the parent over $FNC_SOCKET — see design.mcp.md §2.1.
+ *
+ * Wire shape (design.md §29, design.mcp.md §2.1):
+ *
+ *   {"mcpServers":{"fnclaude":{"command":"<bunExec>","args":["<fncBin>","mcp"]}}}
+ *
+ * Noop sessions add `"--noop"` to args. The Go canonical resolves the exe
+ * path via `filepath.EvalSymlinks(os.Executable())`; the TS equivalent is
+ * `realpathSync(process.argv[1] ?? '')` paired with `process.execPath` for
+ * the runtime that will actually `exec` it. The two-element shape (bun +
+ * script path, vs. a single bundled binary in Go) is necessary because
+ * fnc.js is a script — claude spawning bare `<fncBin>` would invoke node,
+ * not bun, and node can't run the bun-only main.ts.
+ *
+ * Gate: print mode (-p / --print) doesn't get the config — claude is being
+ * driven non-interactively, no MCP tools would be useful. The launcher
+ * also skips the call entirely on win32 where there's no listener.
+ */
+
+export interface InjectMcpConfigArgs {
+  claudeArgs: readonly string[];
+  /** Path to the bun executable that will run the MCP subprocess (typically process.execPath). */
+  bunExec: string;
+  /** Absolute path to the fnc bin script (typically realpathSync(process.argv[1])). */
+  fncBin: string;
+  /** True when the launcher used the noop fallback; appends "--noop" to args. */
+  noop: boolean;
+  /** False for -p / --print sessions; skips injection per design.md §29 gate. */
+  interactive: boolean;
+}
+
+export function injectMcpConfig(args: InjectMcpConfigArgs): string[] {
+  // Gate per design.md §29: only interactive sessions get the config.
+  if (!args.interactive) return [...args.claudeArgs];
+  // Bail out if the launcher couldn't resolve its own path. Without an
+  // absolute fnc bin the spawned subprocess wouldn't be able to find
+  // itself; better to skip than to inject a broken config.
+  if (args.fncBin === '') return [...args.claudeArgs];
+
+  const subprocessArgs: string[] = [args.fncBin, 'mcp'];
+  if (args.noop) subprocessArgs.push('--noop');
+
+  const config = {
+    mcpServers: {
+      fnclaude: {
+        command: args.bunExec,
+        args: subprocessArgs,
+      },
+    },
+  };
+
+  return [...args.claudeArgs, '--mcp-config', JSON.stringify(config)];
+}