docs-agents-md 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# docs-agents-md
+
+**Give your AI coding agent the docs it needs — in one command.**
+
+[![npm version](https://img.shields.io/npm/v/docs-agents-md.svg)](https://www.npmjs.com/package/docs-agents-md)
+[![license](https://img.shields.io/npm/l/docs-agents-md.svg)](https://github.com/a-maged/docs-agents-md/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/docs-agents-md.svg)](https://nodejs.org)
+
+```bash
+npx docs-agents-md
+```
+
+Downloads docs from any GitHub repo and injects a compact, token-optimized index into your `AGENTS.md` or `CLAUDE.md` — so your AI agent uses **real docs** instead of hallucinating.
+
+## Get Started
+
+```bash
+# Pick from 20+ presets interactively
+npx docs-agents-md
+
+# Or one-liner
+npx docs-agents-md --lib nextjs
+
+# Any GitHub repo
+npx docs-agents-md --repo vercel/next.js --name nextjs --docs-path docs
+```
+
+## Presets
+
+20 frameworks built-in. Run `npx docs-agents-md list` to see all.
+
+|                |          |          |                  |
+| -------------- | -------- | -------- | ---------------- |
+| `nextjs`       | `react`  | `vue`    | `svelte`         |
+| `angular`      | `nuxt`   | `astro`  | `tailwindcss`    |
+| `drizzle`      | `prisma` | `nestjs` | `express`        |
+| `fastify`      | `hono`   | `trpc`   | `tanstack-query` |
+| `react-router` | `vite`   | `bun`    | `zustand`        |
+
+> Missing one? Use `--repo` for any GitHub repo, or [open an issue](https://github.com/a-maged/docs-agents-md/issues).
+
+## What It Does
+
+1. **Downloads** only the docs folder via `git sparse-checkout` (fast, minimal)
+2. **Indexes** all doc files into a single-line, pipe-separated format (minimal tokens)
+3. **Injects** into your agent file with namespaced markers (multiple libs coexist)
+4. **Auto-detects** your installed version to match the right docs tag
+5. **Gitignores** the cache directory automatically
+
+## Multiple Libraries
+
+Each library gets its own marker block — they coexist and update independently:
+
+```bash
+npx docs-agents-md --lib react --output AGENTS.md
+npx docs-agents-md --lib drizzle --output AGENTS.md
+npx docs-agents-md --lib tailwindcss --output AGENTS.md
+```
+
+## Options
+
+| Flag                  | Description                           | Default         |
+| --------------------- | ------------------------------------- | --------------- |
+| `--lib <name>`        | Built-in preset                       | —               |
+| `--repo <owner/repo>` | Any GitHub repository                 | —               |
+| `--name <name>`       | Library name (required with `--repo`) | —               |
+| `--tag <tag>`         | Git tag or branch                     | `main` / preset |
+| `--docs-path <path>`  | Docs folder in repo                   | `docs`          |
+| `--output <file>`     | Target file                           | `AGENTS.md`     |
+| `--extensions <exts>` | File types to index                   | `md,mdx`        |
+
+Set `GITHUB_TOKEN` env var for higher API rate limits (5,000/hr vs 60/hr).
+
+## Inspiration
+
+Inspired by Vercel's research on [`AGENTS.md`](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals), which showed that documentation context via `AGENTS.md` significantly outperforms other approaches in agent evaluations.
+
+## Contributing
+
+1. Add an entry to [`src/lib/registry.ts`](src/lib/registry.ts)
+2. Run `npm test`
+3. Open a PR
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,1104 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import fs5 from "fs";
+import path6 from "path";
+import { createRequire } from "module";
+import { Command } from "commander";
+import prompts2 from "prompts";
+import pc2 from "picocolors";
+
+// src/lib/git.ts
+import { execFileSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+// src/lib/constants.ts
+var DOCS_BASE_DIR = ".agents-docs";
+var DEFAULT_OUTPUT = "AGENTS.md";
+var REPO_REGEX2 = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+var TAG_REGEX = /^[a-zA-Z0-9._\-\/+@]+$/;
+var NAME_REGEX = /^[a-z0-9._-]+$/;
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  const mb = kb / 1024;
+  return `${mb.toFixed(1)} MB`;
+}
+
+// src/lib/git.ts
+function validateRepo(repo) {
+  if (!REPO_REGEX2.test(repo)) {
+    throw new Error(
+      `Invalid repo format: "${repo}". Expected: owner/repo (e.g., vercel/next.js)`
+    );
+  }
+}
+function validateTag(tag) {
+  if (!TAG_REGEX.test(tag)) {
+    throw new Error(
+      `Invalid tag format: "${tag}". Expected a git tag or branch name (e.g., v15.1.0, main)`
+    );
+  }
+}
+function validateDocsPath(docsPath) {
+  if (!docsPath || docsPath.includes("..") || path.isAbsolute(docsPath)) {
+    throw new Error(
+      `Invalid docs path: "${docsPath}". Must be a non-empty relative path without "..".`
+    );
+  }
+}
+function cloneDocs(options) {
+  const { repo, tag, docsPath, destDir, timeoutMs = 6e4 } = options;
+  validateRepo(repo);
+  validateTag(tag);
+  validateDocsPath(docsPath);
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "docs-agents-md-"));
+  try {
+    try {
+      execFileSync(
+        "git",
+        [
+          "clone",
+          "--depth",
+          "1",
+          "--filter=blob:none",
+          "--sparse",
+          "--branch",
+          tag,
+          `https://github.com/${repo}.git`,
+          "."
+        ],
+        { cwd: tempDir, stdio: "pipe", timeout: timeoutMs }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (error.killed || error.signal === "SIGTERM") {
+        throw new Error(
+          `Git clone timed out after ${timeoutMs / 1e3}s. Check your network or try again.`
+        );
+      }
+      if (message.includes("not found") || message.includes("did not match")) {
+        throw new Error(
+          `Could not find tag/branch "${tag}" in repo "${repo}". Verify it exists on GitHub.`
+        );
+      }
+      if (message.includes("Could not resolve host") || message.includes("unable to access")) {
+        throw new Error(
+          `Network error: Could not reach GitHub. Check your internet connection.`
+        );
+      }
+      throw error;
+    }
+    execFileSync("git", ["sparse-checkout", "set", docsPath], {
+      cwd: tempDir,
+      stdio: "pipe",
+      timeout: 1e4
+    });
+    const sourceDocsDir = path.join(tempDir, docsPath);
+    if (!fs.existsSync(sourceDocsDir)) {
+      throw new Error(
+        `Docs folder "${docsPath}" not found in ${repo}@${tag}. Check the --docs-path value.`
+      );
+    }
+    if (fs.existsSync(destDir)) {
+      fs.rmSync(destDir, { recursive: true });
+    }
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.cpSync(sourceDocsDir, destDir, { recursive: true });
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  } finally {
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+}
+
+// src/lib/tree.ts
+import fs2 from "fs";
+import path2 from "path";
+function collectDocFiles(dir, extensions = ["md", "mdx"]) {
+  if (!fs2.existsSync(dir)) return [];
+  const extSet = new Set(extensions.map((e) => `.${e.toLowerCase()}`));
+  return fs2.readdirSync(dir, { recursive: true, encoding: "utf-8" }).map((f) => f.split(path2.sep).join("/")).filter((f) => {
+    const ext = f.slice(f.lastIndexOf(".")).toLowerCase();
+    if (!extSet.has(ext)) return false;
+    const basename = f.split("/").pop() || "";
+    if (basename.startsWith("index.")) return false;
+    return true;
+  }).sort().map((f) => ({ relativePath: f }));
+}
+function buildDocTree(files) {
+  const rootFiles = [];
+  const root = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const parts = file.relativePath.split("/");
+    if (parts.length < 2) {
+      rootFiles.push(file);
+      continue;
+    }
+    const topDir = parts[0];
+    if (!root.has(topDir)) {
+      root.set(topDir, { files: [], children: [] });
+    }
+    const entry = root.get(topDir);
+    if (parts.length === 2) {
+      entry.files.push(file);
+    } else {
+      entry.children.push({
+        relativePath: parts.slice(1).join("/")
+      });
+    }
+  }
+  const sections = [];
+  if (rootFiles.length > 0) {
+    sections.push({
+      name: ".",
+      files: rootFiles.sort(
+        (a, b) => a.relativePath.localeCompare(b.relativePath)
+      ),
+      subsections: []
+    });
+  }
+  for (const [name, entry] of root) {
+    const subsections = buildDocTree(entry.children);
+    restoreFullPaths(subsections, name);
+    sections.push({
+      name,
+      files: entry.files,
+      subsections
+    });
+  }
+  sections.sort((a, b) => {
+    if (a.name === ".") return -1;
+    if (b.name === ".") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  for (const section of sections) {
+    section.files.sort(
+      (a, b) => a.relativePath.localeCompare(b.relativePath)
+    );
+  }
+  return sections;
+}
+function restoreFullPaths(sections, parentDir) {
+  for (const section of sections) {
+    section.files = section.files.map((f) => ({
+      relativePath: `${parentDir}/${f.relativePath}`
+    }));
+    restoreFullPaths(section.subsections, `${parentDir}/${section.name}`);
+  }
+}
+
+// src/lib/index-generator.ts
+function generateIndex(sections, meta) {
+  const { name, docsPath, version, outputFile, libKey } = meta;
+  const parts = [];
+  const versionSuffix = version ? ` v${version}` : "";
+  parts.push(`[${name} Docs Index${versionSuffix}]`);
+  parts.push(`root: ${docsPath}`);
+  parts.push(
+    `IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any ${name} tasks.`
+  );
+  const target = outputFile || DEFAULT_OUTPUT;
+  let regenCmd = "npx docs-agents-md";
+  if (libKey) {
+    regenCmd += ` --lib ${libKey}`;
+  } else if (meta.repo) {
+    regenCmd += ` --repo ${meta.repo} --name ${name.toLowerCase()}`;
+    if (meta.repoDocsPath) regenCmd += ` --docs-path ${meta.repoDocsPath}`;
+  }
+  regenCmd += ` --output ${target}`;
+  parts.push(`If docs missing, run: ${regenCmd}`);
+  const allFiles = collectAllFiles(sections);
+  const grouped = groupByDirectory(allFiles);
+  for (const [dir, files] of grouped) {
+    const safeFiles = files.map(
+      (f) => f.replace(/\|/g, "%7C").replace(/,/g, "%2C").replace(/\{/g, "%7B").replace(/\}/g, "%7D")
+    );
+    parts.push(`${dir}:{${safeFiles.join(",")}}`);
+  }
+  return parts.join("|");
+}
+function collectAllFiles(sections) {
+  const files = [];
+  for (const section of sections) {
+    for (const file of section.files) {
+      files.push(file.relativePath);
+    }
+    files.push(...collectAllFiles(section.subsections));
+  }
+  return files;
+}
+function groupByDirectory(files) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const filePath of files) {
+    const lastSlash = filePath.lastIndexOf("/");
+    const dir = lastSlash === -1 ? "." : filePath.slice(0, lastSlash);
+    const fileName = lastSlash === -1 ? filePath : filePath.slice(lastSlash + 1);
+    const existing = grouped.get(dir);
+    if (existing) {
+      existing.push(fileName);
+    } else {
+      grouped.set(dir, [fileName]);
+    }
+  }
+  return grouped;
+}
+
+// src/lib/inject.ts
+function startMarker(name) {
+  return `<!-- DOCS-AGENTS-MD:${name}-START -->`;
+}
+function endMarker(name) {
+  return `<!-- DOCS-AGENTS-MD:${name}-END -->`;
+}
+function hasExistingIndex(content, name) {
+  return content.includes(startMarker(name));
+}
+function injectIndex(existingContent, indexContent, name) {
+  const start = startMarker(name);
+  const end = endMarker(name);
+  const wrappedContent = `${start}${indexContent}${end}`;
+  if (hasExistingIndex(existingContent, name)) {
+    const startIdx = existingContent.indexOf(start);
+    const endIdx = existingContent.indexOf(end) + end.length;
+    if (existingContent.indexOf(end) === -1) {
+      const cleaned = existingContent.replace(start, "");
+      return injectIndex(cleaned, indexContent, name);
+    }
+    if (endIdx <= startIdx) {
+      const cleaned = existingContent.replace(start, "").replace(endMarker(name), "");
+      return injectIndex(cleaned, indexContent, name);
+    }
+    return existingContent.slice(0, startIdx) + wrappedContent + existingContent.slice(endIdx);
+  }
+  if (existingContent === "") {
+    return wrappedContent + "\n";
+  }
+  const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+  return existingContent + separator + wrappedContent + "\n";
+}
+
+// src/lib/gitignore.ts
+import fs3 from "fs";
+import path3 from "path";
+var GITIGNORE_ENTRY = `${DOCS_BASE_DIR}/`;
+var COMMENT_HEADER = "# docs-agents-md";
+function ensureGitignoreEntry(cwd) {
+  const gitignorePath = path3.join(cwd, ".gitignore");
+  const entryRegex = new RegExp(`^\\s*\\${DOCS_BASE_DIR}(?:\\/.*)?$`);
+  let content = "";
+  if (fs3.existsSync(gitignorePath)) {
+    content = fs3.readFileSync(gitignorePath, "utf-8");
+  }
+  const hasEntry = content.split(/\r?\n/).some((line) => entryRegex.test(line));
+  if (hasEntry) {
+    return { path: gitignorePath, updated: false, alreadyPresent: true };
+  }
+  const needsNewline = content.length > 0 && !content.endsWith("\n");
+  const hasComment = content.includes(COMMENT_HEADER);
+  const header = hasComment ? "" : `${COMMENT_HEADER}
+`;
+  const newContent = content + (needsNewline ? "\n" : "") + header + `${GITIGNORE_ENTRY}
+`;
+  fs3.writeFileSync(gitignorePath, newContent, "utf-8");
+  return { path: gitignorePath, updated: true, alreadyPresent: false };
+}
+
+// src/lib/registry.ts
+var REGISTRY = {
+  nextjs: {
+    repo: "vercel/next.js",
+    docsPath: "docs",
+    defaultTag: "canary",
+    name: "Next.js",
+    packages: ["next"],
+    tagPrefix: "v"
+  },
+  react: {
+    repo: "reactjs/react.dev",
+    docsPath: "src/content",
+    defaultTag: "main",
+    name: "React",
+    packages: ["react"],
+    tagPrefix: null
+  },
+  vue: {
+    repo: "vuejs/docs",
+    docsPath: "src",
+    defaultTag: "main",
+    name: "Vue",
+    packages: ["vue"],
+    tagPrefix: null
+  },
+  svelte: {
+    repo: "sveltejs/svelte",
+    docsPath: "documentation/docs",
+    defaultTag: "main",
+    name: "Svelte",
+    packages: ["svelte"],
+    tagPrefix: "svelte@"
+  },
+  astro: {
+    repo: "withastro/docs",
+    docsPath: "src/content/docs",
+    defaultTag: "main",
+    name: "Astro",
+    packages: ["astro"],
+    tagPrefix: null
+  },
+  drizzle: {
+    repo: "drizzle-team/drizzle-orm-docs",
+    docsPath: "src/content",
+    defaultTag: "main",
+    name: "Drizzle ORM",
+    packages: ["drizzle-orm"],
+    tagPrefix: null
+  },
+  hono: {
+    repo: "honojs/hono",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "Hono",
+    packages: ["hono"],
+    tagPrefix: "v"
+  },
+  nestjs: {
+    repo: "nestjs/docs.nestjs.com",
+    docsPath: "content",
+    defaultTag: "master",
+    name: "NestJS",
+    packages: ["@nestjs/core"],
+    tagPrefix: null
+  },
+  angular: {
+    repo: "angular/angular",
+    docsPath: "adev/src/content",
+    defaultTag: "main",
+    name: "Angular",
+    packages: ["@angular/core"],
+    tagPrefix: ""
+  },
+  nuxt: {
+    repo: "nuxt/nuxt",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "Nuxt",
+    packages: ["nuxt"],
+    tagPrefix: "v"
+  },
+  "react-router": {
+    repo: "remix-run/react-router",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "React Router",
+    packages: ["react-router"],
+    tagPrefix: "react-router@"
+  },
+  express: {
+    repo: "expressjs/expressjs.com",
+    docsPath: "en",
+    defaultTag: "gh-pages",
+    name: "Express",
+    packages: ["express"],
+    tagPrefix: null
+  },
+  fastify: {
+    repo: "fastify/fastify",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "Fastify",
+    packages: ["fastify"],
+    tagPrefix: "v"
+  },
+  prisma: {
+    repo: "prisma/docs",
+    docsPath: "content",
+    defaultTag: "main",
+    name: "Prisma",
+    packages: ["prisma"],
+    tagPrefix: null
+  },
+  "tanstack-query": {
+    repo: "TanStack/query",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "TanStack Query",
+    packages: ["@tanstack/react-query"],
+    tagPrefix: "v"
+  },
+  vite: {
+    repo: "vitejs/vite",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "Vite",
+    packages: ["vite"],
+    tagPrefix: "v"
+  },
+  tailwindcss: {
+    repo: "tailwindlabs/tailwindcss.com",
+    docsPath: "src/docs",
+    defaultTag: "main",
+    name: "Tailwind CSS",
+    packages: ["tailwindcss"],
+    tagPrefix: null
+  },
+  trpc: {
+    repo: "trpc/trpc",
+    docsPath: "www/docs",
+    defaultTag: "main",
+    name: "tRPC",
+    packages: ["@trpc/server"],
+    tagPrefix: null
+  },
+  bun: {
+    repo: "oven-sh/bun",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "Bun",
+    packages: ["bun-types"],
+    tagPrefix: "bun-v"
+  },
+  zustand: {
+    repo: "pmndrs/zustand",
+    docsPath: "docs",
+    defaultTag: "main",
+    name: "Zustand",
+    packages: ["zustand"],
+    tagPrefix: "v"
+  }
+};
+function getRegistryEntry(key) {
+  return REGISTRY[key.toLowerCase()] ?? null;
+}
+function listRegistryKeys() {
+  return Object.keys(REGISTRY).sort();
+}
+
+// src/lib/docs-detector.ts
+import https from "https";
+import path4 from "path";
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".github",
+  ".git",
+  "examples",
+  "example",
+  "__tests__",
+  "test",
+  "tests",
+  "__mocks__",
+  "fixtures",
+  ".vitepress",
+  "public",
+  "images",
+  "icons",
+  "logo",
+  "snippets"
+]);
+var DOC_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".mdx"]);
+async function fetchRepoTree(repo, tag) {
+  try {
+    const commitData = await githubGet(
+      `/repos/${repo}/commits/${tag}`
+    );
+    if (!commitData?.commit?.tree?.sha) return null;
+    const treeData = await githubGet(`/repos/${repo}/git/trees/${commitData.commit.tree.sha}?recursive=1`);
+    if (!treeData?.tree) return null;
+    return treeData.tree.filter((entry) => entry.type === "blob").map((entry) => entry.path);
+  } catch {
+    return null;
+  }
+}
+function detectDocsPath(paths) {
+  const dirCounts = /* @__PURE__ */ new Map();
+  for (const filePath of paths) {
+    const ext = path4.posix.extname(filePath).toLowerCase();
+    if (!DOC_EXTENSIONS.has(ext)) continue;
+    const dir = path4.posix.dirname(filePath);
+    if (dir === ".") continue;
+    const parts = dir.split("/");
+    if (parts.some((p) => EXCLUDED_DIRS.has(p))) continue;
+    dirCounts.set(dir, (dirCounts.get(dir) || 0) + 1);
+  }
+  if (dirCounts.size === 0) return null;
+  const aggregated = /* @__PURE__ */ new Map();
+  for (const [dir, count] of dirCounts) {
+    const parts = dir.split("/");
+    for (let i = 1; i <= parts.length; i++) {
+      const ancestor = parts.slice(0, i).join("/");
+      if (EXCLUDED_DIRS.has(parts[i - 1])) continue;
+      aggregated.set(ancestor, (aggregated.get(ancestor) || 0) + count);
+    }
+  }
+  const candidates = [...aggregated.entries()].filter(([, count]) => count >= 3).map(([dir, count]) => ({
+    dir,
+    count,
+    depth: dir.split("/").length
+  }));
+  if (candidates.length === 0) return null;
+  const DOCS_LIKE_NAMES = /* @__PURE__ */ new Set([
+    "docs",
+    "doc",
+    "documentation",
+    "content",
+    "guide",
+    "guides",
+    "wiki",
+    "reference",
+    "manual",
+    "pages"
+  ]);
+  candidates.sort((a, b) => {
+    const aLeaf = a.dir.split("/").pop() || "";
+    const bLeaf = b.dir.split("/").pop() || "";
+    const aBonus = DOCS_LIKE_NAMES.has(aLeaf) ? 1 : 0;
+    const bBonus = DOCS_LIKE_NAMES.has(bLeaf) ? 1 : 0;
+    if (bBonus !== aBonus) return bBonus - aBonus;
+    if (b.count !== a.count) return b.count - a.count;
+    return a.depth - b.depth;
+  });
+  return candidates[0].dir;
+}
+function githubGet(apiPath) {
+  return new Promise((resolve) => {
+    const options = {
+      hostname: "api.github.com",
+      path: apiPath,
+      headers: {
+        "User-Agent": "docs-agents-md",
+        Accept: "application/vnd.github.v3+json",
+        ...process.env.GITHUB_TOKEN && {
+          Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
+        }
+      },
+      timeout: 15e3
+    };
+    const req = https.get(options, (res) => {
+      if (res.statusCode === 403 || res.statusCode === 429) {
+        res.resume();
+        resolve(null);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        resolve(null);
+        return;
+      }
+      let data = "";
+      res.on("data", (chunk) => {
+        data += chunk.toString();
+      });
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+// src/lib/version-detector.ts
+import fs4 from "fs";
+import path5 from "path";
+function detectVersion(packages, tagPrefix) {
+  try {
+    const cwd = process.cwd();
+    const packageJsonPath = path5.join(cwd, "package.json");
+    if (!fs4.existsSync(packageJsonPath)) {
+      return null;
+    }
+    const raw = fs4.readFileSync(packageJsonPath, "utf-8");
+    const packageJson = JSON.parse(raw);
+    const dependencies = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies,
+      ...packageJson.peerDependencies
+    };
+    for (const pkgName of packages) {
+      const specifier = dependencies[pkgName];
+      if (!specifier || typeof specifier !== "string") continue;
+      let version = specifier;
+      if (version.startsWith("npm:")) {
+        const atIdx = version.lastIndexOf("@");
+        if (atIdx > 4) {
+          version = version.slice(atIdx + 1);
+        } else {
+          continue;
+        }
+      }
+      version = version.replace(/^workspace:/, "").replace(/^[~^>=]+/, "");
+      if (!/\d/.test(version)) continue;
+      if (tagPrefix === null) {
+        return { packageName: pkgName, version, gitTag: null };
+      }
+      const gitTag = tagPrefix + version;
+      return { packageName: pkgName, version, gitTag };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+// src/lib/prompt-helpers.ts
+import prompts from "prompts";
+import pc from "picocolors";
+var ON_CANCEL = {
+  onCancel: () => {
+    process.exit(0);
+  }
+};
+async function promptForOutputFile() {
+  const outputResponse = await prompts(
+    {
+      type: "select",
+      name: "output",
+      message: "Target file",
+      choices: [
+        { title: DEFAULT_OUTPUT, value: DEFAULT_OUTPUT },
+        { title: "CLAUDE.md", value: "CLAUDE.md" },
+        { title: "Custom...", value: "__custom__" }
+      ]
+    },
+    ON_CANCEL
+  );
+  if (outputResponse.output === "__custom__") {
+    const customResponse = await prompts(
+      {
+        type: "text",
+        name: "file",
+        message: "Enter file path",
+        initial: DEFAULT_OUTPUT
+      },
+      ON_CANCEL
+    );
+    return customResponse.file;
+  }
+  return outputResponse.output;
+}
+async function confirmOrAutoAccept(opts) {
+  const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+  if (isTTY) {
+    const confirm = await prompts(
+      {
+        type: "confirm",
+        name: "ok",
+        message: opts.confirmMessage,
+        initial: true
+      },
+      ON_CANCEL
+    );
+    return confirm.ok;
+  }
+  console.log(pc.green(opts.autoMessage));
+  return true;
+}
+
+// src/cli.ts
+async function resolveOptions(flags) {
+  const extensions = flags.extensions ? flags.extensions.split(",").map((e) => e.trim()) : ["md", "mdx"];
+  const output = flags.output || DEFAULT_OUTPUT;
+  if (flags.docsPath !== void 0 && !flags.docsPath.trim()) {
+    console.error(pc2.red("Error: --docs-path cannot be empty."));
+    process.exit(1);
+  }
+  if (flags.lib && flags.repo) {
+    console.error(
+      pc2.red(
+        "Error: --lib and --repo are mutually exclusive. Use one or the other."
+      )
+    );
+    process.exit(1);
+  }
+  if (flags.lib) {
+    const ignored = [];
+    if (flags.name) ignored.push("--name");
+    if (flags.docsPath) ignored.push("--docs-path");
+    if (ignored.length > 0) {
+      console.warn(
+        pc2.yellow(
+          `Warning: ${ignored.join(", ")} ignored when using --lib (registry values used)`
+        )
+      );
+    }
+  }
+  if (flags.lib) {
+    const entry = getRegistryEntry(flags.lib);
+    if (!entry) {
+      console.error(
+        pc2.red(
+          `Unknown library: "${flags.lib}". Run "docs-agents-md list" to see available presets.`
+        )
+      );
+      process.exit(1);
+    }
+    if (flags.extensions && entry.extensions) {
+      console.warn(
+        pc2.yellow(
+          "Warning: --extensions ignored when using --lib (registry values used)"
+        )
+      );
+    }
+    let tag = flags.tag || entry.defaultTag;
+    let detectedVersion;
+    if (!flags.tag && entry.packages.length > 0 && entry.tagPrefix != null) {
+      const detected = detectVersion(entry.packages, entry.tagPrefix);
+      if (detected?.gitTag) {
+        const accepted = await confirmOrAutoAccept({
+          confirmMessage: `Detected ${entry.name} ${detected.version} \u2192 use tag ${pc2.cyan(detected.gitTag)}?`,
+          autoMessage: `Auto-detected ${entry.name} ${detected.version} \u2192 ${detected.gitTag}`
+        });
+        if (accepted) {
+          tag = detected.gitTag;
+          detectedVersion = detected.version;
+        }
+      }
+    }
+    return {
+      repo: entry.repo,
+      tag,
+      docsPath: entry.docsPath,
+      name: flags.lib.toLowerCase(),
+      displayName: entry.name,
+      output,
+      extensions: entry.extensions || extensions,
+      libKey: flags.lib.toLowerCase(),
+      detectedVersion
+    };
+  }
+  if (flags.repo) {
+    try {
+      validateRepo(flags.repo);
+    } catch (e) {
+      console.error(pc2.red(`Error: ${e.message}`));
+      process.exit(1);
+    }
+    if (!flags.name) {
+      console.error(
+        pc2.red(
+          "Error: --name is required when using --repo.\nExample: npx docs-agents-md --repo owner/repo --name mylib --tag main"
+        )
+      );
+      process.exit(1);
+    }
+    const safeName = flags.name.trim().toLowerCase();
+    if (!NAME_REGEX.test(safeName)) {
+      console.error(
+        pc2.red(
+          `Error: --name "${flags.name}" contains invalid characters. Use only letters, numbers, dots, hyphens, underscores.`
+        )
+      );
+      process.exit(1);
+    }
+    let docsPath = flags.docsPath || "";
+    const tag = flags.tag || "main";
+    if (!flags.docsPath) {
+      console.log(pc2.gray("Detecting docs folder via GitHub API..."));
+      const treePaths = await fetchRepoTree(flags.repo, tag);
+      if (treePaths) {
+        const detected = detectDocsPath(treePaths);
+        if (detected) {
+          const accepted = await confirmOrAutoAccept({
+            confirmMessage: `Detected docs at "${detected}". Use this path?`,
+            autoMessage: `Auto-detected docs path: "${detected}"`
+          });
+          docsPath = accepted ? detected : "docs";
+          if (!accepted) {
+            console.log(pc2.yellow('Using default "docs" path'));
+          }
+        } else {
+          console.log(
+            pc2.yellow(
+              'Could not auto-detect docs folder, using default "docs"'
+            )
+          );
+          docsPath = "docs";
+        }
+      } else {
+        docsPath = "docs";
+      }
+    }
+    return {
+      repo: flags.repo,
+      tag,
+      docsPath,
+      name: safeName,
+      displayName: flags.name.trim(),
+      output,
+      extensions
+    };
+  }
+  return await promptForOptions(output, extensions);
+}
+async function promptForOptions(defaultOutput, defaultExtensions) {
+  console.log(
+    pc2.cyan("\n\u{1F4DA} docs-agents-md \u2014 Documentation Index for AI Agents\n")
+  );
+  const keys = listRegistryKeys();
+  const presetChoices = keys.map((k) => ({
+    title: `${REGISTRY[k].name} (${REGISTRY[k].repo})`,
+    value: k
+  }));
+  const modeResponse = await prompts2(
+    {
+      type: "select",
+      name: "mode",
+      message: "Choose a library or enter custom repo",
+      choices: [
+        ...presetChoices,
+        { title: "Custom GitHub repo...", value: "__custom__" }
+      ]
+    },
+    ON_CANCEL
+  );
+  if (modeResponse.mode !== "__custom__") {
+    const entry = REGISTRY[modeResponse.mode];
+    let tagInitial = entry.defaultTag;
+    let detectedVersion;
+    if (entry.packages.length > 0 && entry.tagPrefix != null) {
+      const detected = detectVersion(entry.packages, entry.tagPrefix);
+      if (detected?.gitTag) {
+        tagInitial = detected.gitTag;
+        detectedVersion = detected.version;
+        console.log(pc2.green(`  Detected ${entry.name} ${detected.version}`));
+      }
+    }
+    const tagResponse = await prompts2(
+      {
+        type: "text",
+        name: "tag",
+        message: `Git tag/branch for ${entry.name}`,
+        initial: tagInitial
+      },
+      ON_CANCEL
+    );
+    if (tagResponse.tag !== tagInitial) {
+      detectedVersion = void 0;
+    }
+    const output2 = await promptForOutputFile();
+    return {
+      repo: entry.repo,
+      tag: tagResponse.tag,
+      docsPath: entry.docsPath,
+      name: modeResponse.mode,
+      displayName: entry.name,
+      output: output2,
+      extensions: entry.extensions || defaultExtensions,
+      libKey: modeResponse.mode,
+      detectedVersion
+    };
+  }
+  const customResponse = await prompts2(
+    [
+      {
+        type: "text",
+        name: "repo",
+        message: "GitHub repo (owner/repo)",
+        validate: (v) => REPO_REGEX.test(v.trim()) ? true : "Format: owner/repo"
+      },
+      {
+        type: "text",
+        name: "name",
+        message: "Library name (used for markers/directory)",
+        validate: (v) => {
+          const trimmed = v.trim().toLowerCase();
+          if (!trimmed) return "Required";
+          if (!NAME_REGEX.test(trimmed))
+            return "Use only letters, numbers, dots, hyphens, underscores";
+          return true;
+        }
+      },
+      {
+        type: "text",
+        name: "tag",
+        message: "Git tag or branch",
+        initial: "main",
+        validate: (v) => TAG_REGEX.test(v.trim()) ? true : "Invalid characters in tag"
+      },
+      {
+        type: "text",
+        name: "docsPath",
+        message: "Path to docs folder in repo",
+        initial: "docs",
+        validate: (v) => {
+          const t = v.trim();
+          if (!t) return "Required";
+          if (t.includes("..")) return "Path traversal (..) not allowed";
+          if (path6.isAbsolute(t)) return "Must be a relative path";
+          return true;
+        }
+      },
+      {
+        type: "select",
+        name: "output",
+        message: "Target file",
+        choices: [
+          { title: DEFAULT_OUTPUT, value: DEFAULT_OUTPUT },
+          { title: "CLAUDE.md", value: "CLAUDE.md" },
+          { title: "Custom...", value: "__custom__" }
+        ]
+      }
+    ],
+    ON_CANCEL
+  );
+  let output = customResponse.output;
+  if (output === "__custom__") {
+    const customOutputResponse = await prompts2(
+      {
+        type: "text",
+        name: "file",
+        message: "Enter file path",
+        initial: DEFAULT_OUTPUT
+      },
+      ON_CANCEL
+    );
+    output = customOutputResponse.file;
+  }
+  return {
+    repo: customResponse.repo.trim(),
+    tag: customResponse.tag.trim(),
+    docsPath: customResponse.docsPath.trim(),
+    name: customResponse.name.trim().toLowerCase(),
+    displayName: customResponse.name.trim(),
+    output,
+    extensions: defaultExtensions
+  };
+}
+async function runAdd(flags) {
+  const options = await resolveOptions(flags);
+  const cwd = process.cwd();
+  const docsDir = path6.join(cwd, DOCS_BASE_DIR, options.name);
+  const docsLinkPath = `./${DOCS_BASE_DIR}/${options.name}`;
+  const targetPath = path6.resolve(cwd, options.output);
+  if (!targetPath.startsWith(cwd + path6.sep)) {
+    console.error(
+      pc2.red(
+        `Error: Output path "${options.output}" resolves outside the project directory.`
+      )
+    );
+    process.exit(1);
+  }
+  let existingContent = "";
+  let sizeBefore = 0;
+  let isNewFile = true;
+  if (fs5.existsSync(targetPath)) {
+    existingContent = fs5.readFileSync(targetPath, "utf-8");
+    sizeBefore = Buffer.byteLength(existingContent, "utf-8");
+    isNewFile = false;
+  }
+  console.log(
+    `
+Downloading ${pc2.cyan(options.displayName)} docs from ${pc2.gray(options.repo)}@${pc2.cyan(options.tag)}...`
+  );
+  const result = cloneDocs({
+    repo: options.repo,
+    tag: options.tag,
+    docsPath: options.docsPath,
+    destDir: docsDir
+  });
+  if (!result.success) {
+    console.error(pc2.red(`
+\u2717 ${result.error}`));
+    process.exit(1);
+  }
+  const docFiles = collectDocFiles(docsDir, options.extensions);
+  if (docFiles.length === 0) {
+    console.warn(
+      pc2.yellow(
+        `
+\u26A0 No doc files found (extensions: ${options.extensions.join(", ")}). Try --extensions to include other file types.`
+      )
+    );
+    process.exit(1);
+  }
+  const sections = buildDocTree(docFiles);
+  const indexContent = generateIndex(sections, {
+    name: options.displayName,
+    docsPath: docsLinkPath,
+    version: options.detectedVersion || (/^v\d/.test(options.tag) ? options.tag.replace(/^v/, "") : void 0),
+    outputFile: options.output,
+    libKey: options.libKey,
+    repo: options.repo,
+    repoDocsPath: options.docsPath
+  });
+  const newContent = injectIndex(existingContent, indexContent, options.name);
+  fs5.writeFileSync(targetPath, newContent, "utf-8");
+  const sizeAfter = Buffer.byteLength(newContent, "utf-8");
+  const gitignoreResult = ensureGitignoreEntry(cwd);
+  const action = isNewFile ? "Created" : "Updated";
+  const sizeInfo = isNewFile ? formatSize(sizeAfter) : `${formatSize(sizeBefore)} \u2192 ${formatSize(sizeAfter)}`;
+  console.log(
+    `${pc2.green("\u2713")} ${action} ${pc2.bold(options.output)} (${sizeInfo})`
+  );
+  console.log(
+    `${pc2.green("\u2713")} ${docFiles.length} doc files indexed from ${pc2.gray(docsLinkPath)}`
+  );
+  if (gitignoreResult.updated) {
+    console.log(
+      `${pc2.green("\u2713")} Added ${pc2.bold(DOCS_BASE_DIR)} to .gitignore`
+    );
+  }
+  console.log("");
+}
+var program = new Command();
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+program.name("docs-agents-md").description(
+  "Download documentation from any GitHub repo and generate a compact index for AI coding agents."
+).version(pkg.version);
+program.command("add", { isDefault: true }).description("Add documentation index for a library").option("--repo <owner/repo>", "GitHub repository (e.g., vercel/next.js)").option(
+  "--tag <tag>",
+  "Git tag or branch (default: main for --repo, preset-specific for --lib)"
+).option("--docs-path <path>", "Path to docs folder in repo (default: docs)").option(
+  "--name <name>",
+  "Library name for markers/directory (required with --repo)"
+).option(
+  "--lib <name>",
+  "Use a built-in library preset (e.g., nextjs, react, angular, tailwindcss)"
+).option("--output <file>", "Target agent file (default: AGENTS.md)").option(
+  "--extensions <exts>",
+  "Comma-separated file extensions (default: md,mdx)"
+).action(async (options) => {
+  try {
+    await runAdd(options);
+  } catch (error) {
+    console.error(
+      pc2.red(
+        `Error: ${error instanceof Error ? error.message : String(error)}`
+      )
+    );
+    process.exit(1);
+  }
+});
+program.command("list").description("List all available library presets").action(() => {
+  console.log(pc2.cyan("\n\u{1F4DA} Available library presets:\n"));
+  const keys = listRegistryKeys();
+  const maxKeyLen = Math.max(...keys.map((k) => k.length));
+  for (const key of keys) {
+    const entry = REGISTRY[key];
+    const paddedKey = key.padEnd(maxKeyLen);
+    console.log(
+      `  ${pc2.bold(paddedKey)}  ${pc2.gray(entry.repo)} \u2192 ${pc2.gray(entry.docsPath)} (${entry.defaultTag})`
+    );
+  }
+  console.log(`
+  Usage: ${pc2.cyan("npx docs-agents-md --lib <name>")}
+`);
+});
+program.parse();

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "docs-agents-md",
+  "version": "0.1.0",
+  "description": "Download documentation from any GitHub repo and generate a compact index for AI coding agents",
+  "type": "module",
+  "bin": {
+    "docs-agents-md": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "ai-agents",
+    "coding-agents",
+    "documentation",
+    "docs",
+    "claude",
+    "cursor",
+    "copilot",
+    "windsurf",
+    "agents-md",
+    "claude-md",
+    "context",
+    "github",
+    "npx",
+    "cli",
+    "markdown",
+    "index",
+    "retrieval"
+  ],
+  "author": "Abdelrahman Maged",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a-maged/docs-agents-md.git"
+  },
+  "homepage": "https://github.com/a-maged/docs-agents-md#readme",
+  "bugs": {
+    "url": "https://github.com/a-maged/docs-agents-md/issues"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}