Merge pull request #3 from Swofty-Developments/feat/claude-detect

feat: claude CLI detection for native and homebrew installs

Author: Swofty-Developments

crates/forge-index/src/headless.rs

@@ -20,13 +20,14 @@ const STDERR_SNIPPET_LEN: usize = 500;
 /// extracted result text. The binary resolves via the login-shell PATH so
 /// desktop-launched apps find the right install.
 pub(crate) async fn run_headless_claude(repo_root: &Path, prompt: &str) -> Result<String> {
-    // `which` checks the login-shell PATH first, then the process PATH; a `None`
-    // here is definitive — there is no `claude` to fall back to. Name it rather
-    // than spawning a bare "claude" that would fail with a confusing ENOENT.
-    let claude = forge_session::shell_env::which("claude").ok_or_else(|| {
+    // `locate_claude` checks the login-shell PATH, then the well-known install
+    // locations (native installer, legacy local, Homebrew); a `None` here is
+    // definitive — there is no `claude` to fall back to. Name it rather than
+    // spawning a bare "claude" that would fail with a confusing ENOENT.
+    let claude = forge_session::shell_env::locate_claude().ok_or_else(|| {
         Error::Indexer(
-            "Claude CLI not found on PATH — install Claude Code (https://claude.com/claude-code) \
-             and ensure `claude` is on your login shell PATH"
+            "Claude Code CLI not found — install it (`brew install --cask claude-code` or \
+             `curl -fsSL https://claude.ai/install.sh | bash`) and reopen the app"
                 .into(),
         )
     })?;

crates/forge-session/src/shell_env.rs

@@ -67,6 +67,47 @@ pub fn which(cmd: &str) -> Option<PathBuf> {
     None
 }
 
+/// Locate the Claude Code CLI: the resolved PATH first, then the well-known
+/// install locations PATH misses when the login-shell probe fails or the
+/// profile doesn't export them — the native installer (`~/.local/bin`), the
+/// legacy local install (`~/.claude/local`), and Homebrew (Apple-silicon and
+/// Intel prefixes).
+pub fn locate_claude() -> Option<PathBuf> {
+    if let Some(found) = which("claude") {
+        return Some(found);
+    }
+    well_known_claude_paths().into_iter().find(|p| is_executable(p))
+}
+
+/// Candidate `claude` install locations outside PATH, best-first.
+fn well_known_claude_paths() -> Vec<PathBuf> {
+    let mut candidates = Vec::new();
+    let home = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE"));
+    if let Some(home) = home {
+        let home = PathBuf::from(home);
+        candidates.push(home.join(".local/bin/claude"));
+        candidates.push(home.join(".claude/local/claude"));
+    }
+    candidates.push(PathBuf::from("/opt/homebrew/bin/claude"));
+    candidates.push(PathBuf::from("/usr/local/bin/claude"));
+    candidates
+}
+
+/// A regular file with an exec bit (symlinks followed, so Homebrew's Cellar
+/// links qualify). Non-unix: existence is the best available signal.
+#[cfg(unix)]
+fn is_executable(path: &std::path::Path) -> bool {
+    use std::os::unix::fs::PermissionsExt;
+    path.metadata()
+        .map(|m| m.is_file() && m.permissions().mode() & 0o111 != 0)
+        .unwrap_or(false)
+}
+
+#[cfg(not(unix))]
+fn is_executable(path: &std::path::Path) -> bool {
+    path.is_file()
+}
+
 /// Resolve the user's login-shell environment by running:
 ///   `$SHELL -l -i -c 'env -0'`  (preferred, NUL-separated)
 ///   `$SHELL -l -c 'env'`        (fallback)
@@ -141,4 +182,29 @@ mod tests {
     fn which_finds_sh() {
         assert!(which("sh").is_some());
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn executable_probe_requires_exec_bit() {
+        use std::os::unix::fs::PermissionsExt;
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let plain = tmp.path().join("claude");
+        std::fs::write(&plain, "#!/bin/sh\n").expect("write");
+        std::fs::set_permissions(&plain, std::fs::Permissions::from_mode(0o644)).expect("chmod");
+        assert!(!is_executable(&plain), "no exec bit");
+        std::fs::set_permissions(&plain, std::fs::Permissions::from_mode(0o755)).expect("chmod");
+        assert!(is_executable(&plain), "exec bit set");
+        assert!(!is_executable(&tmp.path().join("missing")), "missing file");
+    }
+
+    #[test]
+    fn well_known_paths_cover_native_and_homebrew() {
+        let paths = well_known_claude_paths();
+        let rendered: Vec<String> =
+            paths.iter().map(|p| p.to_string_lossy().into_owned()).collect();
+        assert!(rendered.iter().any(|p| p.ends_with(".local/bin/claude")), "native installer");
+        assert!(rendered.iter().any(|p| p.ends_with(".claude/local/claude")), "legacy local");
+        assert!(rendered.contains(&"/opt/homebrew/bin/claude".to_string()), "brew arm64");
+        assert!(rendered.contains(&"/usr/local/bin/claude".to_string()), "brew intel");
+    }
 }

crates/tauri-app/frontend/src/ipc.ts

@@ -25,6 +25,7 @@ import { listen, type UnlistenFn } from "@tauri-apps/api/event";
 import type {
   AgentEventPayload,
   BranchInfo,
+  ClaudeCliStatus,
   DaemonStatus,
   DiffByFeature,
   Feature,
@@ -177,6 +178,11 @@ export function savePastedImage(dataBase64: string, mime: string): Promise<strin
   return invoke("save_pasted_image", { dataBase64, mime });
 }
 
+/** Claude CLI health check: locate (PATH + well-known installs) and run --version. */
+export function claudeCliStatus(): Promise<ClaudeCliStatus> {
+  return invoke("claude_cli_status");
+}
+
 // ── Terminals (FZ-3) ─────────────────────────────────────────────────────────
 
 /** Spawn a PTY rooted at `cwd` (the active worktree). Returns its terminal id. */

crates/tauri-app/frontend/src/types.ts

@@ -88,6 +88,12 @@ export interface DocUpdatedPayload {
   detail: string;
 }
 
+/** Claude CLI health verdict from `claude_cli_status` (tagged, no conflation). */
+export type ClaudeCliStatus =
+  | { state: "ok"; path: string; version: string; shellEnvResolved: boolean }
+  | { state: "broken"; path: string; detail: string; shellEnvResolved: boolean }
+  | { state: "notFound"; shellEnvResolved: boolean };
+
 interface TimelineEventBase {
   id: number;
   ts: string; // RFC3339

crates/tauri-app/frontend/src/views/Welcome.tsx

@@ -1,11 +1,21 @@
-/* Welcome view — open-repo CTA wired to the dialog plugin + open_repo command. */
+/* Welcome view — open-repo CTA wired to the dialog plugin + open_repo command,
+ * plus the Claude CLI health check (ok / broken / notFound, named states). */
 
-import { Show } from "solid-js";
+import { Show, Switch, Match, createSignal, onMount } from "solid-js";
 import { open } from "@tauri-apps/plugin-dialog";
 import { appStore } from "../stores/app-store";
+import { claudeCliStatus } from "../ipc";
+import type { ClaudeCliStatus } from "../types";
 
 export function Welcome() {
   const { store } = appStore;
+  const [cli, setCli] = createSignal<ClaudeCliStatus | null>(null);
+
+  onMount(() => {
+    claudeCliStatus()
+      .then(setCli)
+      .catch((e) => appStore.pushError(`Claude CLI check failed: ${String(e)}`));
+  });
 
   async function pickRepo() {
     const dir = await open({ directory: true, multiple: false, title: "Open a repository" });
@@ -45,6 +55,43 @@ export function Welcome() {
         <Show when={store.lastError}>
           <div class="welcome-error">{store.lastError}</div>
         </Show>
+
+        <Switch>
+          <Match when={cli()?.state === "ok" && cli()}>
+            {(ok) => {
+              const s = ok() as Extract<ClaudeCliStatus, { state: "ok" }>;
+              return <div class="welcome-cli-ok">{s.version} · {s.path}</div>;
+            }}
+          </Match>
+          <Match when={cli()?.state === "notFound" && cli()}>
+            {(missing) => (
+              <div class="welcome-cli-warn">
+                <div class="welcome-cli-warn-title">Claude Code CLI not found</div>
+                <div>Sessions and indexing need it. Install with either:</div>
+                <code>brew install --cask claude-code</code>
+                <code>curl -fsSL https://claude.ai/install.sh | bash</code>
+                <Show when={!missing().shellEnvResolved}>
+                  <div class="welcome-cli-warn-note">
+                    Your login-shell PATH could not be read, so an existing install outside the
+                    standard locations may also be invisible to CodeForge.
+                  </div>
+                </Show>
+              </div>
+            )}
+          </Match>
+          <Match when={cli()?.state === "broken" && cli()}>
+            {(broken) => {
+              const s = broken() as Extract<ClaudeCliStatus, { state: "broken" }>;
+              return (
+                <div class="welcome-cli-warn">
+                  <div class="welcome-cli-warn-title">Claude Code CLI found but not runnable</div>
+                  <code>{s.path}</code>
+                  <div class="welcome-cli-warn-note">{s.detail}</div>
+                </div>
+              );
+            }}
+          </Match>
+        </Switch>
       </div>
 
       <style>{`
@@ -121,6 +168,31 @@ export function Welcome() {
           word-break: break-word;
           user-select: text; -webkit-user-select: text;
         }
+        .welcome-cli-ok {
+          margin-top: var(--space-5);
+          font-size: 10px; font-family: var(--font-mono);
+          color: var(--text-tertiary);
+        }
+        .welcome-cli-warn {
+          margin-top: var(--space-5);
+          text-align: left;
+          display: flex; flex-direction: column; gap: 6px;
+          font-size: 11px;
+          padding: 10px 12px; border-radius: var(--radius-sm);
+          background: rgba(var(--amber-rgb), 0.08);
+          border: 1px solid rgba(var(--amber-rgb), 0.2);
+          color: var(--text-secondary);
+        }
+        .welcome-cli-warn-title { color: var(--amber); font-weight: 600; }
+        .welcome-cli-warn code {
+          font-family: var(--font-mono); font-size: 10.5px;
+          padding: 3px 6px; border-radius: var(--radius-sm);
+          background: var(--bg-muted); border: 1px solid var(--border);
+          color: var(--text);
+          user-select: text; -webkit-user-select: text;
+          width: fit-content;
+        }
+        .welcome-cli-warn-note { color: var(--text-tertiary); word-break: break-word; }
       `}</style>
     </div>
   );

crates/tauri-app/src/commands/cli.rs

@@ -0,0 +1,80 @@
+//! Claude Code CLI health check surfaced on the welcome screen.
+
+use serde::Serialize;
+
+/// Named CLI states — found-and-runs, found-but-broken, and not-found are
+/// distinct verdicts, never conflated. `shell_env_resolved` says whether the
+/// login-shell PATH probe worked, so a miss can explain its cause.
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "state", rename_all = "camelCase", rename_all_fields = "camelCase")]
+pub enum ClaudeCliStatus {
+    Ok { path: String, version: String, shell_env_resolved: bool },
+    Broken { path: String, detail: String, shell_env_resolved: bool },
+    NotFound { shell_env_resolved: bool },
+}
+
+/// Locate `claude` (login-shell PATH, then native-installer / legacy-local /
+/// Homebrew locations) and prove the install actually executes by running
+/// `claude --version`.
+#[tauri::command]
+pub async fn claude_cli_status() -> Result<ClaudeCliStatus, String> {
+    let shell_env_resolved = forge_session::shell_env::is_resolved();
+    let Some(path) = forge_session::shell_env::locate_claude() else {
+        return Ok(ClaudeCliStatus::NotFound { shell_env_resolved });
+    };
+    let display = path.to_string_lossy().into_owned();
+
+    let mut cmd = tokio::process::Command::new(&path);
+    cmd.arg("--version").stdin(std::process::Stdio::null());
+    forge_session::shell_env::apply(&mut cmd);
+
+    let status = match tokio::time::timeout(std::time::Duration::from_secs(10), cmd.output()).await
+    {
+        Err(_) => ClaudeCliStatus::Broken {
+            path: display,
+            detail: "`claude --version` timed out after 10s".into(),
+            shell_env_resolved,
+        },
+        Ok(Err(e)) => ClaudeCliStatus::Broken {
+            path: display,
+            detail: format!("failed to spawn: {e}"),
+            shell_env_resolved,
+        },
+        Ok(Ok(out)) if !out.status.success() => ClaudeCliStatus::Broken {
+            path: display,
+            detail: format!(
+                "`--version` exited with {}: {}",
+                out.status,
+                String::from_utf8_lossy(&out.stderr).trim()
+            ),
+            shell_env_resolved,
+        },
+        Ok(Ok(out)) => ClaudeCliStatus::Ok {
+            path: display,
+            version: String::from_utf8_lossy(&out.stdout).trim().to_string(),
+            shell_env_resolved,
+        },
+    };
+    Ok(status)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn status_serializes_to_the_tagged_camel_case_shape() {
+        let ok = ClaudeCliStatus::Ok {
+            path: "/opt/homebrew/bin/claude".into(),
+            version: "2.1.0".into(),
+            shell_env_resolved: true,
+        };
+        let json = serde_json::to_string(&ok).unwrap();
+        assert!(json.contains("\"state\":\"ok\""));
+        assert!(json.contains("\"shellEnvResolved\":true"));
+
+        let missing = ClaudeCliStatus::NotFound { shell_env_resolved: false };
+        let json = serde_json::to_string(&missing).unwrap();
+        assert!(json.contains("\"state\":\"notFound\""));
+    }
+}

crates/tauri-app/src/commands/mod.rs

@@ -2,6 +2,7 @@
 //! `Result<T, String>` (errors formatted with `format!("{e:#}")` for anyhow
 //! chains); IDs and paths cross IPC as strings.
 
+pub mod cli;
 pub mod features;
 pub mod repo;
 pub mod sessions;

crates/tauri-app/src/main.rs

@@ -62,6 +62,7 @@ fn main() {
         .plugin(tauri_plugin_process::init())
         .manage(app_state)
         .invoke_handler(tauri::generate_handler![
+            commands::cli::claude_cli_status,
             commands::repo::open_repo,
             commands::repo::init_repo,
             commands::repo::close_repo,