nuxt-agents-md 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# nuxt-agents-md
+
+Generate a Nuxt documentation index for AI coding agents. The Nuxt equivalent of [`npx @next/codemod agents-md`](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals).
+
+Downloads the Nuxt docs matching your project's version, builds a compact pipe-delimited index, and injects it into your `CLAUDE.md` or `AGENTS.md`. Agents read local docs instead of guessing from training data.
+
+## Usage
+
+```bash
+npx nuxt-agents-md
+```
+
+This will:
+
+1. Detect your Nuxt version from `package.json`
+2. Download matching docs to `.nuxt-docs/` via git sparse-checkout
+3. Build a ~4KB compressed index of all 220+ doc files
+4. Inject it into `CLAUDE.md` between marker comments
+
+### Options
+
+```bash
+npx nuxt-agents-md --output AGENTS.md     # target a different file
+npx nuxt-agents-md --version 4.3.1        # override detected version
+npx nuxt-agents-md --docs-dir ./docs-ref  # custom docs directory
+```
+
+### Re-running
+
+The command is idempotent. Running it again updates the existing index in place (content between `<!-- NUXT-AGENTS-MD-START -->` and `<!-- NUXT-AGENTS-MD-END -->` markers).
+
+## What gets injected
+
+A single-line pipe-delimited index that tells the agent where to find each doc file:
+
+```
+[Nuxt Docs Index]|root: ./.nuxt-docs|STOP. What you remember about Nuxt is WRONG...|1.getting-started:{01.introduction.md,02.installation.md,...}|4.api/2.composables:{use-fetch.md,use-async-data.md,...}
+```
+
+The agent reads the relevant `.nuxt-docs/` file when it needs to look something up — no network requests, no stale training data.
+
+## Monorepo support
+
+Automatically detects Nuxt in pnpm, npm, and yarn workspaces.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI for nuxt-agents-md.
+ *
+ * Usage:
+ *   npx nuxt-agents-md                          # interactive (auto-detect version)
+ *   npx nuxt-agents-md --output CLAUDE.md        # specify output file
+ *   npx nuxt-agents-md --version 4.3.1           # override version
+ *   npx nuxt-agents-md --docs-dir .nuxt-docs     # override docs destination
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * CLI for nuxt-agents-md.
+ *
+ * Usage:
+ *   npx nuxt-agents-md                          # interactive (auto-detect version)
+ *   npx nuxt-agents-md --output CLAUDE.md        # specify output file
+ *   npx nuxt-agents-md --version 4.3.1           # override version
+ *   npx nuxt-agents-md --docs-dir .nuxt-docs     # override docs destination
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getNuxtVersion, pullDocs, collectDocFiles, buildDocTree, generateIndex, injectIndex, } from "./index.js";
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith("--") && i + 1 < argv.length) {
+            args[argv[i].slice(2)] = argv[i + 1];
+            i++;
+        }
+    }
+    return args;
+}
+async function main() {
+    const cwd = process.cwd();
+    const args = parseArgs(process.argv.slice(2));
+    const outputFile = args.output || "CLAUDE.md";
+    const docsDir = path.isAbsolute(args["docs-dir"] || "")
+        ? args["docs-dir"]
+        : path.join(cwd, args["docs-dir"] || ".nuxt-docs");
+    const versionOverride = args.version;
+    // Detect version
+    const detected = versionOverride ? { version: versionOverride } : getNuxtVersion(cwd);
+    console.log(`Nuxt version: ${detected.version || "unknown"}`);
+    if (!detected.version && !versionOverride) {
+        console.error(`Error: ${detected.error}`);
+        process.exit(1);
+    }
+    // Download docs
+    console.log(`Downloading Nuxt docs to ${docsDir}...`);
+    const pull = await pullDocs({ cwd, version: versionOverride, docsDir });
+    if (!pull.success) {
+        console.error(`Error downloading docs: ${pull.error}`);
+        process.exit(1);
+    }
+    console.log(`Downloaded docs for Nuxt ${pull.nuxtVersion}`);
+    // Build index
+    const files = collectDocFiles(pull.docsPath);
+    console.log(`Found ${files.length} doc files`);
+    const tree = buildDocTree(files);
+    // Use relative path in the index so it's portable across machines
+    const relativeDocsPath = path.relative(cwd, docsDir) || ".nuxt-docs";
+    const index = generateIndex({ docsPath: `./${relativeDocsPath}`, sections: tree, outputFile });
+    // Inject into target file
+    const outputPath = path.isAbsolute(outputFile) ? outputFile : path.join(cwd, outputFile);
+    let existing = "";
+    if (fs.existsSync(outputPath)) {
+        existing = fs.readFileSync(outputPath, "utf-8");
+    }
+    const result = injectIndex(existing, index);
+    fs.writeFileSync(outputPath, result, "utf-8");
+    const indexSize = Buffer.byteLength(index, "utf-8");
+    console.log(`Injected ${(indexSize / 1024).toFixed(1)}KB index into ${outputFile}`);
+    console.log("Done.");
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * nuxt-agents-md: Generate Nuxt documentation index for AI coding agents.
+ *
+ * Downloads docs from GitHub via git sparse-checkout, builds a compact
+ * index of all doc files, and injects it into CLAUDE.md or AGENTS.md.
+ */
+interface NuxtVersionResult {
+    version: string | null;
+    error?: string;
+}
+export declare function getNuxtVersion(cwd: string): NuxtVersionResult;
+interface PullResult {
+    success: boolean;
+    docsPath?: string;
+    nuxtVersion?: string;
+    error?: string;
+}
+export declare function pullDocs(options: {
+    cwd: string;
+    version?: string;
+    docsDir?: string;
+}): Promise<PullResult>;
+export declare function collectDocFiles(dir: string): {
+    relativePath: string;
+}[];
+interface DocSection {
+    name: string;
+    files: {
+        relativePath: string;
+    }[];
+    subsections: DocSection[];
+}
+export declare function buildDocTree(files: {
+    relativePath: string;
+}[]): DocSection[];
+export declare function generateIndex(data: {
+    docsPath: string;
+    sections: DocSection[];
+    outputFile?: string;
+}): string;
+export declare function injectIndex(existingContent: string, indexContent: string): string;
+export {};

package/dist/index.js

@@ -0,0 +1,258 @@
+/**
+ * nuxt-agents-md: Generate Nuxt documentation index for AI coding agents.
+ *
+ * Downloads docs from GitHub via git sparse-checkout, builds a compact
+ * index of all doc files, and injects it into CLAUDE.md or AGENTS.md.
+ */
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+export function getNuxtVersion(cwd) {
+    const packageJsonPath = path.join(cwd, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return { version: null, error: "No package.json found in the current directory" };
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+        const deps = pkg.dependencies || {};
+        const devDeps = pkg.devDependencies || {};
+        const nuxtVersion = deps.nuxt || devDeps.nuxt;
+        if (nuxtVersion) {
+            const clean = nuxtVersion.replace(/^[\^~>=<]+/, "");
+            return { version: clean };
+        }
+        // Check pnpm workspace
+        const pnpmWorkspace = path.join(cwd, "pnpm-workspace.yaml");
+        if (fs.existsSync(pnpmWorkspace)) {
+            const found = findNuxtInWorkspace(cwd, parsePnpmWorkspace(pnpmWorkspace));
+            if (found)
+                return { version: found };
+        }
+        // Check npm/yarn workspaces
+        if (pkg.workspaces) {
+            const patterns = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces.packages || [];
+            const found = findNuxtInWorkspace(cwd, patterns);
+            if (found)
+                return { version: found };
+        }
+        return { version: null, error: "Nuxt is not installed in this project." };
+    }
+    catch (err) {
+        return { version: null, error: `Failed to parse package.json: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+function parsePnpmWorkspace(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const packages = [];
+        let inPackages = false;
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed === "packages:") {
+                inPackages = true;
+                continue;
+            }
+            if (inPackages) {
+                if (trimmed && !trimmed.startsWith("-") && !trimmed.startsWith("#"))
+                    break;
+                const match = trimmed.match(/^-\s*['"]?([^'"]+)['"]?$/);
+                if (match)
+                    packages.push(match[1]);
+            }
+        }
+        return packages;
+    }
+    catch {
+        return [];
+    }
+}
+function findNuxtInWorkspace(cwd, patterns) {
+    for (const pattern of patterns) {
+        const dirs = expandGlob(cwd, pattern);
+        for (const dir of dirs) {
+            const pkgPath = path.join(dir, "package.json");
+            if (!fs.existsSync(pkgPath))
+                continue;
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                const ver = pkg.dependencies?.nuxt || pkg.devDependencies?.nuxt;
+                if (ver)
+                    return ver.replace(/^[\^~>=<]+/, "");
+            }
+            catch { /* skip */ }
+        }
+    }
+    return null;
+}
+function expandGlob(cwd, pattern) {
+    // Simple glob expansion for workspace patterns like "packages/*"
+    if (!pattern.includes("*"))
+        return [path.join(cwd, pattern)];
+    const base = pattern.replace(/\/?\*.*$/, "");
+    const baseDir = path.join(cwd, base);
+    if (!fs.existsSync(baseDir))
+        return [];
+    return fs.readdirSync(baseDir)
+        .map((name) => path.join(baseDir, name))
+        .filter((p) => fs.statSync(p).isDirectory());
+}
+// --- Major version mapping ---
+function majorVersion(version) {
+    const match = version.match(/^(\d+)/);
+    return match ? match[1] : "4";
+}
+function gitBranchForVersion(version) {
+    const major = majorVersion(version);
+    // Nuxt 4.x is on main branch, Nuxt 3.x was on 3.x branch
+    if (parseInt(major) >= 4)
+        return "main";
+    return `${major}.x`;
+}
+export async function pullDocs(options) {
+    const { cwd, version: versionOverride, docsDir } = options;
+    let nuxtVersion;
+    if (versionOverride) {
+        nuxtVersion = versionOverride;
+    }
+    else {
+        const result = getNuxtVersion(cwd);
+        if (!result.version)
+            return { success: false, error: result.error || "Could not detect Nuxt version" };
+        nuxtVersion = result.version;
+    }
+    const docsPath = docsDir ?? path.join(cwd, ".nuxt-docs");
+    try {
+        const branch = gitBranchForVersion(nuxtVersion);
+        await cloneDocsFolder(branch, docsPath);
+        return { success: true, docsPath, nuxtVersion };
+    }
+    catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function cloneDocsFolder(branch, destDir) {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "nuxt-agents-md-"));
+    try {
+        execSync(`git clone --depth 1 --filter=blob:none --sparse --branch ${branch} https://github.com/nuxt/nuxt.git .`, { cwd: tempDir, stdio: "pipe" });
+        execSync("git sparse-checkout set docs", { cwd: tempDir, stdio: "pipe" });
+        const sourceDocsDir = path.join(tempDir, "docs");
+        if (!fs.existsSync(sourceDocsDir)) {
+            throw new Error("docs folder not found in cloned repository");
+        }
+        if (fs.existsSync(destDir))
+            fs.rmSync(destDir, { recursive: true });
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.cpSync(sourceDocsDir, destDir, { recursive: true });
+    }
+    finally {
+        if (fs.existsSync(tempDir))
+            fs.rmSync(tempDir, { recursive: true });
+    }
+}
+// --- Index building ---
+export function collectDocFiles(dir) {
+    return fs.readdirSync(dir, { recursive: true })
+        .filter((f) => (f.endsWith(".md") || f.endsWith(".mdx"))
+        && !f.startsWith(".")
+        && !f.startsWith("README"))
+        .sort()
+        .map((f) => ({ relativePath: f.replace(/\\/g, "/") }));
+}
+export function buildDocTree(files) {
+    const sections = new Map();
+    for (const file of files) {
+        const parts = file.relativePath.split("/");
+        if (parts.length < 2)
+            continue;
+        const topDir = parts[0];
+        if (!sections.has(topDir)) {
+            sections.set(topDir, { name: topDir, files: [], subsections: [] });
+        }
+        const section = sections.get(topDir);
+        if (parts.length === 2) {
+            section.files.push(file);
+        }
+        else {
+            const subDir = parts[1];
+            let sub = section.subsections.find((s) => s.name === subDir);
+            if (!sub) {
+                sub = { name: subDir, files: [], subsections: [] };
+                section.subsections.push(sub);
+            }
+            if (parts.length === 3) {
+                sub.files.push(file);
+            }
+            else {
+                const subSubDir = parts[2];
+                let subSub = sub.subsections.find((s) => s.name === subSubDir);
+                if (!subSub) {
+                    subSub = { name: subSubDir, files: [], subsections: [] };
+                    sub.subsections.push(subSub);
+                }
+                subSub.files.push(file);
+            }
+        }
+    }
+    const sorted = Array.from(sections.values()).sort((a, b) => a.name.localeCompare(b.name));
+    for (const s of sorted) {
+        s.files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+        s.subsections.sort((a, b) => a.name.localeCompare(b.name));
+        for (const sub of s.subsections) {
+            sub.files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+            sub.subsections.sort((a, b) => a.name.localeCompare(b.name));
+        }
+    }
+    return sorted;
+}
+function collectAllFiles(sections) {
+    const files = [];
+    for (const s of sections) {
+        for (const f of s.files)
+            files.push(f.relativePath);
+        files.push(...collectAllFiles(s.subsections));
+    }
+    return files;
+}
+function groupByDirectory(files) {
+    const grouped = 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;
+}
+export function generateIndex(data) {
+    const { docsPath, sections, outputFile } = data;
+    const parts = [];
+    parts.push("[Nuxt Docs Index]");
+    parts.push(`root: ${docsPath}`);
+    parts.push("STOP. What you remember about Nuxt is WRONG for this project. Always search docs and read before any task.");
+    const targetFile = outputFile || "CLAUDE.md";
+    parts.push(`If docs missing, run: npx nuxt-agents-md --output ${targetFile}`);
+    const allFiles = collectAllFiles(sections);
+    const grouped = groupByDirectory(allFiles);
+    for (const [dir, files] of grouped) {
+        parts.push(`${dir}:{${files.join(",")}}`);
+    }
+    return parts.join("|");
+}
+// --- Injection ---
+const START_MARKER = "<!-- NUXT-AGENTS-MD-START -->";
+const END_MARKER = "<!-- NUXT-AGENTS-MD-END -->";
+export function injectIndex(existingContent, indexContent) {
+    const wrapped = `${START_MARKER}\n${indexContent}\n${END_MARKER}`;
+    if (existingContent.includes(START_MARKER)) {
+        const startIdx = existingContent.indexOf(START_MARKER);
+        const endIdx = existingContent.indexOf(END_MARKER) + END_MARKER.length;
+        return existingContent.slice(0, startIdx) + wrapped + existingContent.slice(endIdx);
+    }
+    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+    return existingContent + separator + wrapped + "\n";
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "nuxt-agents-md",
+  "version": "0.1.0",
+  "description": "Generate Nuxt documentation index for AI coding agents (CLAUDE.md / AGENTS.md)",
+  "type": "module",
+  "bin": {
+    "nuxt-agents-md": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts"
+  },
+  "keywords": [
+    "nuxt",
+    "agents",
+    "claude",
+    "ai",
+    "coding-agents",
+    "documentation"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}