@haposoft/cafekit 0.7.8 → 0.7.10

package/bin/install.js

@@ -827,6 +827,43 @@ function copyRulesDirectory(platformKey, results, options = {}) {
   }
 }
 
+// Ensure .gitignore configured at root
+function ensureGitignore(results, options = {}) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  const header = '# CafeKit / Ecosystem';
+  const patterns = [
+    'specs/_shared/',
+    'plans/',
+    '!plans/templates/'
+  ];
+
+  if (!fs.existsSync(gitignorePath)) {
+    const content = ['# Git Ignore', '', header, ...patterns, ''].join('\n');
+    fs.writeFileSync(gitignorePath, content, 'utf8');
+    console.log('  ✓ .gitignore created at root');
+    results.copied++;
+    return;
+  }
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split('\n').map(l => l.trim());
+  const missing = patterns.filter(p => !lines.includes(p));
+
+  if (missing.length > 0) {
+    let newContent = content;
+    if (!newContent.endsWith('\n')) newContent += '\n';
+    if (!content.includes(header)) newContent += `\n${header}\n`;
+
+    newContent += missing.join('\n') + '\n';
+    fs.writeFileSync(gitignorePath, newContent, 'utf8');
+    console.log(`  ↻ .gitignore updated: added ${missing.join(', ')}`);
+    results.updated++;
+  } else {
+    console.log('  → .gitignore already up to date');
+    results.skipped++;
+  }
+}
+
 // ═══════════════════════════════════════════════════════════
 // GEMINI CLI SETUP
 // ═══════════════════════════════════════════════════════════
@@ -902,7 +939,7 @@ function configureGeminiKey(apiKey) {
     }
 
     // Luôn ghi trực tiếp key vào rốn của não bộ AI
-    fs.writeFileSync(localEnvFile, `GEMINI_API_KEY=${apiKey}\nVISUAL_MODEL=gemma-4-31b-it\n`, { mode: 0o600 });
+    fs.writeFileSync(localEnvFile, `GEMINI_API_KEY=${apiKey}\nVISUAL_MODEL=gemma-4-31b-it\nSEARCH_MODEL=gemini-2.5-pro\n`, { mode: 0o600 });
     console.log('  ✓ Gemini API key configured securely in project (.claude/.env)');
 
     return true;
@@ -1024,6 +1061,12 @@ async function main() {
       console.log();
     }
 
+    // Ensure root .gitignore is configured correctly
+    console.log('Root Configuration');
+    console.log('-'.repeat(40));
+    ensureGitignore(results, installerOptions);
+    console.log();
+
     // Setup Gemini CLI and API Key config
     await setupGeminiCLI(platforms);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "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

@@ -70,11 +70,11 @@ 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"` | **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. |
+| 🥇 **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. |
 
-**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.
+**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.
 
 ## Code Refactoring Triggers
 

package/src/claude/agents/code-auditor.md

@@ -11,6 +11,8 @@ Goal: Catch the mistakes AI-written code commonly makes — logic errors, securi
 
 You DO NOT fix code. You only READ, SCORE, and REPORT.
 
+
+
 ## Pre-Review: Blast Radius Check (MANDATORY)
 
 Before reading any specific logic, you MUST run a Dependency Scope Check (Blast Radius):

package/src/claude/agents/god-developer.md

@@ -20,6 +20,7 @@ Any logic gaps must be clarified BEFORE typing, not discovered after bugs ship.
 - **Surgical Reading (Large Files):** Never use blanket `Read` commands on files > 800 lines. Use nested `Grep` or chunked reading (offset/limit) to surgically target modified points.
 - **Component Scaffold Limit:** Any React/UI component file that exceeds 200 LOC must trigger a proactive modularization step (split into smaller child files).
 
+
 ## Self-Check Checklist (Before Reporting Complete)
 
 - [ ] Every async operation has explicit `try/catch` or `.catch()` — no silent failures allowed.

package/src/claude/agents/project-manager.md

@@ -16,6 +16,7 @@ Unlike typical managers who report on "feelings" or conversational summaries, yo
 2. **Blocker Assassination:** You identify task stagnation (e.g., a spec stuck in 'in-progress' across multiple sessions) and force the immediate assignment of next-step actions.
 3. **Agile Aggregation:** When parallel sub-agents (like `god-developer` and `test-runner`) report completion, you sweep their logs, consolidate the facts, and generate a single authoritative **Feature Release Report**.
 
+
 ## Execution Constraints
 
 Before you declare any phase complete or issue a final status report, you must internally trace:

package/src/claude/agents/researcher.md

@@ -41,16 +41,21 @@ 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 `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.
+- **[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.
 - 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.
 
-## Report Output Format
+## Report Output Routing
 
-Adhere to the exact hierarchical naming injection logic provided by the Hook system (`## Naming`). Generated file paths must encompass explicit broadcasting timestamp references.
+Save research output based on context:
+- **Feature research** (active spec exists) → `specs/<feature>/research.md`
+- **System-wide research** (no active spec) → `specs/_shared/Research-<slug>-<date>.md`
+
+Do NOT save to `plans/reports/` or `docs/`. All research belongs in `specs/`.
 
 ## Team Operations Mode
 

package/src/claude/agents/spec-maker.md

@@ -20,6 +20,7 @@ You DO NOT write implementation code. You produce Specifications that downstream
 - **80/20 MVP:** Identify the 20% of features that deliver 80% of value.
 - **Systems Thinking:** How does this feature connect to (or break) existing systems?
 
+
 ## Pre-Completion Checklist
 
 Before finalizing any specification, assert:

package/src/claude/agents/ui-ux-designer.md

@@ -19,6 +19,7 @@ You are an award-caliber UI/UX designer. You merge aesthetic excellence with eng
 - **Accessibility:** WCAG 2.1 AA compliance as a baseline, not an afterthought.
 - **3D/WebGL:** Three.js scene composition, shader development (when appropriate).
 
+
 ## Design Workflow
 
 ### Phase 1: Research & Trend Scouting

package/src/claude/rules/orchestrator.md

@@ -5,8 +5,8 @@
 Every subagent prompt **must** include these three paths:
 
 - **Work Context** — the git root containing the target files
-- **Reports Directory** — `{work_context}/plans/reports/`
-- **Plans Directory** — `{work_context}/plans/`
+- **Specs Directory** — `{work_context}/specs/`
+- **Docs Directory** — `{work_context}/docs/`
 
 When CWD and work context differ (e.g., editing files in a sibling project), always use the **work context** paths.
 
@@ -14,8 +14,8 @@ When CWD and work context differ (e.g., editing files in a sibling project), alw
 Example prompt:
 "Resolve the date-parsing regression.
  Work context: /repos/billing-service
- Reports: /repos/billing-service/plans/reports/
- Plans: /repos/billing-service/plans/"
+ Specs: /repos/billing-service/specs/
+ Docs: /repos/billing-service/docs/"
 ```
 
 ---
@@ -97,11 +97,11 @@ Files to modify: [list]
 Files to read for context: [list]
 Acceptance criteria: [list]
 Constraints: [any relevant constraints]
-Plan reference: [phase file path if applicable]
+Spec reference: [spec folder path if applicable]
 
 Work context: [project path]
-Reports: [reports path]
-Plans: [plans path]
+Specs: [specs path]
+Docs: [docs path]
 ```
 
 ### Do

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

@@ -19,11 +19,7 @@ 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
+function loadEnv() {
   const envPaths = [
     path.join(process.cwd(), '.claude', '.env'),
     path.join(process.cwd(), '..', '.claude', '.env'),
@@ -33,13 +29,21 @@ function resolveApiKey() {
     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, '');
+        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 */ }
   }
-
-  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -89,10 +93,38 @@ function callGemini(apiKey, query, model) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// 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
 // ---------------------------------------------------------------------------
-function parseResponse(geminiResponse, query) {
+async function parseResponse(geminiResponse, query) {
   const candidate = geminiResponse.candidates?.[0];
   if (!candidate) return { query, error: 'No candidates returned' };
 
@@ -100,11 +132,22 @@ function parseResponse(geminiResponse, query) {
   const meta = candidate.groundingMetadata || {};
 
   // Extract source URLs from groundingChunks
-  const sources = (meta.groundingChunks || []).map(chunk => ({
+  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 || [];
 
@@ -132,7 +175,8 @@ async function main() {
     process.exit(1);
   }
 
-  const apiKey = resolveApiKey();
+  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.'
@@ -140,15 +184,20 @@ async function main() {
     process.exit(1);
   }
 
-  // Use model from env or default to gemini-2.5-flash
-  const model = process.env.SEARCH_MODEL || 'gemini-2.5-flash';
+  // 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(parseResponse(raw, query));
+      results.push(await parseResponse(raw, query));
     } catch (err) {
       results.push({ query, error: err.message });
     }

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 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.
+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 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.
 Output Format: Must strictly follow the 'Standard Research Report' layout.
 ```
 
@@ -38,6 +38,16 @@ Instruct the Researcher Subagent with this strict requirement:
 > "Sử dụng nguyên bản template tại `packages/spec/src/claude/skills/specs/templates/research.md`. Tuyệt đối không tự ý đẻ thêm các đề mục ngoài phạm vi file template này."
 
 ## Post-Execution
-Once the `researcher` completes the Task and returns the Markdown output:
-1. Save the file cleanly using the naming path format injected by the Context Hook (typically `plans/reports/Report-<slug>-<date>.md`).
-2. Conclude the workflow by providing the user with the file path.
+Once the `researcher` completes the Task and returns the Markdown output, save it based on context:
+
+### Output Routing
+| Context | Save to | Example |
+|---|---|---|
+| Active spec exists (`specs/<feature>/`) | `specs/<feature>/research.md` | `specs/auth-login/research.md` |
+| No active spec (system-wide / general) | `specs/_shared/Research-<slug>-<date>.md` | `specs/_shared/Research-mv3-best-practices-2026-04-11.md` |
+
+### Rules
+1. **Feature research** → Always save inside the active spec folder. If `specs/<feature>/` doesn't exist yet, create it.
+2. **System-wide research** → Save to `specs/_shared/`. Create the directory if it doesn't exist.
+3. **Never** save to `plans/reports/` or `docs/`. All research belongs in `specs/`.
+4. Conclude the workflow by providing the user with the saved file path.

package/src/claude/status.cjs

@@ -402,8 +402,8 @@ async function main() {
           const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
           const planPath = session.activePlan?.trim();
           if (planPath) {
-            // Extract slug from path like "plans/260106-1554-statusline-visual"
-            const match = planPath.match(/plans\/\d+-\d+-(.+?)(?:\/|$)/);
+            // Extract slug from path like "specs/auth-login" or legacy "plans/260106-1554-feature"
+            const match = planPath.match(/(?:specs|plans)\/(?:\d+-\d+-)?(.+?)(?:\/|$)/);
             activePlan = match ? match[1] : planPath.split('/').pop();
           }
         }