Merge pull request #110 from AxmeAI/fix/find-claude-path-fallback-20260417

fix(agents): findClaudePath resolves via env vars, standard paths, nvm (B-009)

Author: George-iam

benchmarks/package-lock.json

@@ -3,27 +3,97 @@
  */
 
 import { execSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { resolveAuthMode } from "./auth-config.js";
 
 type Options = import("@anthropic-ai/claude-agent-sdk").Options;
 
 /**
- * Find claude binary path. Cached after first lookup.
+ * Find the `claude` CLI binary path. Cached after first successful lookup.
  *
- * Exported because the SDK resolves its own path via `import.meta.url`, which
- * returns undefined inside the bundled CJS build and crashes with
- * `fileURLToPath(undefined)` (B-006 / D-121). Every direct `sdk.query()` call
- * site must set `pathToClaudeCodeExecutable` to the result of this function.
+ * The Claude Agent SDK resolves its own executable via `import.meta.url`,
+ * which is `undefined` inside our bundled CJS builds and crashes with
+ * `fileURLToPath(undefined)` (B-006 / D-121). Every `sdk.query()` call must
+ * set `pathToClaudeCodeExecutable` to the result of this function.
+ *
+ * Resolution order (B-009 — first match wins):
+ *   1. `AXME_CLAUDE_EXECUTABLE` env var — explicit override for CI / unusual installs
+ *   2. `CLAUDE_CODE_ENTRYPOINT` env var — set by Claude Code itself in some contexts
+ *   3. `which claude` — standard PATH lookup (works on most dev machines)
+ *   4. Standard install locations (no PATH dependency):
+ *      - ~/.local/bin/claude
+ *      - /usr/local/bin/claude
+ *      - /opt/homebrew/bin/claude (macOS Apple Silicon)
+ *      - /usr/bin/claude
+ *   5. nvm-managed installs: ~/.nvm/versions/node/* /bin/claude
+ *
+ * Returns undefined only if none of the above yields a readable file.
+ * Callers should treat undefined as "claude not installed" and either
+ * fail-fast with an actionable message or skip the LLM call.
  */
 let _claudePath: string | undefined;
 export function findClaudePath(): string | undefined {
   if (_claudePath !== undefined) return _claudePath || undefined;
+
+  // 1. Explicit override
+  if (process.env.AXME_CLAUDE_EXECUTABLE && existsSync(process.env.AXME_CLAUDE_EXECUTABLE)) {
+    _claudePath = process.env.AXME_CLAUDE_EXECUTABLE;
+    return _claudePath;
+  }
+
+  // 2. SDK's own env var
+  if (process.env.CLAUDE_CODE_ENTRYPOINT && existsSync(process.env.CLAUDE_CODE_ENTRYPOINT)) {
+    _claudePath = process.env.CLAUDE_CODE_ENTRYPOINT;
+    return _claudePath;
+  }
+
+  // 3. which claude (PATH lookup)
   try {
-    _claudePath = execSync("which claude", { encoding: "utf-8" }).trim();
-  } catch {
-    _claudePath = "";
+    const p = execSync("which claude", { encoding: "utf-8", timeout: 5000 }).trim();
+    if (p && existsSync(p)) {
+      _claudePath = p;
+      return _claudePath;
+    }
+  } catch { /* not in PATH — continue to standard locations */ }
+
+  // 4. Standard install locations
+  const home = homedir();
+  const standardPaths = [
+    join(home, ".local", "bin", "claude"),
+    "/usr/local/bin/claude",
+    "/opt/homebrew/bin/claude",
+    "/usr/bin/claude",
+  ];
+  for (const candidate of standardPaths) {
+    if (existsSync(candidate)) {
+      _claudePath = candidate;
+      return _claudePath;
+    }
   }
-  return _claudePath || undefined;
+
+  // 5. nvm-managed installs (common on dev machines)
+  try {
+    const nvmDir = join(home, ".nvm", "versions", "node");
+    if (existsSync(nvmDir)) {
+      for (const ver of readdirSync(nvmDir)) {
+        const candidate = join(nvmDir, ver, "bin", "claude");
+        if (existsSync(candidate)) {
+          _claudePath = candidate;
+          return _claudePath;
+        }
+      }
+    }
+  } catch { /* nvm not present — fine */ }
+
+  _claudePath = "";
+  return undefined;
+}
+
+/** @internal Reset cached claude path. Used in tests only. */
+export function _resetFindClaudePath(): void {
+  _claudePath = undefined;
 }
 
 export type AgentRole = "scanner" | "tester" | "reviewer" | "engineer" | "architect" | "auditor";

package-lock.json

@@ -0,0 +1,144 @@
+/**
+ * Tests for findClaudePath() resolver (B-009).
+ *
+ * The resolver has 5 steps: env override, SDK env var, `which claude`,
+ * standard install locations, nvm glob. We test the env-based steps
+ * (1, 2) directly and verify cache + reset behavior.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdirSync, unlinkSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { findClaudePath, _resetFindClaudePath } from "../src/utils/agent-options.ts";
+
+// Save original env
+let savedAxme: string | undefined;
+let savedEntrypoint: string | undefined;
+
+function createTmpExecutable(name: string): string {
+  const dir = join(tmpdir(), `axme-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, name);
+  writeFileSync(file, "#!/bin/sh\necho mock", "utf-8");
+  try { chmodSync(file, 0o755); } catch {}
+  return file;
+}
+
+function removeTmp(path: string): void {
+  try { unlinkSync(path); } catch {}
+}
+
+describe("findClaudePath — resolution order (B-009)", () => {
+  beforeEach(() => {
+    _resetFindClaudePath();
+    savedAxme = process.env.AXME_CLAUDE_EXECUTABLE;
+    savedEntrypoint = process.env.CLAUDE_CODE_ENTRYPOINT;
+    delete process.env.AXME_CLAUDE_EXECUTABLE;
+    delete process.env.CLAUDE_CODE_ENTRYPOINT;
+  });
+
+  afterEach(() => {
+    _resetFindClaudePath();
+    if (savedAxme !== undefined) process.env.AXME_CLAUDE_EXECUTABLE = savedAxme;
+    else delete process.env.AXME_CLAUDE_EXECUTABLE;
+    if (savedEntrypoint !== undefined) process.env.CLAUDE_CODE_ENTRYPOINT = savedEntrypoint;
+    else delete process.env.CLAUDE_CODE_ENTRYPOINT;
+  });
+
+  it("step 1: AXME_CLAUDE_EXECUTABLE env var takes priority over everything", () => {
+    const tmp = createTmpExecutable("claude");
+    try {
+      process.env.AXME_CLAUDE_EXECUTABLE = tmp;
+      const result = findClaudePath();
+      assert.equal(result, tmp);
+    } finally {
+      removeTmp(tmp);
+    }
+  });
+
+  it("step 1: AXME_CLAUDE_EXECUTABLE with non-existent path is skipped", () => {
+    process.env.AXME_CLAUDE_EXECUTABLE = "/nonexistent/path/to/claude";
+    const result = findClaudePath();
+    // Should fall through to step 2+ (not crash, not return the bogus path)
+    assert.notEqual(result, "/nonexistent/path/to/claude");
+  });
+
+  it("step 2: CLAUDE_CODE_ENTRYPOINT used when AXME_CLAUDE_EXECUTABLE absent", () => {
+    const tmp = createTmpExecutable("claude");
+    try {
+      process.env.CLAUDE_CODE_ENTRYPOINT = tmp;
+      const result = findClaudePath();
+      assert.equal(result, tmp);
+    } finally {
+      removeTmp(tmp);
+    }
+  });
+
+  it("step 2: CLAUDE_CODE_ENTRYPOINT with non-existent path is skipped", () => {
+    process.env.CLAUDE_CODE_ENTRYPOINT = "/nonexistent/entrypoint";
+    const result = findClaudePath();
+    assert.notEqual(result, "/nonexistent/entrypoint");
+  });
+
+  it("step 1 beats step 2 when both are set", () => {
+    const tmp1 = createTmpExecutable("claude-axme");
+    const tmp2 = createTmpExecutable("claude-sdk");
+    try {
+      process.env.AXME_CLAUDE_EXECUTABLE = tmp1;
+      process.env.CLAUDE_CODE_ENTRYPOINT = tmp2;
+      const result = findClaudePath();
+      assert.equal(result, tmp1, "AXME_CLAUDE_EXECUTABLE should win over CLAUDE_CODE_ENTRYPOINT");
+    } finally {
+      removeTmp(tmp1);
+      removeTmp(tmp2);
+    }
+  });
+
+  it("result is cached after first successful lookup", () => {
+    const tmp = createTmpExecutable("claude");
+    try {
+      process.env.AXME_CLAUDE_EXECUTABLE = tmp;
+      const first = findClaudePath();
+      assert.equal(first, tmp);
+
+      // Change env — cached result should still be the first one
+      delete process.env.AXME_CLAUDE_EXECUTABLE;
+      const second = findClaudePath();
+      assert.equal(second, tmp, "Should return cached value, not re-resolve");
+    } finally {
+      removeTmp(tmp);
+    }
+  });
+
+  it("_resetFindClaudePath clears the cache", () => {
+    const tmp1 = createTmpExecutable("claude-a");
+    const tmp2 = createTmpExecutable("claude-b");
+    try {
+      process.env.AXME_CLAUDE_EXECUTABLE = tmp1;
+      assert.equal(findClaudePath(), tmp1);
+
+      _resetFindClaudePath();
+      process.env.AXME_CLAUDE_EXECUTABLE = tmp2;
+      assert.equal(findClaudePath(), tmp2, "After reset, should re-resolve");
+    } finally {
+      removeTmp(tmp1);
+      removeTmp(tmp2);
+    }
+  });
+
+  it("returns a string (not undefined) on a dev machine with claude installed", () => {
+    // This test runs on our dev machine where `claude` IS in PATH via nvm.
+    // On CI without claude installed, this test will find it via nvm glob
+    // or standard paths — if neither exist, we just skip the assertion.
+    const result = findClaudePath();
+    if (result) {
+      assert.equal(typeof result, "string");
+      assert.ok(result.length > 0);
+      assert.ok(result.includes("claude"), `Expected path containing 'claude', got: ${result}`);
+    }
+    // If result is undefined (bare CI runner), that's OK — the important
+    // tests are the env-var ones above which we control.
+  });
+});