@fnclaude/cli 1.0.0 → 1.1.0

package/bin/fnc.js

@@ -1,24 +1,89 @@
-#!/usr/bin/env bun
-// fnclaude entry point — invokes the main run loop.
+#!/usr/bin/env node
+// @fnclaude/cli entry point — owns the Node→Bun preflight and re-execs
+// itself under Bun when needed.
 //
-// Bun is the runtime: we rely on Bun.TOML, Bun.spawn, process.execve, and
-// node-pty's Bun adaptation. The shebang prefers `bun` directly; PATH
-// resolution should pick up the user's mise-managed bun (per project
-// CLAUDE.md tooling discipline). When installed via npm, the package's
-// `bin` entry rewires to whatever Bun lives in the user's environment.
+// 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.
 //
 // 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 { existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+// 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';
 
-const here = dirname(fileURLToPath(import.meta.url));
+const selfPath = fileURLToPath(import.meta.url);
+const here = dirname(selfPath);
+
+// 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], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      FNC_ARGS_JSON: JSON.stringify(argv),
+    },
+  });
+  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`);
+    process.exit(1);
+  }
+  process.exit(r.status ?? 0);
+}
+
+// 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);
 

package/bin/preflight.js

@@ -0,0 +1,66 @@
+// Preflight for the cli `fnc` bin shim — decide whether to proceed,
+// re-exec under Bun, or hard-error out with a directive message.
+//
+// The cli relies on Bun-only globals (`Bun.spawn`, `Bun.TOML.parse`,
+// `Bun.which`, `process.execve`). When the bin is invoked under Node
+// (typically because `npm i -g @fnclaude/cli` puts it on PATH and the
+// user runs `fnc`), those Bun calls fail silently — `Bun.which` returns
+// `undefined`, `Bun.TOML.parse` throws "Bun is not defined", etc. The
+// cli then degrades into a "claude not found" / config-broken state
+// that LOOKS like a normal failure but is actually a runtime mismatch.
+//
+// This preflight runs first and either re-execs under Bun (if `bun` is
+// on PATH) or prints a directive error and exits non-zero — never the
+// silent-degradation path.
+//
+// Extracted from the shim itself to keep it unit-testable: the decision
+// function takes injected seams (typeof-Bun probe + PATH lookup) and
+// returns a discriminated union; the shim handles the dispatch.
+
+import { spawnSync } from 'node:child_process';
+
+/**
+ * @typedef {{ kind: 'run' }
+ *         | { kind: 'reexec', bun: string }
+ *         | { kind: 'error', message: string }
+ * } PreflightDecision
+ */
+
+/**
+ * Decide what the shim should do.
+ *
+ * @param {{ hasBun: boolean, lookupBun: () => string | null }} seams
+ * @returns {PreflightDecision}
+ */
+export function decide({ hasBun, lookupBun }) {
+  if (hasBun) return { kind: 'run' };
+  const bun = lookupBun();
+  if (bun !== null) return { kind: 'reexec', bun };
+  return {
+    kind: 'error',
+    message:
+      'fnclaude: this CLI requires Bun (https://bun.sh) to run.\n' +
+      '  The shim was invoked under Node, but the CLI depends on Bun-only\n' +
+      '  globals (Bun.spawn, Bun.TOML.parse, process.execve). Install Bun\n' +
+      '  and re-run `fnc`, or invoke the script via `bun ...` directly.',
+  };
+}
+
+/**
+ * Default PATH lookup for `bun`. Returns the literal string `'bun'` on
+ * success (the OS will resolve it via PATH at spawn time), or null when
+ * `bun` is not reachable.
+ *
+ * Implementation note: `spawnSync('bun', ['--version'])` is the simplest
+ * cross-platform probe. ENOENT comes back as `result.error.code`, and a
+ * present-but-broken bun returns non-zero status. Both are treated as
+ * "not usable."
+ *
+ * @returns {string | null}
+ */
+export function defaultLookupBun() {
+  const r = spawnSync('bun', ['--version'], { stdio: 'ignore' });
+  if (r.error) return null;
+  if (r.status !== 0) return null;
+  return 'bun';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnclaude/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "fnclaude CLI implementation (TypeScript rewrite, in progress)",
   "license": "MIT",
   "repository": {

package/src/main.ts

@@ -145,6 +145,41 @@ export interface RunDeps {
   data?: RunConfig;
 }
 
+/**
+ * Read the user's argv, preferring `FNC_ARGS_JSON` over `process.argv`.
+ *
+ * The umbrella shim (packages/fnclaude/bin/fnc.js) sets `FNC_ARGS_JSON`
+ * on the env it spawns Bun with, because Bun strips the first `--`
+ * from a script's argv (confirmed empirically across `bun script.js`,
+ * `bun --`, `bun run`, and shebang invocations). Passing user args via
+ * the env var sidesteps that — Bun never sees them as its own argv.
+ *
+ * We DELETE the var after consumption so any child processes the cli
+ * spawns (claude, gh, the relaunch chain) don't inherit a stale value.
+ *
+ * Defensive: malformed or wrong-shape values fall through to
+ * `process.argv.slice(2)` rather than throwing — a corrupted env var
+ * shouldn't break the cli, just degrade to the pre-fix behaviour.
+ */
+function readArgvFromEnvOrProcess(): readonly string[] {
+  const envArgs = process.env.FNC_ARGS_JSON;
+  if (envArgs !== undefined) {
+    delete process.env.FNC_ARGS_JSON;
+    try {
+      const parsed: unknown = JSON.parse(envArgs);
+      if (
+        Array.isArray(parsed) &&
+        parsed.every((x): x is string => typeof x === 'string')
+      ) {
+        return parsed;
+      }
+    } catch {
+      // Fall through to process.argv.
+    }
+  }
+  return process.argv.slice(2);
+}
+
 function lookupClaudeFromPath(name: string): string | undefined {
   // Bun's PATH lookup: Bun.which() returns null when not found. Coerce to
   // undefined to keep the absent-value sentinel consistent with the rest of
@@ -174,7 +209,7 @@ export async function run(deps: RunDeps = {}): Promise<number> {
   const io = deps.io ?? {};
   const data = deps.data ?? {};
 
-  const argv = io.argv ?? process.argv.slice(2);
+  const argv = io.argv ?? readArgvFromEnvOrProcess();
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
   const home = io.home ?? process.env.HOME ?? homedir();