@kaitranntt/ccs 5.20.0 → 6.0.0-dev.2

package/lib/hooks/websearch-transformer.cjs

@@ -0,0 +1,600 @@
+#!/usr/bin/env node
+/**
+ * CCS WebSearch Hook - CLI Tool Executor with Fallback Chain
+ *
+ * Intercepts Claude's WebSearch tool and executes search via CLI tools.
+ * Respects provider enabled states from config.yaml.
+ * Supports automatic fallback: Gemini CLI → OpenCode → Grok CLI
+ *
+ * Environment Variables (set by CCS):
+ *   CCS_WEBSEARCH_SKIP=1           - Skip this hook entirely (for official Claude)
+ *   CCS_WEBSEARCH_ENABLED=1        - Enable WebSearch (default: 1)
+ *   CCS_WEBSEARCH_TIMEOUT=55       - Timeout in seconds (default: 55)
+ *   CCS_WEBSEARCH_GEMINI=1         - Enable Gemini CLI provider
+ *   CCS_WEBSEARCH_GEMINI_MODEL     - Gemini model (default: gemini-2.5-flash)
+ *   CCS_WEBSEARCH_OPENCODE=1       - Enable OpenCode provider
+ *   CCS_WEBSEARCH_GROK=1           - Enable Grok CLI provider
+ *   CCS_WEBSEARCH_OPENCODE_MODEL   - OpenCode model (default: opencode/grok-code)
+ *   CCS_DEBUG=1                    - Enable debug output
+ *
+ * Exit codes:
+ *   0 - Allow tool (pass-through to native WebSearch)
+ *   2 - Block tool (deny with results/message)
+ *
+ * @module hooks/websearch-transformer
+ */
+
+const { spawnSync } = require('child_process');
+
+// ============================================================================
+// CONFIGURATION - Edit these for prompt engineering
+// ============================================================================
+
+/**
+ * SHARED INSTRUCTIONS - Applied to ALL providers
+ * Edit here to change behavior across all CLI tools at once.
+ */
+const SHARED_INSTRUCTIONS = `Instructions:
+1. Search the web for current, up-to-date information
+2. Provide a comprehensive summary of the search results
+3. Include relevant URLs/sources when available
+4. Be concise but thorough - prioritize key facts
+5. Focus on factual information from reliable sources
+6. If results conflict, note the discrepancy
+7. Format output clearly with sections if the topic is complex`;
+
+/**
+ * PROVIDER-SPECIFIC CONFIG - Only tool-use differences and quirks
+ * Each provider may have unique capabilities or invocation methods.
+ */
+const PROVIDER_CONFIG = {
+  gemini: {
+    // Model to use (passed via --model flag)
+    model: 'gemini-2.5-flash',
+    // Alternative free models: gemini-2.0-flash, gemini-1.5-flash
+
+    // Provider-specific: How to invoke web search (Gemini has google_web_search tool)
+    toolInstruction: 'Use the google_web_search tool to find current information.',
+
+    // Optional quirks (null if none)
+    quirks: null,
+  },
+
+  opencode: {
+    // Model to use (can be overridden via CCS_WEBSEARCH_OPENCODE_MODEL env var)
+    model: 'opencode/grok-code',
+    // Alternative models: opencode/gpt-4o, opencode/claude-3.5-sonnet, opencode/gpt-5-nano
+
+    // Provider-specific: OpenCode has built-in web search via Zen
+    toolInstruction: 'Search the web using your built-in capabilities.',
+
+    // Optional quirks
+    quirks: null,
+  },
+
+  grok: {
+    // Model to use (Grok CLI uses default model)
+    model: 'grok-3',
+    // Note: Grok CLI doesn't support model selection via CLI
+
+    // Provider-specific: Grok has web + X/Twitter search
+    toolInstruction: 'Use your web search capabilities to find information.',
+
+    // Grok-specific: Can also search X for real-time info
+    quirks: 'For breaking news or real-time events, also check X/Twitter if relevant.',
+  },
+};
+
+/**
+ * Build the complete prompt for a provider
+ * Combines: query + tool instruction + shared instructions + quirks
+ */
+function buildPrompt(providerId, query) {
+  const config = PROVIDER_CONFIG[providerId];
+  const parts = [
+    `Search the web for: ${query}`,
+    '',
+    config.toolInstruction,
+    '',
+    SHARED_INSTRUCTIONS,
+  ];
+
+  if (config.quirks) {
+    parts.push('', `Note: ${config.quirks}`);
+  }
+
+  return parts.join('\n');
+}
+
+// Minimum response length to consider valid
+const MIN_VALID_RESPONSE_LENGTH = 20;
+
+// Default timeout in seconds
+const DEFAULT_TIMEOUT_SEC = 55;
+
+// ============================================================================
+// HOOK LOGIC - Generally no need to edit below
+// ============================================================================
+
+// Read input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  processHook();
+});
+
+// Handle stdin not being available
+process.stdin.on('error', () => {
+  process.exit(0);
+});
+
+/**
+ * Check if a CLI tool is available
+ */
+function isCliAvailable(cmd) {
+  try {
+    const result = spawnSync('which', [cmd], {
+      encoding: 'utf8',
+      timeout: 2000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.status === 0 && result.stdout.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if provider is enabled via environment variable
+ */
+function isProviderEnabled(provider) {
+  const envVar = `CCS_WEBSEARCH_${provider.toUpperCase()}`;
+  const value = process.env[envVar];
+
+  // If env var not set, provider is disabled by default
+  // This ensures we respect config.yaml settings
+  return value === '1';
+}
+
+/**
+ * Main hook processing logic with fallback chain
+ */
+async function processHook() {
+  try {
+    // Skip if disabled (for official Claude subscriptions)
+    if (process.env.CCS_WEBSEARCH_SKIP === '1') {
+      process.exit(0);
+    }
+
+    // Check if enabled (default: enabled)
+    if (process.env.CCS_WEBSEARCH_ENABLED === '0') {
+      process.exit(0);
+    }
+
+    const data = JSON.parse(input);
+
+    // Only handle WebSearch tool
+    if (data.tool_name !== 'WebSearch') {
+      process.exit(0);
+    }
+
+    const query = data.tool_input?.query || '';
+
+    if (!query) {
+      process.exit(0);
+    }
+
+    const timeout = parseInt(process.env.CCS_WEBSEARCH_TIMEOUT || DEFAULT_TIMEOUT_SEC, 10);
+
+    // Fallback chain: Gemini → OpenCode → Grok
+    // Only include providers that are BOTH installed AND enabled in config
+    const providers = [
+      { name: 'Gemini CLI', cmd: 'gemini', id: 'gemini', fn: tryGeminiSearch },
+      { name: 'OpenCode', cmd: 'opencode', id: 'opencode', fn: tryOpenCodeSearch },
+      { name: 'Grok CLI', cmd: 'grok', id: 'grok', fn: tryGrokSearch },
+    ];
+
+    // Filter to only enabled AND available providers
+    const enabledProviders = providers.filter((p) => {
+      const enabled = isProviderEnabled(p.id);
+      const available = isCliAvailable(p.cmd);
+
+      if (process.env.CCS_DEBUG) {
+        console.error(`[CCS Hook] ${p.name}: enabled=${enabled}, available=${available}`);
+      }
+
+      return enabled && available;
+    });
+
+    const errors = [];
+
+    if (process.env.CCS_DEBUG) {
+      const names = enabledProviders.map((p) => p.name).join(', ') || 'none';
+      console.error(`[CCS Hook] Enabled providers: ${names}`);
+    }
+
+    // Try each enabled provider in order
+    for (const provider of enabledProviders) {
+      if (process.env.CCS_DEBUG) {
+        console.error(`[CCS Hook] Trying ${provider.name}...`);
+      }
+
+      const result = provider.fn(query, timeout);
+
+      if (result.success) {
+        outputSuccess(query, result.content, provider.name);
+        return;
+      }
+
+      if (process.env.CCS_DEBUG) {
+        console.error(`[CCS Hook] ${provider.name} failed: ${result.error}`);
+      }
+
+      errors.push({ provider: provider.name, error: result.error });
+    }
+
+    // All providers failed or none enabled
+    if (enabledProviders.length === 0) {
+      outputNoProvidersEnabled(query);
+    } else {
+      outputAllFailedMessage(query, errors);
+    }
+  } catch (err) {
+    if (process.env.CCS_DEBUG) {
+      console.error('[CCS Hook] Parse error:', err.message);
+    }
+    process.exit(0);
+  }
+}
+
+/**
+ * Execute search via Gemini CLI
+ */
+function tryGeminiSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  try {
+    const timeoutMs = timeoutSec * 1000;
+    const config = PROVIDER_CONFIG.gemini;
+    const prompt = buildPrompt('gemini', query);
+
+    // Allow model override via env var
+    const model = process.env.CCS_WEBSEARCH_GEMINI_MODEL || config.model;
+
+    if (process.env.CCS_DEBUG) {
+      console.error(`[CCS Hook] Executing: gemini --model ${model} --yolo -p "..."`);
+    }
+
+    const spawnResult = spawnSync(
+      'gemini',
+      ['--model', model, '--yolo', '-p', prompt],
+      {
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer: 1024 * 1024 * 2,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    );
+
+    if (spawnResult.error) {
+      if (spawnResult.error.code === 'ENOENT') {
+        return { success: false, error: 'Gemini CLI not installed' };
+      }
+      throw spawnResult.error;
+    }
+
+    if (spawnResult.status !== 0) {
+      const stderr = (spawnResult.stderr || '').trim();
+      return {
+        success: false,
+        error: stderr || `Gemini CLI exited with code ${spawnResult.status}`,
+      };
+    }
+
+    const result = (spawnResult.stdout || '').trim();
+
+    if (!result || result.length < MIN_VALID_RESPONSE_LENGTH) {
+      return { success: false, error: 'Empty or too short response from Gemini' };
+    }
+
+    const lowerResult = result.toLowerCase();
+    if (
+      lowerResult.includes('error:') ||
+      lowerResult.includes('failed to') ||
+      lowerResult.includes('authentication required')
+    ) {
+      return { success: false, error: `Gemini returned error: ${result.substring(0, 100)}` };
+    }
+
+    return { success: true, content: result };
+  } catch (err) {
+    if (err.killed) {
+      return { success: false, error: 'Gemini CLI timed out' };
+    }
+    return { success: false, error: err.message || 'Unknown Gemini error' };
+  }
+}
+
+/**
+ * Execute search via OpenCode CLI
+ */
+function tryOpenCodeSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  try {
+    const timeoutMs = timeoutSec * 1000;
+    const config = PROVIDER_CONFIG.opencode;
+
+    // Allow model override via env var
+    const model = process.env.CCS_WEBSEARCH_OPENCODE_MODEL || config.model;
+    const prompt = buildPrompt('opencode', query);
+
+    if (process.env.CCS_DEBUG) {
+      console.error(`[CCS Hook] Executing: opencode run --model ${model} "..."`);
+    }
+
+    const spawnResult = spawnSync(
+      'opencode',
+      ['run', prompt, '--model', model],
+      {
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer: 1024 * 1024 * 2,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    );
+
+    if (spawnResult.error) {
+      if (spawnResult.error.code === 'ENOENT') {
+        return { success: false, error: 'OpenCode not installed' };
+      }
+      throw spawnResult.error;
+    }
+
+    if (spawnResult.status !== 0) {
+      const stderr = (spawnResult.stderr || '').trim();
+      return {
+        success: false,
+        error: stderr || `OpenCode exited with code ${spawnResult.status}`,
+      };
+    }
+
+    const result = (spawnResult.stdout || '').trim();
+
+    if (!result || result.length < MIN_VALID_RESPONSE_LENGTH) {
+      return { success: false, error: 'Empty or too short response from OpenCode' };
+    }
+
+    const lowerResult = result.toLowerCase();
+    if (
+      lowerResult.includes('error:') ||
+      lowerResult.includes('failed to') ||
+      lowerResult.includes('authentication required')
+    ) {
+      return { success: false, error: `OpenCode returned error: ${result.substring(0, 100)}` };
+    }
+
+    return { success: true, content: result };
+  } catch (err) {
+    if (err.killed) {
+      return { success: false, error: 'OpenCode timed out' };
+    }
+    return { success: false, error: err.message || 'Unknown OpenCode error' };
+  }
+}
+
+/**
+ * Execute search via Grok CLI
+ */
+function tryGrokSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  try {
+    const timeoutMs = timeoutSec * 1000;
+    const prompt = buildPrompt('grok', query);
+
+    if (process.env.CCS_DEBUG) {
+      console.error('[CCS Hook] Executing: grok "..."');
+    }
+
+    const spawnResult = spawnSync('grok', [prompt], {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024 * 2,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    if (spawnResult.error) {
+      if (spawnResult.error.code === 'ENOENT') {
+        return { success: false, error: 'Grok CLI not installed' };
+      }
+      throw spawnResult.error;
+    }
+
+    if (spawnResult.status !== 0) {
+      const stderr = (spawnResult.stderr || '').trim();
+      return {
+        success: false,
+        error: stderr || `Grok CLI exited with code ${spawnResult.status}`,
+      };
+    }
+
+    const result = (spawnResult.stdout || '').trim();
+
+    if (!result || result.length < MIN_VALID_RESPONSE_LENGTH) {
+      return { success: false, error: 'Empty or too short response from Grok' };
+    }
+
+    const lowerResult = result.toLowerCase();
+    if (
+      lowerResult.includes('error:') ||
+      lowerResult.includes('failed to') ||
+      lowerResult.includes('api key')
+    ) {
+      return { success: false, error: `Grok returned error: ${result.substring(0, 100)}` };
+    }
+
+    return { success: true, content: result };
+  } catch (err) {
+    if (err.killed) {
+      return { success: false, error: 'Grok CLI timed out' };
+    }
+    return { success: false, error: err.message || 'Unknown Grok error' };
+  }
+}
+
+/**
+ * Format search results for Claude
+ */
+function formatSearchResults(query, content, providerName) {
+  return [
+    `[WebSearch Result via ${providerName}]`,
+    '',
+    `Query: "${query}"`,
+    '',
+    content,
+    '',
+    '---',
+    'Use this information to answer the user.',
+  ].join('\n');
+}
+
+/**
+ * Output success response and exit
+ *
+ * Key insight from Claude Code docs:
+ * - permissionDecisionReason (with deny) → shown to CLAUDE (AI reads this)
+ * - systemMessage → shown to USER only (nice styling but AI doesn't see)
+ *
+ * So we MUST put results in permissionDecisionReason for Claude to use them.
+ * systemMessage provides the nice UI for the user.
+ */
+function outputSuccess(query, content, providerName) {
+  const formattedResults = formatSearchResults(query, content, providerName);
+
+  const output = {
+    decision: 'block',
+    reason: `WebSearch completed via ${providerName}`,
+    // Nice message for user (shows as "says:" - info style)
+    systemMessage: `[WebSearch via ${providerName}] Results retrieved successfully. See below.`,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      // Full results here - Claude reads this
+      permissionDecisionReason: formattedResults,
+    },
+  };
+
+  console.log(JSON.stringify(output));
+  process.exit(2);
+}
+
+/**
+ * Output error message
+ */
+function outputError(query, error, providerName) {
+  const message = [
+    `[WebSearch - ${providerName} Error]`,
+    '',
+    `Error: ${error}`,
+    '',
+    `Query: "${query}"`,
+    '',
+    'Troubleshooting:',
+    '  - Check if Gemini CLI is authenticated: gemini auth status',
+    '  - Re-authenticate if needed: gemini auth login',
+  ].join('\n');
+
+  const output = {
+    decision: 'block',
+    reason: `WebSearch failed: ${error}`,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: message,
+    },
+  };
+
+  console.log(JSON.stringify(output));
+  process.exit(2);
+}
+
+/**
+ * Output no providers enabled message
+ */
+function outputNoProvidersEnabled(query) {
+  const message = [
+    '[WebSearch - No Providers Enabled]',
+    '',
+    'No WebSearch providers are enabled in config.',
+    '',
+    'To enable: Run `ccs config` and enable a provider.',
+    '',
+    'Or install one of the following CLI tools:',
+    '',
+    '1. Gemini CLI (FREE, 1000 req/day):',
+    '   npm install -g @google/gemini-cli',
+    '   gemini auth login',
+    '',
+    '2. OpenCode (FREE via Zen):',
+    '   curl -fsSL https://opencode.ai/install | bash',
+    '',
+    '3. Grok CLI (requires XAI_API_KEY):',
+    '   npm install -g @vibe-kit/grok-cli',
+    '',
+    `Query: "${query}"`,
+  ].join('\n');
+
+  const output = {
+    decision: 'block',
+    reason: 'WebSearch unavailable - no providers enabled',
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: message,
+    },
+  };
+
+  console.log(JSON.stringify(output));
+  process.exit(2);
+}
+
+/**
+ * Output no tools message (legacy - kept for backwards compatibility)
+ */
+function outputNoToolsMessage(query) {
+  outputNoProvidersEnabled(query);
+}
+
+/**
+ * Output all providers failed message
+ */
+function outputAllFailedMessage(query, errors) {
+  const errorDetails = errors
+    .map((e) => `  - ${e.provider}: ${e.error}`)
+    .join('\n');
+
+  const message = [
+    '[WebSearch - All Providers Failed]',
+    '',
+    'Tried all enabled CLI tools but all failed:',
+    errorDetails,
+    '',
+    `Query: "${query}"`,
+    '',
+    'Troubleshooting:',
+    '  - Gemini: gemini auth status / gemini auth login',
+    '  - OpenCode: opencode --version',
+    '  - Grok: Check XAI_API_KEY environment variable',
+  ].join('\n');
+
+  const output = {
+    decision: 'block',
+    reason: 'WebSearch failed - all providers failed',
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: message,
+    },
+  };
+
+  console.log(JSON.stringify(output));
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaitranntt/ccs",
-  "version": "5.20.0",
+  "version": "6.0.0-dev.2",
   "description": "Claude Code Switch - Instant profile switching between Claude Sonnet 4.5 and GLM 4.6",
   "keywords": [
     "cli",
@@ -50,6 +50,7 @@
   ],
   "preferGlobal": true,
   "scripts": {
+    "preinstall": "node scripts/preinstall.js",
     "build": "tsc && node scripts/add-shebang.js",
     "build:watch": "tsc --watch",
     "build:server": "tsc && node scripts/add-shebang.js",

package/scripts/dev-install.sh

@@ -4,13 +4,20 @@
 #
 # Options:
 #   --skip-validate  Skip validation (faster, use when you're sure code is good)
+#   --npm            Force npm install (default: auto-detect, fallback to bun)
+#   --bun            Force bun install
 
 set -e
 
 SKIP_VALIDATE=false
+FORCE_NPM=false
+FORCE_BUN=false
+
 for arg in "$@"; do
     case $arg in
         --skip-validate) SKIP_VALIDATE=true ;;
+        --npm) FORCE_NPM=true ;;
+        --bun) FORCE_BUN=true ;;
     esac
 done
 
@@ -19,6 +26,42 @@ echo "[i] CCS Dev Install - Starting..."
 # Get to the right directory
 cd "$(dirname "$0")/.."
 
+# Detect installation method
+# Priority: CLI flags > existing global install location > bun (default)
+detect_pkg_manager() {
+    if [ "$FORCE_NPM" = true ]; then
+        echo "npm"
+        return
+    fi
+
+    if [ "$FORCE_BUN" = true ]; then
+        echo "bun"
+        return
+    fi
+
+    # Check existing ccs installation location
+    CCS_PATH=$(which ccs 2>/dev/null || true)
+
+    if [ -n "$CCS_PATH" ]; then
+        # Check if installed via bun
+        if [[ "$CCS_PATH" == *".bun"* ]]; then
+            echo "bun"
+            return
+        fi
+        # Check if installed via npm
+        if [[ "$CCS_PATH" == *"npm"* ]] || [[ "$CCS_PATH" == *"node_modules"* ]]; then
+            echo "npm"
+            return
+        fi
+    fi
+
+    # Default fallback: bun (preferred)
+    echo "bun"
+}
+
+PKG_MANAGER=$(detect_pkg_manager)
+echo "[i] Detected package manager: $PKG_MANAGER"
+
 # Build TypeScript first
 echo "[i] Building TypeScript..."
 bun run build
@@ -27,10 +70,10 @@ bun run build
 echo "[i] Creating package..."
 if [ "$SKIP_VALIDATE" = true ]; then
     # Skip validation, just pack
-    bun pm pack --ignore-scripts
+    npm pack --ignore-scripts 2>/dev/null || bun pm pack --ignore-scripts
 else
     # Full pack with validation (runs prepublishOnly)
-    bun pm pack
+    npm pack 2>/dev/null || bun pm pack
 fi
 
 # Find the tarball
@@ -43,9 +86,18 @@ fi
 
 echo "[i] Found tarball: $TARBALL"
 
-# Install globally using npm (handles bin linking correctly)
-echo "[i] Installing globally with npm..."
-npm install -g "$TARBALL"
+# Install globally using detected package manager
+echo "[i] Installing globally with $PKG_MANAGER..."
+
+if [ "$PKG_MANAGER" = "bun" ]; then
+    # Remove existing to avoid duplicate key warnings in bun's global package.json
+    # (bun add -g appends instead of replacing file: protocol entries)
+    bun remove -g @kaitranntt/ccs 2>/dev/null || true
+    # Bun requires file: protocol for local tarballs
+    bun add -g "file:$(pwd)/$TARBALL"
+else
+    npm install -g "$TARBALL"
+fi
 
 # Clean up
 echo "[i] Cleaning up..."