alp-code 0.9.0

package/skills/docs-seeker/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "docs-seeker-scripts",
+  "version": "3.0.0",
+  "description": "Documentation discovery scripts for docs-seeker skill",
+  "private": true,
+  "scripts": {
+    "test": "node scripts/tests/run-tests.js",
+    "test:detect": "node scripts/tests/test-detect-topic.js",
+    "test:fetch": "node scripts/tests/test-fetch-docs.js",
+    "test:analyze": "node scripts/tests/test-analyze-llms.js"
+  },
+  "keywords": [
+    "documentation",
+    "llms.txt",
+    "context7",
+    "docs-discovery"
+  ],
+  "author": "AnhlpKit",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

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

@@ -0,0 +1,82 @@
+# Ca khó
+
+## Tài liệu nhiều ngôn ngữ
+
+1. Xác định ngôn ngữ cần từ yêu cầu được giao.
+2. Tìm `llms.txt` theo ngôn ngữ: `llms-es.txt`, `llms-ja.txt`, `llms-vi.txt`.
+3. Không có thì dùng bản tiếng Anh.
+4. **Ghi rõ đã dùng bản ngôn ngữ nào** — bản dịch thường chậm hơn bản gốc vài phiên bản.
+
+## Tài liệu theo phiên bản
+
+**Bản mới nhất** — dùng URL gốc, không cần chỉ định gì.
+
+**Phiên bản cụ thể:**
+
+```
+WebSearch: "{thư viện} v{phiên bản} llms.txt"
+```
+
+Thử các đường: `/v2/llms.txt` · `/docs/v2/llms.txt` · `/{version}/llms.txt`
+
+Với repo: `git checkout v{phiên bản}` hoặc `tags/{phiên bản}`.
+
+**Luôn ghi phiên bản đã đọc.** Đây là chỗ sai âm thầm hay gặp nhất của cả skill: đọc tài
+liệu v3 rồi trả lời cho project đang dùng v2. Tài liệu không có phiên bản gần như vô dụng
+cho việc đánh giá của `research`.
+
+## Framework có nhiều plugin
+
+Framework lõi + 50 plugin thì đừng tài liệu hoá hết.
+
+1. Đọc **lõi trước**.
+2. Hỏi lại xem cần plugin nào.
+3. Tìm riêng đúng plugin đó.
+4. Liệt kê tên các plugin có sẵn trong báo cáo, để bên đọc biết còn gì.
+
+Đọc hết 50 plugin là phá ngân sách context của cả phiên để trả lời một câu hỏi về hai
+plugin.
+
+## Tài liệu đang viết dở
+
+**Dấu hiệu:** bản phát hành mới mà tài liệu chưa theo kịp · nhiều trang "coming soon" ·
+issue trên GitHub đang xin tài liệu.
+
+Cách làm:
+
+1. **Nói ngay ở đầu báo cáo** rằng tài liệu chưa đầy đủ.
+2. Kết hợp phần tài liệu có sẵn với đọc repo.
+3. Xem thư mục `tests/` và `examples/` — chúng thường chính xác hơn tài liệu vì chúng chạy.
+4. **Đánh dấu rõ phần nào là "suy ra từ code"**, không trộn lẫn với phần có tài liệu.
+5. Dẫn link issue liên quan để bên đọc theo dõi.
+
+## Nguồn mâu thuẫn nhau
+
+1. Xác định đâu là **nguồn sơ cấp chính thức**.
+2. Kiểm xem có phải khác phiên bản không — phần lớn mâu thuẫn là do đó.
+3. **Trình bày cả hai**, kèm ngữ cảnh của từng bên.
+4. Khuyến nghị bản chính thức mới nhất.
+5. Giải thích vì sao có mâu thuẫn.
+
+Thứ tự ưu tiên nguồn:
+
+```
+1. Tài liệu chính thức, bản mới nhất
+2. Tài liệu chính thức, bản theo phiên bản
+3. README trên GitHub
+4. Tutorial cộng đồng
+5. Stack Overflow
+```
+
+**Không chọn hộ bên giao việc khi mâu thuẫn là thật** (hai bên cùng đúng trong hai ngữ cảnh khác
+nhau). Nêu cả hai, chỉ ra ngữ cảnh nào hợp với project. Đây là luật "đang tranh cãi" của
+`research`.
+
+## Giới hạn tần suất API
+
+- Đặt `CONTEXT7_API_KEY` vào biến môi trường — báo principal, **không tự tạo file `.env`
+  trong `skills/`** (thư mục đóng băng, CHARTER §8).
+- Bị giới hạn thì giãn dần thời gian giữa các lần gọi, đừng gọi dồn.
+- Nhớ kết quả đã lấy **trong phiên**, đừng gọi lại cùng một URL.
+- Vẫn bị chặn → dừng, báo lại. Ngân sách 5 lượt của `research` không đủ để ngồi chờ
+  rate limit hồi.

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

@@ -0,0 +1,68 @@
+# Mẫu URL context7.com
+
+Tài liệu này để **hiểu script đang làm gì** và để gỡ khi script hỏng. Bình thường cứ chạy
+script — đoán URL bằng tay thì sai là tốn một lượt trong ngân sách 5 lượt của `research`.
+
+## Ưu tiên 1 — URL theo chủ đề
+
+```
+https://context7.com/{path}/llms.txt?topic={từ khoá}
+```
+
+Trả về **chỉ tài liệu liên quan tới chủ đề**. Nhanh hơn nhiều lần, ít token hơn nhiều.
+
+| Câu hỏi | URL |
+|---|---|
+| date picker của shadcn/ui | `context7.com/shadcn-ui/ui/llms.txt?topic=date` |
+| caching của Next.js | `context7.com/vercel/next.js/llms.txt?topic=cache` |
+| OAuth của Better Auth | `context7.com/better-auth/better-auth/llms.txt?topic=oauth` |
+| nén của FFmpeg | `context7.com/websites/ffmpeg_doxygen_8_0/llms.txt?topic=compress` |
+
+## Ưu tiên 2 — URL cả thư viện
+
+```
+https://context7.com/{org}/{repo}/llms.txt          # repo GitHub
+https://context7.com/websites/{đường-dẫn}/llms.txt  # website
+```
+
+Dùng khi câu hỏi rộng, hoặc URL theo chủ đề trả 404.
+
+## Ánh xạ tên đã biết
+
+Tên thông dụng không trùng đường dẫn repo:
+
+| Người ta gọi | Đường dẫn thật |
+|---|---|
+| `next.js`, `nextjs` | `vercel/next.js` |
+| `astro` | `withastro/astro` |
+| `remix` | `remix-run/remix` |
+| `shadcn`, `shadcn/ui` | `shadcn-ui/ui` |
+| `better-auth` | `better-auth/better-auth` |
+
+## Chuẩn hoá từ khoá chủ đề
+
+- Viết thường.
+- Bỏ ký tự đặc biệt.
+- Chủ đề nhiều từ → lấy từ đầu.
+- Tối đa 20 ký tự.
+
+| Câu hỏi có | Từ khoá |
+|---|---|
+| "date picker" | `date` |
+| "OAuth" | `oauth` |
+| "Server-Side" | `server` |
+| "caching strategies" | `caching` |
+
+## Dự phòng — site chính thức
+
+**Chỉ dùng khi context7.com không truy cập được:**
+
+```
+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
+```
+
+Dùng đường dự phòng thì **ghi rõ trong báo cáo** — nguồn khác nhau có thể ở phiên bản khác
+nhau, và `research` yêu cầu ghi phiên bản kèm ngày cho mọi nguồn.

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

@@ -0,0 +1,72 @@
+# Lỗi và chuỗi dự phòng
+
+## Loại lỗi
+
+| Lỗi | Nghĩa thường là |
+|---|---|
+| **404** | URL theo chủ đề không có · thư viện không có trên context7 · không có `llms.txt` |
+| **Timeout** | mạng · repo lớn khi clone · API chậm |
+| **Phản hồi hỏng** | `llms.txt` sai định dạng · nội dung rỗng · URL không hợp lệ |
+
+**404 không có nghĩa là thư viện không tồn tại.** Nó chỉ nghĩa là context7 không có bản
+index cho đường dẫn đó. Kiểm lại tên repo trong `context7-patterns.md` trước khi bỏ cuộc —
+tên thông dụng thường khác đường dẫn repo (`next.js` → `vercel/next.js`).
+
+## Chuỗi dự phòng
+
+### Hỏi chủ đề cụ thể
+
+```
+1. URL theo chủ đề     context7.com/{lib}/llms.txt?topic={từ khoá}
+   ↓ 404
+2. URL cả thư viện     context7.com/{lib}/llms.txt
+   ↓ 404
+3. WebSearch           "{lib} llms.txt site:{domain chính thức}"
+   ↓ không có
+4. Đọc thẳng repo      workflows/repo-analysis.md
+```
+
+### Hỏi cả thư viện
+
+```
+1. context7.com/{lib}/llms.txt
+   ↓ 404
+2. WebSearch "{lib} llms.txt"
+   ↓ không có
+3. Đọc thẳng repo
+   ↓ không có repo
+4. Nguồn thứ cấp — và PHẢI ghi rõ là thứ cấp
+```
+
+Bước 4 trong bản gốc là "chia cho nhiều Researcher agent" — không áp dụng khi loadout
+không cho giao việc: tự gom nguồn thứ cấp, đối chiếu hai nguồn độc lập, và nói rõ trong
+báo cáo rằng không có nguồn sơ cấp.
+
+## Timeout
+
+| Thao tác | Giới hạn |
+|---|---|
+| `WebFetch` | 60s |
+| clone repo | 5 phút |
+| `repomix` | 10 phút |
+
+**Hỏng thì bỏ, đừng thử lại cách vừa hỏng.** Chuyển sang bước dự phòng kế tiếp. Thử lại
+cùng một URL 404 ba lần chỉ tốn ngân sách — `research` chỉ có 5 lượt.
+
+## Kết quả rỗng
+
+`llms.txt` trả về 0 URL:
+
+1. **Ghi vào báo cáo** — rỗng là thông tin, không phải "không có gì để nói".
+2. Thử đọc thẳng repo.
+3. Kiểm site chính thức bằng tay.
+
+Đừng để kết quả rỗng biến thành im lặng. Bên giao việc không phân biệt được "đã tìm và không có" với
+"quên tìm" nếu bạn không nói.
+
+## Script hỏng
+
+Script trong `scripts/` lỗi thì **sửa rồi chạy lại cho tới khi được** — đó là luật của repo.
+Đừng bỏ script rồi tự dựng URL bằng tay: script có sẵn chuỗi fallback, làm tay là mất nó.
+
+Sửa không được thì báo lại, kèm lỗi nguyên văn.

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