nuxt-agent-md 0.0.1-alpha.1 → 0.2.0

package/README.md

@@ -0,0 +1,84 @@
+# nuxt-agent-md
+
+Generate `AGENTS.md` with Nuxt documentation for AI coding agents.
+
+Inspired by [Vercel's blog post](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) showing that `AGENTS.md` with a documentation index achieves 100% success rate on agent evaluations.
+
+## Usage
+
+```bash
+# Run directly with bunx
+bunx nuxt-agent-md
+
+# Or install globally
+bun add -g nuxt-agent-md
+nuxt-agent-md
+```
+
+## What it does
+
+1. Detects your Nuxt version from `package.json`
+2. Downloads the corresponding `@nuxt/docs` documentation
+3. Generates a minified index of all documentation files
+4. Creates/updates `AGENTS.md` with the index and key Nuxt patterns
+
+## Options
+
+```
+-d, --docs-dir <path>      Directory to store docs (default: .nuxt-docs)
+-o, --output <path>        Output AGENTS.md path (default: AGENTS.md)
+-v, --nuxt-version <ver>   Nuxt docs version (auto-detected from package.json)
+    --minify               Generate minified index (default: true)
+    --no-minify            Generate full index instead of minified
+    --dry-run              Show what would be done without making changes
+-h, --help                 Show this help message
+```
+
+## Examples
+
+```bash
+# Auto-detect Nuxt version from package.json
+nuxt-agent-md
+
+# Use specific Nuxt version
+nuxt-agent-md -v 4.0.0
+
+# Generate full (non-minified) index
+nuxt-agent-md --no-minify
+
+# Custom output paths
+nuxt-agent-md -d .docs -o CLAUDE.md
+
+# Preview changes without writing
+nuxt-agent-md --dry-run
+```
+
+## Output
+
+The tool generates:
+
+1. `.nuxt-docs/` - Directory containing raw markdown documentation
+2. `AGENTS.md` - File with minified index pointing to the docs
+
+The index format is pipe-delimited for minimal token usage:
+
+```
+CATEGORY|path/to/file.md|keyword1,keyword2,keyword3
+```
+
+## Why this approach?
+
+From Vercel's research:
+
+| Approach | Success Rate |
+|----------|--------------|
+| Baseline (no docs) | 53% |
+| Skills | 53% |
+| Skills with explicit instructions | 79% |
+| **AGENTS.md with docs index** | **100%** |
+
+The key insight: providing a compressed index in `AGENTS.md` that points to detailed documentation files gives agents immediate access to accurate API information without decision overhead.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// src/index.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync2, appendFileSync } from "node:fs";
+
+// src/detect.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+async function detectNuxtVersion(cwd = process.cwd()) {
+  const packageJsonPath = join(cwd, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    throw new Error("No package.json found. Run this command in a Nuxt project root.");
+  }
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+  const nuxtVersion = deps.nuxt;
+  if (!nuxtVersion) {
+    throw new Error("Nuxt is not installed in this project. Add nuxt to your dependencies.");
+  }
+  const cleanVersion = nuxtVersion.replace(/[\^~>=<]/g, "").split(" ")[0];
+  if (cleanVersion === "latest" || !cleanVersion.match(/^\d/)) {
+    return "4.0.0";
+  }
+  return cleanVersion;
+}
+function mapToDocsVersion(nuxtVersion) {
+  const major = parseInt(nuxtVersion.split(".")[0]);
+  if (major >= 4) {
+    return "4.3.0";
+  } else if (major === 3) {
+    return "3.21.0";
+  }
+  throw new Error(`Unsupported Nuxt version: ${nuxtVersion}. Only Nuxt 3.x and 4.x are supported.`);
+}
+
+// src/download.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync2, mkdirSync, rmSync, renameSync } from "node:fs";
+import { join as join2 } from "node:path";
+async function downloadDocs(version, targetDir) {
+  const tempDir = ".nuxt-docs-temp";
+  if (existsSync2(targetDir))
+    rmSync(targetDir, { recursive: true });
+  if (existsSync2(tempDir))
+    rmSync(tempDir, { recursive: true });
+  mkdirSync(tempDir, { recursive: true });
+  try {
+    const pack = spawnSync("npm", ["pack", `@nuxt/docs@${version}`, "--pack-destination", tempDir], {
+      encoding: "utf-8"
+    });
+    if (pack.status !== 0)
+      throw new Error(pack.stderr);
+    const tarball = pack.stdout.trim().split(`
+`).pop();
+    if (!tarball)
+      throw new Error("No tarball");
+    const extract = spawnSync("tar", ["-xf", join2(tempDir, tarball), "-C", tempDir], {
+      encoding: "utf-8"
+    });
+    if (extract.status !== 0)
+      throw new Error(extract.stderr);
+    renameSync(join2(tempDir, "package"), targetDir);
+  } finally {
+    if (existsSync2(tempDir))
+      rmSync(tempDir, { recursive: true });
+  }
+}
+
+// src/generate.ts
+import { readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { join as join3, relative } from "node:path";
+async function generateIndex(docsDir) {
+  const entries = [];
+  walkDir(docsDir, docsDir, entries);
+  return {
+    entries,
+    minified: generateMinifiedIndex(entries, docsDir),
+    full: generateFullIndex(entries, docsDir)
+  };
+}
+function walkDir(dir, baseDir, entries) {
+  let items;
+  try {
+    items = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const item of items) {
+    const fullPath = join3(dir, item);
+    let stat;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      if (!item.startsWith(".") && item !== "node_modules") {
+        walkDir(fullPath, baseDir, entries);
+      }
+    } else if (item.endsWith(".md") && !item.startsWith(".")) {
+      const relativePath = relative(baseDir, fullPath);
+      const content = readFileSync2(fullPath, "utf-8");
+      const pathParts = relativePath.split("/");
+      const category = pathParts[0].replace(/^\d+\./, "").toUpperCase().replace(/-/g, "_");
+      entries.push({
+        path: relativePath,
+        title: extractTitle(content),
+        keywords: extractKeywords(content, relativePath),
+        category
+      });
+    }
+  }
+}
+function extractTitle(content) {
+  const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (frontmatterMatch) {
+    const titleMatch = frontmatterMatch[1].match(/^title:\s*['"]?([^'"\n]+)['"]?/m);
+    if (titleMatch) {
+      return titleMatch[1].trim();
+    }
+  }
+  const h1Match = content.match(/^#\s+(.+)$/m);
+  return h1Match ? h1Match[1].trim() : "";
+}
+function extractKeywords(content, path) {
+  const keywords = new Set;
+  const pathParts = path.replace(/\.md$/, "").split("/");
+  for (const part of pathParts) {
+    const clean = part.replace(/^\d+\./, "").replace(/-/g, " ");
+    if (clean.length > 2) {
+      keywords.add(clean);
+    }
+  }
+  const codeMatches = content.match(/`([a-zA-Z$][a-zA-Z0-9$]*(?:\(\))?)`/g) || [];
+  for (const match of codeMatches) {
+    const clean = match.replace(/`/g, "").replace(/\(\)$/, "");
+    if (clean.length > 2 && !["true", "false", "null", "undefined", "string", "number", "boolean", "object", "array"].includes(clean.toLowerCase())) {
+      keywords.add(clean);
+    }
+  }
+  const nuxtTerms = [
+    "useFetch",
+    "useAsyncData",
+    "useState",
+    "useCookie",
+    "useRuntimeConfig",
+    "useRoute",
+    "useRouter",
+    "useHead",
+    "useSeoMeta",
+    "useNuxtApp",
+    "definePageMeta",
+    "defineNuxtConfig",
+    "defineEventHandler",
+    "defineNuxtPlugin",
+    "defineNuxtRouteMiddleware",
+    "defineNuxtModule",
+    "NuxtLink",
+    "NuxtPage",
+    "NuxtLayout",
+    "ClientOnly",
+    "navigateTo",
+    "abortNavigation",
+    "createError",
+    "$fetch",
+    "nitro",
+    "h3",
+    "server/api",
+    "server/middleware"
+  ];
+  for (const term of nuxtTerms) {
+    if (content.includes(term)) {
+      keywords.add(term);
+    }
+  }
+  return [...keywords].slice(0, 15);
+}
+function generateMinifiedIndex(entries, docsDir) {
+  const sorted = [...entries].sort((a, b) => {
+    if (a.category !== b.category)
+      return a.category.localeCompare(b.category);
+    return a.path.localeCompare(b.path);
+  });
+  const lines = [];
+  for (const entry of sorted) {
+    const keywords = entry.keywords.slice(0, 6).join(",");
+    lines.push(`${entry.category}|${docsDir}/${entry.path}|${keywords}`);
+  }
+  return lines.join(`
+`);
+}
+function generateFullIndex(entries, docsDir) {
+  const categories = new Map;
+  for (const entry of entries) {
+    if (!categories.has(entry.category)) {
+      categories.set(entry.category, []);
+    }
+    categories.get(entry.category).push(entry);
+  }
+  let output = "";
+  const sortedCategories = [...categories.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+  for (const [category, files] of sortedCategories) {
+    output += `
+### ${category.toLowerCase().replace(/_/g, " ")}
+`;
+    const sortedFiles = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    for (const file of sortedFiles) {
+      const title = file.title || file.path.split("/").pop()?.replace(/\.md$/, "") || file.path;
+      output += `- [${title}](${docsDir}/${file.path})`;
+      if (file.keywords.length > 0) {
+        output += ` - \`${file.keywords.slice(0, 5).join("`, `")}\``;
+      }
+      output += `
+`;
+    }
+  }
+  return output;
+}
+
+// src/inject.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync } from "node:fs";
+var START_MARKER = "<!-- NUXT_DOCS_START -->";
+var END_MARKER = "<!-- NUXT_DOCS_END -->";
+async function injectAgentsMd(outputPath, index, nuxtVersion, docsDir, minify) {
+  let content = "";
+  if (existsSync3(outputPath)) {
+    content = readFileSync3(outputPath, "utf-8");
+  }
+  const nuxtSection = generateNuxtSection(index, nuxtVersion, docsDir, minify);
+  if (content.includes(START_MARKER) && content.includes(END_MARKER)) {
+    const regex = new RegExp(`${START_MARKER}[\\s\\S]*${END_MARKER}`, "m");
+    content = content.replace(regex, nuxtSection);
+  } else if (content.length > 0) {
+    content = content.trimEnd() + `
+
+` + nuxtSection;
+  } else {
+    content = generateFullAgentsMd(nuxtSection);
+  }
+  writeFileSync(outputPath, content);
+}
+function generateNuxtSection(index, nuxtVersion, docsDir, minify) {
+  const majorVersion = nuxtVersion.split(".")[0];
+  return `${START_MARKER}
+## Nuxt Documentation
+
+This project uses **Nuxt ${majorVersion}** (v${nuxtVersion}).
+
+When working with Nuxt APIs, ALWAYS read the referenced documentation files before making changes.
+
+### Quick Reference Index
+
+\`\`\`
+${minify ? index.minified : index.full}
+\`\`\`
+
+### Key Nuxt ${majorVersion} Patterns
+
+#### Data Fetching
+- Use \`useFetch\` for component-level data fetching (auto-deduped, SSR-safe)
+- Use \`useAsyncData\` when you need more control over the key/handler
+- Use \`$fetch\` in event handlers and server routes (NOT in setup for SSR)
+- Always handle \`pending\` and \`error\` states
+
+#### Server Routes
+- Files in \`server/api/\` become API endpoints
+- Use \`defineEventHandler\` for all handlers
+- Access body with \`readBody(event)\`
+- Access query with \`getQuery(event)\`
+- Access params with \`event.context.params\`
+
+#### State Management
+- Use \`useState\` for SSR-friendly reactive state
+- Use \`useCookie\` for cookie-based state
+- Use \`useRuntimeConfig\` for environment variables
+
+#### Routing & Navigation
+- Use \`definePageMeta\` for page-level config
+- Use \`navigateTo\` for programmatic navigation
+- Use \`useRoute\` and \`useRouter\` for route info
+
+#### Configuration
+- \`nuxt.config.ts\` for build-time config
+- \`runtimeConfig\` for environment variables (private/public)
+- \`app.config.ts\` for public runtime config
+
+${END_MARKER}`;
+}
+function generateFullAgentsMd(nuxtSection) {
+  return `# AGENTS.md
+
+This file provides documentation references for AI coding agents.
+
+${nuxtSection}
+`;
+}
+
+// src/index.ts
+function updateGitignore(entry) {
+  const path = ".gitignore";
+  if (!existsSync4(path)) {
+    writeFileSync2(path, entry + `
+`);
+    return true;
+  }
+  const content = readFileSync4(path, "utf-8");
+  if (content.split(`
+`).some((l) => l.trim() === entry))
+    return false;
+  appendFileSync(path, (content.endsWith(`
+`) ? "" : `
+`) + entry + `
+`);
+  return true;
+}
+async function generateAgentsMd(options = {}) {
+  const {
+    docsDir = ".nuxt-docs",
+    outputPath = "AGENTS.md",
+    nuxtVersion,
+    minify = true,
+    dryRun = false
+  } = options;
+  const version = nuxtVersion || await detectNuxtVersion();
+  const docsVersion = mapToDocsVersion(version);
+  if (dryRun) {
+    console.log(`[dry-run] Would download @nuxt/docs@${docsVersion} to ${docsDir}`);
+    console.log(`[dry-run] Would generate index and inject into ${outputPath}`);
+    return;
+  }
+  console.log(`Downloading @nuxt/docs@${docsVersion}...`);
+  await downloadDocs(docsVersion, docsDir);
+  const index = await generateIndex(docsDir);
+  console.log(`Indexed ${index.entries.length} files`);
+  await injectAgentsMd(outputPath, index, version, docsDir, minify);
+  if (updateGitignore(docsDir)) {
+    console.log(`Added ${docsDir} to .gitignore`);
+  }
+  console.log(`Generated ${outputPath}`);
+}
+
+// src/cli.ts
+var { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    "docs-dir": {
+      type: "string",
+      short: "d",
+      default: ".nuxt-docs"
+    },
+    output: {
+      type: "string",
+      short: "o",
+      default: "AGENTS.md"
+    },
+    "nuxt-version": {
+      type: "string",
+      short: "v"
+    },
+    minify: {
+      type: "boolean",
+      default: true
+    },
+    "no-minify": {
+      type: "boolean",
+      default: false
+    },
+    "dry-run": {
+      type: "boolean",
+      default: false
+    },
+    help: {
+      type: "boolean",
+      short: "h",
+      default: false
+    }
+  },
+  strict: true,
+  allowPositionals: false
+});
+if (values.help) {
+  console.log(`
+nuxt-agent-md - Generate AGENTS.md with Nuxt documentation for AI coding agents
+
+Usage:
+  nuxt-agent-md [options]
+
+Options:
+  -d, --docs-dir <path>      Directory to store docs (default: .nuxt-docs)
+  -o, --output <path>        Output AGENTS.md path (default: AGENTS.md)
+  -v, --nuxt-version <ver>   Nuxt docs version (auto-detected from package.json)
+      --minify               Generate minified index (default: true)
+      --no-minify            Generate full index instead of minified
+      --dry-run              Show what would be done without making changes
+  -h, --help                 Show this help message
+
+Examples:
+  nuxt-agent-md                           # Auto-detect Nuxt version
+  nuxt-agent-md -v 4.0.0                  # Use specific version
+  nuxt-agent-md --no-minify               # Generate full index
+  nuxt-agent-md -d .docs -o CLAUDE.md     # Custom paths
+`);
+  process.exit(0);
+}
+try {
+  await generateAgentsMd({
+    docsDir: values["docs-dir"],
+    outputPath: values.output,
+    nuxtVersion: values["nuxt-version"],
+    minify: values["no-minify"] ? false : values.minify,
+    dryRun: values["dry-run"]
+  });
+} catch (error) {
+  console.error(`Error: ${error instanceof Error ? error.message : error}`);
+  process.exit(1);
+}

package/dist/detect.d.ts

@@ -0,0 +1,2 @@
+export declare function detectNuxtVersion(cwd?: string): Promise<string>;
+export declare function mapToDocsVersion(nuxtVersion: string): string;

package/dist/download.d.ts

@@ -0,0 +1 @@
+export declare function downloadDocs(version: string, targetDir: string): Promise<void>;

package/dist/generate.d.ts

@@ -0,0 +1,2 @@
+import type { IndexResult } from './types';
+export declare function generateIndex(docsDir: string): Promise<IndexResult>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Options } from './types';
+export { detectNuxtVersion, mapToDocsVersion } from './detect';
+export { downloadDocs } from './download';
+export { generateIndex } from './generate';
+export { injectAgentsMd } from './inject';
+export type * from './types';
+export declare function generateAgentsMd(options?: Partial<Options>): Promise<void>;

package/dist/inject.d.ts

@@ -0,0 +1,2 @@
+import type { IndexResult } from './types';
+export declare function injectAgentsMd(outputPath: string, index: IndexResult, nuxtVersion: string, docsDir: string, minify: boolean): Promise<void>;

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export interface Options {
+    docsDir: string;
+    outputPath: string;
+    nuxtVersion?: string;
+    minify: boolean;
+    dryRun: boolean;
+}
+export interface DocEntry {
+    path: string;
+    title: string;
+    keywords: string[];
+    category: string;
+}
+export interface IndexResult {
+    entries: DocEntry[];
+    minified: string;
+    full: string;
+}

package/package.json

@@ -1,7 +1,41 @@
 {
   "name": "nuxt-agent-md",
-  "version": "0.0.1-alpha.1",
-  "description": "Coming soon - stay tuned!",
-  "main": "index.js",
+  "version": "0.2.0",
+  "description": "Generate AGENTS.md with Nuxt documentation for AI coding agents",
+  "type": "module",
+  "bin": {
+    "nuxt-agent-md": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/cli.ts --outdir ./dist --target node && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly",
+    "dev": "bun run ./src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "nuxt",
+    "agents",
+    "ai",
+    "documentation",
+    "cursor",
+    "copilot",
+    "claude"
+  ],
   "license": "MIT"
-}
+}

package/index.js

@@ -1 +0,0 @@
-// placeholder