@manhnv319/codexkit 0.1.0

package/.agents/skills/docs-seeker/scripts/detect-topic.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Topic Detection Script
+ * Analyzes user queries to extract library name and topic keywords
+ * Returns null for general queries, topic info for specific queries
+ */
+
+const { loadEnv } = require('./utils/env-loader');
+
+// Load environment
+const env = loadEnv();
+const DEBUG = env.DEBUG === 'true';
+
+/**
+ * Topic-specific query patterns
+ */
+const TOPIC_PATTERNS = [
+  // "How do I use X in Y?"
+  /how (?:do i|to|can i) (?:use|implement|add|setup|configure) (?:the )?(.+?) (?:in|with|for) (.+)/i,
+
+  // "Y X strategies/patterns" - e.g., "Next.js caching strategies"
+  /(.+?) (.+?) (?:strategies|patterns|techniques|methods|approaches)/i,
+
+  // "X Y documentation" or "Y X docs"
+  /(.+?) (.+?) (?:documentation|docs|guide|tutorial)/i,
+
+  // "Using X with Y"
+  /using (.+?) (?:with|in|for) (.+)/i,
+
+  // "Y X guide/implementation/setup"
+  /(.+?) (.+?) (?:guide|implementation|setup|configuration)/i,
+
+  // "Implement X in Y"
+  /implement(?:ing)? (.+?) (?:in|with|for|using) (.+)/i,
+];
+
+/**
+ * General library query patterns (non-topic specific)
+ */
+const GENERAL_PATTERNS = [
+  /(?:documentation|docs) for (.+)/i,
+  /(.+?) (?:getting started|quick ?start|introduction)/i,
+  /(?:how to use|learn) (.+)/i,
+  /(.+?) (?:api reference|overview|basics)/i,
+];
+
+/**
+ * Normalize topic keyword
+ * @param {string} topic - Raw topic string
+ * @returns {string} Normalized topic keyword
+ */
+function normalizeTopic(topic) {
+  return topic
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')  // Remove special chars
+    .replace(/\s+/g, '-')          // Replace spaces with hyphens
+    .split('-')[0]                 // Take first word for multi-word topics
+    .slice(0, 20);                 // Limit length
+}
+
+/**
+ * Normalize library name
+ * @param {string} library - Raw library string
+ * @returns {string} Normalized library name
+ */
+function normalizeLibrary(library) {
+  return library
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s\-\/\.]/g, '')
+    .replace(/\s+/g, '-');
+}
+
+/**
+ * Detect if query is topic-specific or general
+ * @param {string} query - User query
+ * @returns {Object|null} Topic info or null for general query
+ */
+function detectTopic(query) {
+  if (!query || typeof query !== 'string') {
+    return null;
+  }
+
+  const trimmedQuery = query.trim();
+
+  // Check general patterns first
+  for (const pattern of GENERAL_PATTERNS) {
+    const match = trimmedQuery.match(pattern);
+    if (match) {
+      if (DEBUG) console.error('[DEBUG] Matched general pattern, no topic');
+      return null;
+    }
+  }
+
+  // Check topic-specific patterns
+  for (let i = 0; i < TOPIC_PATTERNS.length; i++) {
+    const pattern = TOPIC_PATTERNS[i];
+    const match = trimmedQuery.match(pattern);
+    if (match) {
+      const [, term1, term2] = match;
+
+      // Determine which is library and which is topic based on pattern
+      let topic, library;
+
+      // Pattern 0: "How do I use X in Y?" -> X is topic, Y is library
+      // Pattern 1: "Y X strategies" -> X is topic, Y is library
+      // Pattern 2-5: X is topic, Y is library in most cases
+
+      // For pattern 1 (strategies/patterns), term1 is library, term2 is topic
+      if (i === 1) {
+        topic = normalizeTopic(term2);
+        library = normalizeLibrary(term1);
+      } else {
+        // For other patterns, term1 is topic, term2 is library
+        topic = normalizeTopic(term1);
+        library = normalizeLibrary(term2);
+      }
+
+      if (DEBUG) {
+        console.error('[DEBUG] Matched topic pattern');
+        console.error('[DEBUG] Topic:', topic);
+        console.error('[DEBUG] Library:', library);
+      }
+
+      return {
+        query: trimmedQuery,
+        topic,
+        library,
+        isTopicSpecific: true,
+      };
+    }
+  }
+
+  if (DEBUG) console.error('[DEBUG] No pattern matched, treating as general');
+  return null;
+}
+
+/**
+ * CLI entry point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node detect-topic.js "<user query>"');
+    process.exit(1);
+  }
+
+  const query = args.join(' ');
+  const result = detectTopic(query);
+
+  if (result) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } else {
+    console.log(JSON.stringify({ isTopicSpecific: false }, null, 2));
+    process.exit(0);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  detectTopic,
+  normalizeTopic,
+  normalizeLibrary,
+};

package/.agents/skills/docs-seeker/scripts/fetch-docs.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Fetcher Script
+ * Fetches documentation from context7.com with topic support and fallback chain
+ */
+
+const https = require('https');
+const { loadEnv } = require('./utils/env-loader');
+const { detectTopic } = require('./detect-topic');
+
+// Load environment
+const env = loadEnv();
+const DEBUG = env.DEBUG === 'true';
+const API_KEY = env.CONTEXT7_API_KEY;
+
+/**
+ * Make HTTPS GET request
+ * @param {string} url - URL to fetch
+ * @returns {Promise<string>} Response body
+ */
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      headers: API_KEY ? { 'Authorization': `Bearer ${API_KEY}` } : {},
+    };
+
+    https.get(url, options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          resolve(data);
+        } else if (res.statusCode === 404) {
+          resolve(null);
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Construct context7.com URL
+ * @param {string} library - Library name (e.g., "next.js", "shadcn/ui")
+ * @param {string} topic - Optional topic keyword
+ * @returns {string} context7.com URL
+ */
+function buildContext7Url(library, topic = null) {
+  // Determine if GitHub repo or website
+  let basePath;
+
+  if (library.includes('/')) {
+    // GitHub repo format: org/repo
+    const [org, repo] = library.split('/');
+    basePath = `${org}/${repo}`;
+  } else {
+    // Try common patterns
+    const normalized = library.toLowerCase().replace(/[^a-z0-9-]/g, '');
+    basePath = `websites/${normalized}`;
+  }
+
+  const baseUrl = `https://context7.com/${basePath}/llms.txt`;
+
+  if (topic) {
+    return `${baseUrl}?topic=${encodeURIComponent(topic)}`;
+  }
+
+  return baseUrl;
+}
+
+/**
+ * Try multiple URL variations for a library
+ * @param {string} library - Library name
+ * @param {string} topic - Optional topic
+ * @returns {Promise<Array>} Array of URLs to try
+ */
+async function getUrlVariations(library, topic = null) {
+  const urls = [];
+
+  // Known repo mappings
+  const knownRepos = {
+    'next.js': 'vercel/next.js',
+    'nextjs': 'vercel/next.js',
+    'remix': 'remix-run/remix',
+    'astro': 'withastro/astro',
+    'shadcn': 'shadcn-ui/ui',
+    'shadcn/ui': 'shadcn-ui/ui',
+    'better-auth': 'better-auth/better-auth',
+  };
+
+  const normalized = library.toLowerCase();
+  const repo = knownRepos[normalized] || library;
+
+  // Primary: Try with topic if available
+  if (topic) {
+    urls.push(buildContext7Url(repo, topic));
+  }
+
+  // Fallback: Try without topic
+  urls.push(buildContext7Url(repo));
+
+  return urls;
+}
+
+/**
+ * Fetch documentation from context7.com
+ * @param {string} query - User query
+ * @returns {Promise<Object>} Documentation result
+ */
+async function fetchDocs(query) {
+  const topicInfo = detectTopic(query);
+
+  if (DEBUG) {
+    console.error('[DEBUG] Topic detection result:', topicInfo);
+  }
+
+  let urls = [];
+
+  if (topicInfo && topicInfo.isTopicSpecific) {
+    // Topic-specific search
+    urls = await getUrlVariations(topicInfo.library, topicInfo.topic);
+
+    if (DEBUG) {
+      console.error('[DEBUG] Topic-specific URLs:', urls);
+    }
+  } else {
+    // Extract library from general query
+    const libraryMatch = query.match(/(?:documentation|docs|guide) (?:for )?(.+)/i);
+    if (libraryMatch) {
+      const library = libraryMatch[1].trim();
+      urls = await getUrlVariations(library);
+
+      if (DEBUG) {
+        console.error('[DEBUG] General library URLs:', urls);
+      }
+    }
+  }
+
+  // Try each URL
+  for (const url of urls) {
+    if (DEBUG) {
+      console.error(`[DEBUG] Trying URL: ${url}`);
+    }
+
+    try {
+      const content = await httpsGet(url);
+
+      if (content) {
+        return {
+          success: true,
+          source: 'context7.com',
+          url,
+          content,
+          topicSpecific: url.includes('?topic='),
+        };
+      }
+    } catch (error) {
+      if (DEBUG) {
+        console.error(`[DEBUG] Failed to fetch ${url}:`, error.message);
+      }
+    }
+  }
+
+  // No URL worked
+  return {
+    success: false,
+    source: 'context7.com',
+    error: 'Documentation not found on context7.com',
+    urls,
+    suggestion: 'Try repository analysis or web search',
+  };
+}
+
+/**
+ * CLI entry point
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node fetch-docs.js "<user query>"');
+    process.exit(1);
+  }
+
+  const query = args.join(' ');
+
+  try {
+    const result = await fetchDocs(query);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.success ? 0 : 1);
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  fetchDocs,
+  buildContext7Url,
+  getUrlVariations,
+  httpsGet,
+};

package/.agents/skills/docs-seeker/scripts/utils/env-loader.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * Environment variable loader for docs-seeker skill
+ * Respects order: process.env > skill/.env > skills/.env > .codex/.env
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse .env file content into key-value pairs
+ * @param {string} content - .env file content
+ * @returns {Object} Parsed environment variables
+ */
+function parseEnvFile(content) {
+  const env = {};
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    // Skip comments and empty lines
+    if (!line || line.trim().startsWith('#')) continue;
+
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (match) {
+      const key = match[1];
+      let value = match[2].trim();
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      env[key] = value;
+    }
+  }
+
+  return env;
+}
+
+/**
+ * Load environment variables from .env files in priority order
+ * Priority: process.env > skill/.env > skills/.env > .codex/.env
+ * @returns {Object} Merged environment variables
+ */
+function loadEnv() {
+  const skillDir = path.resolve(__dirname, '../..');
+  const skillsDir = path.resolve(skillDir, '..');
+  const claudeDir = path.resolve(skillsDir, '..');
+
+  const envPaths = [
+    path.join(claudeDir, '.env'),      // Lowest priority
+    path.join(skillsDir, '.env'),
+    path.join(skillDir, '.env'),       // Highest priority (file)
+  ];
+
+  let mergedEnv = {};
+
+  // Load .env files in order (lowest to highest priority)
+  for (const envPath of envPaths) {
+    if (fs.existsSync(envPath)) {
+      try {
+        const content = fs.readFileSync(envPath, 'utf8');
+        const parsed = parseEnvFile(content);
+        mergedEnv = { ...mergedEnv, ...parsed };
+      } catch (error) {
+        // Silently skip unreadable files
+      }
+    }
+  }
+
+  // process.env has highest priority
+  mergedEnv = { ...mergedEnv, ...process.env };
+
+  return mergedEnv;
+}
+
+/**
+ * Get environment variable with fallback
+ * @param {string} key - Environment variable key
+ * @param {string} defaultValue - Default value if not found
+ * @returns {string} Environment variable value
+ */
+function getEnv(key, defaultValue = '') {
+  const env = loadEnv();
+  return env[key] || defaultValue;
+}
+
+module.exports = {
+  loadEnv,
+  getEnv,
+  parseEnvFile,
+};

package/.agents/skills/docs-seeker/workflows/library-search.md

@@ -0,0 +1,87 @@
+# General Library Documentation Search
+
+**Use when:** User asks about entire library/framework
+
+**Speed:** ⚡⚡ Moderate (30-60s)
+**Token usage:** 🟡 Medium
+**Accuracy:** 📚 Comprehensive
+
+## Trigger Patterns
+
+- "Documentation for [LIBRARY]"
+- "[LIBRARY] getting started"
+- "How to use [LIBRARY]"
+- "[LIBRARY] API reference"
+
+## Workflow (Script-First)
+
+```bash
+# STEP 1: Execute detect-topic.js script
+node scripts/detect-topic.js "<user query>"
+# Returns: {"isTopicSpecific": false} for general queries
+
+# STEP 2: Execute fetch-docs.js script (handles URL construction)
+node scripts/fetch-docs.js "<user query>"
+# Script constructs context7.com URL automatically
+# Script handles GitHub/website URL patterns
+# Returns: llms.txt content with 5-20+ URLs
+
+# STEP 3: Execute analyze-llms-txt.js script
+cat llms.txt | node scripts/analyze-llms-txt.js -
+# Groups URLs: critical, important, supplementary
+# Recommends: agent distribution strategy
+# Returns: {totalUrls, grouped, distribution}
+
+# STEP 4: Deploy agents based on script recommendation
+# - 1-3 URLs: Single agent or direct WebFetch
+# - 4-10 URLs: Deploy 3-5 Explorer agents
+# - 11+ URLs: Deploy 7 agents or phased approach
+
+# STEP 5: Aggregate and present
+# Synthesize findings: installation, concepts, API, examples
+```
+
+## Examples
+
+**Astro framework:**
+```bash
+# Execute scripts (no manual URL construction)
+node scripts/detect-topic.js "Documentation for Astro"
+# {"isTopicSpecific": false}
+
+node scripts/fetch-docs.js "Documentation for Astro"
+# Script fetches: context7.com/withastro/astro/llms.txt
+# Returns: llms.txt with 8 URLs
+
+node scripts/analyze-llms-txt.js < llms.txt
+# {totalUrls: 8, distribution: "3-agents", grouped: {...}}
+
+# Deploy 3 Explorer agents as recommended:
+# Agent 1: Getting started, installation, setup
+# Agent 2: Core concepts, components, layouts
+# Agent 3: Configuration, API reference
+
+# Aggregate and present comprehensive report
+```
+
+## Agent Distribution
+
+**1-3 URLs:** Single agent
+**4-10 URLs:** 3-5 agents (2-3 URLs each)
+**11-20 URLs:** 7 agents (balanced)
+**21+ URLs:** Two-phase (critical first, then important)
+
+## Known Libraries
+
+- Next.js: `vercel/next.js`
+- Astro: `withastro/astro`
+- Remix: `remix-run/remix`
+- shadcn/ui: `shadcn-ui/ui`
+- Better Auth: `better-auth/better-auth`
+
+## Fallback
+
+Scripts handle fallback automatically:
+1. `fetch-docs.js` tries context7.com
+2. If 404, script suggests WebSearch for llms.txt
+3. If still unavailable: [Repository Analysis](./repo-analysis.md)

package/.agents/skills/docs-seeker/workflows/repo-analysis.md

@@ -0,0 +1,91 @@
+# Repository Analysis (No llms.txt)
+
+**Use when:** llms.txt not available on context7.com or official site
+
+**Speed:** ⚡⚡⚡ Slower (5-10min)
+**Token usage:** 🔴 High
+**Accuracy:** 🔍 Code-based
+
+## When to Use
+
+- Library not on context7.com
+- No llms.txt on official site
+- Need to analyze code structure
+- Documentation incomplete
+
+## Workflow
+
+```
+1. Find repository
+   → WebSearch: "[library] github repository"
+   → Verify: Official, active, has docs/
+
+2. Clone repository
+   → Bash: git clone [repo-url] /tmp/docs-analysis
+   → Optional: checkout specific version/tag
+
+3. Install Repomix (if needed)
+   → Bash: npm install -g repomix
+
+4. Pack repository
+   → Bash: cd /tmp/docs-analysis && repomix --output repomix-output.xml
+   → Repomix creates AI-friendly single file
+
+5. Read packed file
+   → Read: /tmp/docs-analysis/repomix-output.xml
+   → Extract: README, docs/, examples/, API files
+
+6. Analyze structure
+   → Identify: Documentation sections
+   → Extract: Installation, usage, API, examples
+   → Note: Code patterns, best practices
+
+7. Present findings
+   → Source: Repository analysis
+   → Caveat: Based on code, not official docs
+   → Include: Repository health (stars, activity)
+```
+
+## Example
+
+**Obscure library without llms.txt:**
+```bash
+# 1. Find
+WebSearch: "MyLibrary github repository"
+# Found: https://github.com/org/mylibrary
+
+# 2. Clone
+git clone https://github.com/org/mylibrary /tmp/docs-analysis
+
+# 3. Pack with Repomix
+cd /tmp/docs-analysis
+repomix --output repomix-output.xml
+
+# 4. Read
+Read: /tmp/docs-analysis/repomix-output.xml
+# Single XML file with entire codebase
+
+# 5. Extract documentation
+- README.md: Installation, overview
+- docs/: Usage guides, API reference
+- examples/: Code samples
+- src/: Implementation patterns
+
+# 6. Present
+Source: Repository analysis (no llms.txt)
+Health: 1.2K stars, active
+```
+
+## Repomix Benefits
+
+✅ Entire repo in single file
+✅ Preserves directory structure
+✅ AI-optimized format
+✅ Includes metadata
+
+## Alternative
+
+If no GitHub repo exists:
+→ Deploy multiple Researcher agents
+→ Gather: Official site, blog posts, tutorials, Stack Overflow
+→ Note: Quality varies, cross-reference sources