@fnclaude/cli 1.1.0 → 2.0.0

package/src/repo/resolve-input.ts

@@ -0,0 +1,179 @@
+/**
+ * Resolver orchestrator — takes the first positional argument (or null)
+ * and decides what fnclaude should do with it. Pure dispatch + filesystem
+ * existence checks; gh-CLI-bound side effects (owner lookup, clone
+ * execution) are surfaced as result variants so the caller (CLI main)
+ * handles them at the boundary.
+ *
+ * Mirrors Go canonical `src/resolver.go:resolveLaunchCwd` minus the gh
+ * branches:
+ *   - Short-circuit for /, ~, ~/ → launch unconditionally (no fs check)
+ *   - Everything else → dual lookup
+ *       path:  is <shellCwd>/<input> a directory?
+ *       repo:  parse, compute clone destination, does it exist?
+ *   - Both found  → ambiguous (caller errors with disambiguation msg)
+ *   - One found   → launch that one
+ *   - Neither     → needs-clone (resolved owner) or needs-owner-lookup
+ *                   (bare name) — caller invokes gh CLI
+ *
+ * See specs.md §18.1 for the user-facing description.
+ */
+
+import { statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+import { expandTilde, noopDir } from '../path/resolve.ts';
+import { buildCloneUrl, computeCloneDestination } from './clone.ts';
+import { hasResolvedOwner, parseRepoRef } from './ref.ts';
+
+export interface ResolveInputArgs {
+  input: string | null;
+  shellCwd: string;
+  home: string;
+  xdgConfigHome: string | undefined;
+  settings: {
+    cloneTemplate: string;
+    hostAliases: Record<string, string>;
+  };
+}
+
+export type ResolveResult =
+  | {
+      kind: 'launch';
+      launchCwd: string;
+      workspace: string;
+      usedNoopFallback: boolean;
+    }
+  | {
+      kind: 'needs-clone';
+      url: string;
+      destination: string;
+      workspace: string;
+    }
+  | {
+      kind: 'needs-owner-lookup';
+      name: string;
+      workspace: string;
+    }
+  | {
+      kind: 'ambiguous';
+      path: string;
+      cloneDestination?: string;
+      repoRef?: string;
+    }
+  | { kind: 'error'; error: string };
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isPathShortCircuit(input: string): boolean {
+  if (input === '~') return true;
+  if (input.startsWith('/')) return true;
+  if (input.startsWith('~/')) return true;
+  return false;
+}
+
+export function resolveInput(args: ResolveInputArgs): ResolveResult {
+  const { input, shellCwd, home, xdgConfigHome, settings } = args;
+
+  // 1. Null / empty → noop fallback
+  if (input === null || input === '') {
+    return {
+      kind: 'launch',
+      launchCwd: noopDir({ xdgConfigHome, home }),
+      usedNoopFallback: true,
+      workspace: '',
+    };
+  }
+
+  // 2. Path short-circuit: /, ~, ~/ skip the repo lookup entirely
+  //    (per specs.md §18.1). Don't check whether the directory exists —
+  //    user said "go here", we go there.
+  if (isPathShortCircuit(input)) {
+    const expanded = expandTilde(input, home);
+    const launchCwd = isAbsolute(expanded) ? expanded : join(shellCwd, expanded);
+    return { kind: 'launch', launchCwd, usedNoopFallback: false, workspace: '' };
+  }
+
+  // 3. Dual lookup: check both path-on-disk and repo-ref interpretation.
+  const pathCandidate = join(shellCwd, input);
+  const pathExists = isDirectory(pathCandidate);
+
+  const parseResult = parseRepoRef(input);
+
+  // If repo-ref parse failed: path is the only chance.
+  if (!parseResult.ok) {
+    if (pathExists) {
+      return {
+        kind: 'launch',
+        launchCwd: pathCandidate,
+        usedNoopFallback: false,
+        workspace: '',
+      };
+    }
+    return { kind: 'error', error: parseResult.error };
+  }
+
+  const ref = parseResult.ref;
+
+  // Bare name (owner not in input) — need gh CLI to find owner.
+  if (!hasResolvedOwner(ref)) {
+    if (pathExists) {
+      return { kind: 'ambiguous', path: pathCandidate, repoRef: input };
+    }
+    return { kind: 'needs-owner-lookup', name: ref.name, workspace: ref.workspace };
+  }
+
+  // Owner is resolved; compute clone destination.
+  if (settings.cloneTemplate === '') {
+    return {
+      kind: 'error',
+      error:
+        'cloneTemplate is not configured in repoSettings; cannot resolve repo references. Set repoSettings.cloneTemplate in ~/.claude/settings.json (e.g. "~/src/{repo}@{owner}")',
+    };
+  }
+
+  const destResult = computeCloneDestination({
+    ref,
+    template: settings.cloneTemplate,
+    hostAliases: settings.hostAliases,
+    home,
+  });
+  if (!destResult.ok) {
+    return { kind: 'error', error: destResult.error };
+  }
+  const destination = destResult.path;
+  const destExists = isDirectory(destination);
+
+  if (pathExists && destExists) {
+    return { kind: 'ambiguous', path: pathCandidate, cloneDestination: destination };
+  }
+  if (pathExists) {
+    return {
+      kind: 'launch',
+      launchCwd: pathCandidate,
+      usedNoopFallback: false,
+      workspace: ref.workspace,
+    };
+  }
+  if (destExists) {
+    return {
+      kind: 'launch',
+      launchCwd: destination,
+      usedNoopFallback: false,
+      workspace: ref.workspace,
+    };
+  }
+
+  return {
+    kind: 'needs-clone',
+    url: buildCloneUrl(ref),
+    destination,
+    workspace: ref.workspace,
+  };
+}

package/src/repo/template.ts

@@ -0,0 +1,92 @@
+/**
+ * Template substitution for cloneTemplate values (and any future templates
+ * fnclaude reads from repoSettings). Placeholder vocabulary aligns with
+ * the claude-code-worktree-paths plugin so users learn one templating
+ * language across both tools.
+ *
+ * Ports Go canonical's template.go. fnclaude only uses cloneTemplate,
+ * which is computed BEFORE a clone exists — placeholders like {repo-dir},
+ * {clone-path}, {input}, {cwd} aren't meaningful here and are rejected
+ * via the unknown-placeholder error.
+ *
+ * Lazy resolvers: {host-short} defers the LUT lookup error until the
+ * placeholder is actually referenced. Templates that don't use it don't
+ * need the LUT populated.
+ */
+
+export interface TemplateResolveOk {
+  ok: true;
+  value: string;
+}
+
+export interface TemplateResolveErr {
+  ok: false;
+  error: string;
+}
+
+export type TemplateResolveResult = TemplateResolveOk | TemplateResolveErr;
+
+export type TemplateVars = Record<string, () => TemplateResolveResult>;
+
+export function applyTemplate(tpl: string, vars: TemplateVars): TemplateResolveResult {
+  let out = '';
+  let i = 0;
+  while (i < tpl.length) {
+    const c = tpl[i]!;
+    if (c !== '{') {
+      out += c;
+      i++;
+      continue;
+    }
+    const closeIdx = tpl.indexOf('}', i + 1);
+    if (closeIdx < 0) {
+      // Unterminated `{` — pass through literally; the user's template is
+      // malformed and an error here would be confusing.
+      out += c;
+      i++;
+      continue;
+    }
+    const name = tpl.slice(i + 1, closeIdx);
+    const resolver = vars[name];
+    if (!resolver) {
+      return { ok: false, error: `unknown placeholder {${name}} in template ${JSON.stringify(tpl)}` };
+    }
+    const r = resolver();
+    if (!r.ok) return r;
+    out += r.value;
+    i = closeIdx + 1;
+  }
+  return { ok: true, value: out };
+}
+
+/**
+ * Build the placeholder map for cloneTemplate expansion given the resolved
+ * repo coordinates. Lazy resolvers (host-short) let templates that don't
+ * reference them skip LUT lookups.
+ */
+export function cloneTemplateVars(
+  repo: string,
+  owner: string,
+  host: string,
+  hostAliases: Record<string, string>,
+): TemplateVars {
+  const dotIdx = host.indexOf('.');
+  const hostPlain = dotIdx >= 0 ? host.slice(0, dotIdx) : host;
+
+  return {
+    repo: () => ({ ok: true, value: repo }),
+    owner: () => ({ ok: true, value: owner }),
+    host: () => ({ ok: true, value: host }),
+    'host-plain': () => ({ ok: true, value: hostPlain }),
+    'host-short': () => {
+      const alias = hostAliases[host];
+      if (alias === undefined) {
+        return {
+          ok: false,
+          error: `host ${JSON.stringify(host)} has no entry in hostAliases LUT; add one to ~/.claude/settings.json's hostShortAliases block`,
+        };
+      }
+      return { ok: true, value: alias };
+    },
+  };
+}

package/src/warnings/buffer.ts

@@ -0,0 +1,39 @@
+// Deferred-flush warning buffer (design.md §27).
+//
+// Non-fatal warnings issued during the launch sequence (config-parse,
+// fragment-load, name-sanitization, etc.) shouldn't be written to stderr
+// as they happen — claude's TUI takes over the terminal moments later and
+// scrolls them off-screen before the user sees them. Instead, accumulate
+// them here and flush once claude has exited, so they land in the user's
+// shell where they have time to read them.
+//
+// Terminal errors that exit non-zero (bad argv, missing claude binary,
+// clone failure, etc.) bypass this buffer and write directly to stderr —
+// those aren't warnings, they're the reason the launch is aborting, and
+// the user needs to see them immediately.
+
+export interface WarningBuffer {
+  /** Queue a warning. Trailing newline is added on flush if absent. */
+  add(msg: string): void;
+  /**
+   * Write every queued warning to the given stream, one per line, then
+   * drain the buffer. Subsequent `flush` calls without new `add`s are
+   * no-ops. Idempotent on an empty queue.
+   */
+  flush(stream: NodeJS.WritableStream): void;
+}
+
+export function createWarningBuffer(): WarningBuffer {
+  const queue: string[] = [];
+  return {
+    add(msg: string): void {
+      queue.push(msg);
+    },
+    flush(stream: NodeJS.WritableStream): void {
+      while (queue.length > 0) {
+        const msg = queue.shift()!;
+        stream.write(msg.endsWith('\n') ? msg : `${msg}\n`);
+      }
+    },
+  };
+}

package/src/worktree/auto-tmux.ts

@@ -0,0 +1,45 @@
+/**
+ * Auto-tmux gating (§5.4) — when `config.auto.tmux = "worktree"` and the
+ * user is creating a new worktree (i.e. `-w <name>` was set and the
+ * worktree-intercept layer did NOT find an existing match), inject
+ * `--tmux` into passthrough. The injection itself is the caller's job;
+ * this module decides whether.
+ *
+ * Per design.md §1 and prd.launcher.md "Auto-tmux for new worktrees".
+ *
+ * All five conditions must hold:
+ *   1. configAutoTmux === "worktree"
+ *   2. worktreeSet === true (user passed -w / 2nd-positional)
+ *   3. worktreeMatched === false (a new worktree, not entering an
+ *      existing one)
+ *   4. noTmux === false (user did not pass --no-tmux escape hatch)
+ *   5. passthrough does NOT already contain `--tmux` or `--tmux=…`
+ *      (short -T is assumed to have been expanded by §4.5)
+ *
+ * If any fails: do nothing — explicit user intent always wins.
+ */
+
+export interface AutoTmuxArgs {
+  configAutoTmux: string | undefined;
+  worktreeSet: boolean;
+  worktreeMatched: boolean;
+  noTmux: boolean;
+  passthrough: readonly string[];
+}
+
+function passthroughHasTmux(passthrough: readonly string[]): boolean {
+  for (const tok of passthrough) {
+    if (tok === '--tmux') return true;
+    if (tok.startsWith('--tmux=')) return true;
+  }
+  return false;
+}
+
+export function shouldInjectTmux(args: AutoTmuxArgs): boolean {
+  if (args.configAutoTmux !== 'worktree') return false;
+  if (!args.worktreeSet) return false;
+  if (args.worktreeMatched) return false;
+  if (args.noTmux) return false;
+  if (passthroughHasTmux(args.passthrough)) return false;
+  return true;
+}

package/src/worktree/git-list.ts

@@ -0,0 +1,73 @@
+/**
+ * Run `git worktree list --porcelain` in a directory and parse the output
+ * into Worktree[] for the intercept layer (§5.3).
+ *
+ * Porcelain block format (per git docs):
+ *
+ *   worktree /abs/path
+ *   HEAD <sha>
+ *   branch refs/heads/<name>     OR     detached
+ *
+ * Blocks separated by blank lines. The branch field's "refs/heads/"
+ * prefix is stripped so callers can match against the user-typed name
+ * directly. Detached worktrees get branch = "".
+ *
+ * listWorktrees() returns null if git isn't installed, the directory
+ * isn't a git repo, or git errored — the intercept layer treats null as
+ * "no worktrees, no match" and forwards `-w` to claude unchanged.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import type { Worktree } from './intercept.ts';
+
+const REFS_HEADS_PREFIX = 'refs/heads/';
+
+export function parseGitWorktreeListPorcelain(out: string): Worktree[] {
+  const lines = out.split('\n');
+  const worktrees: Worktree[] = [];
+  let cur: { path: string | null; branch: string | null } = { path: null, branch: null };
+
+  const flush = (): void => {
+    if (cur.path !== null) {
+      worktrees.push({ path: cur.path, branch: cur.branch ?? '' });
+    }
+    cur = { path: null, branch: null };
+  };
+
+  for (const line of lines) {
+    if (line === '') {
+      flush();
+      continue;
+    }
+    if (line.startsWith('worktree ')) {
+      flush();
+      cur.path = line.slice('worktree '.length);
+    } else if (line.startsWith('branch ')) {
+      const v = line.slice('branch '.length);
+      cur.branch = v.startsWith(REFS_HEADS_PREFIX) ? v.slice(REFS_HEADS_PREFIX.length) : v;
+    } else if (line === 'detached') {
+      cur.branch = '';
+    }
+    // HEAD <sha> and any unknown lines: ignored.
+  }
+  flush();
+
+  return worktrees;
+}
+
+export function listWorktrees(cwd: string): Worktree[] | null {
+  let result;
+  try {
+    result = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  } catch {
+    return null;
+  }
+  if (result.error !== undefined) return null;
+  if (result.status !== 0) return null;
+  return parseGitWorktreeListPorcelain(result.stdout);
+}

package/src/worktree/intercept.ts

@@ -0,0 +1,150 @@
+/**
+ * Worktree intercept — handles `-w <name>` (and 2nd-positional, which
+ * the parser routes through the same worktreeArg slot).
+ *
+ * Mirrors Go canonical `src/main.go:631-743` with one rewrite deviation
+ * per PRD item #8: ALSO set `--name <name>` on match. Go canonical
+ * didn't; the rewrite always sets `--name` so the session name reflects
+ * the worktree name regardless of match.
+ *
+ * Behavior matrix (specs.md §10):
+ *
+ *   worktreeSet=false       → no-op (passthrough unchanged)
+ *   bare -w (arg='')        → push `--worktree` alone (no name)
+ *   -w <name>, match found  → swap launchCwd to match.path;
+ *                             push `--name <name>` (unless --name/-n
+ *                             already in passthrough);
+ *                             do NOT push `--worktree`
+ *   -w <name>, no match     → push `--worktree <name>`; push
+ *                             `--name <name>` (unless already set)
+ *   -w <name>, not a repo   → same as no-match (listWorktrees returns
+ *                             null; git errors degrade silently)
+ *
+ * Match priority ladder against sanitizeForPath(<name>):
+ *   1. branch === query
+ *   2. branch with "worktree-" prefix stripped === query
+ *   3. basename(worktree.path) === query
+ *
+ * The name is sanitized via §5.1 sanitizeForPath. Invalid → original
+ * kept (with a deferred warning); changed-but-valid → sanitized used
+ * (with a deferred warning naming both).
+ */
+
+import { basename } from 'node:path';
+
+import { sanitizeForPath } from '../name/sanitize.ts';
+
+export interface Worktree {
+  path: string;
+  branch: string;
+}
+
+export interface InterceptArgs {
+  worktreeSet: boolean;
+  worktreeArg: string;
+  launchCwd: string;
+  passthrough: readonly string[];
+  /**
+   * Return the list of worktrees in launchCwd, or null if it's not a
+   * git repo (or git failed). Caller wires `git worktree list
+   * --porcelain` parsing.
+   */
+  listWorktrees: (cwd: string) => Worktree[] | null;
+}
+
+export interface InterceptResult {
+  launchCwd: string;
+  passthrough: string[];
+  worktreeMatched: boolean;
+  warnings: string[];
+}
+
+const WORKTREE_BRANCH_PREFIX = 'worktree-';
+
+function hasNameInPassthrough(passthrough: readonly string[]): boolean {
+  for (let i = 0; i < passthrough.length; i++) {
+    const tok = passthrough[i]!;
+    if (tok === '--name' || tok === '-n') return true;
+    if (tok.startsWith('--name=') || tok.startsWith('-n=')) return true;
+  }
+  return false;
+}
+
+function findMatch(name: string, wts: Worktree[]): Worktree | null {
+  // Priority 1: exact branch match
+  for (const wt of wts) {
+    if (wt.branch === name) return wt;
+  }
+  // Priority 2: branch with worktree- prefix stripped
+  for (const wt of wts) {
+    if (
+      wt.branch.startsWith(WORKTREE_BRANCH_PREFIX) &&
+      wt.branch.slice(WORKTREE_BRANCH_PREFIX.length) === name
+    ) {
+      return wt;
+    }
+  }
+  // Priority 3: basename of worktree path
+  for (const wt of wts) {
+    if (basename(wt.path) === name) return wt;
+  }
+  return null;
+}
+
+export function applyWorktreeIntercept(args: InterceptArgs): InterceptResult {
+  const passthrough = [...args.passthrough];
+  const warnings: string[] = [];
+
+  if (!args.worktreeSet) {
+    return { launchCwd: args.launchCwd, passthrough, worktreeMatched: false, warnings };
+  }
+
+  // Bare -w (no value)
+  if (args.worktreeArg === '') {
+    passthrough.push('--worktree');
+    return { launchCwd: args.launchCwd, passthrough, worktreeMatched: false, warnings };
+  }
+
+  // Sanitize the name, collecting any warning.
+  const san = sanitizeForPath(args.worktreeArg);
+  let name: string;
+  if (san.kind === 'unchanged') {
+    name = san.value;
+  } else if (san.kind === 'changed') {
+    name = san.value;
+    warnings.push(
+      `fnclaude: -w ${JSON.stringify(san.original)} sanitized to ${JSON.stringify(san.value)} (illegal path/branch chars)`,
+    );
+  } else {
+    // Invalid — pass original through with warning, no match attempted.
+    name = san.original;
+    warnings.push(
+      `fnclaude: -w ${JSON.stringify(san.original)} is not a safe path/branch name; passed through unchanged`,
+    );
+  }
+
+  const wts = args.listWorktrees(args.launchCwd);
+  const match = wts === null ? null : findMatch(name, wts);
+
+  if (match !== null) {
+    // Match: swap cwd, set --name unless already set, don't forward --worktree.
+    const result: InterceptResult = {
+      launchCwd: match.path,
+      passthrough,
+      worktreeMatched: true,
+      warnings,
+    };
+    if (!hasNameInPassthrough(passthrough)) {
+      passthrough.push('--name', name);
+    }
+    return result;
+  }
+
+  // No match: pass --worktree <name> through, set --name unless already set.
+  passthrough.push('--worktree', name);
+  if (!hasNameInPassthrough(args.passthrough)) {
+    passthrough.push('--name', name);
+  }
+
+  return { launchCwd: args.launchCwd, passthrough, worktreeMatched: false, warnings };
+}

package/bin/preflight.js

@@ -1,66 +0,0 @@
-// 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/prompts/agent-pitfall.md

@@ -1 +0,0 @@
-When using the Task / Agent tool with isolation set to "worktree", do not name the main repo's absolute path in the spawn prompt — the agent will cd there and silently bypass its isolated worktree. Phrase locations as "your worktree" or "this directory", and verify with git log on the worktree branch after the agent reports done.