@fnclaude/cli 1.1.1 → 2.0.0

package/src/name/auto-name.ts

@@ -0,0 +1,162 @@
+/**
+ * Pure-function pieces of auto-name (§5.2 / design.md §18):
+ *   - shouldAutoName(parsed) — gating condition: does this invocation
+ *     qualify for auto-naming?
+ *   - sanitizeLLMOutput(s) — slug-clean an LLM's freeform response
+ *   - heuristicName(prompt) — deterministic fallback when no LLM
+ *
+ * The LLM call itself (Anthropic SDK with ANTHROPIC_API_KEY, or `claude
+ * -p` subprocess fallback) sits at the orchestrator layer; this module
+ * provides the building blocks it relies on.
+ *
+ * Mirrors Go canonical src/autoname.go:1-253.
+ */
+
+import {
+  findPromptSentinel,
+  hasPromptBody,
+  promptBody,
+} from '../argv/sentinel.ts';
+import type { ParsedArgsOk } from '../argv/parse.ts';
+
+// ── shouldAutoName ──────────────────────────────────────────────────────────
+
+const BLOCKERS_NO_VALUE = new Set([
+  '-p',
+  '--print',
+  '-r',
+  '--resume',
+  '-c',
+  '--continue',
+  '--from-pr',
+  '-P',
+]);
+
+// Token forms like `--name=foo`, `-n=foo`, `-r=abc`, `--resume=abc`,
+// `--from-pr=123`, `-P=123`. Stored as prefixes to check via startsWith.
+const BLOCKERS_EQUAL_PREFIX = [
+  '--name=',
+  '-n=',
+  '--resume=',
+  '-r=',
+  '--from-pr=',
+  '-P=',
+];
+
+// Two-token form (flag + separate value). When we see any of these, the
+// next-token shape doesn't matter — the presence of the flag itself
+// blocks auto-name.
+const BLOCKERS_TWO_TOKEN = new Set(['--name', '-n']);
+
+export function shouldAutoName(parsed: ParsedArgsOk): boolean {
+  const pt = parsed.passthrough;
+  const sentinelIdx = findPromptSentinel(pt);
+  if (sentinelIdx < 0) return false;
+  if (!hasPromptBody(pt, sentinelIdx)) return false;
+  if (promptBody(pt, sentinelIdx).every((t) => t === '')) return false;
+
+  // Scan up to the sentinel — only flags BEFORE `--` count.
+  for (let i = 0; i < sentinelIdx; i++) {
+    const tok = pt[i]!;
+    if (BLOCKERS_NO_VALUE.has(tok)) return false;
+    if (BLOCKERS_TWO_TOKEN.has(tok)) return false;
+    for (const pre of BLOCKERS_EQUAL_PREFIX) {
+      if (tok.startsWith(pre)) return false;
+    }
+  }
+  return true;
+}
+
+// ── sanitizeLLMOutput ───────────────────────────────────────────────────────
+
+const RE_WHITESPACE = /\s+/g;
+const RE_NON_SLUG = /[^a-z0-9-]+/g;
+const RE_MULTI_DASH = /-{2,}/g;
+
+export function sanitizeLLMOutput(input: string): string {
+  let s = input.trim().toLowerCase();
+  s = s.replace(RE_WHITESPACE, '-');
+  s = s.replace(RE_NON_SLUG, '');
+  s = s.replace(RE_MULTI_DASH, '-');
+  s = trimChar(s, '-');
+  // Take first 3 segments
+  const parts = s.split('-').filter((p) => p.length > 0).slice(0, 3);
+  s = parts.join('-');
+  return trimChar(s, '-');
+}
+
+function trimChar(s: string, ch: string): string {
+  let start = 0;
+  let end = s.length;
+  while (start < end && s[start] === ch) start++;
+  while (end > start && s[end - 1] === ch) end--;
+  return s.slice(start, end);
+}
+
+// ── heuristicName ───────────────────────────────────────────────────────────
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'the',
+  'is', 'are', 'was', 'were',
+  'do', 'does', 'did',
+  'of', 'for', 'to', 'in', 'on', 'at', 'with',
+  'this', 'that',
+  'please', 'can', 'could', 'would', 'should',
+]);
+
+const RE_NON_ALNUM = /[^a-z0-9]/g;
+
+export function heuristicName(prompt: string): string {
+  const fields = prompt.toLowerCase().split(/\s+/).filter((w) => w.length > 0);
+  const kept: string[] = [];
+  for (const word of fields) {
+    if (STOP_WORDS.has(word)) continue;
+    const stripped = word.replace(RE_NON_ALNUM, '');
+    if (stripped === '') continue;
+    kept.push(stripped);
+    if (kept.length === 3) break;
+  }
+  if (kept.length === 0) return 'session';
+  return kept.join('-');
+}
+
+// ── autoName orchestrator ───────────────────────────────────────────────────
+
+export interface AutoNameOptions {
+  prompt: string;
+  /** Provide to use an LLM. If omitted, heuristic is used directly. */
+  llmCall?: (prompt: string) => Promise<string>;
+  /** Timeout in ms for the LLM call. */
+  timeoutMs?: number;
+}
+
+/**
+ * Generate a session name from the prompt. Tries the LLM (if provided)
+ * first, falls back to the heuristic on timeout, error, or empty result.
+ *
+ * The LLM call surface is injected so this layer stays pure of network/
+ * API-key concerns — the CLI wires either an Anthropic SDK call (when
+ * ANTHROPIC_API_KEY is set) or a `claude -p` subprocess.
+ */
+export async function autoName(opts: AutoNameOptions): Promise<string> {
+  const { prompt, llmCall, timeoutMs = 3000 } = opts;
+
+  if (llmCall === undefined) return heuristicName(prompt);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const llmPromise = llmCall(prompt).then((s) => sanitizeLLMOutput(s));
+  const timeoutPromise = new Promise<string>((_, reject) => {
+    timer = setTimeout(() => reject(new Error('auto-name LLM timeout')), timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([llmPromise, timeoutPromise]);
+    if (result !== '') return result;
+  } catch {
+    // fall through to heuristic
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+
+  return heuristicName(prompt);
+}

package/src/name/llm-prompt.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared constants for the auto-name LLM call (§5.2).
+ *
+ * Both the Anthropic SDK fast-path (`sdk-llm.ts`) and the `claude -p`
+ * subprocess fallback (in `main.ts`) drive the same model with the same
+ * system prompt; extracting them here keeps the two paths in sync.
+ */
+
+export const AUTO_NAME_MODEL = 'claude-haiku-4-5';
+
+export const AUTO_NAME_SYSTEM_PROMPT =
+  "Generate a 1-3 word lowercase hyphen-separated label for this user's request. " +
+  "Output ONLY the label — no punctuation, no quotes, no explanation, no leading 'Label:'. " +
+  "Examples: 'fix-login-bug', 'add-dark-mode', 'refactor-auth'.";

package/src/name/sanitize.ts

@@ -0,0 +1,57 @@
+/**
+ * Sanitize a name for use as a path component (worktree name, etc.).
+ *
+ * Mirrors Go canonical `src/sanitize.go:1-50`.
+ *
+ * Pipeline (in order):
+ *   1. Empty input → invalid.
+ *   2. Input starting with `/` → invalid (path-escape risk).
+ *   3. Replace runs of chars NOT in [A-Za-z0-9._/-] with a single `-`.
+ *   4. Collapse `-{2,}` runs to single `-`.
+ *   5. Collapse `/{2,}` runs to single `/`.
+ *   6. TrimLeft `[-.]`  (strips leading dashes and dots).
+ *   7. TrimRight `[-/]` (strips trailing dashes and slashes).
+ *   8. Empty result → invalid.
+ *   9. Result contains `..` → invalid (path-escape prevention).
+ *
+ * `/` is intentionally permitted so nested git refs (`feat/foo`,
+ * `team/x/y`) pass through and produce nested worktree paths.
+ */
+
+const RE_PATH_SAFE_BAD = /[^A-Za-z0-9._/-]+/g;
+const RE_DASH_RUN = /-{2,}/g;
+const RE_SLASH_RUN = /\/{2,}/g;
+
+export type SanitizeResult =
+  | { kind: 'unchanged'; value: string }
+  | { kind: 'changed'; value: string; original: string }
+  | { kind: 'invalid'; original: string };
+
+export function sanitizeForPath(input: string): SanitizeResult {
+  if (input === '') return { kind: 'invalid', original: input };
+  if (input.startsWith('/')) return { kind: 'invalid', original: input };
+
+  let s = input.replace(RE_PATH_SAFE_BAD, '-');
+  s = s.replace(RE_DASH_RUN, '-');
+  s = s.replace(RE_SLASH_RUN, '/');
+  s = trimLeftChars(s, '-.');
+  s = trimRightChars(s, '-/');
+
+  if (s === '') return { kind: 'invalid', original: input };
+  if (s.includes('..')) return { kind: 'invalid', original: input };
+
+  if (s === input) return { kind: 'unchanged', value: s };
+  return { kind: 'changed', value: s, original: input };
+}
+
+function trimLeftChars(s: string, chars: string): string {
+  let i = 0;
+  while (i < s.length && chars.includes(s[i]!)) i++;
+  return s.slice(i);
+}
+
+function trimRightChars(s: string, chars: string): string {
+  let i = s.length;
+  while (i > 0 && chars.includes(s[i - 1]!)) i--;
+  return s.slice(0, i);
+}

package/src/name/sdk-llm.ts

@@ -0,0 +1,42 @@
+/**
+ * Anthropic SDK fast-path for auto-naming (§5.2).
+ *
+ * When ANTHROPIC_API_KEY is set, the launcher calls the API directly via
+ * the official SDK instead of shelling out to `claude -p`. Same model
+ * (haiku) + same system prompt as the subprocess path, but skips the
+ * cold-start overhead of spawning the claude binary, parsing its config,
+ * etc. — typically saves multiple seconds.
+ *
+ * No timeout handling here; `autoName` wraps the call with Promise.race
+ * for that, and the SDK has its own retry/backoff machinery on transient
+ * errors. We just need to return the text (or throw — autoName treats
+ * either error or empty output as "fall back to heuristic").
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+
+import { AUTO_NAME_SYSTEM_PROMPT, AUTO_NAME_MODEL } from './llm-prompt.ts';
+
+export async function sdkLlmCall(prompt: string): Promise<string> {
+  // SDK picks ANTHROPIC_API_KEY up from process.env by default. Letting it
+  // do so (rather than passing apiKey explicitly) keeps the env-var name
+  // the single source of truth and matches the way every other Anthropic
+  // tool documents it.
+  const client = new Anthropic();
+  const msg = await client.messages.create({
+    model: AUTO_NAME_MODEL,
+    max_tokens: 64,
+    system: AUTO_NAME_SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: prompt }],
+  });
+  // The response is an array of content blocks; auto-name's prompt steers
+  // the model to a one-line label so we expect exactly one text block.
+  // Concatenate any text blocks defensively in case the model emits more
+  // than one — sanitizeLLMOutput downstream will collapse whitespace
+  // and clip to 3 segments either way.
+  let out = '';
+  for (const block of msg.content) {
+    if (block.type === 'text') out += block.text;
+  }
+  return out;
+}

package/src/noop/seed.ts

@@ -0,0 +1,63 @@
+/**
+ * Seed `handoff.template.md` into the noop dir on first noop-fallback
+ * launches (design.md §19).
+ *
+ * The function is a strict guard:
+ *   - if `<noopDir>/handoff.template.md` already exists → no-op
+ *   - if `templateSourcePath` doesn't exist on disk → no-op (graceful
+ *     degradation; the launch must not fail because the embedded template
+ *     wasn't shipped)
+ *   - otherwise copy source → dest, creating the noop dir if missing
+ *
+ * NB: only `handoff.template.md` is seeded. `CLAUDE.md` and every other
+ * file in the noop dir is user-owned and fnclaude never touches them.
+ * That's the README divergence the rewrite caller was warned about.
+ *
+ * Mirrors Go canonical's `seedNoop` (src/noop.go:1–58) loosely — the Go
+ * version uses SHA-256 to detect template drift; the rewrite goes with
+ * "missing only" semantics, which is simpler and matches what users
+ * actually want (don't clobber my hand-edited template on every launch).
+ */
+
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface SeedNoopDirArgs {
+  noopDir: string;
+  templateSourcePath: string | null;
+}
+
+export interface SeedNoopDirResult {
+  ok: boolean;
+  copied: boolean;
+  reason?: string;
+}
+
+const TEMPLATE_FILENAME = 'handoff.template.md';
+
+export async function seedNoopDir(args: SeedNoopDirArgs): Promise<SeedNoopDirResult> {
+  if (args.templateSourcePath === null || args.templateSourcePath === '') {
+    return { ok: true, copied: false, reason: 'no source template' };
+  }
+  if (!existsSync(args.templateSourcePath)) {
+    return { ok: true, copied: false, reason: 'no source template' };
+  }
+
+  const dest = join(args.noopDir, TEMPLATE_FILENAME);
+  if (existsSync(dest)) {
+    return { ok: true, copied: false, reason: 'already exists' };
+  }
+
+  try {
+    await mkdir(args.noopDir, { recursive: true });
+    await copyFile(args.templateSourcePath, dest);
+    return { ok: true, copied: true };
+  } catch (err) {
+    return {
+      ok: false,
+      copied: false,
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/noop/template-source.ts

@@ -0,0 +1,62 @@
+/**
+ * Resolve the on-disk source for `handoff.template.md`, which fnclaude
+ * seeds into the noop dir on first noop-fallback launches (design.md §19).
+ *
+ * Precedence (mirrors prompts/dir.ts):
+ *   1. $FNC_NOOP_TEMPLATE_PATH (env override; empty string treated as unset)
+ *   2. <exe-dir>/templates/handoff.template.md         (dev / sibling layout)
+ *   3. <exe-dir>/../templates/handoff.template.md      (npm / monorepo layout
+ *                                                       where the bin lives
+ *                                                       in its own subdir)
+ *   4. <exe-dir>/../share/fnclaude/templates/handoff.template.md
+ *                                                      (FHS / AUR layout —
+ *                                                       this is also where
+ *                                                       the repo ships the
+ *                                                       canonical copy)
+ *
+ * Symlink resolution of exeDir is the caller's responsibility — pass the
+ * already-resolved path here.
+ *
+ * Returns the first candidate that exists and is a regular file. If none
+ * match, returns null. Seeding gracefully degrades on null (the noop dir
+ * is still created and the session still launches per design.md §19) so
+ * we don't bother surfacing a warning here.
+ */
+
+import { statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface ResolveTemplateSourceArgs {
+  envOverride: string | undefined;
+  exeDir: string;
+}
+
+export interface ResolveTemplateSourceResult {
+  path: string | null;
+  tried: string[];
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function resolveTemplateSourcePath(args: ResolveTemplateSourceArgs): ResolveTemplateSourceResult {
+  const candidates: string[] = [];
+
+  if (args.envOverride !== undefined && args.envOverride !== '') {
+    candidates.push(args.envOverride);
+  }
+  candidates.push(join(args.exeDir, 'templates', 'handoff.template.md'));
+  candidates.push(resolve(args.exeDir, '..', 'templates', 'handoff.template.md'));
+  candidates.push(resolve(args.exeDir, '..', 'share', 'fnclaude', 'templates', 'handoff.template.md'));
+
+  for (const c of candidates) {
+    if (isFile(c)) return { path: c, tried: candidates };
+  }
+
+  return { path: null, tried: candidates };
+}

package/src/path/ensure-cwd.ts

@@ -0,0 +1,95 @@
+/**
+ * Fabricate a missing cwd tree so Bun.spawn doesn't report ENOENT against
+ * the claude binary path. Per design.md §26 (Go canonical src/pty_run.go:154-237).
+ *
+ * Motivation: when resuming a session whose stored cwd no longer exists,
+ * the kernel returns ENOENT during spawn — but the error message blames
+ * the binary, not the cwd. Pre-creating the cwd tree gets us a clean
+ * spawn; the cwd is held by inode reference after the child chdirs, so
+ * we can remove the fabricated dirs immediately afterward and the child
+ * still has a working pwd.
+ *
+ * Algorithm:
+ *   1. Dir exists & is a directory → return ok with empty created list
+ *   2. Dir exists & is NOT a directory → error
+ *   3. Walk up the tree recording missing levels (shallowest first)
+ *   4. mkdir each missing level in order
+ *   5. Return a cleanup() that rmdirs each in deepest-first order
+ *
+ * Cleanup robustness:
+ *   - Tolerates a created dir that became non-empty (rmdir refuses;
+ *     we swallow the error — the spec treats this as "shouldn't happen"
+ *     but we don't want cleanup to crash the launcher path)
+ *   - Idempotent: safe to call cleanup() twice
+ */
+
+import { mkdirSync, rmdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export type EnsureCwdResult =
+  | { ok: true; created: string[]; cleanup: () => void }
+  | { ok: false; error: string };
+
+export function ensureCwd(path: string): EnsureCwdResult {
+  // Walk up collecting missing levels (deepest first while collecting,
+  // we reverse at the end).
+  const missing: string[] = [];
+  let cur = path;
+  while (true) {
+    let st;
+    try {
+      st = statSync(cur);
+    } catch {
+      missing.push(cur);
+      const parent = dirname(cur);
+      if (parent === cur) {
+        // Reached filesystem root and still missing — implausible but defensive.
+        return { ok: false, error: `cannot ensure cwd: walked to root looking for ${path}` };
+      }
+      cur = parent;
+      continue;
+    }
+    // Found an existing level.
+    if (!st.isDirectory()) {
+      return { ok: false, error: `cannot ensure cwd: ${cur} exists but is not a directory` };
+    }
+    break;
+  }
+
+  // Reverse so shallowest-first; that's the mkdir order we need.
+  missing.reverse();
+  const created: string[] = [];
+  for (const p of missing) {
+    try {
+      mkdirSync(p);
+      created.push(p);
+    } catch (err) {
+      // Unwind what we created on failure.
+      cleanupCreated(created);
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, error: `cannot ensure cwd: mkdir ${p} failed (${msg})` };
+    }
+  }
+
+  let cleanedUp = false;
+  const cleanup = (): void => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    cleanupCreated(created);
+  };
+
+  return { ok: true, created, cleanup };
+}
+
+function cleanupCreated(created: readonly string[]): void {
+  // Deepest first.
+  for (let i = created.length - 1; i >= 0; i--) {
+    try {
+      rmdirSync(created[i]!);
+    } catch {
+      // Dir became non-empty, was already removed, or some other condition.
+      // Don't crash the launcher; the spec treats this as "shouldn't happen"
+      // but our policy is best-effort cleanup.
+    }
+  }
+}

package/src/path/resolve.ts

@@ -0,0 +1,58 @@
+/**
+ * Path-targeting primitives: tilde expansion, noop fallback, and the
+ * full launch-cwd resolver.
+ *
+ * Mirrors Go canonical's expandTildePath (src/resolver.go:267-278) and
+ * the cwd-resolution block in main.go around lines 940-963: tilde first,
+ * then make absolute by joining against the shell cwd.
+ *
+ * Repo-reference resolution (bare-name multi-org search, owner/name,
+ * SSH/HTTPS URLs, name@owner cloneTemplate forms) is a separate concern
+ * handled in §3.4 — resolveCwd here ASSUMES its input is a filesystem
+ * path. Callers route repo references through the resolver first.
+ */
+
+import { isAbsolute, join } from 'node:path';
+
+const SEPARATOR = '/';
+
+export interface ResolveEnv {
+  home: string;
+  xdgConfigHome: string | undefined;
+  shellCwd: string;
+}
+
+export interface ResolveResult {
+  launchCwd: string;
+  usedNoopFallback: boolean;
+}
+
+export function expandTilde(input: string, home: string): string {
+  if (input === '~') return home;
+  if (input.startsWith(`~${SEPARATOR}`)) return join(home, input.slice(2));
+  return input;
+}
+
+export function noopDir(env: { xdgConfigHome: string | undefined; home: string }): string {
+  const base = env.xdgConfigHome && env.xdgConfigHome.length > 0
+    ? env.xdgConfigHome
+    : join(env.home, '.config');
+  return join(base, 'fnclaude', 'noop');
+}
+
+export function resolveCwd(firstPath: string | null, env: ResolveEnv): ResolveResult {
+  if (firstPath === null || firstPath === '') {
+    return {
+      launchCwd: noopDir(env),
+      usedNoopFallback: true,
+    };
+  }
+
+  const expanded = expandTilde(firstPath, env.home);
+  const launchCwd = isAbsolute(expanded) ? expanded : join(env.shellCwd, expanded);
+
+  return {
+    launchCwd,
+    usedNoopFallback: false,
+  };
+}

package/src/prompts/dir.ts

@@ -0,0 +1,61 @@
+/**
+ * Resolve the prompts directory to load fragments from (specs.md §12.1).
+ *
+ * Precedence:
+ *   1. $FNC_PROMPTS_DIR (env override; empty string treated as unset)
+ *   2. <exe-dir>/prompts/                       (dev / sibling layout)
+ *   3. <exe-dir>/../prompts/                    (npm / monorepo layout
+ *                                                where the bin lives in
+ *                                                its own subdir)
+ *   4. <exe-dir>/../share/fnclaude/prompts/     (FHS / AUR layout)
+ *
+ * Symlink resolution of exeDir is the caller's responsibility — pass the
+ * already-resolved path here (Go canonical uses filepath.EvalSymlinks
+ * before invoking this).
+ *
+ * Returns the first candidate that exists and is a directory. If none
+ * match, returns null + a warning naming all candidates tried, so the
+ * caller can degrade gracefully (PromptSet empty, session still launches
+ * per specs.md §12.1).
+ */
+
+import { statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface ResolvePromptsDirArgs {
+  envOverride: string | undefined;
+  exeDir: string;
+}
+
+export interface ResolvePromptsDirResult {
+  dir: string | null;
+  warning: string | undefined;
+}
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function resolvePromptsDir(args: ResolvePromptsDirArgs): ResolvePromptsDirResult {
+  const candidates: string[] = [];
+
+  if (args.envOverride !== undefined && args.envOverride !== '') {
+    candidates.push(args.envOverride);
+  }
+  candidates.push(join(args.exeDir, 'prompts'));
+  candidates.push(resolve(args.exeDir, '..', 'prompts'));
+  candidates.push(resolve(args.exeDir, '..', 'share', 'fnclaude', 'prompts'));
+
+  for (const c of candidates) {
+    if (isDir(c)) return { dir: c, warning: undefined };
+  }
+
+  return {
+    dir: null,
+    warning: `fnclaude: prompts directory not found; tried: ${candidates.join(', ')}. Set FNC_PROMPTS_DIR to override.`,
+  };
+}