@fnclaude/cli 1.1.1 → 2.0.0

package/bin/fnc.js

@@ -1,90 +1,45 @@
 #!/usr/bin/env node
-// @fnclaude/cli entry point — owns the Node→Bun preflight and re-execs
-// itself under Bun when needed.
 //
-// Why Node-shebang for a Bun cli: when `npm i -g @fnclaude/cli` puts
-// `fnc` on PATH, the user's shell invokes it under whichever runtime npm
-// happened to link against — typically Node, since npm itself runs under
-// Node. We must therefore be loadable under Node, do our own runtime
-// check, and re-exec under Bun ourselves. This shim used to live in the
-// umbrella package (`fnclaude`), which meant standalone installs of
-// `@fnclaude/cli` skipped it and silently degraded (and, on the Bun
-// side, hit the `--`-stripping bug). Owning the preflight here is the
-// single source of truth.
+// Node→Bun preflight. Bun 1.3.14 still strips the literal `--` sentinel from
+// `process.argv` (see docs/decisions.md), which would corrupt `fnc -- <prompt>`
+// invocations. Running this shim under Node first preserves the unstripped
+// argv long enough to stuff it into FNC_ARGS_JSON, then re-execs under Bun
+// where main.ts reads back from the env var instead of process.argv.
 //
-// Module resolution: dist/main.js is what npm-installed users execute;
-// local devs running from source use Bun's TS support to import
-// src/main.ts directly. We attempt dist first and fall back to src so
-// both workflows are first-class without a separate dev shim.
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { decide, defaultLookupBun } from './preflight.js';
+// When this file is invoked directly under Bun (e.g. `bun bin/fnc.js`, or
+// via the `#!/usr/bin/env bun` future state), `typeof Bun !== 'undefined'`
+// short-circuits the preflight and we jump straight to main.
 
-const selfPath = fileURLToPath(import.meta.url);
-const here = dirname(selfPath);
+import { fileURLToPath } from 'node:url';
 
-// Short-circuit --version BEFORE the Bun preflight. Reading package.json
-// is pure Node-stdlib work and doesn't need Bun — friendlier when
-// someone is diagnosing a broken install without Bun on PATH.
-const argv = process.argv.slice(2);
-if (argv.includes('--version') || argv.includes('-v')) {
-  const pkg = JSON.parse(
-    readFileSync(join(here, '..', 'package.json'), 'utf8'),
-  );
-  process.stdout.write(`fnclaude ${pkg.version}\n`);
-  process.exit(0);
-}
-
-const decision = decide({
-  hasBun: typeof globalThis.Bun !== 'undefined',
-  lookupBun: defaultLookupBun,
-});
-
-if (decision.kind === 'error') {
-  process.stderr.write(`${decision.message}\n`);
-  process.exit(1);
-}
-
-if (decision.kind === 'reexec') {
-  // Re-launch ourselves under Bun. `spawnSync` with stdio:'inherit'
-  // forwards streams transparently; we propagate the child's exit code
-  // so the OS / parent process sees the same status it would have seen
-  // had Bun been the launcher all along.
-  //
-  // Argv-via-env: Bun strips the first `--` from a script's argv,
-  // regardless of where it appears (script invocation, `bun --`, `bun
-  // run`, shebang). Confirmed empirically. So passing the user's args
-  // as Bun-script argv would silently mangle `fnc -- "prompt"` into
-  // `fnc "prompt"` — the cli then treats the prompt as a cwd
-  // positional, the resolver fires, and 8 GitHub orgs 404 in series
-  // before the user gets a misleading "could not resolve" error. We
-  // sidestep by serialising the user's args into FNC_ARGS_JSON; main()
-  // reads from there when present (and deletes the env var to avoid
-  // leaking to its own children).
-  const r = spawnSync(decision.bun, [selfPath], {
+if (typeof Bun === 'undefined') {
+  const { spawnSync } = await import('node:child_process');
+  const self = fileURLToPath(import.meta.url);
+  const argvJson = JSON.stringify(process.argv.slice(2));
+  const result = spawnSync('bun', [self], {
     stdio: 'inherit',
-    env: {
-      ...process.env,
-      FNC_ARGS_JSON: JSON.stringify(argv),
-    },
+    env: { ...process.env, FNC_ARGS_JSON: argvJson },
   });
-  if (r.error) {
-    // ENOENT shouldn't reach here — lookupBun confirmed bun is reachable
-    // — but if something else broke (EACCES, ETXTBSY), surface it
-    // instead of swallowing.
-    process.stderr.write(`fnclaude: failed to re-exec under bun: ${r.error.message}\n`);
+  if (result.error) {
+    const err = result.error;
+    const isMissingBun = /** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT';
+    if (isMissingBun) {
+      process.stderr.write(
+        'fnc: Bun runtime not found on PATH.\n' +
+          '  fnclaude requires Bun (Node alone is not supported).\n' +
+          '  Install: https://bun.sh — `curl -fsSL https://bun.sh/install | bash`\n',
+      );
+    } else {
+      process.stderr.write(`fnc: failed to re-exec under bun (${err.message})\n`);
+    }
+    process.exit(127);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    // Unreachable on Unix; defensive return for Windows where kill-self doesn't terminate.
     process.exit(1);
   }
-  process.exit(r.status ?? 0);
+  process.exit(result.status ?? 1);
 }
 
-// decision.kind === 'run' — we're already under Bun. Import main() and
-// dispatch.
-const distMain = resolve(here, '..', 'dist', 'main.js');
-const srcMain = resolve(here, '..', 'src', 'main.ts');
-const target = existsSync(distMain) ? distMain : srcMain;
-const { main } = await import(pathToFileURL(target).href);
-
-main();
+await import('../src/main.ts');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnclaude/cli",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "fnclaude CLI implementation (TypeScript rewrite, in progress)",
   "license": "MIT",
   "repository": {
@@ -9,28 +9,25 @@
     "directory": "packages/cli"
   },
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./src/main.ts",
   "bin": {
     "fnc": "./bin/fnc.js"
   },
   "files": [
     "bin",
-    "dist",
-    "prompts",
+    "share",
     "src"
   ],
   "scripts": {
-    "lint": "echo 'lint stub (cli)' && exit 0",
+    "lint": "echo 'lint stub (cli, rewrite window)' && exit 0",
     "test": "bun test",
-    "build": "tsc -p tsconfig.json"
+    "build": "echo 'no build step (bun runs ts directly)' && exit 0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.98.0",
-    "node-pty": "1.2.0-beta.13"
+    "@anthropic-ai/sdk": "^0.99.0"
   }
 }

package/share/fnclaude/templates/handoff.template.md

@@ -0,0 +1,11 @@
+<!-- BURN AFTER READING -->
+
+This file is a scratch handoff buffer claude writes when one noop session
+hands the conversation off to another. The receiving session reads it,
+acts on it, and is free to overwrite or delete it.
+
+Treat anything below this line as the previous session's outgoing brief.
+If the file is otherwise empty, no prior session has written one yet —
+that's the normal first-launch state.
+
+---

package/src/argv/classify.ts

@@ -0,0 +1,48 @@
+/**
+ * Token classification. Pure functions over a single argv token.
+ *
+ * The Go canonical does this inline inside its argv loop; here it's
+ * lifted out as a pure function so the magic-positional state machine
+ * (§2.3) and short-flag expander (§4.5) can share the same classifier
+ * without restating the alphabets.
+ *
+ * Case-sensitive on the magic words — `Opus`, `OPUS`, etc. are positionals.
+ * Matches Go canonical, which does exact string comparison against
+ * lowercase literals.
+ */
+
+export const MODELS = ['opus', 'sonnet', 'haiku'] as const;
+export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'] as const;
+
+export type Model = (typeof MODELS)[number];
+export type Effort = (typeof EFFORTS)[number];
+export type CanonicalSubcommand = 'resume' | 'continue' | 'fork';
+
+export const SUBCOMMAND_ALIASES: Readonly<Record<string, CanonicalSubcommand>> = Object.freeze({
+  resume: 'resume',
+  res: 'resume',
+  continue: 'continue',
+  con: 'continue',
+  fork: 'fork',
+  fk: 'fork',
+});
+
+const MODEL_SET = new Set<string>(MODELS);
+const EFFORT_SET = new Set<string>(EFFORTS);
+
+export type TokenKind = 'flag' | 'model' | 'effort' | 'subcommand' | 'positional';
+
+export function classifyToken(tok: string): TokenKind {
+  // Flag-shape check is first because tokens starting with `-` shouldn't
+  // ever match a magic word alphabet (none start with `-`), and a leading
+  // `-` is the cheapest possible discriminator.
+  if (tok.startsWith('-')) return 'flag';
+  if (MODEL_SET.has(tok)) return 'model';
+  if (EFFORT_SET.has(tok)) return 'effort';
+  if (tok in SUBCOMMAND_ALIASES) return 'subcommand';
+  return 'positional';
+}
+
+export function canonicalSubcommand(tok: string): CanonicalSubcommand | null {
+  return SUBCOMMAND_ALIASES[tok] ?? null;
+}

package/src/argv/expand.ts

@@ -0,0 +1,51 @@
+/**
+ * Expand magic-captured aliases into the passthrough flag list claude
+ * eventually receives. The parser captures `model`/`effort`/`subcommand`
+ * into structured fields; this module emits the corresponding
+ * `--model`/`--effort`/`--resume`/`--fork-session` flags and prepends
+ * them to the original passthrough.
+ *
+ * Order: magic flags first (so explicit user-supplied flags appear later
+ * and win via claude's last-occurrence semantics). Within the magic
+ * block: model → effort → subcommand.
+ *
+ * §4.3 (effort-without-model → opus) is already handled in the parser
+ * by setting `model = 'opus'` when a bare effort is captured at the
+ * first magic slot; this module just emits whatever the parser captured.
+ *
+ * Subcommand mapping (§4.4 / design.md §1):
+ *   resume   → --resume
+ *   continue → --continue
+ *   fork     → --resume --fork-session
+ *
+ * Mirrors Go canonical `buildClaudeArgs` (`src/main.go` near the magic
+ * + subcommand merge point).
+ */
+
+import type { CanonicalSubcommand } from './classify.ts';
+import type { ParsedArgsOk } from './parse.ts';
+
+const SUBCOMMAND_FLAGS: Record<CanonicalSubcommand, readonly string[]> = {
+  resume: ['--resume'],
+  continue: ['--continue'],
+  fork: ['--resume', '--fork-session'],
+};
+
+export function expandAliases(parsed: ParsedArgsOk): string[] {
+  const out: string[] = [];
+
+  if (parsed.model !== null) {
+    out.push('--model', parsed.model);
+  }
+  if (parsed.effort !== null) {
+    out.push('--effort', parsed.effort);
+  }
+  if (parsed.subcommand !== null) {
+    for (const f of SUBCOMMAND_FLAGS[parsed.subcommand]) out.push(f);
+  }
+
+  // Append the original passthrough verbatim.
+  for (const tok of parsed.passthrough) out.push(tok);
+
+  return out;
+}

package/src/argv/intake.ts

@@ -0,0 +1,52 @@
+/**
+ * Argv intake. Reads the user's command-line arguments, working around
+ * bun's argv-stripping behavior via the Node-shebang preflight indirection.
+ *
+ * When invoked under Node first, `bin/fnc.js`'s preflight stuffs the raw
+ * argv into `FNC_ARGS_JSON` and re-execs under Bun. By the time main.ts
+ * runs, `process.argv` may have lost its `--` sentinel (bun 1.3.14 still
+ * strips it; see `docs/decisions.md`), so we prefer the env var.
+ *
+ * Direct `bun fnc.js` invocations (no preflight) still work — there's
+ * just no way to recover `--` in that path.
+ */
+
+const ENV_KEY = 'FNC_ARGS_JSON';
+
+function warnStderr(msg: string): void {
+  try {
+    Bun.write(Bun.stderr, `fnc: ${msg}\n`);
+  } catch {
+    // Stderr write failure is non-fatal — the fallback still applies.
+  }
+}
+
+function tryParseArgsJson(raw: string): readonly string[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    warnStderr(`${ENV_KEY} is not valid JSON (${(err as Error).message}); falling back to process.argv`);
+    return null;
+  }
+  if (!Array.isArray(parsed)) {
+    warnStderr(`${ENV_KEY} did not parse to an array; falling back to process.argv`);
+    return null;
+  }
+  for (const el of parsed) {
+    if (typeof el !== 'string') {
+      warnStderr(`${ENV_KEY} contains a non-string element; falling back to process.argv`);
+      return null;
+    }
+  }
+  return parsed as readonly string[];
+}
+
+export function readArgv(): readonly string[] {
+  const raw = process.env[ENV_KEY];
+  if (raw !== undefined) {
+    const parsed = tryParseArgsJson(raw);
+    if (parsed !== null) return parsed;
+  }
+  return process.argv.slice(2);
+}

package/src/argv/magic.ts

@@ -0,0 +1,103 @@
+/**
+ * Magic-positional state machine.
+ *
+ * Walks the prefix of argv consuming model/effort/subcommand tokens per
+ * the rules in docs/design.md §1. Subcommands are order-independent and
+ * do not advance the model/effort state; model+effort move through a
+ * three-state machine:
+ *
+ *   state 0 → next token may be model OR effort (effort implies opus,
+ *             rewrite extension)
+ *   state 1 → next token may be effort (model already consumed)
+ *   state 2 → magic scanning is done
+ *
+ * Magic also ends as soon as a flag (token starting with `-`) is seen.
+ *
+ * Only one subcommand per invocation; the second is an error.
+ *
+ * The fn returns `consumed` (the count of leading tokens absorbed by the
+ * scan) rather than slicing — the caller still owns the original argv
+ * for downstream phases that need indices into it.
+ */
+
+import {
+  canonicalSubcommand,
+  classifyToken,
+  type CanonicalSubcommand,
+  type Effort,
+  type Model,
+} from './classify.ts';
+
+export interface MagicResultOk {
+  ok: true;
+  model: Model | null;
+  effort: Effort | null;
+  subcommand: CanonicalSubcommand | null;
+  consumed: number;
+}
+
+export interface MagicResultErr {
+  ok: false;
+  error: string;
+}
+
+export type MagicResult = MagicResultOk | MagicResultErr;
+
+const ERR_DUPLICATE_SUBCOMMAND = 'fnc: only one of resume/continue/fork may be used per invocation';
+
+export function scanMagic(args: readonly string[]): MagicResult {
+  let model: Model | null = null;
+  let effort: Effort | null = null;
+  let subcommand: CanonicalSubcommand | null = null;
+  let state: 0 | 1 | 2 = 0;
+  let i = 0;
+
+  while (i < args.length) {
+    const tok = args[i]!;
+    const kind = classifyToken(tok);
+
+    if (kind === 'flag') break;
+
+    if (kind === 'subcommand') {
+      if (subcommand !== null) {
+        return { ok: false, error: ERR_DUPLICATE_SUBCOMMAND };
+      }
+      subcommand = canonicalSubcommand(tok);
+      i++;
+      continue;
+    }
+
+    if (state === 0) {
+      if (kind === 'model') {
+        model = tok as Model;
+        state = 1;
+        i++;
+        continue;
+      }
+      if (kind === 'effort') {
+        // Rewrite extension: effort-only at pos 1 implies opus.
+        effort = tok as Effort;
+        model = 'opus';
+        state = 2;
+        i++;
+        continue;
+      }
+      break;
+    }
+
+    if (state === 1) {
+      if (kind === 'effort') {
+        effort = tok as Effort;
+        state = 2;
+        i++;
+        continue;
+      }
+      break;
+    }
+
+    // state === 2 — magic is done, leave the rest to downstream phases.
+    break;
+  }
+
+  return { ok: true, model, effort, subcommand, consumed: i };
+}

package/src/argv/parse.ts

@@ -0,0 +1,213 @@
+/**
+ * Full argv parser. Consumes the user's raw argv (post-intake) and produces
+ * a structured Args record for the launcher and MCP pipeline.
+ *
+ * Mirrors Go canonical `parseArgs` (`fnclaude@fnrhombus/src/main.go:130–343`):
+ * one left-to-right walk with a sticky `inFlags` boundary. Magic positionals
+ * (model/effort/subcommand) consume the leading prefix; then a maximum of
+ * two non-flag positionals fill firstPath and worktreeArg; once the first
+ * flag-shape token is seen, all subsequent tokens are flag territory.
+ *
+ * fnclaude-eaten flags (NOT forwarded to claude):
+ *   --no-tmux              → noTmux = true
+ *   -A | --also <dir>      → push to extraDirs
+ *   -A=<dir> | --also=<dir>
+ *   -w | --worktree <name> → worktreeSet, worktreeArg
+ *   -w=<name> | --worktree=<name>
+ *   bare -w or --worktree  → worktreeSet, worktreeArg = ''
+ *
+ * Subcommand tokens (resume/res/continue/con/fork/fk) are recognized at
+ * any positional slot, are order-independent with magic, and do not
+ * advance the magic state. At most one per invocation.
+ *
+ * Short-flag clusters (-BVC, -BVCM plan) are NOT expanded here — they
+ * land in passthrough verbatim and §4.5 transforms them later. Unknown
+ * long flags also pass through unchanged.
+ */
+
+import {
+  canonicalSubcommand,
+  classifyToken,
+  type CanonicalSubcommand,
+  type Effort,
+  type Model,
+} from './classify.ts';
+
+export interface ParsedArgsOk {
+  ok: true;
+  model: Model | null;
+  effort: Effort | null;
+  subcommand: CanonicalSubcommand | null;
+  firstPath: string | null;
+  worktreeSet: boolean;
+  worktreeArg: string;
+  extraDirs: string[];
+  noTmux: boolean;
+  passthrough: string[];
+}
+
+export interface ParsedArgsErr {
+  ok: false;
+  error: string;
+}
+
+export type ParsedArgs = ParsedArgsOk | ParsedArgsErr;
+
+const ERR_DUPLICATE_SUBCOMMAND = 'fnc: only one of resume/continue/fork may be used per invocation';
+const ERR_TOO_MANY_POSITIONALS = (got: string): string =>
+  `fnc: too many positional arguments (got ${JSON.stringify(got)}; max is 2 — cwd and worktree-name)`;
+
+export function parseArgs(args: readonly string[]): ParsedArgs {
+  let model: Model | null = null;
+  let effort: Effort | null = null;
+  let subcommand: CanonicalSubcommand | null = null;
+  let firstPath: string | null = null;
+  let worktreeSet = false;
+  let worktreeArg = '';
+  const extraDirs: string[] = [];
+  let noTmux = false;
+  const passthrough: string[] = [];
+
+  let magicState: 0 | 1 | 2 = 0;
+  let inFlags = false;
+
+  let i = 0;
+  while (i < args.length) {
+    const tok = args[i]!;
+
+    // ── Positional territory (before the first flag-shape token) ────────────
+    if (!inFlags && !tok.startsWith('-')) {
+      const kind = classifyToken(tok);
+
+      // Subcommand: any positional slot, doesn't advance magic state.
+      if (kind === 'subcommand') {
+        if (subcommand !== null) {
+          return { ok: false, error: ERR_DUPLICATE_SUBCOMMAND };
+        }
+        subcommand = canonicalSubcommand(tok);
+        i++;
+        continue;
+      }
+
+      // Magic state 0 → check model OR effort (effort implies opus).
+      if (magicState === 0) {
+        if (kind === 'model') {
+          model = tok as Model;
+          magicState = 1;
+          i++;
+          continue;
+        }
+        if (kind === 'effort') {
+          effort = tok as Effort;
+          model = 'opus';
+          magicState = 2;
+          i++;
+          continue;
+        }
+        // Not magic — fall through to positional slot assignment, but advance
+        // magicState so position 2's effort check doesn't re-fire.
+        magicState = 2;
+      } else if (magicState === 1) {
+        // Magic state 1 → check effort (model was matched at state 0).
+        if (kind === 'effort') {
+          effort = tok as Effort;
+          magicState = 2;
+          i++;
+          continue;
+        }
+        magicState = 2;
+      }
+      // magicState === 2 from here on.
+
+      // Positional slot assignment.
+      if (firstPath === null) {
+        firstPath = tok;
+      } else if (!worktreeSet) {
+        worktreeSet = true;
+        worktreeArg = tok;
+      } else {
+        return { ok: false, error: ERR_TOO_MANY_POSITIONALS(tok) };
+      }
+      i++;
+      continue;
+    }
+
+    // ── Flag territory (sticky) ─────────────────────────────────────────────
+    inFlags = true;
+
+    // fnclaude-eaten: --no-tmux
+    if (tok === '--no-tmux') {
+      noTmux = true;
+      i++;
+      continue;
+    }
+
+    // fnclaude-eaten: -A / --also (extra dirs)
+    if (tok === '-A' || tok === '--also') {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('-')) {
+        const which = next === undefined ? tok : `${tok} ${next}`;
+        return { ok: false, error: `fnc: ${which} requires a directory argument` };
+      }
+      extraDirs.push(next);
+      i += 2;
+      continue;
+    }
+    if (tok.startsWith('-A=')) {
+      const val = tok.slice(3);
+      if (val === '') return { ok: false, error: 'fnc: -A= requires a directory argument' };
+      extraDirs.push(val);
+      i++;
+      continue;
+    }
+    if (tok.startsWith('--also=')) {
+      const val = tok.slice(7);
+      if (val === '') return { ok: false, error: 'fnc: --also= requires a directory argument' };
+      extraDirs.push(val);
+      i++;
+      continue;
+    }
+
+    // fnclaude-eaten: -w / --worktree (worktree flag)
+    if (tok === '-w' || tok === '--worktree') {
+      worktreeSet = true;
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        worktreeArg = next;
+        i += 2;
+      } else {
+        i++;
+      }
+      continue;
+    }
+    if (tok.startsWith('-w=')) {
+      worktreeSet = true;
+      worktreeArg = tok.slice(3);
+      i++;
+      continue;
+    }
+    if (tok.startsWith('--worktree=')) {
+      worktreeSet = true;
+      worktreeArg = tok.slice('--worktree='.length);
+      i++;
+      continue;
+    }
+
+    // Everything else (including `--` and following prompt body) → passthrough
+    passthrough.push(tok);
+    i++;
+  }
+
+  return {
+    ok: true,
+    model,
+    effort,
+    subcommand,
+    firstPath,
+    worktreeSet,
+    worktreeArg,
+    extraDirs,
+    noTmux,
+    passthrough,
+  };
+}