@fnclaude/cli 1.1.0 → 2.0.0

package/src/mcp/socketListener.ts

@@ -1,540 +0,0 @@
-/**
- * Parent-side AF_UNIX socket listener — accepts one MCP Request per
- * connection, dispatches by Op, returns one Response, then closes. Ported
- * from src/socket_listener.go in the Go reference (fnclaude@fnrhombus).
- *
- * The triggered/handoff-argv channel pattern is preserved: when a handoff
- * action fires (OpRestart, OpSwitch), the listener stashes the new argv
- * and resolves a `triggered` promise so the PTY-runner can unblock and
- * kill claude. First-wins on the argv; subsequent calls don't replace it.
- *
- * Cross-cutting helpers (clipboard write, sibling spawn) are dependency-
- * injected so tests can stub them without exec'ing real binaries. This
- * mirrors Go's `clipboardExec` / `spawnSibling` indirection vars.
- */
-
-import { createServer, type Server, type Socket } from 'node:net';
-import { writeFile, unlink, chmod } from 'node:fs/promises';
-import type { Config } from '../config.js';
-import { errorMessage } from '../errors.js';
-import { handoffContentPath, type HandoffSpec } from '../handoff.js';
-import {
-  appendRestartReminder,
-  readLivePermissionMode,
-} from '../sessionState.js';
-import {
-  encodeResponse,
-  type CopyRequest,
-  type Request,
-  type Response,
-  type RestartRequest,
-  type SpawnRequest,
-  type SwitchRequest,
-  readRequest,
-} from './protocol.js';
-import {
-  applyOverrides,
-  flagPresent,
-  preserveArgs,
-  splitLeadingMagic,
-  transferDenyBareOK,
-  transferDenyFlags,
-} from '../args/preserve.js';
-
-// ── Session ID validation (matches Go sessionIDPattern) ───────────────────
-
-const SESSION_ID_PATTERN =
-  /^[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}$/;
-
-// ── Injected dependencies ─────────────────────────────────────────────────
-
-/** Result of a clipboard write — mirrors Go's (bool, error). */
-export interface ClipboardResult {
-  ok: boolean;
-  error?: Error;
-}
-
-/** Result of a sibling spawn — mirrors Go's (bool, error). */
-export interface SpawnResult {
-  spawned: boolean;
-  error?: Error;
-}
-
-export interface SocketListenerDeps {
-  /**
-   * Write text to the user's clipboard. Production default is a stub that
-   * always reports failure — wire the real implementation in via the
-   * constructor (or accept the no-op behavior in tests that don't care).
-   */
-  copyToClipboard: (text: string) => Promise<ClipboardResult>;
-
-  /**
-   * Spawn a sibling fnclaude session at `dest`, passing `summaryPath` as
-   * the @-arg and `extraArgs` as the tail flag list. Return `spawned:true`
-   * when a launcher was found and started; `spawned:false` (with no
-   * error) when no launcher resolved — caller falls back to paste-flow.
-   */
-  spawnSibling: (
-    cfg: Config,
-    dest: string,
-    name: string,
-    summaryPath: string,
-    extraArgs: readonly string[],
-  ) => Promise<SpawnResult>;
-}
-
-/**
- * Default deps used when the caller doesn't supply their own. Both are
- * intentionally no-op fallbacks: real implementations live in higher
- * layers (clipboard.ts / spawn.ts in future phases). The listener
- * remains usable end-to-end with the defaults — clipboard writes report
- * failure, spawn always reports "no launcher".
- */
-export function defaultDeps(): SocketListenerDeps {
-  return {
-    copyToClipboard: async () => ({
-      ok: false,
-      error: new Error('no clipboard backend wired'),
-    }),
-    spawnSibling: async () => ({ spawned: false }),
-  };
-}
-
-// ── SocketListener ────────────────────────────────────────────────────────
-
-export interface StartOptions {
-  spec: HandoffSpec;
-  cfg: Config;
-  launchCWD: string;
-  /** os.Args[1:] equivalent captured at startup; used to preserve flags. */
-  origArgs?: readonly string[];
-  /** Override for clipboard + spawn — tests pass stubs here. */
-  deps?: Partial<SocketListenerDeps>;
-}
-
-export class SocketListener {
-  private readonly socketPath: string;
-  private readonly server: Server;
-  private readonly cfg: Config;
-  private readonly launchCWD: string;
-  private readonly origArgs: readonly string[];
-  private readonly deps: SocketListenerDeps;
-
-  private handoffArgv: string[] | undefined;
-  private triggeredResolve!: () => void;
-  private readonly triggeredPromise: Promise<void>;
-  private triggeredFired = false;
-
-  private constructor(opts: StartOptions, server: Server) {
-    this.socketPath = opts.spec.socketPath;
-    this.server = server;
-    this.cfg = opts.cfg;
-    this.launchCWD = opts.launchCWD;
-    this.origArgs = (opts.origArgs ?? []).slice();
-    const fallback = defaultDeps();
-    this.deps = {
-      copyToClipboard: opts.deps?.copyToClipboard ?? fallback.copyToClipboard,
-      spawnSibling: opts.deps?.spawnSibling ?? fallback.spawnSibling,
-    };
-    this.triggeredPromise = new Promise<void>((resolve) => {
-      this.triggeredResolve = resolve;
-    });
-  }
-
-  /**
-   * Open the AF_UNIX listener at spec.socketPath and start the accept
-   * loop. Best-effort removes any stale socket file from a prior crashed
-   * invocation at this path (net listen errors with EADDRINUSE otherwise).
-   *
-   * The socket file is chmod'd to 0600 immediately after bind so other
-   * UIDs on the host cannot dial it. Node's createServer() does NOT honor
-   * a mode option for AF_UNIX paths — it inherits the process umask, which
-   * defaults to 022 (world-readable) or worse depending on caller. We
-   * tighten unconditionally rather than rely on umask discipline at every
-   * launch site. The race window between bind and chmod is small (single
-   * tick) but real; we accept it as the trade vs. a per-process umask
-   * dance that would still leak any *other* file created in the same tick.
-   */
-  static async start(opts: StartOptions): Promise<SocketListener> {
-    try {
-      await unlink(opts.spec.socketPath);
-    } catch {
-      // best-effort — fine if it didn't exist
-    }
-    const server = createServer();
-    const listener = new SocketListener(opts, server);
-    server.on('connection', (sock) => {
-      void listener.handleConn(sock);
-    });
-    await new Promise<void>((resolve, reject) => {
-      const onErr = (e: Error) => {
-        server.off('listening', onOk);
-        reject(e);
-      };
-      const onOk = () => {
-        server.off('error', onErr);
-        resolve();
-      };
-      server.once('error', onErr);
-      server.once('listening', onOk);
-      server.listen(opts.spec.socketPath);
-    });
-    // Tighten the socket to owner-only rw — see method-level note above.
-    // Windows AF_UNIX implementations don't honor POSIX modes; the chmod
-    // call is a no-op there but harmless.
-    try {
-      await chmod(opts.spec.socketPath, 0o600);
-    } catch (err) {
-      // Don't leave a world-readable socket up if we can't tighten it.
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-      try {
-        await unlink(opts.spec.socketPath);
-      } catch {
-        // already gone
-      }
-      throw new Error(
-        `failed to chmod socket to 0600 at ${opts.spec.socketPath}: ${errorMessage(err)}`,
-      );
-    }
-    return listener;
-  }
-
-  /** Shut down and remove the socket file. */
-  async close(): Promise<void> {
-    await new Promise<void>((resolve) => {
-      this.server.close(() => resolve());
-    });
-    try {
-      await unlink(this.socketPath);
-    } catch {
-      // already removed (some platforms do this on close)
-    }
-  }
-
-  /**
-   * Promise that resolves when a handoff action (restart or switch) has
-   * stashed an argv to relaunch with. The PTY runner awaits this to know
-   * when to kill claude.
-   */
-  triggered(): Promise<void> {
-    return this.triggeredPromise;
-  }
-
-  /** Parsed argv (leading "fnclaude" token already dropped) to re-exec. */
-  getHandoffArgv(): string[] | undefined {
-    return this.handoffArgv === undefined ? undefined : this.handoffArgv.slice();
-  }
-
-  /** First-wins. Subsequent calls don't overwrite. */
-  private stashArgv(argv: string[]): void {
-    if (this.handoffArgv === undefined) {
-      this.handoffArgv = argv;
-    }
-    if (!this.triggeredFired) {
-      this.triggeredFired = true;
-      this.triggeredResolve();
-    }
-  }
-
-  // ── per-connection handler ──────────────────────────────────────────────
-
-  private async handleConn(sock: Socket): Promise<void> {
-    try {
-      // Read one Request from the socket's data stream.
-      let req: Request | undefined;
-      try {
-        req = await readRequest(sock);
-      } catch (err) {
-        sock.write(
-          encodeResponse({
-            action: 'error',
-            error: `malformed request: ${errorMessage(err)}`,
-          }),
-        );
-        sock.end();
-        return;
-      }
-      if (req === undefined) {
-        // EOF without a line — client disconnected silently. Nothing to respond.
-        sock.end();
-        return;
-      }
-      const resp = await this.dispatch(req);
-      sock.write(encodeResponse(resp));
-      sock.end();
-    } catch (err) {
-      // Best-effort error response then close.
-      try {
-        sock.write(
-          encodeResponse({
-            action: 'error',
-            error: `handler failure: ${errorMessage(err)}`,
-          }),
-        );
-      } catch {
-        // ignore — socket may already be torn down
-      }
-      sock.end();
-    }
-  }
-
-  private async dispatch(req: Request): Promise<Response> {
-    switch (req.op) {
-      case 'restart':
-        return this.handleRestart(req);
-      case 'switch':
-        return this.handleSwitch(req);
-      case 'spawn':
-        return this.handleSpawn(req);
-      case 'copy_to_clipboard':
-        return this.handleCopy(req);
-      default: {
-        // Exhaustiveness: adding a new Op variant to Request without
-        // handling it here becomes a compile error on this line. The
-        // runtime branch defends against malformed wire input that
-        // squeezes through with an unknown op.
-        const _exhaustive: never = req;
-        void _exhaustive;
-        return {
-          action: 'error',
-          error: `unsupported op ${JSON.stringify((req as { op: unknown }).op)}`,
-        };
-      }
-    }
-  }
-
-  // ── handleRestart ───────────────────────────────────────────────────────
-
-  private async handleRestart(req: RestartRequest): Promise<Response> {
-    const sid = req.session_id;
-    if (!sid) {
-      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_PATTERN.test(sid)) {
-      return {
-        action: 'error',
-        error: `session_id ${JSON.stringify(sid)} 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(this.origArgs, null, null);
-    // Apply MCP-supplied overrides.
-    let withOverrides = applyOverrides(preserved, req);
-    // Auto-capture live permission-mode from the session JSONL when the
-    // caller didn't override AND none was preserved.
-    if (
-      !req.permission_mode &&
-      !flagPresent(withOverrides, '--permission-mode')
-    ) {
-      const live = readLivePermissionMode(this.launchCWD, sid);
-      if (live !== undefined) {
-        withOverrides = [...withOverrides, '--permission-mode', live];
-      }
-    }
-    const { magic, rest } = splitLeadingMagic(withOverrides);
-
-    // Append a system-reminder to the session JSONL so the resumed model
-    // sees a fresh directive to continue the in-flight work rather than
-    // treat the restart as a hard reset and idle (issue #77).
-    appendRestartReminder(this.launchCWD, sid, {
-      model: req.model,
-      effort: req.effort,
-      permissionMode: req.permission_mode,
-      agent: req.agent,
-      ide: req.ide === true,
-    });
-
-    const argv = [...magic, this.launchCWD, '--resume', sid, ...rest];
-    this.stashArgv(argv);
-    return { action: 'done' };
-  }
-
-  // ── handleSwitch ────────────────────────────────────────────────────────
-
-  private async handleSwitch(req: SwitchRequest): Promise<Response> {
-    if (this.cfg.auto.handoff === 'never') {
-      return this.handleSwitchNeverMode(req);
-    }
-    const summaryPath = handoffContentPath();
-    try {
-      await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
-    } catch (err) {
-      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
-    }
-
-    // Preserve user flags minus the transfer denylist, then apply overrides.
-    const preserved = preserveArgs(this.origArgs, transferDenyFlags, transferDenyBareOK);
-    let withOverrides = applyOverrides(preserved, req);
-    // Auto-capture live permission-mode (same pattern as restart).
-    if (
-      !req.permission_mode &&
-      !flagPresent(withOverrides, '--permission-mode') &&
-      req.session_id
-    ) {
-      const live = readLivePermissionMode(this.launchCWD, req.session_id);
-      if (live !== undefined) {
-        withOverrides = [...withOverrides, '--permission-mode', live];
-      }
-    }
-    const { magic, rest } = splitLeadingMagic(withOverrides);
-
-    const argv = [
-      ...magic,
-      req.destination ?? '',
-      ...rest,
-      '--name',
-      req.name ?? '',
-      `@${summaryPath}`,
-    ];
-    this.stashArgv(argv);
-    return { action: 'done' };
-  }
-
-  // ── handleSpawn ─────────────────────────────────────────────────────────
-
-  private async handleSpawn(req: SpawnRequest): Promise<Response> {
-    if (this.cfg.auto.handoff === 'never') {
-      return this.handleSpawnNeverMode(req);
-    }
-    const summaryPath = handoffContentPath();
-    try {
-      await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
-    } catch (err) {
-      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
-    }
-
-    // Spawn doesn't preserve startup flags — fresh-start sibling.
-    const extraArgs = applyOverrides([], req);
-
-    const dest = req.destination ?? '';
-    const name = req.name ?? '';
-    const { spawned, error } = await this.deps.spawnSibling(
-      this.cfg,
-      dest,
-      name,
-      summaryPath,
-      extraArgs,
-    );
-    if (error) {
-      return { action: 'error', error: `spawn: ${error.message}` };
-    }
-    if (!spawned) {
-      // No launcher resolved — fall back to paste-flow.
-      const cmdStr = renderSpawnCommand(dest, name, summaryPath, extraArgs);
-      const { ok } = await this.deps.copyToClipboard(cmdStr);
-      const msg = ok
-        ? '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: msg,
-        command: cmdStr,
-        clipboard_ok: ok,
-      };
-    }
-    return {
-      action: 'done',
-      message: `Spawned sibling fnclaude for ${dest} in a new window.`,
-    };
-  }
-
-  // ── never-mode handlers ─────────────────────────────────────────────────
-
-  private async handleSwitchNeverMode(req: SwitchRequest): Promise<Response> {
-    const summaryPath = handoffContentPath();
-    try {
-      await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
-    } catch (err) {
-      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
-    }
-    const preserved = preserveArgs(this.origArgs, transferDenyFlags, transferDenyBareOK);
-    const withOverrides = applyOverrides(preserved, req);
-    const { magic, rest } = splitLeadingMagic(withOverrides);
-    const cmdStr = renderSwitchCommand(
-      magic,
-      req.destination ?? '',
-      rest,
-      req.name ?? '',
-      summaryPath,
-    );
-    const { ok } = await this.deps.copyToClipboard(cmdStr);
-    const msg = ok
-      ? "I've prepared the handoff command (already on your clipboard)."
-      : 'Copy this command and run it:';
-    return {
-      action: 'paste_flow',
-      message: msg,
-      command: cmdStr,
-      clipboard_ok: ok,
-    };
-  }
-
-  private async handleSpawnNeverMode(req: SpawnRequest): Promise<Response> {
-    const summaryPath = handoffContentPath();
-    try {
-      await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
-    } catch (err) {
-      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
-    }
-    const extraArgs = applyOverrides([], req);
-    const dest = req.destination ?? '';
-    const name = req.name ?? '';
-    const cmdStr = renderSpawnCommand(dest, name, summaryPath, extraArgs);
-    const { ok } = await this.deps.copyToClipboard(cmdStr);
-    const msg = ok
-      ? 'Auto-handoff is disabled — the relaunch command is on your clipboard; paste it into a new terminal window.'
-      : 'Auto-handoff is disabled — copy this command and run it in a new terminal window:';
-    return {
-      action: 'paste_flow',
-      message: msg,
-      command: cmdStr,
-      clipboard_ok: ok,
-    };
-  }
-
-  // ── handleCopy ──────────────────────────────────────────────────────────
-
-  private async handleCopy(req: CopyRequest): Promise<Response> {
-    const { ok } = await this.deps.copyToClipboard(req.text ?? '');
-    return { action: 'done', clipboard_ok: ok };
-  }
-}
-
-// ── command-string rendering ──────────────────────────────────────────────
-
-/**
- * Build the user-visible relaunch command for paste-flow Responses (spawn).
- */
-export function renderSpawnCommand(
-  destination: string,
-  name: string,
-  summaryPath: string,
-  extraArgs: readonly string[],
-): string {
-  let cmd = `fnclaude ${destination} --name ${name} @${summaryPath}`;
-  if (extraArgs.length > 0) {
-    cmd += ` ${extraArgs.join(' ')}`;
-  }
-  return cmd;
-}
-
-/**
- * Build the user-visible relaunch command for paste-flow Responses
- * (never-mode switch). Magic words come first, then destination, then
- * preserved/override flags, then --name name @summary at the end.
- */
-export 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(' ');
-}

package/src/noop.ts

@@ -1,106 +0,0 @@
-// Port of src/noop.go (fnclaude/fnclaude Go reference).
-//
-// Ensures the user's noop dir exists and contains the up-to-date handoff
-// template (a single-use bridge file written by the noop router when it
-// hands off to a project session). Never touches CLAUDE.md or any other
-// file in the dir — those are user territory.
-//
-// `defaultNoopDir` is re-exported from argParser.ts so callers can reach it
-// from one canonical location; it's defined there because the parser uses
-// it as the fallback when no positional path was provided.
-
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-
-export { defaultNoopDir } from './argParser.js';
-
-/**
- * The embedded handoff.template.md content. Sourced verbatim from
- * src/noop_templates/handoff.template.md in the Go reference. Inlined here
- * (rather than read from disk) so the npm package ships a single binary
- * with no companion data files to lose.
- *
- * Update process: when the upstream template changes, copy the new content
- * here and the next seedNoop will detect the SHA-256 mismatch and rewrite
- * the on-disk copy.
- */
-export const NOOP_HANDOFF_TEMPLATE = `<!--
-============================================================================
-  HANDOFF — BURN AFTER READING
-============================================================================
-  This file is a single-use bridge between Claude sessions.
-
-  RECEIVING CLAUDE: your VERY FIRST action after reading this file is:
-      rm <HANDOFF_PATH>
-  Do this BEFORE responding to the user. The file is in tmpfs and
-  would eventually clear on logout, but explicit deletion keeps the
-  handoff queue accurate — leftover handoff files look like
-  unhandled handoffs. Confirm deletion in your first message, then
-  proceed with the work below.
-============================================================================
--->
-
-# Handoff from noop session — <ISO 8601 datetime>
-
-## What the user asked for
-<verbatim or near-verbatim version of the user's request — preserve their wording where you can>
-
-## Context I gathered in noop
-<anything relevant the receiving session needs: tool versions, decisions, links. Tight; don't pad.>
-
-## What I did NOT do
-<short list of what was correctly avoided in noop, so the receiving session knows where work starts>
-
-## Suggested first steps for receiving session
-1. <next concrete action>
-2. <…>
-
-## Open questions for the user
-<only if any — otherwise omit the section>
-`;
-
-/**
- * Hex SHA-256 of the embedded template. Comparing hex strings is simpler
- * than comparing Buffers and reads cleanly in the on-disk check.
- */
-const TEMPLATE_SHA = createHash('sha256').update(NOOP_HANDOFF_TEMPLATE).digest('hex');
-
-/**
- * Ensure `noopDir` exists and contains the latest handoff template. Creates
- * the dir if missing; rewrites the template iff the on-disk SHA-256 differs
- * from the embedded SHA-256. Never touches any other file in the directory.
- *
- * Returns void on success; throws a wrapped Error on filesystem failure that
- * the caller should surface as a warning (best-effort — a noop session
- * without a freshly-seeded template can still receive the system prompt and
- * route requests, just won't have the template to follow).
- */
-export async function seedNoop(noopDir: string): Promise<void> {
-  try {
-    await mkdir(noopDir, { recursive: true, mode: 0o755 });
-  } catch (err) {
-    throw new Error(`create noop dir ${noopDir}: ${(err as Error).message}`);
-  }
-
-  const path = join(noopDir, 'handoff.template.md');
-
-  // Compare existing on-disk hash with the embedded hash; skip rewrite when
-  // they match.
-  try {
-    const existing = await readFile(path);
-    const existingSha = createHash('sha256').update(existing).digest('hex');
-    if (existingSha === TEMPLATE_SHA) return;
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-      throw new Error(`read ${path}: ${(err as Error).message}`);
-    }
-    // ENOENT — fall through to write.
-  }
-
-  try {
-    await writeFile(path, NOOP_HANDOFF_TEMPLATE, { mode: 0o644 });
-  } catch (err) {
-    throw new Error(`write ${path}: ${(err as Error).message}`);
-  }
-}

package/src/passthrough.ts

@@ -1,36 +0,0 @@
-// Passthrough-slice inspection helpers — the small predicates that ask
-// "does this argv list already contain <flag>?". Shared between the
-// argParser (which builds the slice) and the downstream pipeline stages
-// (argv.ts, worktree.ts) that decide whether to inject more.
-//
-// Lives in its own module to break the import cycle that would otherwise
-// arise: argParser.ts imports the predicates → argv.ts imports them too
-// → worktree.ts needs nameInPassthrough → if it imported from argParser.ts
-// that would close the loop (argParser → argv → worktree → argParser).
-// With every consumer importing from here, the cycle disappears.
-
-/**
- * True when any token is `--setting-sources` or starts with `--setting-sources=`.
- */
-export function settingSourcesInPassthrough(passthrough: readonly string[]): boolean {
-  return passthrough.some(
-    (t) => t === '--setting-sources' || t.startsWith('--setting-sources='),
-  );
-}
-
-/**
- * True when the exact token appears, or any `token=<anything>` form.
- */
-export function tokenInPassthrough(passthrough: readonly string[], long: string): boolean {
-  const prefix = `${long}=`;
-  return passthrough.some((t) => t === long || t.startsWith(prefix));
-}
-
-/**
- * True when --name or -n (bare or =value) appears anywhere in passthrough.
- */
-export function nameInPassthrough(passthrough: readonly string[]): boolean {
-  return passthrough.some(
-    (t) => t === '--name' || t === '-n' || t.startsWith('--name=') || t.startsWith('-n='),
-  );
-}