@fnclaude/cli 1.1.1 → 2.0.0

package/src/argv/preserve-args.ts

@@ -0,0 +1,333 @@
+/**
+ * Shared argv-preservation + override helpers.
+ *
+ * Foundation for transfer (§8.x) and silent-relaunch (§9.3) flows: both
+ * need to take the user's original argv, strip a destination/state-bound
+ * subset of flags, and optionally splice in caller-supplied overrides
+ * before re-execing fnc.
+ *
+ * Ports the Go canonical `preserveArgs` + `applyOverrides` from
+ * `fnclaude@fnrhombus/src/preserve_args.go` — same three-phase walk
+ * (magic → positionals → flags) and the same three-state override
+ * semantics (string non-empty replaces; bool undefined preserves; bool
+ * true/false enforces presence/absence).
+ *
+ * Pure module: no I/O, no spawn, no relaunch wiring. The §8/§9 commits
+ * compose this with side-effect code at the boundary.
+ */
+
+import { EFFORTS, MODELS } from './classify.ts';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transfer denylists (consumed by §8.x — re-exported here so callers don't
+// duplicate the lists)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Flag tokens stripped when preserving args across a project transfer
+ * (`fnc_switch_project`). These are destination-bound or session-state-
+ * bound — carrying them into the new session would either be wrong
+ * (--add-dir is the OLD project's dir, -A the OLD extras, --mcp-config
+ * the OLD config, --settings the OLD settings) or actively bogus
+ * (--resume / --continue / --fork-session / --from-pr reference the
+ * OLD session id or PR; -w/--worktree is the OLD worktree name; --name
+ * is the OLD session name and the transfer supplies a new one).
+ */
+export const TRANSFER_DENY_FLAGS: ReadonlySet<string> = new Set([
+  '-A',
+  '--also',
+  '--add-dir',
+  '--mcp-config',
+  '--settings',
+  '-w',
+  '--worktree',
+  '-P',
+  '--from-pr',
+  '-r',
+  '--resume',
+  '-c',
+  '--continue',
+  '-F',
+  '--fork-session',
+  '-n',
+  '--name',
+]);
+
+/**
+ * Subset of `TRANSFER_DENY_FLAGS` that may appear in bare (no-value) form.
+ * For these, `preserveArgs` only consumes the following token when it
+ * doesn't itself look like another flag — leaving subsequent flags alone.
+ */
+export const TRANSFER_DENY_BARE_OK: ReadonlySet<string> = new Set([
+  '-w',
+  '--worktree',
+  '-r',
+  '--resume',
+  '-c',
+  '--continue',
+  '-F',
+  '--fork-session',
+  '-P',
+  '--from-pr',
+]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Magic-word membership (private — callers reach for `splitLeadingMagic`)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MODEL_SET: ReadonlySet<string> = new Set(MODELS);
+const EFFORT_SET: ReadonlySet<string> = new Set(EFFORTS);
+
+function isMagicWord(tok: string): boolean {
+  return MODEL_SET.has(tok) || EFFORT_SET.has(tok);
+}
+
+function isFlag(tok: string): boolean {
+  return tok.startsWith('-');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// splitLeadingMagic
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Walks args left-to-right and returns the leading run of magic words
+ * (model alias / effort level — subcommands are NOT included). The first
+ * non-magic token ends the run. Used by transfer/restart callers that
+ * need to keep the user's magic prefix at the front of the relaunched
+ * argv without re-parsing it.
+ */
+export function splitLeadingMagic(args: readonly string[]): {
+  magic: string[];
+  rest: string[];
+} {
+  let i = 0;
+  while (i < args.length && isMagicWord(args[i]!)) {
+    i++;
+  }
+  return { magic: args.slice(0, i), rest: args.slice(i) };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// preserveArgs — three-phase walk
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the subset of `origArgs` to carry across an fnclaude relaunch.
+ *
+ *  - Phase 1: collect leading magic words (model alias / effort level).
+ *  - Phase 2: skip contiguous non-flag, non-magic positional tokens
+ *    (cwd + optional worktree-name slot).
+ *  - Phase 3: keep flag-region tokens, minus any flag listed in `deny`.
+ *    For each denied flag, the flag token AND the immediately-following
+ *    value token are stripped — UNLESS the flag is in `bareOK`, in which
+ *    case the bare form is allowed and the next token is only consumed
+ *    when it doesn't itself look like a flag. The `--flag=value` form
+ *    is always handled as a single token.
+ *
+ * Pass an empty set for `deny` to preserve all flags.
+ */
+export function preserveArgs(
+  origArgs: readonly string[],
+  deny: ReadonlySet<string>,
+  bareOK: ReadonlySet<string>,
+): string[] {
+  const out: string[] = [];
+  let i = 0;
+
+  // Phase 1 — leading magic words.
+  while (i < origArgs.length && isMagicWord(origArgs[i]!)) {
+    out.push(origArgs[i]!);
+    i++;
+  }
+
+  // Phase 2 — skip contiguous positional tokens (non-flag, non-magic).
+  while (i < origArgs.length && !isFlag(origArgs[i]!)) {
+    i++;
+  }
+
+  // Phase 3 — flag region with denylist applied.
+  while (i < origArgs.length) {
+    const tok = origArgs[i]!;
+
+    // Equals-form: match deny by the prefix before `=`.
+    const eq = tok.indexOf('=');
+    if (eq > 0) {
+      const flagPart = tok.slice(0, eq);
+      if (deny.has(flagPart)) {
+        i++;
+        continue;
+      }
+    }
+
+    // Bare-token deny check.
+    if (deny.has(tok)) {
+      i++;
+      if (i < origArgs.length) {
+        const next = origArgs[i]!;
+        if (bareOK.has(tok)) {
+          // bareOK: only consume next if it's not itself a flag.
+          if (!isFlag(next)) {
+            i++;
+          }
+        } else {
+          // Not bareOK: always consume the next token as the value.
+          i++;
+        }
+      }
+      continue;
+    }
+
+    out.push(tok);
+    i++;
+  }
+
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// applyOverrides
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Three-state override request. String fields use empty-string-or-undefined
+ * = "preserve" semantics. Boolean fields use the explicit three-state form
+ * (undefined = preserve; true = ensure-present; false = ensure-absent).
+ */
+export interface OverrideRequest {
+  model?: string;
+  effort?: string;
+  permissionMode?: string;
+  allowedTools?: string;
+  agent?: string;
+  brief?: boolean;
+  chrome?: boolean;
+  ide?: boolean;
+  verbose?: boolean;
+}
+
+/**
+ * Takes a preserved arg slice and replaces or appends flags according to
+ * `req`'s override fields. Per design.md §13:
+ *
+ *  - String field set (non-empty): strip any existing occurrence of the
+ *    corresponding flag (including the bare-magic-word form for `--model`
+ *    and `--effort` — `opus`/`sonnet`/`haiku` and `low`/`medium`/`high`/
+ *    `xhigh`/`max`/`auto`), then append `--flag <value>` at the end.
+ *  - Boolean field undefined: preserve existing occurrences.
+ *  - Boolean field true: strip existing, append `--flag`.
+ *  - Boolean field false: strip existing, do NOT append.
+ *
+ * Overrides always emit flag form (`--model sonnet`), never the magic-
+ * positional form, to avoid awkward mixing.
+ */
+export function applyOverrides(
+  preserved: readonly string[],
+  req: OverrideRequest,
+): string[] {
+  let out: string[] = [...preserved];
+
+  // String overrides — strip any existing form, then append flag-pair.
+  if (req.model !== undefined && req.model !== '') {
+    out = stripFlag(out, '--model');
+    out = stripBareMagic(out, MODEL_SET);
+    out.push('--model', req.model);
+  }
+  if (req.effort !== undefined && req.effort !== '') {
+    out = stripFlag(out, '--effort');
+    out = stripBareMagic(out, EFFORT_SET);
+    out.push('--effort', req.effort);
+  }
+  if (req.permissionMode !== undefined && req.permissionMode !== '') {
+    out = stripFlag(out, '--permission-mode');
+    out.push('--permission-mode', req.permissionMode);
+  }
+  if (req.allowedTools !== undefined && req.allowedTools !== '') {
+    out = stripFlag(out, '--allowedTools');
+    out.push('--allowedTools', req.allowedTools);
+  }
+  if (req.agent !== undefined && req.agent !== '') {
+    out = stripFlag(out, '--agent');
+    out.push('--agent', req.agent);
+  }
+
+  // Boolean overrides — undefined = preserve; true = strip + append; false = strip.
+  out = applyBoolOverride(out, '--brief', req.brief);
+  out = applyBoolOverride(out, '--chrome', req.chrome);
+  out = applyBoolOverride(out, '--ide', req.ide);
+  out = applyBoolOverride(out, '--verbose', req.verbose);
+
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// strip helpers (private)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Remove every occurrence of `flag` (consuming the following value token
+ * if it's not itself a flag) and every `flag=value` token in `args`.
+ */
+function stripFlag(args: readonly string[], flag: string): string[] {
+  const result: string[] = [];
+  const eqPrefix = `${flag}=`;
+  let i = 0;
+  while (i < args.length) {
+    const tok = args[i]!;
+    if (tok === flag) {
+      i++;
+      if (i < args.length && !isFlag(args[i]!)) {
+        i++;
+      }
+      continue;
+    }
+    if (tok.startsWith(eqPrefix)) {
+      i++;
+      continue;
+    }
+    result.push(tok);
+    i++;
+  }
+  return result;
+}
+
+/**
+ * Remove every bare-token occurrence of `flag` (no value consumed).
+ * Used for boolean flags that take no argument.
+ */
+function stripFlagBare(args: readonly string[], flag: string): string[] {
+  const result: string[] = [];
+  for (const tok of args) {
+    if (tok !== flag) result.push(tok);
+  }
+  return result;
+}
+
+/**
+ * Remove any token whose value is in `magic`. Used so a `--model` or
+ * `--effort` override strips the bare magic-positional form (e.g. `opus`
+ * or `max`) — the resulting argv carries only the explicit flag-pair
+ * appended afterward.
+ */
+function stripBareMagic(args: readonly string[], magic: ReadonlySet<string>): string[] {
+  const result: string[] = [];
+  for (const tok of args) {
+    if (!magic.has(tok)) result.push(tok);
+  }
+  return result;
+}
+
+/**
+ * Apply a tri-state bool override for a bare flag (e.g. `--ide`):
+ * undefined = preserve; true = strip + append once; false = strip.
+ */
+function applyBoolOverride(
+  args: readonly string[],
+  flag: string,
+  b: boolean | undefined,
+): string[] {
+  if (b === undefined) return [...args];
+  const out = stripFlagBare(args, flag);
+  if (b) out.push(flag);
+  return out;
+}

package/src/argv/sentinel.ts

@@ -0,0 +1,41 @@
+/**
+ * `--` sentinel helpers over the parsed passthrough array.
+ *
+ * After parseArgs has done its work, the prompt body (if any) lives as
+ * a suffix of `passthrough` starting at the first literal `--` token.
+ * Pre-sentinel tokens are flags + flag values destined for claude;
+ * post-sentinel tokens are the user's prompt body, also passed to claude
+ * but as positional prompt input rather than flag content.
+ *
+ * The split matters for downstream phases:
+ *   - the auto-name code path (§5.2) feeds promptBody() to the naming LLM
+ *   - the prompt-fragment splicer (§5.5) inserts --append-system-prompt
+ *     BEFORE the sentinel so claude doesn't treat the flag-pair as more
+ *     prompt content (regression class: PR #117 in the Go-port era)
+ *
+ * Only the FIRST `--` is the sentinel; any subsequent `--` is prompt
+ * content. This matches conventional Unix arg-parsing semantics.
+ */
+
+const SENTINEL = '--';
+
+export function findPromptSentinel(passthrough: readonly string[]): number {
+  return passthrough.indexOf(SENTINEL);
+}
+
+export function hasPromptBody(passthrough: readonly string[]): boolean {
+  const idx = findPromptSentinel(passthrough);
+  return idx >= 0 && idx < passthrough.length - 1;
+}
+
+export function promptBody(passthrough: readonly string[]): string[] {
+  const idx = findPromptSentinel(passthrough);
+  if (idx < 0) return [];
+  return passthrough.slice(idx + 1);
+}
+
+export function preSentinelArgs(passthrough: readonly string[]): string[] {
+  const idx = findPromptSentinel(passthrough);
+  if (idx < 0) return [...passthrough];
+  return passthrough.slice(0, idx);
+}

package/src/argv/short-flags.ts

@@ -0,0 +1,152 @@
+/**
+ * Capital-letter short-flag → long-flag translation.
+ *
+ * Mirrors Go canonical `src/main.go:350-423` (parseShortFlag and cluster
+ * walking). Operates on the passthrough token stream after parseArgs.
+ *
+ * Three tables govern translation. Lowercase short flags (and any
+ * capital not in the tables) pass through verbatim — claude handles
+ * those itself.
+ *
+ *   shortNoValue: B C D F I V        — toggle flags, no value
+ *   shortRequired: G M W             — must take a value
+ *   shortOptional: P R T             — may take a value if not flag-shaped
+ *
+ * Cluster mechanics:
+ *   - Each char walks independently.
+ *   - shortRequired NOT at last position → ERROR (can't absorb value mid-cluster).
+ *   - shortRequired at last position consumes next argv token; ERROR if next
+ *     starts with `-` or there's no next token.
+ *   - shortOptional at last position consumes next token if it does NOT
+ *     start with `-`; otherwise emits the long flag with no value.
+ *   - shortOptional NOT at last position emits the long flag with no value
+ *     (no token to consume; let walking continue).
+ *   - `-X=val` single-token form (only single-char clusters) → `--long=val`.
+ *
+ * Sentinel: anything after `--` passes through verbatim — that's prompt
+ * body / claude-handled flags / etc., not for us to touch.
+ */
+
+const SHORT_NO_VALUE: Record<string, string> = {
+  B: '--brief',
+  C: '--chrome',
+  D: '--dangerously-skip-permissions',
+  F: '--fork-session',
+  I: '--ide',
+  V: '--verbose',
+};
+
+const SHORT_REQUIRED: Record<string, string> = {
+  G: '--agent',
+  M: '--permission-mode',
+  W: '--allowedTools',
+};
+
+const SHORT_OPTIONAL: Record<string, string> = {
+  P: '--from-pr',
+  R: '--remote-control',
+  T: '--tmux',
+};
+
+export type ExpandShortFlagsResult =
+  | { ok: true; tokens: string[] }
+  | { ok: false; error: string };
+
+export function expandShortFlags(tokens: readonly string[]): ExpandShortFlagsResult {
+  const out: string[] = [];
+  let i = 0;
+  let pastSentinel = false;
+
+  while (i < tokens.length) {
+    const tok = tokens[i]!;
+
+    if (pastSentinel) {
+      out.push(tok);
+      i++;
+      continue;
+    }
+    if (tok === '--') {
+      pastSentinel = true;
+      out.push(tok);
+      i++;
+      continue;
+    }
+
+    // Anything not starting with `-`, or just `-`, or `--long…` passes through.
+    if (!tok.startsWith('-') || tok === '-' || tok.startsWith('--')) {
+      out.push(tok);
+      i++;
+      continue;
+    }
+
+    // Short cluster.
+    const body = tok.slice(1);
+
+    // -X=val single-char form (only for single-char clusters, per Go spec).
+    const eqIdx = body.indexOf('=');
+    if (eqIdx === 1) {
+      const ch = body[0]!;
+      const val = body.slice(2);
+      const long = SHORT_NO_VALUE[ch] ?? SHORT_REQUIRED[ch] ?? SHORT_OPTIONAL[ch];
+      if (long !== undefined) {
+        out.push(`${long}=${val}`);
+        i++;
+        continue;
+      }
+      // Unknown short with `=` → pass through verbatim.
+      out.push(tok);
+      i++;
+      continue;
+    }
+
+    // Walk each cluster char.
+    let advanceConsumedNext = false;
+    let errored: string | null = null;
+
+    for (let j = 0; j < body.length; j++) {
+      const ch = body[j]!;
+      const isLast = j === body.length - 1;
+
+      if (SHORT_NO_VALUE[ch] !== undefined) {
+        out.push(SHORT_NO_VALUE[ch]!);
+        continue;
+      }
+      if (SHORT_REQUIRED[ch] !== undefined) {
+        if (!isLast) {
+          errored = `fnclaude: flag -${ch} cannot be in middle of collapsed group, requires a value`;
+          break;
+        }
+        const next = tokens[i + 1];
+        if (next === undefined || next.startsWith('-')) {
+          errored = `fnclaude: -${ch} requires a value`;
+          break;
+        }
+        out.push(SHORT_REQUIRED[ch]!, next);
+        advanceConsumedNext = true;
+        continue;
+      }
+      if (SHORT_OPTIONAL[ch] !== undefined) {
+        if (isLast) {
+          const next = tokens[i + 1];
+          if (next !== undefined && !next.startsWith('-')) {
+            out.push(SHORT_OPTIONAL[ch]!, next);
+            advanceConsumedNext = true;
+            continue;
+          }
+        }
+        out.push(SHORT_OPTIONAL[ch]!);
+        continue;
+      }
+      // Unknown short — pass through verbatim as `-<char>`.
+      out.push(`-${ch}`);
+    }
+
+    if (errored !== null) {
+      return { ok: false, error: errored };
+    }
+
+    i += advanceConsumedNext ? 2 : 1;
+  }
+
+  return { ok: true, tokens: out };
+}

package/src/config/load.ts

@@ -0,0 +1,116 @@
+/**
+ * Load fnclaude's config.toml.
+ *
+ * The full config (per prd.launcher.md "Config file") looks like:
+ *
+ *   [name]
+ *   model = "claude-haiku-4-5"
+ *   timeout = "3s"
+ *
+ *   [auto]
+ *   tmux = "never"      # or "worktree"
+ *   handoff = "ask"
+ *   spawn_command = ""
+ *
+ *   [exec.env]
+ *   MY_VAR = "value"
+ *
+ * Only fields fnclaude actively uses are surfaced on FnConfig today.
+ * Others land as they're wired into the launch pipeline.
+ *
+ * Robustness: missing file / non-file at path / malformed TOML all
+ * degrade silently to defaults (all-undefined). Caller checks each
+ * field for undefined.
+ *
+ * Bun supports `import(path, { with: { type: 'toml' } })` natively, so
+ * no third-party TOML parser dependency.
+ */
+
+import { statSync } from 'node:fs';
+
+export interface FnConfig {
+  autoTmux: string | undefined;
+  autoHandoff: string | undefined;
+  /**
+   * `[auto] spawn_command`. Whitespace-tokenized launcher template
+   * consumed by §8.3 (fnc_spawn_session). Supported placeholders:
+   * `{bin}`, `{dest}`, `{name}`, `{summary}`. Empty/undefined means
+   * "fall back to $TMUX auto-detect, then paste-flow".
+   */
+  autoSpawnCommand: string | undefined;
+  execEnv: Record<string, string> | undefined;
+}
+
+export interface LoadConfigArgs {
+  path: string;
+}
+
+const EMPTY: FnConfig = {
+  autoTmux: undefined,
+  autoHandoff: undefined,
+  autoSpawnCommand: undefined,
+  execEnv: undefined,
+};
+
+export async function loadConfig(args: LoadConfigArgs): Promise<FnConfig> {
+  let isFile = false;
+  try {
+    isFile = statSync(args.path).isFile();
+  } catch {
+    return EMPTY;
+  }
+  if (!isFile) return EMPTY;
+
+  let parsed: unknown;
+  try {
+    const mod = await import(args.path, { with: { type: 'toml' } });
+    parsed = (mod as { default?: unknown }).default;
+  } catch {
+    return EMPTY;
+  }
+
+  if (parsed === null || typeof parsed !== 'object') return EMPTY;
+  const root = parsed as Record<string, unknown>;
+
+  return {
+    autoTmux: pickAutoTmux(root),
+    autoHandoff: pickAutoHandoff(root),
+    autoSpawnCommand: pickAutoSpawnCommand(root),
+    execEnv: pickExecEnv(root),
+  };
+}
+
+function pickAutoTmux(root: Record<string, unknown>): string | undefined {
+  const auto = root.auto;
+  if (auto === null || typeof auto !== 'object' || Array.isArray(auto)) return undefined;
+  const v = (auto as Record<string, unknown>).tmux;
+  return typeof v === 'string' ? v : undefined;
+}
+
+function pickAutoHandoff(root: Record<string, unknown>): string | undefined {
+  const auto = root.auto;
+  if (auto === null || typeof auto !== 'object' || Array.isArray(auto)) return undefined;
+  const v = (auto as Record<string, unknown>).handoff;
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' && Number.isFinite(v)) return String(v);
+  return undefined;
+}
+
+function pickAutoSpawnCommand(root: Record<string, unknown>): string | undefined {
+  const auto = root.auto;
+  if (auto === null || typeof auto !== 'object' || Array.isArray(auto)) return undefined;
+  const v = (auto as Record<string, unknown>).spawn_command;
+  return typeof v === 'string' ? v : undefined;
+}
+
+function pickExecEnv(root: Record<string, unknown>): Record<string, string> | undefined {
+  const exec = root.exec;
+  if (exec === null || typeof exec !== 'object' || Array.isArray(exec)) return undefined;
+  const env = (exec as Record<string, unknown>).env;
+  if (env === null || typeof env !== 'object' || Array.isArray(env)) return undefined;
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env as Record<string, unknown>)) {
+    if (typeof v === 'string') out[k] = v;
+  }
+  return out;
+}