claude-scionos 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-01-06
+
+### Added
+- **Auto-Installation**: Prompts users to automatically install Claude Code CLI (`npm install -g`) if missing.
+- **Native Path Detection**: Now detects Claude Code installations in native paths (`~/.local/bin`, Windows Apps, etc.) per official docs.
+- **SIGTERM Support**: Added handling for `SIGTERM` signals (Docker, CI/CD) to cleanly stop the child process.
+
+### Fixed
+- **Crash on Config-Only**: Fixed a critical bug where the wrapper would crash if a configuration file existed but the CLI executable was missing.
+- **Recursion Safety**: Now launches the detected absolute path of the executable instead of the generic command name, preventing potential loop issues.
+- **Error Logging**: Errors are now correctly sent to `stderr` instead of `stdout`.
+
+## [2.1.0] - 2026-01-06
+
+### Added
+- **Debug Mode**: New `--scionos-debug` flag for detailed diagnostic output
+- **Test Infrastructure**: Added Vitest test suite covering core detection logic
+- **Linting**: Fixed development environment and linting rules
+
+### Fixed
+- **Windows Path Handling**: Fixed an issue where `where claude` returned multiple paths on Windows
+- **Signal Handling**: Improved `SIGINT` (Ctrl+C) handling to prevent wrapper from killing Claude prematurely
+
 ## [2.0.0] - 2025-12-12
 
 ### ⚠️ BREAKING CHANGES
@@ -55,7 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release
 - Ephemeral and secure token handling (memory-only storage)
-- Support for SNIA environment (`https://hubs02225.snia.ch`)
+- Support for ScioNos environment (`https://routerlab.ch`)
 - Bilingual documentation (English and French)
 - Command-line interface with `--version` flag
 - Secure token input with masking

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-claude-scionos is a lightweight Node.js CLI wrapper that provides ephemeral and secure execution of the official Claude Code CLI. It's designed for the SNIA environment and focuses on in-memory credential management with zero disk persistence.
+claude-scionos is a lightweight Node.js CLI wrapper that provides ephemeral and secure execution of the official Claude Code CLI. It's designed for the ScioNos environment and focuses on in-memory credential management with zero disk persistence.
 
 ## Architecture
 
@@ -14,7 +14,7 @@ The project is a single-file Node.js application (`index.js`) that:
 2. **Windows-specific check**: Verifies Git Bash installation (required by Claude Code on Windows)
 3. **Secure token collection**: Uses `@inquirer/prompts` for masked password input
 4. **Environment isolation**: Creates isolated environment variables with:
-   - `ANTHROPIC_BASE_URL`: Set to `https://routerlab.ch` (hardcoded SNIA endpoint)
+   - `ANTHROPIC_BASE_URL`: Set to `https://routerlab.ch` (hardcoded ScioNos endpoint)
    - `ANTHROPIC_AUTH_TOKEN`: User-provided token (memory only)
    - `ANTHROPIC_API_KEY`: Explicitly set to empty string
 5. **Process spawning**: Launches Claude Code CLI with inherited stdio and custom environment
@@ -77,7 +77,7 @@ Currently no automated tests are configured. When implementing tests, focus on:
 
 ## Important Constants
 
-- `ANTHROPIC_BASE_URL`: `"https://routerlab.ch"` (SNIA-specific endpoint)
+- `ANTHROPIC_BASE_URL`: `"https://routerlab.ch"` (ScioNos-specific endpoint)
 - Minimum Node.js version: 22
 - Package entry point: `index.js` with shebang for direct execution
 

package/README.fr.md

@@ -34,7 +34,7 @@ _[🇬🇧 Read in English](./README.md)_
 
 **claude-scionos** est un exécuteur éphémère et sécurisé pour la CLI officielle [Claude Code](https://github.com/anthropics/claude-code). Il initialise toutes les variables d'environnement nécessaires **directement en mémoire**, garantissant qu'aucun fichier de configuration ni aucune donnée d'authentification n'est jamais écrit sur le disque.
 
-L'objectif est d'offrir une couche d'exécution propre, isolée et professionnelle, entièrement compatible avec Claude Code, spécifiquement conçue pour **l'environnement SNIA**.
+L'objectif est d'offrir une couche d'exécution propre, isolée et professionnelle, entièrement compatible avec Claude Code, spécifiquement conçue pour **l'environnement ScioNos**.
 
 ---
 
@@ -54,14 +54,10 @@ L'objectif est d'offrir une couche d'exécution propre, isolée et professionnel
 Avant d'utiliser `claude-scionos`, assurez-vous d'avoir :
 
 - **Node.js** version 22 ou supérieure ([Télécharger](https://nodejs.org/))
-- La CLI **Claude Code** installée globalement :
-
-  ```bash
-  npm install -g @anthropic-ai/claude-code
-  ```
-
 - Un **ANTHROPIC_AUTH_TOKEN** valide depuis [https://routerlab.ch/keys](https://routerlab.ch/keys)
 
+*(Note : Si la CLI **Claude Code** n'est pas installée, l'outil vous proposera de l'installer automatiquement.)*
+
 ---
 
 ### 📥 Installation
@@ -102,11 +98,19 @@ npx claude-scionos
 
 **Ce qui se passe :**
 
-1. L'outil vérifie si la CLI Claude Code est installée
+1. L'outil vérifie si la CLI Claude Code est installée (si non, propose l'**installation automatique**)
 2. Vous invite à saisir votre `ANTHROPIC_AUTH_TOKEN`
 3. Lance Claude Code avec le jeton stocké **uniquement en mémoire**
 4. Nettoie automatiquement les informations d'identification à la sortie
 
+#### Débogage
+
+Si vous rencontrez des problèmes, utilisez le flag de débogage pour voir les informations détaillées :
+
+```bash
+npx claude-scionos --scionos-debug
+```
+
 #### Exemple de session
 
 ```bash
@@ -127,6 +131,18 @@ npx claude-scionos --version
 npx claude-scionos -v
 ```
 
+#### Compatibilité totale avec Claude Code
+
+**`claude-scionos` est un wrapper transparent** — il accepte **tous les flags et commandes** supportés par la CLI officielle Claude Code.
+
+Vous pouvez utiliser n'importe quel flag ou commande Claude Code, comme :
+- `npx claude-scionos --model opus "expliquer ce code"`
+- `npx claude-scionos --verbose --continue`
+- `npx claude-scionos -p --output-format json "requête"`
+- `npx claude-scionos --chrome --agents '{"reviewer":{...}}'`
+
+Pour une liste complète des flags et commandes disponibles, consultez la [documentation officielle de la CLI Claude Code](https://code.claude.com/docs/cli-reference).
+
 ---
 
 ### 🔍 Fonctionnement

package/README.md

@@ -34,7 +34,7 @@ _[🇫🇷 Lire en français](./README.fr.md)_
 
 **claude-scionos** is an ephemeral and secure runner for the official [Claude Code](https://github.com/anthropics/claude-code) CLI. It initializes all required environment variables **directly in memory**, ensuring that no configuration files or authentication data are ever written to disk.
 
-The goal is to offer a clean, isolated, and professional execution layer fully compatible with Claude Code, specifically designed for the **SNIA environment**.
+The goal is to offer a clean, isolated, and professional execution layer fully compatible with Claude Code, specifically designed for the **ScioNos environment**.
 
 ---
 
@@ -54,14 +54,10 @@ The goal is to offer a clean, isolated, and professional execution layer fully c
 Before using `claude-scionos`, ensure you have:
 
 - **Node.js** version 22 or later ([Download](https://nodejs.org/))
-- **Claude Code** CLI installed globally:
-
-  ```bash
-  npm install -g @anthropic-ai/claude-code
-  ```
-
 - A valid **ANTHROPIC_AUTH_TOKEN** from [https://routerlab.ch/keys](https://routerlab.ch/keys)
 
+*(Note: If **Claude Code** is not installed, the tool will offer to install it for you automatically.)*
+
 ---
 
 ### 📥 Installation
@@ -94,7 +90,7 @@ claude-scionos
 
 #### Basic Usage
 
-Simply execute the command:
+Run the command:
 
 ```bash
 npx claude-scionos
@@ -102,24 +98,20 @@ npx claude-scionos
 
 **What happens:**
 
-1. The tool checks if Claude Code CLI is installed
-2. Prompts you to enter your `ANTHROPIC_AUTH_TOKEN`
-3. Launches Claude Code with the token stored **only in memory**
-4. Automatically cleans up credentials when you exit
+1.  Checks if Claude Code CLI is installed (if not, offers **automatic installation**)
+2.  Prompts for your `ANTHROPIC_AUTH_TOKEN`
+3.  Launches Claude Code with token stored **in memory only**
+4.  Automatically cleans credentials on exit
 
-#### Example Session
-
-```bash
-$ npx claude-scionos
+#### Debugging
 
-Claude Code (via ScioNos)
-To retrieve your token, visit: https://routerlab.ch/keys
-? Please enter your ANTHROPIC_AUTH_TOKEN: ********
+If you encounter issues, you can run with the debug flag to see detailed diagnostic information:
 
-# Claude Code starts...
+```bash
+npx claude-scionos --scionos-debug
 ```
 
-#### Command-Line Options
+#### Command Line Options
 
 ```bash
 # Display version
@@ -127,6 +119,18 @@ npx claude-scionos --version
 npx claude-scionos -v
 ```
 
+#### Full Claude Code Compatibility
+
+**`claude-scionos` is a transparent wrapper** — it accepts **all flags and commands** supported by the official Claude Code CLI.
+
+You can use any Claude Code flag or command, such as:
+- `npx claude-scionos --model opus "explain this code"`
+- `npx claude-scionos --verbose --continue`
+- `npx claude-scionos -p --output-format json "query"`
+- `npx claude-scionos --chrome --agents '{"reviewer":{...}}'`
+
+For a complete list of available flags and commands, see the [official Claude Code CLI documentation](https://code.claude.com/docs/cli-reference).
+
 ---
 
 ### 🔍 How It Works

package/index.js

@@ -1,117 +1,188 @@
 #!/usr/bin/env node
-
-import chalk from 'chalk';
-import { password } from '@inquirer/prompts';
-import spawn from 'cross-spawn';
-import updateNotifier from 'update-notifier';
-import process from 'node:process';
-import { createRequire } from 'node:module';
-import { isClaudeCodeInstalled, detectOS, checkGitBashOnWindows, getInstallationInstructions } from './src/detectors/claude-only.js';
-
-const require = createRequire(import.meta.url);
-const pkg = require('./package.json');
-
-// Initialize update notifier
-updateNotifier({ pkg }).notify();
-
-// 0. Handle --version / -v flag
-if (process.argv.includes('--version') || process.argv.includes('-v')) {
-    console.log(pkg.version);
-    process.exit(0);
-}
-
-// 1. Enhanced System Detection
-console.log(chalk.cyan('🔍 Checking system configuration...'));
-
-// Detect OS and environment
-const osInfo = detectOS();
-console.log(chalk.gray(`✓ OS: ${osInfo.type} (${osInfo.arch})`));
-console.log(chalk.gray(`✓ Shell: ${osInfo.shell}`));
-
-// Check Claude Code installation
-const claudeStatus = isClaudeCodeInstalled();
-
-if (!claudeStatus.installed) {
-    console.error(chalk.redBright('\n❌ Claude Code not found'));
-
-    // Show detailed detection info
-    console.log(chalk.yellow('\nDetection Details:'));
-    console.log(chalk.gray(claudeStatus.details));
-
-    // Show installation instructions
-    const instructions = getInstallationInstructions(osInfo, claudeStatus);
-    console.log(chalk.cyan(instructions));
-
-    process.exit(1);
-}
-
-// Show Claude Code status
-console.log(chalk.green('\n✓ Claude Code detected'));
-console.log(chalk.gray(claudeStatus.details));
-
-// 2. Check Git Bash on Windows (if needed)
-if (process.platform === 'win32') {
-    console.log(chalk.cyan('\n🔍 Checking Git Bash availability...'));
-    const gitBashStatus = checkGitBashOnWindows();
-
-    if (!gitBashStatus.available) {
-        console.log(chalk.red('\n❌ Git Bash is required on Windows'));
-        console.log(chalk.gray(gitBashStatus.message));
-
-        // Show Git Bash installation instructions
-        console.log(chalk.cyan('\n📥 Install Git for Windows:'));
-        console.log(chalk.white('   https://git-scm.com/downloads/win\n'));
-        console.log(chalk.cyan('⚙️  Or set the path manually:'));
-        console.log(chalk.white('   set CLAUDE_CODE_GIT_BASH_PATH=C:\\Program Files\\Git\\bin\\bash.exe'));
-        console.log(chalk.white('   (PowerShell: $env:CLAUDE_CODE_GIT_BASH_PATH="C:\\Program Files\\Git\\bin\\bash.exe")\n'));
-        console.log(chalk.yellow('💡 After installation, restart your terminal and try again.\n'));
-        process.exit(1);
-    } else {
-        console.log(chalk.green('✓ Git Bash available'));
-        console.log(chalk.gray(gitBashStatus.message));
-    }
-}
-
-// 3. Intro
-console.clear();
-console.log(chalk.cyan.bold("Claude Code (via ScioNos)"));
-console.log(chalk.gray(`Running on ${osInfo.type} with ${osInfo.shell}`));
-
-// 4. Token info
-console.log(chalk.blueBright("To retrieve your token, visit: https://routerlab.ch/keys"));
-
-// 5. Token input
-const token = await password({
-    message: "Please enter your ANTHROPIC_AUTH_TOKEN:",
-    validate: (input) => {
-        if (!input || input.trim() === '') {
-            return "Token cannot be empty.";
-        }
-        return true;
-    },
-    mask: '*'
-});
-
-// 6. Environment configuration
-const env = {
-    ...process.env,
-    ANTHROPIC_BASE_URL: "https://routerlab.ch",
-    ANTHROPIC_AUTH_TOKEN: token,
-    ANTHROPIC_API_KEY: "" // Force empty string
-};
-
-// 7. Launch Claude Code
-const args = process.argv.slice(2);
-const child = spawn('claude', args, {
-    stdio: 'inherit',
-    env: env
-});
-
-child.on('close', (code) => {
-    process.exit(code);
-});
-
-child.on('error', (err) => {
-    console.error(chalk.red(`Error launching Claude: ${err.message}`));
-    process.exit(1);
-});
+
+import chalk from 'chalk';
+import { password, confirm } from '@inquirer/prompts';
+import spawn from 'cross-spawn';
+import updateNotifier from 'update-notifier';
+import process from 'node:process';
+import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { isClaudeCodeInstalled, detectOS, checkGitBashOnWindows, getInstallationInstructions } from './src/detectors/claude-only.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('./package.json');
+
+// Initialize update notifier
+updateNotifier({ pkg }).notify();
+
+// 0. Handle Flags
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    console.log(pkg.version);
+    process.exit(0);
+}
+
+const isDebug = process.argv.includes('--scionos-debug');
+
+// 1. Enhanced System Detection
+console.log(chalk.cyan('🔍 Checking system configuration...'));
+
+// Detect OS and environment
+const osInfo = detectOS();
+console.log(chalk.gray(`✓ OS: ${osInfo.type} (${osInfo.arch})`));
+console.log(chalk.gray(`✓ Shell: ${osInfo.shell}`));
+
+// Check Claude Code installation
+let claudeStatus = isClaudeCodeInstalled();
+
+if (!claudeStatus.installed) {
+    console.error(chalk.redBright('\n❌ Claude Code CLI not found'));
+
+    // Show detailed detection info
+    console.error(chalk.yellow('\nDetection Details:'));
+    console.error(chalk.gray(claudeStatus.details));
+    console.log(''); // spacer
+
+    const shouldInstall = await confirm({
+        message: 'Claude Code CLI is not installed. Do you want to install it via npm now?',
+        default: true
+    });
+
+    if (shouldInstall) {
+        try {
+            console.log(chalk.cyan('\n📦 Installing @anthropic-ai/claude-code globally...'));
+            execSync('npm install -g @anthropic-ai/claude-code', { stdio: 'inherit' });
+            console.log(chalk.green('✓ Installation successful!'));
+            
+            // Re-detect to get the new path
+            claudeStatus = isClaudeCodeInstalled();
+            
+            if (!claudeStatus.installed) {
+                 // Fallback if install succeeded but path isn't picked up immediately
+                 console.warn(chalk.yellow('⚠ Installation finished, but the executable was not found in the standard paths immediately.'));
+                 console.warn(chalk.yellow('You may need to restart your terminal.'));
+                 process.exit(0);
+            }
+        } catch (e) {
+            console.error(chalk.red(`\n❌ Installation failed: ${e.message}`));
+            console.error(chalk.yellow('Please try installing manually using the instructions below.'));
+            
+            const instructions = getInstallationInstructions(osInfo, claudeStatus);
+            console.error(chalk.cyan(instructions));
+            process.exit(1);
+        }
+    } else {
+        // User declined install
+        const instructions = getInstallationInstructions(osInfo, claudeStatus);
+        console.error(chalk.cyan(instructions));
+        process.exit(1);
+    }
+}
+
+// Show Claude Code status
+console.log(chalk.green('\n✓ Claude Code detected'));
+console.log(chalk.gray(claudeStatus.details));
+
+// 2. Check Git Bash on Windows (if needed)
+let gitBashPath = null;
+if (process.platform === 'win32') {
+    console.log(chalk.cyan('\n🔍 Checking Git Bash availability...'));
+    const gitBashStatus = checkGitBashOnWindows();
+
+    if (!gitBashStatus.available) {
+        console.log(chalk.red('\n❌ Git Bash is required on Windows'));
+        console.log(chalk.gray(gitBashStatus.message));
+
+        // Show Git Bash installation instructions
+        console.log(chalk.cyan('\n📥 Install Git for Windows:'));
+        console.log(chalk.white('   https://git-scm.com/downloads/win\n'));
+        console.log(chalk.cyan('⚙️  Or set the path manually:'));
+        console.log(chalk.white('   set CLAUDE_CODE_GIT_BASH_PATH=C:\\Program Files\\Git\\bin\\bash.exe'));
+        console.log(chalk.white('   (PowerShell: $env:CLAUDE_CODE_GIT_BASH_PATH="C:\\Program Files\\Git\\bin\\bash.exe")\n'));
+        console.log(chalk.yellow('💡 After installation, restart your terminal and try again.\n'));
+        process.exit(1);
+    } else {
+        console.log(chalk.green('✓ Git Bash available'));
+        console.log(chalk.gray(gitBashStatus.message));
+        gitBashPath = gitBashStatus.path;
+    }
+}
+
+// 3. Intro
+console.clear();
+console.log(chalk.cyan.bold("Claude Code (via ScioNos)"));
+console.log(chalk.gray(`Running on ${osInfo.type} with ${osInfo.shell}`));
+if (isDebug) console.log(chalk.yellow("🐞 Debug Mode Active"));
+
+// 4. Token info
+console.log(chalk.blueBright("To retrieve your token, visit: https://routerlab.ch/keys"));
+
+// 5. Token input
+const token = await password({
+    message: "Please enter your ANTHROPIC_AUTH_TOKEN:",
+    validate: (input) => {
+        if (!input || input.trim() === '') {
+            return "Token cannot be empty.";
+        }
+        return true;
+    },
+    mask: '*'
+});
+
+// 6. Environment configuration
+const env = {
+    ...process.env,
+    ANTHROPIC_BASE_URL: "https://routerlab.ch",
+    ANTHROPIC_AUTH_TOKEN: token,
+    ANTHROPIC_API_KEY: "" // Force empty string
+};
+
+// 7. Launch Claude Code
+// Filter out our internal flag before passing args to Claude
+const args = process.argv.slice(2).filter(arg => arg !== '--scionos-debug');
+
+if (isDebug) {
+    console.log(chalk.yellow('\n--- DEBUG INFO ---'));
+    console.log(chalk.gray(`Platform: ${process.platform}`));
+    console.log(chalk.gray(`Claude Command: claude ${args.join(' ')}`));
+    console.log(chalk.gray(`Router URL: ${env.ANTHROPIC_BASE_URL}`));
+    console.log(chalk.gray(`Token Length: ${token.length} chars`));
+    if (gitBashPath) console.log(chalk.gray(`Git Bash: ${gitBashPath}`));
+    console.log(chalk.yellow('------------------\n'));
+}
+
+const child = spawn(claudeStatus.cliPath, args, {
+    stdio: 'inherit',
+    env: env
+});
+
+// Signal Handling
+// We intentionally ignore SIGINT in the parent process.
+// Because stdio is 'inherit', the child process (Claude) receives the Ctrl+C (SIGINT) directly from the TTY.
+process.on('SIGINT', () => {
+    if (isDebug) {
+        console.error(chalk.yellow('\n[Wrapper] Received SIGINT. Waiting for Claude to exit...'));
+    }
+});
+
+// Handle SIGTERM (e.g., Docker stop, kill)
+process.on('SIGTERM', () => {
+    if (isDebug) {
+        console.error(chalk.yellow('\n[Wrapper] Received SIGTERM. Forwarding to Claude...'));
+    }
+    if (child) {
+        child.kill('SIGTERM');
+    }
+    process.exit(0);
+});
+
+child.on('close', (code) => {
+    if (isDebug) {
+        console.error(chalk.yellow(`\n[Wrapper] Child process exited with code ${code}`));
+    }
+    process.exit(code);
+});
+
+child.on('error', (err) => {
+    console.error(chalk.red(`Error launching Claude at ${claudeStatus.cliPath}: ${err.message}`));
+    process.exit(1);
+});

package/package.json

@@ -1,14 +1,14 @@
 {
     "name": "claude-scionos",
-    "version": "2.0.0",
-    "description": "Ephemeral and secure runner for Claude Code CLI in SNIA environment",
+    "version": "2.2.0",
+    "description": "Ephemeral and secure runner for Claude Code CLI in ScioNos environment",
     "type": "module",
     "main": "index.js",
     "bin": {
         "claude-scionos": "index.js"
     },
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1",
+        "test": "vitest run",
         "lint": "eslint .",
         "release:patch": "npm version patch -m \"Chore: Bump version to %s\"",
         "release:minor": "npm version minor -m \"Chore: Bump version to %s\"",
@@ -16,7 +16,7 @@
     },
     "keywords": [
         "claude",
-        "snia",
+        "scionos",
         "cli",
         "wrapper"
     ],
@@ -35,15 +35,16 @@
     },
     "private": false,
     "dependencies": {
-        "@inquirer/prompts": "^8.0.2",
+        "@inquirer/prompts": "^8.1.0",
         "chalk": "^5.6.2",
         "cross-spawn": "^7.0.6",
         "update-notifier": "^7.3.1",
         "which": "^6.0.0"
     },
     "devDependencies": {
-        "@eslint/js": "^9.39.1",
-        "eslint": "^9.39.1",
-        "globals": "^16.5.0"
+        "@eslint/js": "^9.39.2",
+        "eslint": "^9.39.2",
+        "globals": "^17.0.0",
+        "vitest": "^4.0.16"
     }
 }

package/src/detectors/claude-only.js

@@ -13,79 +13,68 @@ function isClaudeCodeInstalled() {
   const claudeDir = path.join(os.homedir(), '.claude');
   const details = [];
 
+  // 1. Check for Configuration
+  let configFound = false;
   if (fs.existsSync(claudeDir)) {
-    details.push(`✓ Found Claude directory: ${claudeDir}`);
-
-    // Check for settings.json to confirm it's actually Claude Code
     const settingsPath = path.join(claudeDir, 'settings.json');
     if (fs.existsSync(settingsPath)) {
-      details.push(`✓ Configuration file found: ${settingsPath}`);
-
-      // Try to read the config to see if it's configured
-      try {
-        const config = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-        const hasBaseUrl = config.env?.ANTHROPIC_BASE_URL;
-        const hasApiKey = config.env?.ANTHROPIC_API_KEY;
-
-        if (hasBaseUrl && hasApiKey) {
-          details.push(`✓ Claude Code is configured with custom API`);
-        } else if (hasBaseUrl || hasApiKey) {
-          details.push(`⚠ Claude Code is partially configured`);
-        } else {
-          details.push(`ℹ Claude Code installed but not configured`);
-        }
-      } catch (error) {
-        details.push(`⚠ Could not read configuration file`);
-      }
-
-      return {
-        installed: true,
-        path: claudeDir,
-        configPath: settingsPath,
-        cliAvailable: false, // Will check next
-        details: details.join('\n  ')
-      };
-    } else {
-      details.push(`⚠ Directory exists but no settings.json found`);
+      configFound = true;
+      details.push(`✓ Configuration found at: ${settingsPath}`);
     }
   }
 
-  // Also check for the claude CLI command in PATH
-  try {
-    const command = process.platform === 'win32' ? 'where claude' : 'which claude';
-    const claudePath = execSync(command, { encoding: 'utf8' }).trim();
+  // 2. Check for Executable (CLI)
+  let cliPath = null;
 
-    if (claudePath) {
-      details.push(`✓ Claude CLI found in PATH: ${claudePath}`);
+  // 2a. Check Native Install Paths (per official docs)
+  const home = os.homedir();
+  const nativePaths = process.platform === 'win32' 
+    ? [path.join(home, '.local', 'bin', 'claude.exe'), path.join(home, 'AppData', 'Local', 'Microsoft', 'WindowsApps', 'claude.exe')]
+    : [path.join(home, '.local', 'bin', 'claude'), '/opt/homebrew/bin/claude', '/usr/local/bin/claude'];
+
+  for (const p of nativePaths) {
+    if (fs.existsSync(p)) {
+      cliPath = p;
+      details.push(`✓ Found native binary: ${p}`);
+      break;
+    }
+  }
 
-      // Try to get version to confirm it's working
-      try {
-        const version = execSync('claude --version', { encoding: 'utf8' }).trim();
-        details.push(`✓ Version: ${version}`);
-      } catch (error) {
-        details.push(`⚠ CLI found but version check failed`);
+  // 2b. Check PATH if not found yet
+  if (!cliPath) {
+    try {
+      const command = process.platform === 'win32' ? 'where claude' : 'which claude';
+      const output = execSync(command, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const foundPath = output.split(/\r?\n/)[0].trim();
+      if (foundPath && fs.existsSync(foundPath)) {
+        cliPath = foundPath;
+        details.push(`✓ Found in PATH: ${foundPath}`);
       }
+    } catch (e) {
+      // Ignore error if not found in PATH
+    }
+  }
 
-      return {
-        installed: true,
-        path: claudeDir && fs.existsSync(claudeDir) ? claudeDir : null,
-        configPath: claudeDir && fs.existsSync(path.join(claudeDir, 'settings.json'))
-          ? path.join(claudeDir, 'settings.json')
-          : null,
-        cliAvailable: true,
-        cliPath: claudePath,
-        details: details.join('\n  ')
-      };
+  // 3. Verify Version (if executable found)
+  if (cliPath) {
+    try {
+      // We use the full path to avoid recursion or alias issues
+      const version = execSync(`"${cliPath}" --version`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      details.push(`✓ Version: ${version}`);
+    } catch (error) {
+      details.push(`⚠ Executable found but version check failed: ${error.message}`);
     }
-  } catch (error) {
-    details.push(`✗ Claude CLI not found in PATH`);
+  } else {
+    details.push(`✗ Executable 'claude' not found in PATH or standard locations.`);
   }
 
   return {
-    installed: false,
-    path: null,
-    configPath: null,
-    cliAvailable: false,
+    installed: !!cliPath, // STRICT: Only true if the binary is found
+    configFound: configFound,
+    path: claudeDir,
+    configPath: configFound ? path.join(claudeDir, 'settings.json') : null,
+    cliAvailable: !!cliPath,
+    cliPath: cliPath,
     details: details.join('\n  ')
   };
 }
@@ -180,10 +169,9 @@ function checkGitBashOnWindows() {
 /**
  * Provides installation instructions based on OS and current state
  * @param {Object} osInfo - OS detection result
- * @param {Object} claudeStatus - Claude Code detection result
  * @returns {string} Installation instructions
  */
-function getInstallationInstructions(osInfo, claudeStatus) {
+function getInstallationInstructions(osInfo) {
   let instructions = [];
 
   if (osInfo.type === 'Windows') {

package/tests/detectors.test.js

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import child_process from 'child_process';
+import { isClaudeCodeInstalled, detectOS, checkGitBashOnWindows } from '../src/detectors/claude-only.js';
+
+// Mock modules
+vi.mock('fs');
+vi.mock('os');
+vi.mock('child_process');
+
+describe('System Detectors', () => {
+  const originalPlatform = process.platform;
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: originalPlatform });
+    process.env = originalEnv;
+  });
+
+  describe('detectOS', () => {
+    it('should detect Windows', () => {
+      vi.mocked(os.platform).mockReturnValue('win32');
+      vi.mocked(os.arch).mockReturnValue('x64');
+      Object.defineProperty(process, 'platform', { value: 'win32' });
+      process.env.WINDIR = 'C:\\Windows'; // Simulate CMD
+
+      const result = detectOS();
+      expect(result.type).toBe('Windows');
+      expect(result.shell).toBe('Command Prompt (CMD)');
+    });
+
+    it('should detect macOS', () => {
+      vi.mocked(os.platform).mockReturnValue('darwin');
+      vi.mocked(os.arch).mockReturnValue('arm64');
+      Object.defineProperty(process, 'platform', { value: 'darwin' });
+      process.env.SHELL = '/bin/zsh';
+
+      const result = detectOS();
+      expect(result.type).toBe('macOS');
+      expect(result.shell).toBe('Zsh');
+    });
+  });
+
+  describe('checkGitBashOnWindows', () => {
+    it('should return available if Git Bash exists in standard path on Windows', () => {
+      Object.defineProperty(process, 'platform', { value: 'win32' });
+      vi.mocked(fs.existsSync).mockImplementation((p) => p === 'C:\\Program Files\\Git\\bin\\bash.exe');
+
+      const result = checkGitBashOnWindows();
+      expect(result.available).toBe(true);
+      expect(result.path).toBe('C:\\Program Files\\Git\\bin\\bash.exe');
+    });
+
+    it('should return not available if no Git Bash found on Windows', () => {
+      Object.defineProperty(process, 'platform', { value: 'win32' });
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+
+      const result = checkGitBashOnWindows();
+      expect(result.available).toBe(false);
+    });
+
+    it('should not require Git Bash on non-Windows', () => {
+      Object.defineProperty(process, 'platform', { value: 'darwin' });
+      
+      const result = checkGitBashOnWindows();
+      expect(result.available).toBe(true);
+      expect(result.message).toContain('Not required');
+    });
+  });
+
+  describe('isClaudeCodeInstalled', () => {
+    it('should detect Claude in PATH', () => {
+        // Mock homedir to avoid finding config file
+        vi.mocked(os.homedir).mockReturnValue('/home/user');
+        
+        // Mock execSync to return a path
+        vi.mocked(child_process.execSync).mockImplementation((cmd) => {
+            if (cmd.includes('which claude') || cmd.includes('where claude')) {
+                return '/usr/local/bin/claude';
+            }
+            if (cmd.includes('--version')) {
+                return '0.0.1';
+            }
+            return '';
+        });
+
+        // Mock existsSync: false for config, true for CLI path
+        vi.mocked(fs.existsSync).mockImplementation((p) => {
+             if (p === '/usr/local/bin/claude') return true;
+             return false;
+        });
+
+        const result = isClaudeCodeInstalled();
+        expect(result.installed).toBe(true);
+        expect(result.cliAvailable).toBe(true);
+        expect(result.cliPath).toBe('/usr/local/bin/claude');
+    });
+
+    it('should detect Claude from config file ONLY if CLI is also found', () => {
+        vi.mocked(os.homedir).mockReturnValue('/home/user');
+        // Simulate .claude directory and settings.json existence
+        vi.mocked(fs.existsSync).mockImplementation((p) => {
+            if (p.endsWith('.claude')) return true;
+            if (p.endsWith('settings.json')) return true;
+            return false;
+        });
+        
+        // Mock reading config
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({
+            env: { ANTHROPIC_BASE_URL: 'https://api.anthropic.com' }
+        }));
+
+        // BUT execSync fails (CLI not found)
+        vi.mocked(child_process.execSync).mockImplementation(() => {
+            throw new Error('not found');
+        });
+
+        const result = isClaudeCodeInstalled();
+        // Updated logic: installed should be false if CLI is missing, even if config exists
+        expect(result.installed).toBe(false);
+        expect(result.configFound).toBe(true);
+        expect(result.cliAvailable).toBe(false);
+        expect(result.details).toContain('Executable \'claude\' not found');
+    });
+
+    it('should detect Claude in native path (Linux/Mac)', () => {
+        // Force Linux platform to ensure implementation looks for 'claude' not 'claude.exe'
+        Object.defineProperty(process, 'platform', { value: 'linux' });
+
+        // We simulate logic but path.join will use OS separators.
+        // On Windows, path.join produces backslashes.
+        // The code under test uses path.join.
+        const mockHome = '/home/user';
+        const expectedPath = path.join(mockHome, '.local', 'bin', 'claude');
+        
+        vi.mocked(os.homedir).mockReturnValue(mockHome);
+        
+        // Simulate native path existence
+        vi.mocked(fs.existsSync).mockImplementation((p) => {
+            return p === expectedPath;
+        });
+
+        const result = isClaudeCodeInstalled();
+        expect(result.installed).toBe(true);
+        expect(result.cliPath).toBe(expectedPath);
+    });
+
+    it('should return false if neither CLI nor config found', () => {
+        vi.mocked(os.homedir).mockReturnValue('/home/user');
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        vi.mocked(child_process.execSync).mockImplementation(() => {
+            throw new Error('not found');
+        });
+
+        const result = isClaudeCodeInstalled();
+        expect(result.installed).toBe(false);
+    });
+  });
+});