@fnclaude/cli 0.7.2 → 0.7.3

package/src/argv.ts

@@ -16,22 +16,22 @@
 //   4. System-prompt fragment injection: --append-system-prompt <merged-text>
 //      composed by selectFragments + withAppendedSystemPrompts.
 
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
-import process from 'node:process';
-import type { Args } from './args.js';
+import type { InterceptedArgs } from './args.js';
 import {
   nameInPassthrough as _nameInPassthrough,
   settingSourcesInPassthrough,
   tokenInPassthrough,
-} from './argParser.js';
+} from './passthrough.js';
 import type { Config } from './config.js';
+import { resolveSelfPath } from './paths.js';
 import { isInteractiveSession, selectFragments, type PromptSet } from './prompts.js';
 
 // Re-export the passthrough inspection helpers from their canonical home so
 // callers can reach them via "./argv.js" — mirrors the Go reference where
 // they sit next to buildArgv. The single-source-of-truth implementation
-// stays in argParser.ts.
+// stays in passthrough.ts.
 export { settingSourcesInPassthrough, tokenInPassthrough };
 
 // ── MCP self-injection ─────────────────────────────────────────────────────
@@ -58,14 +58,7 @@ interface McpConfigEntry {
  * → repo/bin/fnclaude symlink resolves to the real binary path).
  */
 export function buildFnclaudeMCPConfigJSON(noop: boolean): string | null {
-  const argv1 = process.argv.length > 1 ? process.argv[1] : undefined;
-  let exe = argv1 !== undefined && argv1 !== '' ? argv1 : process.execPath;
-
-  try {
-    exe = realpathSync(exe);
-  } catch {
-    // Fall back to unresolved path; symlink resolution failure isn't fatal.
-  }
+  const exe = resolveSelfPath();
 
   const args = ['mcp'];
   if (noop) args.push('--noop');
@@ -123,17 +116,23 @@ export function withAppendedSystemPrompts(
 // ── buildArgv ──────────────────────────────────────────────────────────────
 
 /**
- * buildArgv constructs the argv slice to exec claude with, given the parsed
- * fnclaude args, the user's shell cwd (used to resolve relative extra-dir
- * paths), the loaded config, and the set of prompt fragments loaded from
- * the install dir.
+ * buildArgv constructs the argv slice to exec claude with, given the
+ * fnclaude args at their final pipeline stage (`InterceptedArgs` — the
+ * intercept must have run so `worktreeMatched` is meaningful), the user's
+ * shell cwd (used to resolve relative extra-dir paths), the loaded config,
+ * and the set of prompt fragments loaded from the install dir.
+ *
+ * Accepting `InterceptedArgs` makes the ordering invariant a compile-time
+ * check: passing a `ParsedArgs` or `ResolvedArgs` is a type error,
+ * preventing the auto-tmux gate from reading a stale `worktreeMatched`
+ * value the parse stage couldn't know.
  *
  * `shellCWD` is the process working directory at fnclaude startup —
  * normally `process.cwd()`. It's threaded through (rather than reached for
  * directly) so tests can pin it without `chdir`-ing.
  */
 export function buildArgv(
-  a: Args,
+  a: InterceptedArgs,
   shellCWD: string,
   cfg: Config,
   prompts: PromptSet,
@@ -200,5 +199,5 @@ export function buildArgv(
 }
 
 // Re-export so callers that already import nameInPassthrough from argv.ts
-// (parity with the Go file layout) don't have to reach into argParser.
+// (parity with the Go file layout) don't have to reach into passthrough.
 export const nameInPassthrough = _nameInPassthrough;

package/src/config.ts

@@ -22,7 +22,14 @@ function home(): string {
 // ── public types ───────────────────────────────────────────────────────────
 
 export type TmuxMode = 'never' | 'worktree';
-export type HandoffMode = 'never' | 'ask' | string; // or a non-negative integer-as-string
+/**
+ * `'never'`, `'ask'`, or a non-negative integer-as-string (e.g. `'5'`).
+ *
+ * The template-literal `${number}` variant narrows correctly: a bare
+ * `string` would collapse the union, so runtime validation gates env-var
+ * and config-file inputs into this type via `normalizeHandoffMode`.
+ */
+export type HandoffMode = 'never' | 'ask' | `${number}`;
 
 export interface NameConfig {
   /** Model used for the noop name session. */
@@ -121,34 +128,48 @@ export function parseBoolEnv(v: string): boolean {
   }
 }
 
+/**
+ * Result of a normalize-mode call: the validated value plus an optional
+ * warning describing any fallback that was applied. Callers thread the
+ * warning into their own returned warnings list rather than mutating a
+ * module-global sink.
+ */
+export interface NormalizeResult<T> {
+  value: T;
+  warning: string | null;
+}
+
 /**
  * normalizeTmuxMode validates against the supported set and falls back to
- * "never" for anything else, emitting a stderr warning (except for the
- * empty-string case, which is the absent-value default path).
+ * "never" for anything else, returning the fallback value and an optional
+ * warning describing what was rejected (the empty-string case is the
+ * absent-value default path and produces no warning).
  */
-export function normalizeTmuxMode(v: string): TmuxMode {
-  if (v === 'never' || v === 'worktree') return v;
-  if (v === '') return 'never';
-  warn(
-    `fnclaude: auto.tmux=${JSON.stringify(v)} is not a valid mode (use "never" or "worktree"), falling back to "never"`,
-  );
-  return 'never';
+export function normalizeTmuxMode(v: string): NormalizeResult<TmuxMode> {
+  if (v === 'never' || v === 'worktree') return { value: v, warning: null };
+  if (v === '') return { value: 'never', warning: null };
+  return {
+    value: 'never',
+    warning: `fnclaude: auto.tmux=${JSON.stringify(v)} is not a valid mode (use "never" or "worktree"), falling back to "never"`,
+  };
 }
 
 /**
  * normalizeHandoffMode validates against the supported set and falls back
- * to "ask" for anything else (with a stderr warning, except empty string).
- * Valid: "never", "ask", or a non-negative integer (as a string).
+ * to "ask" for anything else (with an optional warning, except empty
+ * string). Valid: "never", "ask", or a non-negative integer (as a string).
  */
-export function normalizeHandoffMode(v: string): HandoffMode {
-  if (v === 'never' || v === 'ask') return v;
-  if (v === '') return 'ask';
-  // Non-negative integer (no decimal, no unit).
-  if (/^\d+$/.test(v)) return v;
-  warn(
-    `fnclaude: auto.handoff=${JSON.stringify(v)} is not a valid mode (use "never", "ask", or a non-negative integer), falling back to "ask"`,
-  );
-  return 'ask';
+export function normalizeHandoffMode(v: string): NormalizeResult<HandoffMode> {
+  if (v === 'never' || v === 'ask') return { value: v, warning: null };
+  if (v === '') return { value: 'ask', warning: null };
+  // Non-negative integer (no decimal, no unit). The regex guarantees the
+  // template-literal shape, which TS's type narrowing can't infer from a
+  // .test() call alone — so assert it explicitly once.
+  if (/^\d+$/.test(v)) return { value: v as `${number}`, warning: null };
+  return {
+    value: 'ask',
+    warning: `fnclaude: auto.handoff=${JSON.stringify(v)} is not a valid mode (use "never", "ask", or a non-negative integer), falling back to "ask"`,
+  };
 }
 
 /**
@@ -188,23 +209,6 @@ export function parseDuration(s: string): number | null {
   return total;
 }
 
-// Deferred stderr warnings — fnclaude collects these during config load
-// and flushes them via the shared warnings sink at a sensible time (after
-// claude exits, in run()). The local `deferredWarnings` export is kept
-// for backward compatibility with callers that imported it; it shadows
-// the shared sink's view of config-emitted warnings only.
-export const deferredWarnings: string[] = [];
-
-// Defer-import the shared warnings module so config remains import-cycle-
-// safe and any test that loads config in isolation still works without
-// the warnings module having been initialized.
-import { warn as globalWarn } from './warnings.js';
-
-function warn(msg: string): void {
-  deferredWarnings.push(msg);
-  globalWarn(msg);
-}
-
 // ── raw TOML shape (mirrors the Go rawConfig) ──────────────────────────────
 
 interface RawConfig {
@@ -228,26 +232,46 @@ interface RawConfig {
 
 // ── loadConfig ─────────────────────────────────────────────────────────────
 
+/**
+ * Result of `loadConfig` — the merged Config plus any non-fatal warnings
+ * raised during the load (malformed file, invalid mode value, bogus
+ * duration, etc.). The caller threads warnings into the deferred-flush
+ * mechanism in `main.ts`; this module owns no global mutable state.
+ */
+export interface LoadConfigResult {
+  config: Config;
+  warnings: readonly string[];
+}
+
 /**
  * loadConfig loads the configuration from the config file and environment
  * variables, merging over built-in defaults. Order of precedence:
  *
  *   env var > config file > built-in default
  *
- * A missing config file is not an error. A malformed config file queues a
- * warning and falls back to defaults.
+ * A missing config file is not an error. A malformed config file produces
+ * a warning and falls back to defaults.
  */
-export function loadConfig(): Config {
+export function loadConfig(): LoadConfigResult {
   const cfg = defaultConfig();
+  const warnings: string[] = [];
   const path = configFilePath();
 
+  const recordNormalize = <T>(
+    r: NormalizeResult<T>,
+    set: (v: T) => void,
+  ): void => {
+    set(r.value);
+    if (r.warning !== null) warnings.push(r.warning);
+  };
+
   if (existsSync(path)) {
     let raw: RawConfig | null = null;
     try {
       const body = readFileSync(path, 'utf8');
       raw = Bun.TOML.parse(body) as RawConfig;
     } catch (err) {
-      warn(
+      warnings.push(
         `fnclaude: config file ${path} is malformed, using defaults: ${(err as Error).message}`,
       );
       raw = null;
@@ -259,7 +283,7 @@ export function loadConfig(): Config {
         if (d !== null) {
           cfg.name.timeout = d;
         } else {
-          warn(
+          warnings.push(
             `fnclaude: invalid timeout ${JSON.stringify(raw.name.timeout)} in config, using default`,
           );
         }
@@ -268,10 +292,14 @@ export function loadConfig(): Config {
         cfg.name.quietMissingAPIKey = raw.name.quiet_missing_api_key;
       }
       if (typeof raw.auto?.tmux === 'string' && raw.auto.tmux !== '') {
-        cfg.auto.tmux = raw.auto.tmux as TmuxMode;
+        recordNormalize(normalizeTmuxMode(raw.auto.tmux), (v) => {
+          cfg.auto.tmux = v;
+        });
       }
       if (typeof raw.auto?.handoff === 'string' && raw.auto.handoff !== '') {
-        cfg.auto.handoff = raw.auto.handoff;
+        recordNormalize(normalizeHandoffMode(raw.auto.handoff), (v) => {
+          cfg.auto.handoff = v;
+        });
       }
       if (
         typeof raw.auto?.spawn_command === 'string' &&
@@ -293,7 +321,7 @@ export function loadConfig(): Config {
     if (d !== null) {
       cfg.name.timeout = d;
     } else {
-      warn(
+      warnings.push(
         `fnclaude: invalid FNCLAUDE_NAME_TIMEOUT ${JSON.stringify(e.FNCLAUDE_NAME_TIMEOUT)}, using current value`,
       );
     }
@@ -301,14 +329,19 @@ export function loadConfig(): Config {
   if (e.FNCLAUDE_QUIET_MISSING_API_KEY) {
     cfg.name.quietMissingAPIKey = parseBoolEnv(e.FNCLAUDE_QUIET_MISSING_API_KEY);
   }
-  if (e.FNCLAUDE_TMUX) cfg.auto.tmux = e.FNCLAUDE_TMUX as TmuxMode;
-  if (e.FNCLAUDE_HANDOFF) cfg.auto.handoff = e.FNCLAUDE_HANDOFF;
+  if (e.FNCLAUDE_TMUX) {
+    recordNormalize(normalizeTmuxMode(e.FNCLAUDE_TMUX), (v) => {
+      cfg.auto.tmux = v;
+    });
+  }
+  if (e.FNCLAUDE_HANDOFF) {
+    recordNormalize(normalizeHandoffMode(e.FNCLAUDE_HANDOFF), (v) => {
+      cfg.auto.handoff = v;
+    });
+  }
   if (e.FNCLAUDE_SPAWN_COMMAND) cfg.auto.spawnCommand = e.FNCLAUDE_SPAWN_COMMAND;
 
-  cfg.auto.tmux = normalizeTmuxMode(cfg.auto.tmux);
-  cfg.auto.handoff = normalizeHandoffMode(cfg.auto.handoff);
-
-  return cfg;
+  return { config: cfg, warnings };
 }
 
 // ── envFromConfig ─────────────────────────────────────────────────────────

package/src/help.ts

@@ -135,5 +135,5 @@ Examples:
   fnclaude ~/src/proj -- "fix the bug"    # auto-name from prompt
   fnclaude -A docs/ ~/src/proj -V         # ergonomic flag form
 
-For more, see https://github.com/fnrhombus/fnclaude
+For more, see https://github.com/fnclaude/fnclaude
 `;

package/src/hostAliases.ts

@@ -27,11 +27,22 @@ export function hostAliasesUserPath(home: string): string {
   return join(home, '.local', 'share', 'fnrhombus', 'host-aliases.json');
 }
 
+/**
+ * Result of a host-aliases load: the merged alias map plus any non-fatal
+ * warnings (e.g. malformed files that were skipped). Mirrors
+ * `LoadConfigResult` so the caller can thread warnings into the deferred
+ * flush.
+ */
+export interface LoadHostAliasesResult {
+  aliases: Record<string, string>;
+  warnings: readonly string[];
+}
+
 /**
  * Read both files (if present) and merge them, user-level winning per
  * key. Either or both missing returns whatever is available (or empty).
  */
-export function loadHostAliases(home: string): Record<string, string> {
+export function loadHostAliases(home: string): LoadHostAliasesResult {
   return mergeHostAliases([HOST_ALIASES_SYSTEM_PATH, hostAliasesUserPath(home)]);
 }
 
@@ -40,43 +51,57 @@ export function loadHostAliases(home: string): Record<string, string> {
  * winning over earlier ones. Callers order system-first, user-second so
  * user wins on conflict.
  */
-export function mergeHostAliases(paths: string[]): Record<string, string> {
+export function mergeHostAliases(paths: string[]): LoadHostAliasesResult {
   const merged: Record<string, string> = {};
+  const warnings: string[] = [];
   for (const p of paths) {
-    const entries = readHostAliasesFile(p);
-    for (const k of Object.keys(entries)) {
-      merged[k] = entries[k] as string;
+    const { aliases, warning } = readHostAliasesFile(p);
+    if (warning !== null) warnings.push(warning);
+    for (const k of Object.keys(aliases)) {
+      merged[k] = aliases[k] as string;
     }
   }
-  return merged;
+  return { aliases: merged, warnings };
+}
+
+export interface ReadHostAliasesFileResult {
+  aliases: Record<string, string>;
+  warning: string | null;
 }
 
 /**
- * Parse one alias file. Missing file, malformed JSON, non-object root,
- * and non-string values all degrade to "no aliases from this file"
- * silently — same fail-soft posture as the JS plugin.
+ * Parse one alias file. Missing file is the common path and stays
+ * silent. Malformed JSON or non-object roots produce a warning so the
+ * user can fix the file rather than wondering why their aliases don't
+ * apply. Non-string values are silently dropped (mirrors the JS plugin).
  */
-export function readHostAliasesFile(path: string): Record<string, string> {
+export function readHostAliasesFile(path: string): ReadHostAliasesFileResult {
   let data: string;
   try {
     data = readFileSync(path, 'utf8');
   } catch {
-    return {};
+    return { aliases: {}, warning: null };
   }
   let raw: unknown;
   try {
     raw = JSON.parse(data);
-  } catch {
-    return {};
+  } catch (err) {
+    return {
+      aliases: {},
+      warning: `fnclaude: host-aliases file ${path} is malformed, skipping: ${(err as Error).message}`,
+    };
   }
   if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-    return {};
+    return {
+      aliases: {},
+      warning: `fnclaude: host-aliases file ${path} has a non-object root, skipping`,
+    };
   }
   const out: Record<string, string> = {};
   for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
     if (typeof v === 'string') out[k] = v;
   }
-  return out;
+  return { aliases: out, warning: null };
 }
 
 /**

package/src/index.ts

@@ -9,7 +9,7 @@ export {
   parseRepoRef,
   type RepoRef,
 } from './repoRef.js';
-export { expandTildePath } from './paths.js';
+export { expandTildePath, resolveSelfPath } from './paths.js';
 export {
   findPromptsDir,
   isInteractiveSession,
@@ -55,9 +55,14 @@ export {
   readRequest,
   readResponse,
   type Action,
+  type CopyRequest,
   type Op,
   type Request,
+  type RequestOverrides,
   type Response,
+  type RestartRequest,
+  type SpawnRequest,
+  type SwitchRequest,
 } from './mcp/protocol.js';
 export {
   SocketListener,
@@ -83,9 +88,10 @@ export {
 // embedding hosts that want to render their own help.
 export { helpText, setVersion, version, wantsHelp, wantsVersion } from './help.js';
 
-// Warning sink + flush. Test helpers (pendingWarnings, clearWarnings) are
-// re-exported so harness code can introspect/reset between cases.
-export { clearWarnings, flushWarnings, pendingWarnings, warn } from './warnings.js';
+// Warning flush. Loaders (loadConfig / loadRepoSettings / loadHostAliases
+// / loadPrompts) return their warnings; flushWarnings drains a provided
+// list to stderr.
+export { flushWarnings } from './warnings.js';
 
 // noop dir seeding (noop fallback when fnclaude is invoked with no path).
 export { NOOP_HANDOFF_TEMPLATE, defaultNoopDir, seedNoop } from './noop.js';
@@ -94,7 +100,7 @@ export { NOOP_HANDOFF_TEMPLATE, defaultNoopDir, seedNoop } from './noop.js';
 export { silentRelaunch, silentRelaunchHandoff, spawnAndExit } from './silentRelaunch.js';
 
 // Top-level run loop + entry point.
-export { main, run, type RunDeps } from './main.js';
+export { main, run, type RunConfig, type RunDeps, type RunIO } from './main.js';
 
 // PTY runner + shared helpers (ring buffer, cross-cwd detection,
 // reconstructArgv, ensureCWD).