@haposoft/cafekit 0.7.27 → 0.7.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.27",
+  "version": "0.7.28",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -132,11 +132,10 @@ When you need to search the internet for information (research, docs lookup, tro
 
 | Priority | Tool | Command | When to use |
 |----------|------|---------|-------------|
-| 🥇 **P1** | `web-search.cjs` | `node .claude/scripts/web-search.cjs "[query]"` | **EXCLUSIVE PRIMARY.** Works via Gemini Grounding. Supports `--multi`. **TRUST THE SYNTHESIZED ANSWER** — do NOT manually scrape source URLs. |
-| 🥈 **P2** | `WebSearch` (native) | Use WebSearch tool directly | Secondary verification, or when P1 fails. |
-| 🥉 **P3** | `docs-fetch.js` | `node .claude/scripts/docs-fetch.js "library"` | Only for fetching raw documentation when synthesis is insufficient. |
+| 🥇 **P1** | `WebSearch` (native) | Use WebSearch tool directly | Primary search path for internet lookup and current information. |
+| 🥈 **P2** | `WebFetch` / direct fetch | Use only when a specific source URL must be inspected directly | Fallback for targeted source verification and raw document reading. |
 
-**IMPORTANT**: When the user asks you to find information, research a topic, or investigate anything that requires internet access, you MUST use the Web Search Protocol above. **NEVER** reply with "I cannot search the web". **NEVER** attempt manual `Fetch` or Python-based scraping for search results if `web-search.cjs` provides an answer. Trust the grounding.
+**IMPORTANT**: When the user asks you to find information, research a topic, or investigate anything that requires internet access, you MUST use the protocol above. **NEVER** reply with "I cannot search the web". Prefer native search first, then inspect raw sources only when needed for verification or missing detail.
 
 ## Code Quality
 
@@ -175,4 +174,4 @@ When generating spec documents (`requirements.md`, `design.md`, `research.md`, `
 - **Code samples and file paths** are always in English.
 - If the user switches language mid-project, ask which language to standardize on and apply it uniformly to all new and regenerated spec files.
 
-**MANDATORY DIRECTIVE:** All directives within this document, particularly the **Behavioral Principles** and **Operational Procedures**, are absolute core constraints. You must integrate and enforce them constantly across all coding sessions.
+**MANDATORY DIRECTIVE:** All directives within this document, particularly the **Behavioral Principles** and **Operational Procedures**, are absolute core constraints. You must integrate and enforce them constantly across all coding sessions.

package/src/claude/agents/researcher.md

@@ -23,7 +23,7 @@ Before finalizing and emitting a Research Summary Report, you must assert the fo
 ## Skill Artillery (Your Skills)
 
 **CRITICAL**: Deploy `research` skills aggressively to anatomize technology stacks flawlessly.
-**CRITICAL**: Fully exploit internal localized Bash scripts (specifically `node scripts/docs-fetch.js`) to scrape massive payloads of API documentation without manually hunting through raw URLs.
+**CRITICAL**: Use `WebFetch` aggressively when a specific authoritative source must be inspected directly instead of relying on secondary summaries.
 
 ## Role Responsibilities
 - **SUPREME DIRECTIVE**: Maximize token reduction while pushing output velocities for highly-condensed, brilliant technical summaries. 
@@ -41,10 +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.
-- **[PRIORITY 1]** Deploying `node .claude/scripts/web-search.cjs "[query]"` as the **EXCLUSIVE PRIMARY search tool**. This tool uses Gemini Grounding to return a synthesized **answer** plus cited sources. **STOP SEARCHING** once you have a sufficient answer from this script. Do NOT manually crawl source URLs if the provided synthesis is clear.
-- **[PRIORITY 2]** Trust the script's output directly. READ the JSON and extract the `answer` field. **STRICTLY FORBIDDEN**: Writing Python scripts to parse this JSON or manually `Fetch` every URL listed in the sources unless the user explicitly demands a deep-dive implementation detail only found in a raw document.
-- **[PRIORITY 3]** If `web-search.cjs` fails or returns no results, use native `WebSearch` tool (if available) as a backup.
-- **[PRIORITY 4]** Deploying `scripts/docs-fetch.js` ONLY for raw documents where the direct URL is already known and synthesis is insufficient.
+- **[PRIORITY 1]** Use native `WebSearch` as the primary search tool for current information, docs discovery, troubleshooting, and competitive research.
+- **[PRIORITY 2]** Verify key claims across multiple credible sources. Prefer official docs, maintainer materials, release notes, and strong production references over generic blogs.
+- **[PRIORITY 3]** Use direct `WebFetch` when a specific source must be inspected line-by-line for evidence, API detail, or implementation constraints.
 - 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/hooks/lib/config.cjs

@@ -65,7 +65,7 @@ const DEFAULT_CONFIG = {
     'session-init': true,
     'subagent-init': true,
     'dev-rules-reminder': true,
-    'usage-context-awareness': true,
+    'usage': true,
     'context-tracking': true,
     'scout-block': true,
     'privacy-block': true,

package/src/claude/hooks/lib/context.cjs

@@ -489,7 +489,7 @@ function buildReminder(params) {
   // Respect hooks config — skip sections when their corresponding hook is disabled
   const hooksConfig = hooks || {};
   const contextEnabled = hooksConfig['context-tracking'] !== false;
-  const usageEnabled = hooksConfig['usage-context-awareness'] !== false;
+  const usageEnabled = hooksConfig['usage'] !== false;
 
   return [
     ...buildLanguageSection({ thinkingLanguage, responseLanguage }),
@@ -564,7 +564,7 @@ function buildReminderContext({ sessionId, config, staticEnv, configDirName = '.
   // Respect hooks config for sections object too
   const hooksConfig = cfg.hooks || {};
   const contextEnabled = hooksConfig['context-tracking'] !== false;
-  const usageEnabled = hooksConfig['usage-context-awareness'] !== false;
+  const usageEnabled = hooksConfig['usage'] !== false;
 
   return {
     content: lines.join('\n'),

package/src/claude/migration-manifest.json

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

package/src/claude/references/debugger/docs-research.md

@@ -3,12 +3,12 @@
 Never guess the API syntax of third-party libraries, especially when the system is throwing "Deprecated" or "Undefined Function" errors.
 
 ## Where is the Arsenal? (Zero-token Execution Strategy)
-Commanders must utilize the native independent script embedded directly within the tooling framework(`scripts/docs-fetch.js`) by transmitting direct execution commands (Execute) into bash. Documentation retrieval speeds will be 100x faster and entirely avoid context window degradation.
+Commanders should use `WebFetch` against authoritative documentation URLs when raw source inspection is required. Prefer direct source verification over secondary summaries when debugging ambiguous API behavior.
 
 ## Bash Execution Procedure:
 1. **[Script] Fetch Link and Analyze (Fetch/Detect):**
    ```bash
-   node scripts/docs-fetch.js "How to use useForm in React Hook Form"
+   WebFetch the official React Hook Form documentation page for `useForm`
    ```
 
-**Core Imperative:** Never hesitate to call `node scripts/docs-fetch.js` if the library is officially supported or widely known. This mechanism violently exploits automated allied tooling to maximize operational speed.
+**Core Imperative:** Never hesitate to use `WebFetch` when the exact source page is known and line-by-line inspection is needed to resolve uncertainty quickly.

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

@@ -23,11 +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: ALWAYS use `node .claude/scripts/web-search.cjs "[query]"` as the EXCLUSIVE primary search method. This tool uses Gemini Grounding and returns a synthesized answer + cited sources. Do NOT manually crawl source URLs if the script provides a sufficient answer.
-Constraint 2: TRUST THE SYNTHESIS. The output contains the research results. Read the JSON and use the `answer` field directly. Do NOT write Python scripts to re-parse it or manually `Fetch` sources unless deep implementation details are missing.
-Constraint 3: Use native WebSearch or manual Fetch ONLY if the script fails or returns no results.
+Constraint 1: ALWAYS use native `WebSearch` as the primary search method.
+Constraint 2: Validate key claims with multiple credible sources. Prioritize official docs, maintainers, release notes, and strong production references.
+Constraint 3: Use direct `WebFetch` only when search results are insufficient or raw source inspection is required.
 Constraint 4: Limit total search calls to a maximum of 5 distinct queries.
-Constraint 5: Stop excessive "chain-searching". Use the grounding answer as the definitive summary.
+Constraint 5: Stop excessive "chain-searching". Synthesize decisively once the evidence is sufficient.
 Output Format: Must strictly follow the 'Standard Research Report' layout.
 ```
 

package/src/claude/scripts/docs-fetch.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-/**
- * Native Docs Fetcher
- * Aggregates extraction of `llms.txt` patterns from context7.com (Unified logic).
- * Usage: node docs-fetch.js "How to use Next.js App router"
- */
-
-const https = require('https');
-
-function fetchUrl(url) {
-  return new Promise((resolve) => {
-    https.get(url, { headers: { 'User-Agent': 'Docs-Fetcher' } }, (res) => {
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => resolve({ status: res.statusCode, data }));
-    }).on('error', () => resolve({ status: 500, data: null }));
-  });
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  if (args.length === 0) {
-    console.error('[Docs Fetcher] Error: Explicit query parameter required. (Example: node docs-fetch.js "next.js router")');
-    process.exit(1);
-  }
-
-  const query = args.join(' ').toLowerCase();
-
-  // Smart Detection (Keyword mapping index)
-  const knownLibs = {
-    'next.js': 'vercel/next.js',
-    'nextjs': 'vercel/next.js',
-    'react': 'facebook/react',
-    'shadcn': 'shadcn-ui/ui',
-    'shadcn/ui': 'shadcn-ui/ui',
-    'astro': 'withastro/astro',
-    'remix': 'remix-run/remix'
-  };
-
-  let targetRepo = '';
-  for (const [key, repo] of Object.entries(knownLibs)) {
-    if (query.includes(key)) {
-      targetRepo = repo;
-      break;
-    }
-  }
-
-  // Heuristic string fallback matching for "docs for abc" sequences
-  if (!targetRepo) {
-    const fallbackMatch = query.match(/for ([a-z0-9-]+)/);
-    if (fallbackMatch) targetRepo = `websites/${fallbackMatch[1]}`;
-    else targetRepo = `websites/${query.split(' ')[0]}`; // Fallback primitive string assumption
-  }
-
-  const url = `https://context7.com/${targetRepo}/llms.txt`;
-  console.log(`[Docs Fetcher] Interrogating Knowledge Archival Node at: ${url}`);
-
-  const fallbackUrl = `https://raw.githubusercontent.com/${targetRepo}/main/README.md`;
-
-  const result = await fetchUrl(url);
-
-  if (result.status === 200 && result.data) {
-    console.log('\n--- SUCCESSFUL PAYLOAD EXTRACTED ---');
-    // Buffer restriction truncation
-    console.log(result.data.substring(0, 3000));
-    console.log('\n(Output truncated cleanly to minimize LLM Context Overload)');
-  } else {
-    console.warn(`[!] Architectural layout llms.txt missing at: ${url}`);
-    console.log(`[+] Executing GitHub default branch failover (README.md mapping): ${fallbackUrl}`);
-    const fbResult = await fetchUrl(fallbackUrl);
-    if (fbResult.status === 200 && fbResult.data) {
-      console.log('\n--- PAYLOAD EXTRACTED (README.md) ---');
-      console.log(fbResult.data.substring(0, 3000));
-    } else {
-      console.error('\n[FATAL] Documentation retrieval failure. No corresponding books identified within known databanks. Agent must fall back to utilizing standard WebSearch mapping via DuckDuckGo execution streams!');
-      process.exit(1);
-    }
-  }
-}
-
-main();

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

@@ -1,211 +0,0 @@
-#!/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 loadEnv() {
-  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');
-        content.split(/\r?\n/).forEach(line => {
-          const match = line.match(/^([^=]+)=(.*)$/);
-          if (match) {
-            const key = match[1].trim();
-            const val = match[2].trim().replace(/^["']|["']$/g, '');
-            // Only set if not already present in environment
-            if (process.env[key] === undefined) {
-              process.env[key] = val;
-            }
-          }
-        });
-        return; // Loaded successfully, no need to check other paths
-      }
-    } catch { /* skip */ }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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();
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Resolve Vertex AI grounding redirect URLs to real URLs
-// ---------------------------------------------------------------------------
-function resolveRedirectUrl(url) {
-  return new Promise((resolve) => {
-    if (!url || !url.includes('grounding-api-redirect')) {
-      resolve(url);
-      return;
-    }
-
-    const protocol = url.startsWith('https') ? https : require('http');
-    const req = protocol.request(url, { method: 'HEAD', timeout: 5000 }, (res) => {
-      // Follow redirect chain - Location header has the real URL
-      resolve(res.headers.location || url);
-    });
-    req.on('error', () => resolve(url));
-    req.on('timeout', () => { req.destroy(); resolve(url); });
-    req.end();
-  });
-}
-
-async function resolveAllUrls(sources) {
-  return Promise.all(sources.map(async (src) => {
-    const realUrl = await resolveRedirectUrl(src.url);
-    return { ...src, url: realUrl };
-  }));
-}
-
-// ---------------------------------------------------------------------------
-// Parse Grounding Metadata → Structured Output
-// ---------------------------------------------------------------------------
-async 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
-  let sources = (meta.groundingChunks || []).map(chunk => ({
-    title: chunk.web?.title || 'Unknown',
-    url: chunk.web?.uri || '',
-  }));
-
-  // Resolve redirect URLs to real URLs
-  sources = await resolveAllUrls(sources);
-
-  // Deduplicate by resolved URL
-  const seen = new Set();
-  sources = sources.filter(s => {
-    if (seen.has(s.url)) return false;
-    seen.add(s.url);
-    return true;
-  });
-
-  // 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);
-  }
-
-  loadEnv();
-  const apiKey = process.env.GEMINI_API_KEY;
-  if (!apiKey) {
-    console.error(JSON.stringify({
-      error: 'GEMINI_API_KEY not found. Set it in .claude/.env or environment variable.'
-    }));
-    process.exit(1);
-  }
-
-  // Determine which model to use. User might configure MODEL or VISUAL_MODEL in their .env
-  let model = process.env.SEARCH_MODEL || process.env.MODEL || process.env.VISUAL_MODEL || 'gemini-2.5-flash';
-
-  // Google Search Grounding ONLY supports Gemini models (not Claude, not Gemma)
-  if (!model.toLowerCase().includes('gemini') && !model.toLowerCase().includes('learnlm')) {
-    model = 'gemini-2.5-flash'; // Fallback to safe search model
-  }
-
-  const results = [];
-
-  for (const query of queries) {
-    try {
-      const raw = await callGemini(apiKey, query, model);
-      results.push(await 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();