@fnclaude/cli 1.1.0 → 2.0.0

package/src/sessionState.ts

@@ -1,220 +0,0 @@
-// Port of src/session_state.go (fnclaude/fnclaude Go reference).
-//
-// CWD encoding for Claude Code's project dir naming scheme, and JSONL
-// permission-mode last-wins scan over a session log.
-
-import { appendFileSync, readFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-function home(): string {
-  return process.env.HOME ?? homedir();
-}
-
-/**
- * Encode a cwd into the directory name Claude Code uses under
- * `~/.claude/projects/`. The scheme: every character that is NOT in
- * `[A-Za-z0-9-]` is replaced with `-`. An absolute path like
- * `/home/tom/src/fnclaude@fnrhombus` becomes
- * `-home-tom-src-fnclaude-fnrhombus`. Verified empirically against real
- * on-disk session directories — claude replaces `/`, `@`, `+`, `_`, `.`,
- * and likely every other non-alphanumeric; the safe rule is the allowlist
- * above.
- */
-export function encodeCWDForProjects(cwd: string): string {
-  let out = '';
-  for (const ch of cwd) {
-    const code = ch.charCodeAt(0);
-    const isLower = code >= 97 && code <= 122;
-    const isUpper = code >= 65 && code <= 90;
-    const isDigit = code >= 48 && code <= 57;
-    const isDash = ch === '-';
-    out += isLower || isUpper || isDigit || isDash ? ch : '-';
-  }
-  return out;
-}
-
-/**
- * Resolve the path to claude's per-session JSONL log for `sessionID`
- * running in `launchCWD`. The file lives under `~/.claude/projects/`
- * using the encoded-cwd directory name. The caller is responsible for
- * checking existence.
- */
-export function sessionJSONLPath(launchCWD: string, sessionID: string): string {
-  const encoded = encodeCWDForProjects(launchCWD);
-  return join(home(), '.claude', 'projects', encoded, `${sessionID}.jsonl`);
-}
-
-/**
- * Return the most recent permission-mode value recorded in claude's
- * session JSONL for `sessionID` under `launchCWD`.
- *
- * Claude Code persists permission mode by appending records of the form
- *
- *   {"type":"permission-mode","permissionMode":"acceptEdits|auto|bypassPermissions|default|dontAsk|plan"}
- *
- * to the per-session JSONL. The file is append-only, so a forward linear
- * scan with last-wins semantics is correct (and adequate at the file
- * sizes real sessions reach).
- *
- * Returns `undefined` if the file is missing, unreadable, or contains no
- * permission-mode records. Callers should fall back to startup-arg
- * preservation in that case.
- *
- * Only records whose `type` field is literally `"permission-mode"` are
- * considered. Other record types (user / assistant / system messages) may
- * also serialize a `permissionMode` field, but that's a cached snapshot —
- * not authoritative.
- */
-export function readLivePermissionMode(
-  launchCWD: string,
-  sessionID: string,
-): string | undefined {
-  const path = sessionJSONLPath(launchCWD, sessionID);
-  let data: string;
-  try {
-    data = readFileSync(path, 'utf8');
-  } catch {
-    return undefined;
-  }
-  let latest: string | undefined;
-  for (const line of data.split('\n')) {
-    if (line.length === 0) continue;
-    let r: { type?: unknown; permissionMode?: unknown };
-    try {
-      r = JSON.parse(line) as typeof r;
-    } catch {
-      continue; // malformed line — ignore
-    }
-    if (r.type === 'permission-mode' && typeof r.permissionMode === 'string' && r.permissionMode) {
-      latest = r.permissionMode;
-    }
-  }
-  return latest;
-}
-
-/**
- * Overrides that may have landed alongside the restart. When any of these
- * are set the appended reminder names them so the resumed model can briefly
- * acknowledge the change before continuing the pre-restart work.
- */
-export interface RestartReminderOverrides {
-  model?: string;
-  effort?: string;
-  permissionMode?: string;
-  agent?: string;
-  /** True iff `--ide` is being added on the relaunch. */
-  ide?: boolean;
-}
-
-/**
- * Read the trailing entries of `data` and return the most recent `uuid`
- * field, or `undefined` if none found. Used to link the appended reminder
- * into the JSONL parent-chain.
- */
-function lastEntryUUID(data: string): string | undefined {
-  const lines = data.split('\n');
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    if (!line || line.length === 0) continue;
-    let parsed: { uuid?: unknown };
-    try {
-      parsed = JSON.parse(line) as typeof parsed;
-    } catch {
-      continue;
-    }
-    if (typeof parsed.uuid === 'string' && parsed.uuid.length > 0) {
-      return parsed.uuid;
-    }
-  }
-  return undefined;
-}
-
-/** Render the system-reminder body text, optionally naming overrides. */
-export function renderRestartReminderContent(
-  overrides?: RestartReminderOverrides,
-): string {
-  const parts: string[] = [];
-  if (overrides?.model) {
-    parts.push(`model swap to ${overrides.model}`);
-  }
-  if (overrides?.effort) {
-    parts.push(`effort=${overrides.effort}`);
-  }
-  if (overrides?.permissionMode) {
-    parts.push(`permission-mode=${overrides.permissionMode}`);
-  }
-  if (overrides?.agent) {
-    parts.push(`agent=${overrides.agent}`);
-  }
-  if (overrides?.ide) {
-    parts.push('--ide connected');
-  }
-  const overrideClause =
-    parts.length > 0
-      ? ` Restart-specific overrides applied: ${parts.join(', ')} — acknowledge briefly, then continue.`
-      : '';
-  return (
-    '<system-reminder>\n' +
-    'This session was restarted via fnc_restart (all prior context and the ' +
-    'session JSONL are preserved). Resume the work that was in flight ' +
-    'before the restart — finish the task, monitor what you were ' +
-    'monitoring, surface results — rather than treating this as a fresh ' +
-    'session.' +
-    overrideClause +
-    '\n</system-reminder>'
-  );
-}
-
-/**
- * Append an `isMeta:true` user-message bearing a `<system-reminder>` block
- * to the session JSONL at `launchCWD` / `sessionID`. Best-effort: missing
- * or unreadable JSONL is silently tolerated (the restart should still
- * proceed; the reminder is a UX nicety, not a hard requirement).
- *
- * Shape matches the entries Claude Code itself emits for inline reminders
- * — `type:"user"`, `message:{role:"user",content:"<system-reminder>…</system-reminder>"}`,
- * `isMeta:true`. The `parentUuid` is linked to the most recent entry's
- * `uuid` so the resumed session reads it as a fresh terminal user turn.
- */
-export function appendRestartReminder(
-  launchCWD: string,
-  sessionID: string,
-  overrides?: RestartReminderOverrides,
-): void {
-  const path = sessionJSONLPath(launchCWD, sessionID);
-  let existing: string;
-  try {
-    existing = readFileSync(path, 'utf8');
-  } catch {
-    // No JSONL — nothing to append to. The relaunched claude will start
-    // fresh anyway, so the reminder would be off-target.
-    return;
-  }
-  // JSONL parentUuid is on the wire — keep null encoding for "no parent"
-  // entries to match Claude Code's own writer.
-  const parentUuid = lastEntryUUID(existing) ?? null;
-  const entry = {
-    parentUuid,
-    isSidechain: false,
-    type: 'user' as const,
-    message: {
-      role: 'user' as const,
-      content: renderRestartReminderContent(overrides),
-    },
-    isMeta: true,
-    uuid: randomUUID(),
-    timestamp: new Date().toISOString(),
-    userType: 'external' as const,
-    cwd: launchCWD,
-    sessionId: sessionID,
-  };
-  try {
-    appendFileSync(path, `${JSON.stringify(entry)}\n`);
-  } catch {
-    // Best-effort — disk full, permission denied, raced unlink, etc. The
-    // restart proceeds; user gets the historical "Restarted." idle behavior
-    // rather than a hard failure.
-  }
-}

package/src/silentRelaunch.ts

@@ -1,178 +0,0 @@
-// Port of silentRelaunch / silentRelaunchHandoff from src/pty_run_unix.go +
-// src/pty_run_windows.go in the Go reference.
-//
-// silentRelaunch is what fnclaude calls when claude has exited with a
-// cross-cwd-resume marker in its tail output (user selected a session from
-// another directory via the Ctrl+A picker). It replaces the current process
-// with a fresh fnclaude pointed at the new cwd + session UUID.
-//
-// silentRelaunchHandoff is the auto-handoff sibling: invoked when the
-// AF_UNIX socket listener received an OpRestart or OpSwitch confirmation
-// during the run, killed claude, and stashed the argv for the next launch.
-//
-// On POSIX both use `process.execve` (Bun 1.3.14+) to replace the process
-// image — semantically identical to Go's `syscall.Exec`. On Windows execve
-// throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`, so we fall back to spawn-
-// and-propagate-exit-code (mirrors the Go Windows stub).
-
-import { spawn } from 'node:child_process';
-import process from 'node:process';
-import { clearScreen, reconstructArgv } from './pty.js';
-import { resolveSelfPath } from './paths.js';
-
-// `process.execve` is a Bun-native POSIX-only API (1.3.14+). @types/bun
-// hasn't typed it yet — declare the shape inline so TS strict mode is happy.
-// The signature mirrors Bun's native binding: argv[0] is conventionally the
-// program name; env is the full environment (KEY=VALUE strings).
-interface ExecveProcess {
-  execve?: (path: string, argv: string[], env: Record<string, string | undefined>) => never;
-}
-
-/**
- * Replace the current process image with a fresh fnclaude invocation, using
- * `dest` as the new cwd and `uuid` as the session to resume.
- *
- * On POSIX this NEVER returns on success — execve replaces the running
- * process. On failure it writes to stderr and returns, letting the caller
- * propagate claude's exit code.
- *
- * On Windows execve is unavailable; we approximate by spawning a fresh
- * fnclaude as a child, waiting for it to exit, and calling `process.exit`
- * with its code (NEVER returns on success on Windows either, but for a
- * different reason — the exit() in the child-completion handler).
- *
- * `origArgs` is the original `process.argv.slice(2)` from the launching
- * fnclaude invocation; reconstructArgv preserves leading magic words and
- * post-positional flags while swapping in the new cwd + --resume <uuid>.
- */
-export function silentRelaunch(
-  origArgs: readonly string[],
-  dest: string,
-  uuid: string,
-  out: NodeJS.WriteStream = process.stdout,
-): void {
-  let self: string;
-  try {
-    self = resolveSelfPath();
-  } catch (err) {
-    process.stderr.write(
-      `fnclaude: cannot determine executable, cannot relaunch: ${(err as Error).message}\n`,
-    );
-    return;
-  }
-
-  const newArgs = reconstructArgv(origArgs, dest, uuid);
-
-  clearScreen(out);
-
-  // execve argv[0] is conventionally the program name (matches Go's
-  // syscall.Exec contract).
-  const argv = [self, ...newArgs];
-  execOrSpawn(self, argv);
-}
-
-/**
- * Replace the current process with a fresh fnclaude using `argv` as the new
- * arg list. The socket listener has already constructed argv with the
- * leading "fnclaude" token stripped; we prepend the self path as argv[0].
- *
- * Same POSIX vs Windows behavior as `silentRelaunch`.
- */
-export function silentRelaunchHandoff(
-  argv: readonly string[],
-  out: NodeJS.WriteStream = process.stdout,
-): void {
-  let self: string;
-  try {
-    self = resolveSelfPath();
-  } catch (err) {
-    process.stderr.write(
-      `fnclaude: cannot determine executable, cannot relaunch: ${(err as Error).message}\n`,
-    );
-    return;
-  }
-
-  clearScreen(out);
-
-  const full = [self, ...argv];
-  execOrSpawn(self, full, /* handoff */ true);
-}
-
-/**
- * Shared dispatcher: POSIX uses execve (process replacement); Windows
- * spawns a fresh child and exits with its code.
- *
- * `handoff` distinguishes the error message text so logs disambiguate the
- * two callsites.
- */
-function execOrSpawn(self: string, argv: string[], handoff = false): void {
-  const label = handoff ? 'handoff exec' : 'exec relaunch';
-
-  if (process.platform === 'win32') {
-    // No execve on Windows. Approximate process replacement: spawn a child
-    // with inherited stdio and exit with its code once it finishes.
-    spawnAndExit(self, argv);
-    return; // unreachable in practice — spawnAndExit calls process.exit
-  }
-
-  // POSIX path — call Bun's native execve. NEVER returns on success.
-  //
-  // NOTE: `process.env` here is deliberate (mirrors Go's `os.Environ()`).
-  // The exec replaces the current process with a fresh fnclaude, NOT
-  // claude. The relaunched fnclaude will reload its own config and
-  // re-apply [exec.env] before starting its claude child — merging config
-  // env in here would double-inject those vars into the relaunched
-  // fnclaude's own environment.
-  //
-  // Behavioral note: Bun's `process.execve` is uncatchable on failure —
-  // when the kernel rejects the exec (ENOENT / EACCES / ENOEXEC / etc.)
-  // Bun's runtime prints a SystemError to stderr and aborts the process
-  // with SIGABRT (exit code 134). That differs from Go's `syscall.Exec`
-  // which returns the error. The Go code's "if exec fails, fall through"
-  // path is therefore unreachable on Bun — we get an abort instead.
-  //
-  // Implication for callers: don't rely on a returnable execve failure as
-  // a recoverable path; any silentRelaunch* invocation that doesn't replace
-  // the process is fatal. In practice that's the right semantics — if the
-  // self path is unusable, we can't continue, and a noisy abort is more
-  // informative than silently propagating a stale exit code.
-  const execve = (process as ExecveProcess).execve;
-  if (typeof execve !== 'function') {
-    process.stderr.write(
-      `fnclaude: process.execve unavailable on this runtime (Bun 1.3.14+ required); cannot ${label}\n`,
-    );
-    return;
-  }
-
-  // argv[0] is conventionally the program name; pass the full argv slice
-  // with self at the front. Never returns on success; SIGABRTs on failure.
-  execve(self, argv, process.env);
-}
-
-/**
- * Windows fallback for silentRelaunch* — spawn a child fnclaude with
- * inherited stdio, wait for it to exit, and call process.exit with its
- * code. Mirrors src/pty_run_windows.go's silentRelaunchHandoff.
- *
- * Exported for testability; production callers go through execOrSpawn.
- */
-export function spawnAndExit(self: string, argv: string[]): void {
-  // argv[0] is the program name slot (matches POSIX execve convention).
-  // For child_process.spawn we pass the remaining args.
-  const child = spawn(self, argv.slice(1), { stdio: 'inherit' });
-  child.on('exit', (code, signal) => {
-    if (typeof code === 'number') {
-      process.exit(code);
-    } else if (signal !== null) {
-      // Signaled: emit non-zero exit. Match POSIX shell convention of
-      // 128 + signal number where we can map it; default to 1.
-      process.exit(1);
-    } else {
-      process.exit(1);
-    }
-  });
-  child.on('error', (err) => {
-    process.stderr.write(`fnclaude: handoff exec failed: ${err.message}\n`);
-    process.exit(1);
-  });
-}

package/src/spawn.ts

@@ -1,163 +0,0 @@
-// Spawn a sibling fnclaude in a new terminal window. Ported from src/spawn.go
-// (fnclaude/fnclaude Go reference).
-//
-// spawnSibling opens a new terminal window (via tmux or a user-configured
-// launcher) and runs fnclaude there. It is "sibling, not child": the spawned
-// argv is a terminal-emulator command that itself launches fnclaude, so the
-// new session is unaffected when this process exits.
-//
-// The indirection via spawnFn lets tests inject a mock without launching
-// real processes.
-
-import process from 'node:process';
-import type { Config } from './config.js';
-import { resolveSelfPath } from './paths.js';
-import { substitute } from './template.js';
-
-// ── env cleaning ───────────────────────────────────────────────────────────
-
-/**
- * Drop env vars that would mislead the new fnclaude session:
- *
- *  - FNC_SOCKET: points at *this* session's listener. The sibling must
- *    compute its own; leaking ours makes it dial back into us.
- *  - FNCLAUDE_HANDOFF: injected for *this* claude child; not the sibling's.
- *  - CLAUDE_CODE_SESSION_ID: scopes to this session only.
- *
- * Everything else (PATH, XDG_*, exec.env contributions) passes through so
- * the sibling inherits the same user environment.
- */
-export function cleanEnvForSpawn(env: string[]): string[] {
-  const drop = new Set(['FNC_SOCKET', 'FNCLAUDE_HANDOFF', 'CLAUDE_CODE_SESSION_ID']);
-  const out: string[] = [];
-  for (const e of env) {
-    const eq = e.indexOf('=');
-    const key = eq < 0 ? e : e.slice(0, eq);
-    if (!drop.has(key)) out.push(e);
-  }
-  return out;
-}
-
-// ── autoDetectSpawnCommand ─────────────────────────────────────────────────
-
-/**
- * Return a built-in launcher template when the host environment unambiguously
- * declares how to open a new window. Empty string means no match — caller
- * falls back to paste-flow.
- *
- * Only $TMUX is detected. Being inside tmux is an explicit declaration of the
- * windowing layer; "open a new tmux window in this session" is unambiguously
- * what the user wants. Earlier versions also sniffed $KITTY_WINDOW_ID,
- * $TERM_PROGRAM=WezTerm, $WT_SESSION, etc. — those were heuristic
- * conveniences that failed silently for any unlisted terminal. One
- * mechanism (auto.spawnCommand) surfaced in the paste-flow message is
- * strictly better than an allowlist that grows forever.
- */
-export function autoDetectSpawnCommand(): string {
-  if (process.env.TMUX) {
-    return 'tmux new-window -d {bin} {dest} --name {name} @{summary}';
-  }
-  return '';
-}
-
-// ── buildSpawnArgv ─────────────────────────────────────────────────────────
-
-/**
- * Tokenize tmpl on whitespace then substitute the four supported placeholders
- * within each token. No shell involvement: each whitespace-delimited token
- * becomes one argv entry verbatim, so a {dest} expanding to a path with
- * spaces remains a single argv entry.
- */
-export function buildSpawnArgv(
-  tmpl: string,
-  bin: string,
-  dest: string,
-  name: string,
-  summary: string,
-): string[] {
-  const vars: Record<string, string> = { bin, dest, name, summary };
-  return tmpl.split(/\s+/).filter((t) => t.length > 0).map((t) => substitute(t, vars));
-}
-
-// ── SpawnFn type + spawnSibling ────────────────────────────────────────────
-
-/**
- * The function type that actually starts the process. Tests inject a mock;
- * production uses the default (Bun.spawn detached).
- *
- * Returns true when a launcher was resolved and started; false when no
- * launcher is configured and no terminal could be auto-detected (caller
- * falls back to paste-flow). Throws on resolution/start failure.
- */
-export type SpawnFn = (argv: string[], env: string[]) => void;
-
-/**
- * Default SpawnFn: invoke argv[0] with argv[1:] via Bun.spawn, detached.
- * We release the handle immediately — the launcher (tmux, etc.) typically
- * returns in milliseconds after dispatching the new window; we don't care
- * about its exit code.
- */
-function defaultSpawnFn(argv: string[], env: string[]): void {
-  const [cmd, ...args] = argv;
-  if (!cmd) throw new Error('spawn called with empty argv');
-  // Bun.spawn: env is a Record<string,string> or string[]. We pass the
-  // key=value array directly — Bun accepts it.
-  const proc = Bun.spawn([cmd, ...args], {
-    env: Object.fromEntries(
-      env.map((e) => {
-        const i = e.indexOf('=');
-        return i < 0 ? [e, ''] : [e.slice(0, i), e.slice(i + 1)];
-      }),
-    ),
-    stdin: null,
-    stdout: null,
-    stderr: null,
-  });
-  // Don't await — release and move on.
-  void proc.exited.catch(() => undefined);
-}
-
-/**
- * spawnSibling launches a sibling fnclaude in a new window.
- *
- * Returns true when a launcher was resolved and started successfully; false
- * when no launcher is configured AND no terminal could be auto-detected
- * (caller falls back to paste-flow). Throws when a launcher was resolved but
- * failed to start.
- *
- * extraArgs is appended after the template-expanded portion, e.g. override
- * flags the caller wants to pass to the new session.
- */
-export async function spawnSibling(
-  cfg: Config,
-  dest: string,
-  name: string,
-  summaryPath: string,
-  extraArgs: string[],
-  spawnFn: SpawnFn = defaultSpawnFn,
-): Promise<boolean> {
-  const bin = resolveSelfPath();
-
-  let tmpl = cfg.auto.spawnCommand;
-  if (!tmpl) {
-    tmpl = autoDetectSpawnCommand();
-  }
-  if (!tmpl) {
-    return false;
-  }
-
-  const argv = buildSpawnArgv(tmpl, bin, dest, name, summaryPath);
-  if (argv.length === 0) {
-    throw new Error(`spawn template produced empty argv: ${JSON.stringify(tmpl)}`);
-  }
-  const fullArgv = [...argv, ...extraArgs];
-
-  const env = cleanEnvForSpawn(
-    Object.entries(process.env)
-      .filter(([, v]) => v !== undefined)
-      .map(([k, v]) => `${k}=${v}`),
-  );
-
-  spawnFn(fullArgv, env);
-  return true;
-}

package/src/template.ts

@@ -1,44 +0,0 @@
-// Generic `{placeholder}` template substitution. Ported from src/spawn.go
-// (buildSpawnArgv's inline logic) with a factored-out substitute helper.
-//
-// Placeholder vocabulary: any `{key}` in the template string is replaced with
-// the corresponding value from vars. Missing keys are left verbatim — no
-// error — so callers can safely pass a template that uses only a subset of
-// available placeholders.
-//
-// Unterminated `{` (no matching `}`) is passed through literally, matching
-// the Go reference's behaviour.
-
-/**
- * substitute replaces every `{key}` occurrence in tpl with the corresponding
- * value from vars. Keys absent from vars are left as-is (`{key}` verbatim).
- */
-export function substitute(tpl: string, vars: Record<string, string>): string {
-  let out = '';
-  let i = 0;
-  while (i < tpl.length) {
-    const c = tpl[i]!;
-    if (c !== '{') {
-      out += c;
-      i++;
-      continue;
-    }
-    // Find the matching '}'
-    const end = tpl.indexOf('}', i + 1);
-    if (end < 0) {
-      // Unterminated '{' — pass through literally.
-      out += c;
-      i++;
-      continue;
-    }
-    const key = tpl.slice(i + 1, end);
-    if (Object.prototype.hasOwnProperty.call(vars, key)) {
-      out += vars[key]!;
-    } else {
-      // Unknown placeholder — leave verbatim.
-      out += tpl.slice(i, end + 1);
-    }
-    i = end + 1;
-  }
-  return out;
-}

package/src/warnings.ts

@@ -1,34 +0,0 @@
-// Deferred-warning sink. Ported from src/warnings.go in the Go reference.
-//
-// fnclaude accumulates non-fatal warnings issued during setup and flushes
-// them to stderr AFTER claude exits. Warnings printed before claude launches
-// scroll off-screen too fast to read; flushing on exit shows them in the
-// user's shell where they have time to actually be seen.
-//
-// There is no module-global queue here — every loader (loadConfig,
-// loadRepoSettings, loadHostAliases, loadPrompts) returns its warnings
-// alongside its result, and `main.ts` threads them into a single local
-// list that `flushWarnings` drains at the deferred-flush point. The old
-// global queue made test fixtures share state across files and forced
-// callers to know about a sink module they otherwise didn't depend on;
-// the explicit-thread shape is the fix.
-//
-// Fatal errors that prevent launch entirely (e.g. claude binary not on PATH)
-// should still print directly to stderr and exit non-zero — those don't
-// need deferring because there's no claude session about to drown them out.
-
-import process from 'node:process';
-
-/**
- * Print each warning to `stream` on its own line. Returns the number of
- * warnings written (useful for tests). Empty input is a no-op.
- */
-export function flushWarnings(
-  warnings: readonly string[],
-  stream: NodeJS.WriteStream = process.stderr,
-): number {
-  for (const w of warnings) {
-    stream.write(`${w}\n`);
-  }
-  return warnings.length;
-}