@haposoft/cafekit 0.7.6 → 0.7.8

package/bin/install.js

@@ -543,7 +543,7 @@ function copyPlatformFiles(platformKey, results, options = {}) {
       // Copy agent reference manuals (debugger manuals, etc.) recursively
       const refsSource = path.join(__dirname, '../src', platform.sourceDir, 'references');
       if (fs.existsSync(refsSource)) {
-        const refsDest = path.join(platform.destDir, 'references');
+        const refsDest = path.join(platform.folder, 'references');
         const refsExisted = fs.existsSync(refsDest);
         copyRecursive(refsSource, refsDest, options);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Spec-Driven Development workflow for AI coding assistants. Supports Claude Code and Antigravity with spec-first workflows plus Claude Code hapo: skills.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -64,6 +64,18 @@ When triggering Python scripts located under `.claude/skills/`, you must invoke
 
 *Note: If a skill script throws an error, do not abandon the task. try run with venv. if error again, try fix and run
 
+## Web Search Protocol
+
+When you need to search the internet for information (research, docs lookup, troubleshooting, latest updates, etc.), follow this priority chain:
+
+| Priority | Tool | Command | When to use |
+|----------|------|---------|-------------|
+| 🥇 **P1** | `web-search.cjs` | `node .claude/scripts/web-search.cjs "query"` | **ALWAYS try first.** Works on ALL models via Gemini Google Search Grounding. Supports `--multi "q1" "q2"` for batch. Returns JSON with answer + sources. |
+| 🥈 **P2** | `WebSearch` (native) | Use WebSearch tool directly | Secondary verification, or when P1 fails/unavailable. |
+| 🥉 **P3** | `docs-fetch.js` | `node .claude/scripts/docs-fetch.js "library"` | Only when you already know a specific library and need its raw documentation. |
+
+**IMPORTANT**: When the user asks you to find information, research a topic, look up documentation, or investigate anything that requires internet access, you MUST use the Web Search Protocol above. Do NOT reply with "I cannot search the web" — you have `web-search.cjs` available via Bash.
+
 ## Code Refactoring Triggers
 
 - **Size Thresholds**: Automatically consider splitting code files that grow beyond 200 lines.

package/src/claude/agents/researcher.md

@@ -41,7 +41,9 @@ You possess extreme proficiency in:
 - Segregating Stable Production Practices away from Toxic Experimental Paradigms.
 - Sniffing out valid Adoption Patterns and real-world implementation trending.
 - Forgiving nothing when crafting Trade-off computational matrices for thousands of competing libraries.
-- Deploying the `scripts/docs-fetch.js` sniper utility precisely to rip documentation pages directly into context buffers.
+- **[PRIORITY 1]** Deploying `scripts/web-search.cjs` as the **PRIMARY search tool** for all web queries. Usage: `node .claude/scripts/web-search.cjs "query"` or `node .claude/scripts/web-search.cjs --multi "q1" "q2"`. Returns JSON with answer, sources, and citations via Gemini Google Search Grounding. ALWAYS attempt this first before any other search method.
+- **[PRIORITY 2]** If WebSearch native tool is available, use it as secondary verification or when `web-search.cjs` fails.
+- **[PRIORITY 3]** Deploying `scripts/docs-fetch.js` only when official Github/Doc URLs are already identified and you need to pull raw documentation content.
 - Deploying Bash and raw Grep utilities to surgically dissect embedded Document architectures and internal file payloads to evaluate raw insights.
 
 **ABSOLUTE IMMOVEABLE DIRECTIVE**: You are **STRICTLY PROHIBITED** from generating executable endpoint "Implementation Code". You exist ONLY to maneuver data streams, render synthesis Summary text, and return comprehensive Markdown documentation pathways to the main caller Agent.

package/src/claude/migration-manifest.json

@@ -53,7 +53,8 @@
     "required": [
       "docs-fetch.js",
       "validate-docs.cjs",
-      "browser-tool.cjs"
+      "browser-tool.cjs",
+      "web-search.cjs"
     ]
   },
   "agentReferences": {

package/src/claude/scripts/web-search.cjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Web Search via Gemini API + Google Search Grounding
+ * Fallback search tool for models without native WebSearch capability.
+ *
+ * Usage:
+ *   node web-search.cjs "your search query here"
+ *   node web-search.cjs --multi "query1" "query2" "query3"
+ *
+ * Requires: GEMINI_API_KEY in .claude/.env or environment
+ *
+ * Output: JSON-structured search results with sources and citations.
+ */
+
+const https = require('https');
+const path = require('path');
+const fs = require('fs');
+
+// ---------------------------------------------------------------------------
+// ENV Resolution: .claude/.env → process.env
+// ---------------------------------------------------------------------------
+function resolveApiKey() {
+  // Priority 1: Already in environment
+  if (process.env.GEMINI_API_KEY) return process.env.GEMINI_API_KEY;
+
+  // Priority 2: Project-local .claude/.env
+  const envPaths = [
+    path.join(process.cwd(), '.claude', '.env'),
+    path.join(process.cwd(), '..', '.claude', '.env'),
+  ];
+
+  for (const envPath of envPaths) {
+    try {
+      if (fs.existsSync(envPath)) {
+        const content = fs.readFileSync(envPath, 'utf8');
+        const match = content.match(/^GEMINI_API_KEY=(.+)$/m);
+        if (match) return match[1].trim().replace(/^["']|["']$/g, '');
+      }
+    } catch { /* skip */ }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Gemini API Call with Google Search Grounding
+// ---------------------------------------------------------------------------
+function callGemini(apiKey, query, model) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify({
+      contents: [{ parts: [{ text: query }] }],
+      tools: [{ googleSearch: {} }],
+      generationConfig: {
+        temperature: 0.1,
+        maxOutputTokens: 4096,
+      }
+    });
+
+    const options = {
+      hostname: 'generativelanguage.googleapis.com',
+      path: `/v1beta/models/${model}:generateContent?key=${apiKey}`,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (json.error) {
+            reject(new Error(`Gemini API Error: ${json.error.message}`));
+            return;
+          }
+          resolve(json);
+        } catch (e) {
+          reject(new Error(`Failed to parse Gemini response: ${e.message}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Parse Grounding Metadata → Structured Output
+// ---------------------------------------------------------------------------
+function parseResponse(geminiResponse, query) {
+  const candidate = geminiResponse.candidates?.[0];
+  if (!candidate) return { query, error: 'No candidates returned' };
+
+  const text = candidate.content?.parts?.map(p => p.text).join('\n') || '';
+  const meta = candidate.groundingMetadata || {};
+
+  // Extract source URLs from groundingChunks
+  const sources = (meta.groundingChunks || []).map(chunk => ({
+    title: chunk.web?.title || 'Unknown',
+    url: chunk.web?.uri || '',
+  }));
+
+  // Extract search queries used by the model
+  const searchQueries = meta.webSearchQueries || [];
+
+  return {
+    query,
+    answer: text,
+    searchQueriesUsed: searchQueries,
+    sources,
+    sourceCount: sources.length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const args = process.argv.slice(2);
+  const isMulti = args[0] === '--multi';
+  const queries = isMulti ? args.slice(1) : [args.join(' ')];
+
+  if (queries.length === 0 || (queries.length === 1 && !queries[0])) {
+    console.error(JSON.stringify({
+      error: 'Usage: node web-search.cjs "your query" | node web-search.cjs --multi "q1" "q2"'
+    }));
+    process.exit(1);
+  }
+
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error(JSON.stringify({
+      error: 'GEMINI_API_KEY not found. Set it in .claude/.env or environment variable.'
+    }));
+    process.exit(1);
+  }
+
+  // Use model from env or default to gemini-2.5-flash
+  const model = process.env.SEARCH_MODEL || 'gemini-2.5-flash';
+
+  const results = [];
+
+  for (const query of queries) {
+    try {
+      const raw = await callGemini(apiKey, query, model);
+      results.push(parseResponse(raw, query));
+    } catch (err) {
+      results.push({ query, error: err.message });
+    }
+  }
+
+  // Output as JSON for agent consumption
+  const output = isMulti ? results : results[0];
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main();

package/src/claude/skills/research/SKILL.md

@@ -23,9 +23,11 @@ Call the `TaskCreate` tool to spin up the `researcher` subagent.
 **Instructions to pass to Researcher:**
 ```text
 Conduct comprehensive research on: [topic]
-Constraint 1: Limit WebSearch calls to a maximum of 5 distinct queries to conserve context.
-Constraint 2: Utilize scripts/docs-fetch.js if official Github/Doc URLs are discovered.
-Constraint 3: Validate information via cross-referencing capabilities.
+Constraint 1: ALWAYS use `node .claude/scripts/web-search.cjs "query"` as PRIMARY search method (supports --multi for batch). This uses Gemini Google Search Grounding and returns JSON with answer + sources.
+Constraint 2: Use native WebSearch tool as secondary verification or when web-search.cjs fails.
+Constraint 3: Use scripts/docs-fetch.js ONLY when official Github/Doc URLs are already identified.
+Constraint 4: Limit total search calls to a maximum of 5 distinct queries to conserve context.
+Constraint 5: Validate information via cross-referencing capabilities.
 Output Format: Must strictly follow the 'Standard Research Report' layout.
 ```