cokit-cli 1.0.1 → 1.0.2

package/skills/ck-docs-seeker/references/advanced.md

@@ -0,0 +1,79 @@
+# Advanced Scenarios & Edge Cases
+
+## Multi-Language Documentation
+
+**Challenge:** Docs in multiple languages
+
+**Approach:**
+1. Identify target language from user
+2. Search for language-specific llms.txt
+   - `llms-es.txt`, `llms-ja.txt`
+3. Fallback to English if not found
+4. Note language limitations in report
+
+## Version-Specific Documentation
+
+**Latest (default):**
+- Use base llms.txt URL
+- No version specifier needed
+
+**Specific version:**
+```
+WebSearch: "[library] v[version] llms.txt"
+Check paths:
+- /v2/llms.txt
+- /docs/v2/llms.txt
+- /{version}/llms.txt
+
+For repos:
+git checkout v[version] or tags/[version]
+```
+
+## Framework with Plugins
+
+**Challenge:** Core framework + 50 plugins
+
+**Strategy:**
+1. Focus on core framework first
+2. Ask user which plugins needed
+3. Launch targeted search for specific plugins
+4. Note available plugins in report
+5. Don't document everything upfront
+
+## Documentation Under Construction
+
+**Signs:**
+- New release with incomplete docs
+- Many "Coming soon" pages
+- GitHub issues requesting docs
+
+**Approach:**
+1. Note status upfront in report
+2. Combine available docs + repo analysis
+3. Check tests/ and examples/ directories
+4. Clearly mark "inferred from code"
+5. Link to GitHub issues for updates
+
+## Conflicting Information
+
+**When sources disagree:**
+1. Identify primary official source
+2. Note version differences
+3. Present both approaches with context
+4. Recommend official/latest
+5. Explain why conflict exists
+
+**Priority order:**
+1. Official docs (latest version)
+2. Official docs (versioned)
+3. GitHub README
+4. Community tutorials
+5. Stack Overflow
+
+## Rate Limiting
+
+**If hitting API limits:**
+- Use CONTEXT7_API_KEY from .env
+- Implement exponential backoff
+- Cache results in session
+- Batch requests where possible

package/skills/ck-docs-seeker/references/context7-patterns.md

@@ -0,0 +1,68 @@
+# context7.com URL Patterns
+
+## Topic-Specific URLs (Priority #1)
+
+**Pattern:** `https://context7.com/{path}/llms.txt?topic={keyword}`
+
+**When to use:** User asks about specific feature/component
+
+**Examples:**
+```
+shadcn/ui date picker
+→ https://context7.com/shadcn-ui/ui/llms.txt?topic=date
+
+Next.js caching
+→ https://context7.com/vercel/next.js/llms.txt?topic=cache
+
+Better Auth OAuth
+→ https://context7.com/better-auth/better-auth/llms.txt?topic=oauth
+
+FFmpeg compression
+→ https://context7.com/websites/ffmpeg_doxygen_8_0/llms.txt?topic=compress
+```
+
+**Benefits:** Returns ONLY relevant docs, 10x faster, minimal tokens
+
+## General Library URLs (Priority #2)
+
+**GitHub repos:** `https://context7.com/{org}/{repo}/llms.txt`
+
+**Websites:** `https://context7.com/websites/{normalized-path}/llms.txt`
+
+## Known Repository Mappings
+
+```
+next.js → vercel/next.js
+nextjs → vercel/next.js
+astro → withastro/astro
+remix → remix-run/remix
+shadcn → shadcn-ui/ui
+shadcn/ui → shadcn-ui/ui
+better-auth → better-auth/better-auth
+```
+
+## Official Site Fallbacks
+
+Use ONLY if context7.com unavailable:
+```
+Astro: https://docs.astro.build/llms.txt
+Next.js: https://nextjs.org/llms.txt
+Remix: https://remix.run/llms.txt
+SvelteKit: https://kit.svelte.dev/llms.txt
+```
+
+## Topic Keyword Normalization
+
+**Rules:**
+- Lowercase
+- Remove special chars
+- Use first word for multi-word topics
+- Max 20 chars
+
+**Examples:**
+```
+"date picker" → "date"
+"OAuth" → "oauth"
+"Server-Side" → "server"
+"caching strategies" → "caching"
+```

package/skills/ck-docs-seeker/references/errors.md

@@ -0,0 +1,68 @@
+# Error Handling & Fallback Strategies
+
+## Error Codes
+
+**404 Not Found**
+- Topic-specific URL not available
+- Library not on context7.com
+- llms.txt doesn't exist
+
+**Timeout**
+- Network issues
+- Large repository clone
+- Slow API response
+
+**Invalid Response**
+- Malformed llms.txt
+- Empty content
+- Invalid URLs
+
+## Fallback Chain
+
+### For Topic-Specific Queries
+
+```
+1. Try topic-specific URL
+   https://context7.com/{library}/llms.txt?topic={keyword}
+   ↓ 404
+2. Try general library URL
+   https://context7.com/{library}/llms.txt
+   ↓ 404
+3. WebSearch for llms.txt
+   "[library] llms.txt site:[official domain]"
+   ↓ Not found
+4. Repository analysis
+   Use Repomix on GitHub repo
+```
+
+### For General Library Queries
+
+```
+1. Try context7.com
+   https://context7.com/{library}/llms.txt
+   ↓ 404
+2. WebSearch for llms.txt
+   "[library] llms.txt"
+   ↓ Not found
+3. Repository analysis
+   Clone + Repomix
+   ↓ No repo
+4. Research agents
+   Deploy multiple Researcher agents
+```
+
+## Timeout Handling
+
+**Set limits:**
+- WebFetch: 60s
+- Repository clone: 5min
+- Repomix: 10min
+
+**Fail fast:** Don't retry failed methods
+
+## Empty Results
+
+**If llms.txt has 0 URLs:**
+→ Note in report
+→ Try repository analysis
+→ Check official website manually

package/skills/ck-docs-seeker/scripts/analyze-llms-txt.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+/**
+ * llms.txt Analyzer Script
+ * Parses llms.txt content and categorizes URLs for optimal agent distribution
+ */
+
+const { loadEnv } = require('./utils/env-loader');
+
+// Load environment
+const env = loadEnv();
+const DEBUG = env.DEBUG === 'true';
+
+/**
+ * URL priority categories
+ */
+const PRIORITY_KEYWORDS = {
+  critical: [
+    'getting-started', 'quick-start', 'quickstart', 'introduction', 'intro', 'overview',
+    'installation', 'install', 'setup', 'basics', 'core-concepts', 'fundamentals',
+  ],
+  supplementary: [
+    'advanced', 'internals', 'migration', 'migrate', 'troubleshooting', 'troubleshoot',
+    'faq', 'frequently-asked', 'changelog', 'contributing', 'contribute',
+  ],
+  important: [
+    'guide', 'tutorial', 'example', 'api-reference', 'api', 'reference',
+    'configuration', 'config', 'routing', 'route', 'data-fetching', 'authentication', 'auth',
+  ],
+};
+
+/**
+ * Categorize URL by priority
+ * @param {string} url - Documentation URL
+ * @returns {string} Priority level (critical/important/supplementary)
+ */
+function categorizeUrl(url) {
+  const urlLower = url.toLowerCase();
+
+  // Check in priority order: critical first, then supplementary, then important
+  // This ensures specific keywords (advanced, internals) are caught before generic ones
+  const priorities = ['critical', 'supplementary', 'important'];
+
+  for (const priority of priorities) {
+    const keywords = PRIORITY_KEYWORDS[priority];
+    for (const keyword of keywords) {
+      if (urlLower.includes(keyword)) {
+        return priority;
+      }
+    }
+  }
+
+  return 'important'; // Default
+}
+
+/**
+ * Parse llms.txt content to extract URLs
+ * @param {string} content - llms.txt content
+ * @returns {Array<string>} Array of URLs
+ */
+function parseUrls(content) {
+  if (!content || typeof content !== 'string') {
+    return [];
+  }
+
+  const urls = [];
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip comments and empty lines
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Extract URLs (look for http/https)
+    const urlMatch = trimmed.match(/https?:\/\/[^\s<>"]+/i);
+    if (urlMatch) {
+      urls.push(urlMatch[0]);
+    }
+  }
+
+  return urls;
+}
+
+/**
+ * Group URLs by priority
+ * @param {Array<string>} urls - Array of URLs
+ * @returns {Object} URLs grouped by priority
+ */
+function groupByPriority(urls) {
+  const groups = {
+    critical: [],
+    important: [],
+    supplementary: [],
+  };
+
+  for (const url of urls) {
+    const priority = categorizeUrl(url);
+    groups[priority].push(url);
+  }
+
+  return groups;
+}
+
+/**
+ * Suggest optimal agent distribution
+ * @param {number} urlCount - Total number of URLs
+ * @returns {Object} Agent distribution suggestion
+ */
+function suggestAgentDistribution(urlCount) {
+  if (urlCount <= 3) {
+    return {
+      agentCount: 1,
+      strategy: 'single',
+      urlsPerAgent: urlCount,
+      description: 'Single agent can handle all URLs',
+    };
+  } else if (urlCount <= 10) {
+    const agents = Math.min(Math.ceil(urlCount / 2), 5);
+    return {
+      agentCount: agents,
+      strategy: 'parallel',
+      urlsPerAgent: Math.ceil(urlCount / agents),
+      description: `Deploy ${agents} agents in parallel`,
+    };
+  } else if (urlCount <= 20) {
+    return {
+      agentCount: 7,
+      strategy: 'parallel',
+      urlsPerAgent: Math.ceil(urlCount / 7),
+      description: 'Deploy 7 agents with balanced workload',
+    };
+  } else {
+    return {
+      agentCount: 7,
+      strategy: 'phased',
+      urlsPerAgent: Math.ceil(urlCount / 7),
+      phases: 2,
+      description: 'Use two-phase approach: critical first, then important',
+    };
+  }
+}
+
+/**
+ * Analyze llms.txt content
+ * @param {string} content - llms.txt content
+ * @returns {Object} Analysis result
+ */
+function analyzeLlmsTxt(content) {
+  const urls = parseUrls(content);
+  const grouped = groupByPriority(urls);
+  const distribution = suggestAgentDistribution(urls.length);
+
+  return {
+    totalUrls: urls.length,
+    urls,
+    grouped,
+    distribution,
+    summary: {
+      critical: grouped.critical.length,
+      important: grouped.important.length,
+      supplementary: grouped.supplementary.length,
+    },
+  };
+}
+
+/**
+ * CLI entry point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node analyze-llms-txt.js <content-file-or-stdin>');
+    console.error('Or pipe content: cat llms.txt | node analyze-llms-txt.js');
+    process.exit(1);
+  }
+
+  const fs = require('fs');
+  let content;
+
+  if (args[0] === '-') {
+    // Read from stdin
+    content = fs.readFileSync(0, 'utf8');
+  } else {
+    // Read from file
+    const filePath = args[0];
+    if (!fs.existsSync(filePath)) {
+      console.error(`Error: File not found: ${filePath}`);
+      process.exit(1);
+    }
+    content = fs.readFileSync(filePath, 'utf8');
+  }
+
+  const result = analyzeLlmsTxt(content);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  analyzeLlmsTxt,
+  parseUrls,
+  groupByPriority,
+  categorizeUrl,
+  suggestAgentDistribution,
+};

package/skills/ck-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,
+};