@fnclaude/cli 0.7.2 → 0.7.3

package/src/main.ts

@@ -27,34 +27,46 @@ import {
   type LlmClientFn,
 } from './autoname.js';
 import { parseArgs } from './argParser.js';
+import {
+  brandResolved,
+  withPassthroughUpdate,
+  withResolved,
+  type InterceptedArgs,
+  type ResolvedArgs,
+} from './args.js';
 import { buildArgv } from './argv.js';
-import { loadConfig } from './config.js';
+import { loadConfig, type Config } from './config.js';
 import { handoffSocketPath, type HandoffSpec } from './handoff.js';
 import { helpText, version, wantsHelp, wantsVersion } from './help.js';
 import { loadHostAliases } from './hostAliases.js';
 import { expandTildePath } from './paths.js';
-import { loadPrompts } from './prompts.js';
+import { loadPrompts, type PromptSet } from './prompts.js';
 import { detectCrossCwd, runWithPTY } from './pty.js';
 import { loadRepoSettings } from './repoSettings.js';
-import { Resolve } from './resolver.js';
+import { Resolve, type RepoSettings, type ResolveDeps } from './resolver.js';
 import { sanitizeNamesInPassthrough } from './sanitize.js';
 import { runMCPServer } from './mcp/client.js';
 import { seedNoop } from './noop.js';
 import { silentRelaunch, silentRelaunchHandoff } from './silentRelaunch.js';
-import { applyWorktreeIntercept } from './worktree.js';
-import { flushWarnings, warn } from './warnings.js';
+import { applyWorktreeIntercept, type GitRunner } from './worktree.js';
+import { flushWarnings } from './warnings.js';
 
 /**
- * Pluggable seam set used by `run()`. Tests substitute in-memory implementations
- * to drive the orchestration without launching real subprocesses, dialing
- * real sockets, or touching the real filesystem.
+ * `RunIO` — process-shaped seams. Streams, paths, the launch environment,
+ * and the external behaviour the pipeline depends on (claude binary
+ * lookup, PTY runner, relaunch, MCP dispatcher, noop seeder, autoname
+ * LLM call). Plus the *inner* dependency seams of the pipeline modules
+ * themselves — `gitRunner` (consumed by applyWorktreeIntercept) and
+ * `resolveDeps` (consumed by Resolve) — surfaced here so tests can swap
+ * the I/O each module does without a wrapper layer of outer functions.
  *
- * The default values (when the caller omits a field) resolve to the
- * production implementations imported above. Mirrors the Go `run()`'s
- * package-level `runMCPServerFn` / `gitRunner` indirections, expanded so the
- * full integration is testable without monkey-patching.
+ * Earlier shape had both outer (`RunDeps.applyWorktreeIntercept`) and
+ * inner (`applyWorktreeIntercept`'s `GitRunner` parameter) seams for the
+ * same boundary. Collapsed to the inner seam only — the outer one was
+ * dead weight in production (the function never varies) and in tests it
+ * just wrapped the inner seam with two extra lines of closure plumbing.
  */
-export interface RunDeps {
+export interface RunIO {
   /** Source argv (typically `process.argv.slice(2)`). */
   argv?: readonly string[];
   /** Stream where the help/version/error text is written. */
@@ -64,6 +76,7 @@ export interface RunDeps {
   home?: string;
   /** Shell cwd at startup. */
   cwd?: string;
+
   /** PATH lookup for the claude binary; returns null when not found. */
   lookupClaude?: (name: string) => string | null;
   /** Override the run-with-pty step. */
@@ -72,24 +85,63 @@ export interface RunDeps {
   silentRelaunch?: typeof silentRelaunch;
   /** Override the silent-relaunch-handoff step. */
   silentRelaunchHandoff?: typeof silentRelaunchHandoff;
+  /** Override runMCPServer (the `mcp` subcommand dispatcher). */
+  runMCPServer?: typeof runMCPServer;
   /** Override seedNoop (best-effort dir seeder). */
   seedNoop?: typeof seedNoop;
   /** Override generateName for auto-name (skip the LLM call). */
   generateName?: typeof generateName;
-  /** Override loadPrompts (skip disk lookup). */
-  loadPrompts?: typeof loadPrompts;
-  /** Override loadConfig (use a fixed config). */
-  loadConfig?: typeof loadConfig;
-  /** Override loadRepoSettings (skip the four-tier settings.json merge). */
-  loadRepoSettings?: typeof loadRepoSettings;
-  /** Override loadHostAliases. */
-  loadHostAliases?: typeof loadHostAliases;
-  /** Override Resolve. */
-  resolve?: typeof Resolve;
-  /** Override applyWorktreeIntercept. */
-  applyWorktreeIntercept?: typeof applyWorktreeIntercept;
-  /** Override runMCPServer (the `mcp` subcommand dispatcher). */
-  runMCPServer?: typeof runMCPServer;
+
+  /**
+   * GitRunner for applyWorktreeIntercept. Tests that want to drive a
+   * fake `git worktree list` reply pass one here; production uses the
+   * module's `defaultGitRunner`.
+   */
+  gitRunner?: GitRunner;
+
+  /**
+   * Resolver I/O seams (path-exists check, gh CLI, clone). Tests pass a
+   * stub set so the resolver runs without touching the network or
+   * filesystem; production uses `productionDeps()` from resolver.ts.
+   */
+  resolveDeps?: ResolveDeps;
+}
+
+/**
+ * `RunConfig` — pre-loaded data the pipeline reads. When a field is
+ * supplied here, the corresponding loader (loadConfig / loadPrompts /
+ * loadRepoSettings / loadHostAliases) is skipped and the supplied value
+ * is used directly. Tests build a hermetic config payload up-front; in
+ * production every field is omitted and the loaders run for real.
+ *
+ * These were previously expressed as `loadConfig: typeof loadConfig`
+ * function seams in the unified `RunDeps`. The 1:1 thin-wrapper pattern
+ * was double-injection — in production they have zero variance, and in
+ * tests they were always loader stubs that returned a fixed payload.
+ * Storing the payload directly removes a layer of function plumbing.
+ */
+export interface RunConfig {
+  /** Pre-loaded config. Omit to call `loadConfig()`. */
+  config?: Config;
+  /** Pre-loaded prompts. Omit to call `loadPrompts()`. */
+  prompts?: PromptSet;
+  /** Pre-loaded repo settings. Omit to call `loadRepoSettings(home, cwd)`. */
+  repoSettings?: RepoSettings;
+  /** Pre-loaded host aliases. Omit to call `loadHostAliases(home)`. */
+  hostAliases?: Record<string, string>;
+}
+
+/**
+ * Top-level deps for `run()` — two named groups (`io` and `data`),
+ * each optional, each with optional fields. Tests typically populate
+ * only the fields they care about. Production omits everything (passes
+ * `{}` or nothing) and lets every default kick in.
+ */
+export interface RunDeps {
+  /** Process-shaped seams (streams, env, external behaviours). */
+  io?: RunIO;
+  /** Pre-loaded data payloads (skips the corresponding loaders). */
+  data?: RunConfig;
 }
 
 function lookupClaudeFromPath(name: string): string | null {
@@ -117,34 +169,37 @@ function lookupClaudeFromPath(name: string): string | null {
  * through to returning claude's exit code, mirroring Go's behavior.
  */
 export async function run(deps: RunDeps = {}): Promise<number> {
-  const argv = deps.argv ?? process.argv.slice(2);
-  const stdout = deps.stdout ?? process.stdout;
-  const stderr = deps.stderr ?? process.stderr;
-  const home = deps.home ?? process.env.HOME ?? homedir();
-  const shellCWD = deps.cwd ?? process.cwd();
-  const lookupClaude = deps.lookupClaude ?? lookupClaudeFromPath;
-  const runPTY = deps.runWithPTY ?? runWithPTY;
-  const relaunch = deps.silentRelaunch ?? silentRelaunch;
-  const relaunchHandoff = deps.silentRelaunchHandoff ?? silentRelaunchHandoff;
-  const seedNoopFn = deps.seedNoop ?? seedNoop;
-  const generateNameFn = deps.generateName ?? generateName;
-  const loadPromptsFn = deps.loadPrompts ?? loadPrompts;
-  const loadConfigFn = deps.loadConfig ?? loadConfig;
-  const loadRepoSettingsFn = deps.loadRepoSettings ?? loadRepoSettings;
-  const loadHostAliasesFn = deps.loadHostAliases ?? loadHostAliases;
-  const resolveFn = deps.resolve ?? Resolve;
-  const applyWorktreeInterceptFn = deps.applyWorktreeIntercept ?? applyWorktreeIntercept;
-  const runMCPServerFn = deps.runMCPServer ?? runMCPServer;
+  const io = deps.io ?? {};
+  const data = deps.data ?? {};
+
+  const argv = io.argv ?? process.argv.slice(2);
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const home = io.home ?? process.env.HOME ?? homedir();
+  const shellCWD = io.cwd ?? process.cwd();
+  const lookupClaude = io.lookupClaude ?? lookupClaudeFromPath;
+  const runPTY = io.runWithPTY ?? runWithPTY;
+  const relaunch = io.silentRelaunch ?? silentRelaunch;
+  const relaunchHandoff = io.silentRelaunchHandoff ?? silentRelaunchHandoff;
+  const seedNoopFn = io.seedNoop ?? seedNoop;
+  const generateNameFn = io.generateName ?? generateName;
+  const runMCPServerFn = io.runMCPServer ?? runMCPServer;
 
   // Defer-flush warnings on exit, AFTER claude has finished and the user is
   // back at their shell. The silent-relaunch path uses execve which skips
   // this defer; that's intentional — the relaunched fnclaude will re-emit
   // any warnings that still apply.
+  //
+  // Loaders (loadConfig / loadRepoSettings / loadHostAliases / loadPrompts)
+  // and other setup steps return their warnings; we accumulate them in this
+  // local list and drain it via flushWarnings at the deferred-flush point.
+  // No module-global sink — keeps tests hermetic.
+  const warnings: string[] = [];
   let flushed = false;
   const flushOnce = (): void => {
     if (flushed) return;
     flushed = true;
-    flushWarnings(stderr);
+    flushWarnings(warnings, stderr);
   };
 
   try {
@@ -173,90 +228,156 @@ export async function run(deps: RunDeps = {}): Promise<number> {
     }
 
     // ── Parse fnclaude's own argv. ────────────────────────────────────────
-    let a;
+    let parsed;
     try {
-      a = parseArgs(argv, home);
+      parsed = parseArgs(argv, home);
     } catch (err) {
       stderr.write(`${(err as Error).message}\n`);
       return 1;
     }
 
     // ── Seed the noop dir iff fallback was used. ─────────────────────────
-    if (a.usedNoopFallback) {
+    if (parsed.usedNoopFallback) {
       try {
-        await seedNoopFn(a.cwd);
+        await seedNoopFn(parsed.cwd);
       } catch (err) {
-        warn(`fnclaude: noop seed failed: ${(err as Error).message}`);
+        warnings.push(`fnclaude: noop seed failed: ${(err as Error).message}`);
       }
     }
 
-    const cfg = loadConfigFn();
+    // ── Config: pre-loaded or freshly loaded from disk. ──────────────────
+    let cfg: Config;
+    if (data.config !== undefined) {
+      cfg = data.config;
+    } else {
+      const loaded = loadConfig();
+      cfg = loaded.config;
+      warnings.push(...loaded.warnings);
+    }
 
     // ── Repo-reference resolver (path-or-repo two-lookup). ───────────────
+    //
+    // Produces a `ResolvedArgs` either way — the resolver path overwrites
+    // cwd (and possibly worktreeSet/worktreeArg), the tilde-only path
+    // expands cwd, and the absolute-path / noop-fallback path stamps the
+    // existing fields straight through.
+    let resolved: ResolvedArgs;
     if (
-      !a.usedNoopFallback &&
-      a.cwd !== '' &&
-      !isAbsolute(a.cwd) &&
-      !a.cwd.startsWith('~')
+      !parsed.usedNoopFallback &&
+      parsed.cwd !== '' &&
+      !isAbsolute(parsed.cwd) &&
+      !parsed.cwd.startsWith('~')
     ) {
-      const rs = loadRepoSettingsFn(home, shellCWD);
-      const aliases = loadHostAliasesFn(home);
+      let rs: RepoSettings;
+      if (data.repoSettings !== undefined) {
+        rs = data.repoSettings;
+      } else {
+        const loaded = loadRepoSettings(home, shellCWD);
+        rs = loaded.settings;
+        warnings.push(...loaded.warnings);
+      }
+      let aliases: Record<string, string>;
+      if (data.hostAliases !== undefined) {
+        aliases = data.hostAliases;
+      } else {
+        const loaded = loadHostAliases(home);
+        aliases = loaded.aliases;
+        warnings.push(...loaded.warnings);
+      }
+      let result;
       try {
-        const result = await resolveFn({
-          input: a.cwd,
-          cwd: shellCWD,
-          home,
-          settings: rs,
-          hostAliases: aliases,
-        });
-        a.cwd = result.path;
-        // If the user's reference had a +workspace suffix AND they didn't
-        // pass -w explicitly, propagate the workspace to the intercept
-        // layer.
-        if (result.workspace !== undefined && result.workspace !== '' && !a.worktreeSet) {
-          a.worktreeSet = true;
-          a.worktreeArg = result.workspace;
-        }
+        // Resolver's inner deps (path-exists, gh CLI, clone): use the
+        // injected ones in tests, fall back to productionDeps in real
+        // runs. Passing `undefined` lets Resolve default-construct
+        // productionDeps() itself.
+        result = await (io.resolveDeps
+          ? Resolve(
+              {
+                input: parsed.cwd,
+                cwd: shellCWD,
+                home,
+                settings: rs,
+                hostAliases: aliases,
+              },
+              io.resolveDeps,
+            )
+          : Resolve({
+              input: parsed.cwd,
+              cwd: shellCWD,
+              home,
+              settings: rs,
+              hostAliases: aliases,
+            }));
       } catch (err) {
         stderr.write(`${(err as Error).message}\n`);
         return 1;
       }
-    } else if (a.cwd.startsWith('~')) {
+      // If the user's reference had a +workspace suffix AND they didn't
+      // pass -w explicitly, propagate the workspace to the intercept
+      // layer.
+      const promoteWorkspace =
+        result.workspace !== undefined && result.workspace !== '' && !parsed.worktreeSet;
+      resolved = withResolved(parsed, {
+        cwd: result.path,
+        ...(promoteWorkspace
+          ? { worktreeSet: true, worktreeArg: result.workspace! }
+          : {}),
+      });
+    } else if (parsed.cwd.startsWith('~')) {
       // Tilde-expand absolute-shaped inputs that didn't go through the
       // resolver (resolver expands tildes for its short-circuit path, but
       // it isn't called for tilde-prefixed inputs here).
-      a.cwd = expandTildePath(a.cwd);
+      resolved = withResolved(parsed, { cwd: expandTildePath(parsed.cwd) });
+    } else {
+      resolved = brandResolved(parsed);
     }
 
     // ── -w / --worktree intercept. ───────────────────────────────────────
-    applyWorktreeInterceptFn(a, shellCWD);
+    //
+    // GitRunner is the inner seam — production uses the module's default
+    // (synchronous `git -C <dir> ...`); tests inject a stub that yields
+    // the fake `git worktree list --porcelain` shape they want.
+    const intercepted = io.gitRunner
+      ? applyWorktreeIntercept(resolved, shellCWD, io.gitRunner)
+      : applyWorktreeIntercept(resolved, shellCWD);
 
     // ── Resolve the launch cwd relative to shell cwd. ────────────────────
-    const launchCWD = isAbsolute(a.cwd) ? a.cwd : join(shellCWD, a.cwd);
+    const launchCWD = isAbsolute(intercepted.cwd)
+      ? intercepted.cwd
+      : join(shellCWD, intercepted.cwd);
 
     // ── Auto-name if qualifying. ──────────────────────────────────────────
-    if (shouldAutoName(a.passthrough)) {
-      const prompt = extractPrompt(a.passthrough);
+    let named: InterceptedArgs = intercepted;
+    if (shouldAutoName(named.passthrough)) {
+      const prompt = extractPrompt(named.passthrough);
       const apiKey = process.env.ANTHROPIC_API_KEY ?? '';
       let llmFn: LlmClientFn | undefined;
       if (apiKey !== '') llmFn = defaultLlmClient(apiKey);
       else llmFn = claudeCliFn(cfg.name.model);
       const name = await generateNameFn(prompt, cfg.name, apiKey, llmFn);
-      a.passthrough = ['--name', name, ...a.passthrough];
+      named = withPassthroughUpdate(named, {
+        passthrough: ['--name', name, ...named.passthrough],
+      });
     }
 
     // ── Sanitize any --name / -n value to a path-safe slug. ──────────────
-    {
-      const { args: sanitized, warnings } = sanitizeNamesInPassthrough(a.passthrough);
-      a.passthrough = sanitized;
-      for (const w of warnings) warn(w);
-    }
+    const sanitizeResult = sanitizeNamesInPassthrough(named.passthrough);
+    warnings.push(...sanitizeResult.warnings);
+    const sanitized = withPassthroughUpdate(named, {
+      passthrough: sanitizeResult.args,
+    });
 
     // ── Build the claude argv. ───────────────────────────────────────────
-    const promptsResult = loadPromptsFn();
-    for (const w of promptsResult.warnings) warn(w);
+    let prompts: PromptSet;
+    if (data.prompts !== undefined) {
+      prompts = data.prompts;
+    } else {
+      const loaded = loadPrompts();
+      prompts = loaded.prompts;
+      warnings.push(...loaded.warnings);
+    }
 
-    const claudeArgv = buildArgv(a, shellCWD, cfg, promptsResult.prompts);
+    const claudeArgv = buildArgv(sanitized, shellCWD, cfg, prompts);
 
     // ── Verify claude is on PATH before starting the PTY. ────────────────
     if (lookupClaude('claude') === null) {

package/src/mcp/client.ts

@@ -14,10 +14,13 @@ import { connect, type Socket } from 'node:net';
 import type { Readable, Writable } from 'node:stream';
 import {
   encodeRequest,
-  type Op,
   readResponse,
+  type CopyRequest,
   type Request,
   type Response,
+  type RestartRequest,
+  type SpawnRequest,
+  type SwitchRequest,
 } from './protocol.js';
 import pkg from '../../package.json' with { type: 'json' };
 
@@ -420,8 +423,8 @@ async function callRestart(
     );
     return;
   }
-  const req: Request = {
-    op: 'restart' satisfies Op,
+  const req: RestartRequest = {
+    op: 'restart',
     session_id: sid,
     model: readStringArg(args, 'model'),
     effort: readStringArg(args, 'effort'),
@@ -446,8 +449,8 @@ async function callSwitch(
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
-  const req: Request = {
-    op: 'switch' satisfies Op,
+  const req: SwitchRequest = {
+    op: 'switch',
     destination: readStringArg(args, 'destination'),
     name: readStringArg(args, 'name'),
     summary: readStringArg(args, 'summary'),
@@ -476,8 +479,8 @@ async function callSpawn(
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
-  const req: Request = {
-    op: 'spawn' satisfies Op,
+  const req: SpawnRequest = {
+    op: 'spawn',
     destination: readStringArg(args, 'destination'),
     name: readStringArg(args, 'name'),
     summary: readStringArg(args, 'summary'),
@@ -505,8 +508,8 @@ async function callCopy(
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
-  const req: Request = {
-    op: 'copy_to_clipboard' satisfies Op,
+  const req: CopyRequest = {
+    op: 'copy_to_clipboard',
     text: readStringArg(args, 'text'),
   };
   await dialAndRelay(opts, dial, id, req);

package/src/mcp/protocol.ts

@@ -76,50 +76,90 @@ export const ActionError: Action = 'error';
 // ── Request ────────────────────────────────────────────────────────────────
 
 /**
- * Request sent from the MCP subprocess to the parent listener.
+ * Shared override fields applicable to OpRestart / OpSwitch / OpSpawn.
+ *
+ * Empty/undef string values mean "preserve what was on the original
+ * command line" (for restart/transfer) or "don't pass this flag" (for
+ * spawn). For boolean fields: undefined = preserve existing; true =
+ * ensure present; false = ensure absent.
+ */
+export interface RequestOverrides {
+  model?: string;
+  effort?: string;
+  permission_mode?: string;
+  allowed_tools?: string;
+  agent?: string;
+  brief?: boolean | null;
+  chrome?: boolean | null;
+  ide?: boolean | null;
+  verbose?: boolean | null;
+}
+
+/**
+ * Discriminated union of Request variants — exactly one shape per Op.
+ * Adding a new Op requires extending this union *and* every `switch`
+ * over `req.op` (the dispatcher uses an exhaustive-never check so the
+ * compiler enforces this).
  *
  * The wire shape uses snake_case keys (matching Go's `json:` tags). All
  * non-required fields are optional on the wire; the listener tolerates
  * missing keys.
- *
- * Override fields (Model/Effort/PermissionMode/AllowedTools/Agent and the
- * four bools) are applicable to OpRestart/OpSwitch/OpSpawn. Empty/undef
- * string values mean "preserve what was on the original command line"
- * (for restart/transfer) or "don't pass this flag" (for spawn). For
- * boolean fields: undefined = preserve existing; true = ensure present;
- * false = ensure absent.
  */
-export interface Request {
-  op: Op;
+export type Request =
+  | RestartRequest
+  | SwitchRequest
+  | SpawnRequest
+  | CopyRequest;
 
-  /** OpRestart: required UUID — the current Claude session. */
+/** OpRestart: restart the current session in place. */
+export interface RestartRequest extends RequestOverrides {
+  op: 'restart';
+  /** Required UUID — the current Claude session. */
+  session_id?: string;
+}
+
+/** OpSwitch: kill claude and relaunch at destination. */
+export interface SwitchRequest extends RequestOverrides {
+  op: 'switch';
+  /** Destination project ref. */
+  destination?: string;
+  /** 3-6 word kebab-case session topic. */
+  name?: string;
+  /** Continuity summary content. */
+  summary?: string;
+  /**
+   * Optional UUID for live-permission-mode auto-capture. Used to read the
+   * session JSONL when no explicit permission_mode override was set.
+   */
   session_id?: string;
+  /**
+   * Deprecated; no longer read by the server. Left on the type so older
+   * clients that still serialize confirmed=true don't break.
+   */
+  confirmed?: boolean;
+}
 
-  /** OpSwitch / OpSpawn: destination project ref. */
+/** OpSpawn: launch a sibling fnclaude in a new window. */
+export interface SpawnRequest extends RequestOverrides {
+  op: 'spawn';
+  /** Destination project ref. */
   destination?: string;
-  /** OpSwitch / OpSpawn: 3-6 word kebab-case session topic. */
+  /** 3-6 word kebab-case session topic. */
   name?: string;
-  /** OpSwitch / OpSpawn: continuity summary content. */
+  /** Continuity summary content. */
   summary?: string;
   /**
    * Deprecated; no longer read by the server. Left on the type so older
    * clients that still serialize confirmed=true don't break.
    */
   confirmed?: boolean;
+}
 
-  /** OpCopy: text to write to the clipboard. */
+/** OpCopy: write text to the clipboard. Carries no override fields. */
+export interface CopyRequest {
+  op: 'copy_to_clipboard';
+  /** Text to write to the clipboard. */
   text?: string;
-
-  // Overrides.
-  model?: string;
-  effort?: string;
-  permission_mode?: string;
-  allowed_tools?: string;
-  agent?: string;
-  brief?: boolean | null;
-  chrome?: boolean | null;
-  ide?: boolean | null;
-  verbose?: boolean | null;
 }
 
 // ── Response ───────────────────────────────────────────────────────────────