@next/codemod 16.2.0-canary.4 → 16.2.0-canary.41

package/bin/agents-md.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * CLI handler for `npx @next/codemod agents-md`.
+ * See ../lib/agents-md.ts for the core logic.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgentsMd = runAgentsMd;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const shared_1 = require("./shared");
+const agents_md_1 = require("../lib/agents-md");
+const utils_1 = require("../lib/utils");
+const DOCS_DIR_NAME = '.next-docs';
+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`;
+}
+async function runAgentsMd(options) {
+    const cwd = process.cwd();
+    // Mode logic:
+    // 1. No flags → interactive mode (prompts for version + target file)
+    // 2. --version provided → --output is REQUIRED (error if missing)
+    // 3. --output alone → auto-detect version, error if not found
+    let nextjsVersion;
+    let targetFile;
+    if (options.version) {
+        // --version provided: --output is required
+        if (!options.output) {
+            throw new shared_1.BadInput('When using --version, --output is also required.\n' +
+                'Example: npx @next/codemod agents-md --version 15.1.3 --output CLAUDE.md');
+        }
+        nextjsVersion = options.version;
+        targetFile = options.output;
+    }
+    else if (options.output) {
+        // --output alone: auto-detect version
+        const detected = (0, agents_md_1.getNextjsVersion)(cwd);
+        if (!detected.version) {
+            throw new shared_1.BadInput('Could not detect Next.js version. Use --version to specify.\n' +
+                `Example: npx @next/codemod agents-md --version 15.1.3 --output ${options.output}`);
+        }
+        nextjsVersion = detected.version;
+        targetFile = options.output;
+    }
+    else {
+        // No flags: interactive mode
+        const promptedOptions = await promptForOptions(cwd);
+        nextjsVersion = promptedOptions.nextVersion;
+        targetFile = promptedOptions.targetFile;
+    }
+    const claudeMdPath = path_1.default.join(cwd, targetFile);
+    const docsPath = path_1.default.join(cwd, DOCS_DIR_NAME);
+    const docsLinkPath = `./${DOCS_DIR_NAME}`;
+    let sizeBefore = 0;
+    let isNewFile = true;
+    let existingContent = '';
+    if (fs_1.default.existsSync(claudeMdPath)) {
+        existingContent = fs_1.default.readFileSync(claudeMdPath, 'utf-8');
+        sizeBefore = Buffer.byteLength(existingContent, 'utf-8');
+        isNewFile = false;
+    }
+    console.log(`\nDownloading Next.js ${picocolors_1.default.cyan(nextjsVersion)} documentation to ${picocolors_1.default.cyan(DOCS_DIR_NAME)}...`);
+    const pullResult = await (0, agents_md_1.pullDocs)({
+        cwd,
+        version: nextjsVersion,
+        docsDir: docsPath,
+    });
+    if (!pullResult.success) {
+        throw new shared_1.BadInput(`Failed to pull docs: ${pullResult.error}`);
+    }
+    const docFiles = (0, agents_md_1.collectDocFiles)(docsPath);
+    const sections = (0, agents_md_1.buildDocTree)(docFiles);
+    const indexContent = (0, agents_md_1.generateClaudeMdIndex)({
+        docsPath: docsLinkPath,
+        sections,
+        outputFile: targetFile,
+    });
+    const newContent = (0, agents_md_1.injectIntoClaudeMd)(existingContent, indexContent);
+    fs_1.default.writeFileSync(claudeMdPath, newContent, 'utf-8');
+    const sizeAfter = Buffer.byteLength(newContent, 'utf-8');
+    const gitignoreResult = (0, agents_md_1.ensureGitignoreEntry)(cwd);
+    const action = isNewFile ? 'Created' : 'Updated';
+    const sizeInfo = isNewFile
+        ? formatSize(sizeAfter)
+        : `${formatSize(sizeBefore)} → ${formatSize(sizeAfter)}`;
+    console.log(`${picocolors_1.default.green('✓')} ${action} ${picocolors_1.default.bold(targetFile)} (${sizeInfo})`);
+    if (gitignoreResult.updated) {
+        console.log(`${picocolors_1.default.green('✓')} Added ${picocolors_1.default.bold(DOCS_DIR_NAME)} to .gitignore`);
+    }
+    console.log('');
+}
+async function promptForOptions(cwd) {
+    // Detect Next.js version for default
+    const versionResult = (0, agents_md_1.getNextjsVersion)(cwd);
+    const detectedVersion = versionResult.version;
+    console.log(picocolors_1.default.cyan('\n@next/codemod agents-md - Next.js Documentation for AI Agents\n'));
+    if (detectedVersion) {
+        console.log(picocolors_1.default.gray(`  Detected Next.js version: ${detectedVersion}\n`));
+    }
+    const response = await (0, prompts_1.default)([
+        {
+            type: 'text',
+            name: 'nextVersion',
+            message: 'Next.js version',
+            initial: detectedVersion || '',
+            validate: (value) => value.trim() ? true : 'Please enter a Next.js version',
+        },
+        {
+            type: 'select',
+            name: 'targetFile',
+            message: 'Target markdown file',
+            choices: [
+                { title: 'CLAUDE.md', value: 'CLAUDE.md' },
+                { title: 'AGENTS.md', value: 'AGENTS.md' },
+                { title: 'Custom...', value: '__custom__' },
+            ],
+            initial: 0,
+        },
+    ], { onCancel: utils_1.onCancel });
+    // Handle cancelled prompts
+    if (response.nextVersion === undefined || response.targetFile === undefined) {
+        console.log(picocolors_1.default.yellow('\nCancelled.'));
+        process.exit(0);
+    }
+    let targetFile = response.targetFile;
+    if (targetFile === '__custom__') {
+        const customResponse = await (0, prompts_1.default)({
+            type: 'text',
+            name: 'customFile',
+            message: 'Enter custom file path',
+            initial: 'CLAUDE.md',
+            validate: (value) => value.trim() ? true : 'Please enter a file path',
+        }, { onCancel: utils_1.onCancel });
+        if (customResponse.customFile === undefined) {
+            console.log(picocolors_1.default.yellow('\nCancelled.'));
+            process.exit(0);
+        }
+        targetFile = customResponse.customFile;
+    }
+    return {
+        nextVersion: response.nextVersion,
+        targetFile,
+    };
+}
+//# sourceMappingURL=agents-md.js.map

package/bin/next-codemod.js

@@ -12,6 +12,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const upgrade_1 = require("./upgrade");
+const agents_md_1 = require("./agents-md");
 const transform_1 = require("./transform");
 const shared_1 = require("./shared");
 const packageJson = require('../package.json');
@@ -56,5 +57,24 @@ program
         process.exit(1);
     }
 });
+program
+    .command('agents-md')
+    .description('Generate Next.js documentation index for AI coding agents (Claude, Cursor, etc.).')
+    .option('--version <version>', 'Next.js version (auto-detected if not provided)')
+    .option('--output <file>', 'Target file path (e.g., CLAUDE.md, AGENTS.md)')
+    .action(async (options) => {
+    try {
+        await (0, agents_md_1.runAgentsMd)(options);
+    }
+    catch (error) {
+        if (error instanceof shared_1.BadInput) {
+            console.error(error.message);
+        }
+        else {
+            console.error(error);
+        }
+        process.exit(1);
+    }
+});
 program.parse(process.argv);
 //# sourceMappingURL=next-codemod.js.map

package/lib/__tests__/agents-md-e2e.test.js

@@ -0,0 +1,294 @@
+/* global jest */
+jest.autoMockOff()
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { runAgentsMd } = require('../../bin/agents-md')
+
+/**
+ * TRUE E2E TESTS
+ * These tests invoke the actual CLI entry point (runAgentsMd),
+ * simulating what happens when a user runs:
+ * npx @next/codemod agents-md --version 15.0.0 --output CLAUDE.md
+ */
+describe('agents-md e2e (CLI invocation)', () => {
+  let testProjectDir
+  let originalConsoleLog
+  let consoleOutput
+
+  beforeEach(() => {
+    // Create isolated test project directory
+    const tmpBase = process.env.NEXT_TEST_DIR || os.tmpdir()
+    testProjectDir = path.join(
+      tmpBase,
+      `agents-md-e2e-${Date.now()}-${(Math.random() * 1000) | 0}`
+    )
+    fs.mkdirSync(testProjectDir, { recursive: true })
+
+    // Mock console.log to capture CLI output
+    originalConsoleLog = console.log
+    consoleOutput = []
+    console.log = (...args) => {
+      consoleOutput.push(args.join(' '))
+    }
+  })
+
+  afterEach(() => {
+    // Restore console.log
+    console.log = originalConsoleLog
+
+    // Clean up test directory
+    if (testProjectDir && fs.existsSync(testProjectDir)) {
+      fs.rmSync(testProjectDir, { recursive: true, force: true })
+    }
+  })
+
+  it('creates CLAUDE.md and .next-docs directory when run with --version and --output', async () => {
+    // Create a minimal package.json (not required, but realistic)
+    const packageJson = {
+      name: 'test-project',
+      version: '1.0.0',
+      dependencies: {
+        next: '15.0.0',
+      },
+    }
+    fs.writeFileSync(
+      path.join(testProjectDir, 'package.json'),
+      JSON.stringify(packageJson, null, 2)
+    )
+
+    // Change to test directory
+    const originalCwd = process.cwd()
+    process.chdir(testProjectDir)
+
+    try {
+      // Run the actual CLI command
+      await runAgentsMd({
+        version: '15.0.0',
+        output: 'CLAUDE.md',
+      })
+
+      // Verify .next-docs directory was created and populated
+      const docsDir = path.join(testProjectDir, '.next-docs')
+      expect(fs.existsSync(docsDir)).toBe(true)
+
+      const docFiles = fs.readdirSync(docsDir, { recursive: true })
+      expect(docFiles.length).toBeGreaterThan(0)
+
+      // Should contain mdx/md files
+      const mdxFiles = docFiles.filter(
+        (f) => f.endsWith('.mdx') || f.endsWith('.md')
+      )
+      expect(mdxFiles.length).toBeGreaterThan(0)
+
+      // Verify CLAUDE.md was created
+      const claudeMdPath = path.join(testProjectDir, 'CLAUDE.md')
+      expect(fs.existsSync(claudeMdPath)).toBe(true)
+
+      const claudeMdContent = fs.readFileSync(claudeMdPath, 'utf-8')
+
+      // Verify content structure
+      expect(claudeMdContent).toContain('<!-- NEXT-AGENTS-MD-START -->')
+      expect(claudeMdContent).toContain('<!-- NEXT-AGENTS-MD-END -->')
+      expect(claudeMdContent).toContain('[Next.js Docs Index]')
+      expect(claudeMdContent).toContain('root: ./.next-docs')
+
+      // Verify paths are normalized to forward slashes (cross-platform)
+      const lines = claudeMdContent.split('|')
+      const pathLines = lines.filter((line) => line.includes(':'))
+      pathLines.forEach((line) => {
+        // Should not contain Windows backslashes in the output
+        const pathPart = line.split(':')[0]
+        if (pathPart && pathPart.includes('/')) {
+          expect(line).not.toMatch(/[^:]\\/)
+        }
+      })
+
+      // Verify .gitignore was updated
+      const gitignorePath = path.join(testProjectDir, '.gitignore')
+      if (fs.existsSync(gitignorePath)) {
+        const gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8')
+        expect(gitignoreContent).toContain('.next-docs')
+      }
+
+      // Verify console output
+      const output = consoleOutput.join('\n')
+      expect(output).toContain('Downloading Next.js')
+      expect(output).toContain('15.0.0')
+      expect(output).toContain('CLAUDE.md')
+    } finally {
+      // Restore original directory
+      process.chdir(originalCwd)
+    }
+  })
+
+  it('updates existing CLAUDE.md without losing content', async () => {
+    const originalCwd = process.cwd()
+    process.chdir(testProjectDir)
+
+    try {
+      // Create existing CLAUDE.md with custom content
+      const existingContent = `# My Project
+
+This is my project documentation.
+
+## Features
+- Feature 1
+- Feature 2
+`
+      fs.writeFileSync(
+        path.join(testProjectDir, 'CLAUDE.md'),
+        existingContent
+      )
+
+      // Run CLI
+      await runAgentsMd({
+        version: '15.0.0',
+        output: 'CLAUDE.md',
+      })
+
+      // Verify file was updated, not replaced
+      const claudeMdContent = fs.readFileSync(
+        path.join(testProjectDir, 'CLAUDE.md'),
+        'utf-8'
+      )
+
+      // Original content should still be there
+      expect(claudeMdContent).toContain('# My Project')
+      expect(claudeMdContent).toContain('This is my project documentation.')
+      expect(claudeMdContent).toContain('## Features')
+
+      // New index should be injected
+      expect(claudeMdContent).toContain('<!-- NEXT-AGENTS-MD-START -->')
+      expect(claudeMdContent).toContain('[Next.js Docs Index]')
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it('handles custom output filename', async () => {
+    const originalCwd = process.cwd()
+    process.chdir(testProjectDir)
+
+    try {
+      // Run with custom output file
+      await runAgentsMd({
+        version: '15.0.0',
+        output: 'AGENTS.md',
+      })
+
+      // Verify AGENTS.md was created (not CLAUDE.md)
+      expect(fs.existsSync(path.join(testProjectDir, 'AGENTS.md'))).toBe(true)
+      expect(fs.existsSync(path.join(testProjectDir, 'CLAUDE.md'))).toBe(false)
+
+      const agentsMdContent = fs.readFileSync(
+        path.join(testProjectDir, 'AGENTS.md'),
+        'utf-8'
+      )
+      expect(agentsMdContent).toContain('[Next.js Docs Index]')
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it('works when run from a subdirectory', async () => {
+    const originalCwd = process.cwd()
+
+    // Create a subdirectory
+    const subDir = path.join(testProjectDir, 'packages', 'app')
+    fs.mkdirSync(subDir, { recursive: true })
+
+    // Create package.json in root
+    const packageJson = {
+      dependencies: { next: '15.0.0' },
+    }
+    fs.writeFileSync(
+      path.join(testProjectDir, 'package.json'),
+      JSON.stringify(packageJson)
+    )
+
+    // Change to subdirectory
+    process.chdir(subDir)
+
+    try {
+      // Run from subdirectory - should create files in CWD (subdirectory)
+      await runAgentsMd({
+        version: '15.0.0',
+        output: 'CLAUDE.md',
+      })
+
+      // Verify files created in subdirectory
+      expect(fs.existsSync(path.join(subDir, 'CLAUDE.md'))).toBe(true)
+      expect(fs.existsSync(path.join(subDir, '.next-docs'))).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it('normalizes paths on Windows (cross-platform test)', async () => {
+    const originalCwd = process.cwd()
+    process.chdir(testProjectDir)
+
+    try {
+      await runAgentsMd({
+        version: '15.0.0',
+        output: 'CLAUDE.md',
+      })
+
+      const claudeMdContent = fs.readFileSync(
+        path.join(testProjectDir, 'CLAUDE.md'),
+        'utf-8'
+      )
+
+      // Extract the index content between markers
+      const startMarker = '<!-- NEXT-AGENTS-MD-START -->'
+      const endMarker = '<!-- NEXT-AGENTS-MD-END -->'
+      const startIdx = claudeMdContent.indexOf(startMarker) + startMarker.length
+      const endIdx = claudeMdContent.indexOf(endMarker)
+      const indexContent = claudeMdContent.slice(startIdx, endIdx)
+
+      // Parse the index (format: "dir:{file1,file2}|dir2:{file3}")
+      const sections = indexContent.split('|').filter((s) => s.includes(':'))
+
+      sections.forEach((section) => {
+        const [dirPath, filesStr] = section.split(':')
+        if (dirPath && dirPath.trim() && !dirPath.includes('root')) {
+          // Verify no Windows backslashes in directory paths
+          expect(dirPath).not.toContain('\\')
+          // Verify uses forward slashes
+          if (dirPath.includes('/')) {
+            expect(dirPath).toMatch(/^[^\\]+$/)
+          }
+        }
+      })
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it('handles version that requires git clone from GitHub', async () => {
+    const originalCwd = process.cwd()
+    process.chdir(testProjectDir)
+
+    try {
+      // Use a known stable version
+      await runAgentsMd({
+        version: '14.2.0',
+        output: 'CLAUDE.md',
+      })
+
+      // Verify docs were downloaded
+      const docsDir = path.join(testProjectDir, '.next-docs')
+      expect(fs.existsSync(docsDir)).toBe(true)
+
+      const docFiles = fs.readdirSync(docsDir, { recursive: true })
+      const mdxFiles = docFiles.filter(
+        (f) => f.endsWith('.mdx') || f.endsWith('.md')
+      )
+      expect(mdxFiles.length).toBeGreaterThan(50) // Should have many doc files
+    } finally {
+      process.chdir(originalCwd)
+    }
+  }, 30000) // Increase timeout for git clone
+})

package/lib/agents-md.js

@@ -0,0 +1,529 @@
+"use strict";
+/**
+ * agents-md: Generate Next.js 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNextjsVersion = getNextjsVersion;
+exports.pullDocs = pullDocs;
+exports.collectDocFiles = collectDocFiles;
+exports.buildDocTree = buildDocTree;
+exports.generateClaudeMdIndex = generateClaudeMdIndex;
+exports.injectIntoClaudeMd = injectIntoClaudeMd;
+exports.ensureGitignoreEntry = ensureGitignoreEntry;
+const execa_1 = __importDefault(require("execa"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+function getNextjsVersion(cwd) {
+    const packageJsonPath = path_1.default.join(cwd, 'package.json');
+    if (!fs_1.default.existsSync(packageJsonPath)) {
+        return {
+            version: null,
+            error: 'No package.json found in the current directory',
+        };
+    }
+    try {
+        const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf-8'));
+        const dependencies = packageJson.dependencies || {};
+        const devDependencies = packageJson.devDependencies || {};
+        const nextVersion = dependencies.next || devDependencies.next;
+        if (nextVersion) {
+            const cleanVersion = nextVersion.replace(/^[\^~>=<]+/, '');
+            return { version: cleanVersion };
+        }
+        // Not found at root - check for monorepo workspace
+        const workspace = detectWorkspace(cwd);
+        if (workspace.isMonorepo && workspace.packages.length > 0) {
+            const highestVersion = findNextjsInWorkspace(cwd, workspace.packages);
+            if (highestVersion) {
+                return { version: highestVersion };
+            }
+            return {
+                version: null,
+                error: `No Next.js found in ${workspace.type} workspace packages.`,
+            };
+        }
+        return {
+            version: null,
+            error: 'Next.js 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 versionToGitHubTag(version) {
+    return version.startsWith('v') ? version : `v${version}`;
+}
+async function pullDocs(options) {
+    const { cwd, version: versionOverride, docsDir } = options;
+    let nextjsVersion;
+    if (versionOverride) {
+        nextjsVersion = versionOverride;
+    }
+    else {
+        const versionResult = getNextjsVersion(cwd);
+        if (!versionResult.version) {
+            return {
+                success: false,
+                error: versionResult.error || 'Could not detect Next.js version',
+            };
+        }
+        nextjsVersion = versionResult.version;
+    }
+    const docsPath = docsDir ?? fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'next-agents-md-'));
+    const useTempDir = !docsDir;
+    try {
+        if (useTempDir && fs_1.default.existsSync(docsPath)) {
+            fs_1.default.rmSync(docsPath, { recursive: true });
+        }
+        const tag = versionToGitHubTag(nextjsVersion);
+        await cloneDocsFolder(tag, docsPath);
+        return {
+            success: true,
+            docsPath,
+            nextjsVersion,
+        };
+    }
+    catch (error) {
+        if (useTempDir && fs_1.default.existsSync(docsPath)) {
+            fs_1.default.rmSync(docsPath, { recursive: true });
+        }
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function cloneDocsFolder(tag, destDir) {
+    const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'next-agents-md-'));
+    try {
+        try {
+            await (0, execa_1.default)('git', [
+                'clone',
+                '--depth',
+                '1',
+                '--filter=blob:none',
+                '--sparse',
+                '--branch',
+                tag,
+                'https://github.com/vercel/next.js.git',
+                '.',
+            ], { cwd: tempDir });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('not found') || message.includes('did not match')) {
+                throw new Error(`Could not find documentation for Next.js ${tag}. This version may not exist on GitHub yet.`);
+            }
+            throw error;
+        }
+        await (0, execa_1.default)('git', ['sparse-checkout', 'set', 'docs'], { cwd: tempDir });
+        const sourceDocsDir = path_1.default.join(tempDir, 'docs');
+        if (!fs_1.default.existsSync(sourceDocsDir)) {
+            throw new Error('docs folder not found in cloned repository');
+        }
+        if (fs_1.default.existsSync(destDir)) {
+            fs_1.default.rmSync(destDir, { recursive: true });
+        }
+        fs_1.default.mkdirSync(destDir, { recursive: true });
+        fs_1.default.cpSync(sourceDocsDir, destDir, { recursive: true });
+    }
+    finally {
+        if (fs_1.default.existsSync(tempDir)) {
+            fs_1.default.rmSync(tempDir, { recursive: true });
+        }
+    }
+}
+function collectDocFiles(dir) {
+    return fs_1.default.readdirSync(dir, { recursive: true })
+        .filter((f) => (f.endsWith('.mdx') || f.endsWith('.md')) &&
+        !/[/\\]index\.mdx$/.test(f) &&
+        !/[/\\]index\.md$/.test(f) &&
+        !f.startsWith('index.'))
+        .sort()
+        .map((f) => ({ relativePath: f.replace(/\\/g, '/') }));
+}
+function buildDocTree(files) {
+    const sections = new Map();
+    for (const file of files) {
+        const parts = file.relativePath.split(/[/\\]/);
+        if (parts.length < 2)
+            continue;
+        const topLevelDir = parts[0];
+        if (!sections.has(topLevelDir)) {
+            sections.set(topLevelDir, {
+                name: topLevelDir,
+                files: [],
+                subsections: [],
+            });
+        }
+        const section = sections.get(topLevelDir);
+        if (parts.length === 2) {
+            section.files.push({ relativePath: file.relativePath });
+        }
+        else {
+            const subsectionDir = parts[1];
+            let subsection = section.subsections.find((s) => s.name === subsectionDir);
+            if (!subsection) {
+                subsection = { name: subsectionDir, files: [], subsections: [] };
+                section.subsections.push(subsection);
+            }
+            if (parts.length === 3) {
+                subsection.files.push({ relativePath: file.relativePath });
+            }
+            else {
+                const subSubDir = parts[2];
+                let subSubsection = subsection.subsections.find((s) => s.name === subSubDir);
+                if (!subSubsection) {
+                    subSubsection = { name: subSubDir, files: [], subsections: [] };
+                    subsection.subsections.push(subSubsection);
+                }
+                subSubsection.files.push({ relativePath: file.relativePath });
+            }
+        }
+    }
+    const sortedSections = Array.from(sections.values()).sort((a, b) => a.name.localeCompare(b.name));
+    for (const section of sortedSections) {
+        section.files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+        section.subsections.sort((a, b) => a.name.localeCompare(b.name));
+        for (const subsection of section.subsections) {
+            subsection.files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+            subsection.subsections.sort((a, b) => a.name.localeCompare(b.name));
+        }
+    }
+    return sortedSections;
+}
+function generateClaudeMdIndex(data) {
+    const { docsPath, sections, outputFile } = data;
+    const parts = [];
+    parts.push('[Next.js Docs Index]');
+    parts.push(`root: ${docsPath}`);
+    parts.push('STOP. What you remember about Next.js is WRONG for this project. Always search docs and read before any task.');
+    const targetFile = outputFile || 'CLAUDE.md';
+    parts.push(`If docs missing, run this command first: npx @next/codemod agents-md --output ${targetFile}`);
+    const allFiles = collectAllFilesFromSections(sections);
+    const grouped = groupByDirectory(allFiles);
+    for (const [dir, files] of grouped) {
+        parts.push(`${dir}:{${files.join(',')}}`);
+    }
+    return parts.join('|');
+}
+function collectAllFilesFromSections(sections) {
+    const files = [];
+    for (const section of sections) {
+        for (const file of section.files) {
+            files.push(file.relativePath);
+        }
+        files.push(...collectAllFilesFromSections(section.subsections));
+    }
+    return files;
+}
+function groupByDirectory(files) {
+    const grouped = new Map();
+    for (const filePath of files) {
+        const lastSlash = Math.max(filePath.lastIndexOf('/'), 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;
+}
+const START_MARKER = '<!-- NEXT-AGENTS-MD-START -->';
+const END_MARKER = '<!-- NEXT-AGENTS-MD-END -->';
+function hasExistingIndex(content) {
+    return content.includes(START_MARKER);
+}
+function wrapWithMarkers(content) {
+    return `${START_MARKER}${content}${END_MARKER}`;
+}
+function injectIntoClaudeMd(claudeMdContent, indexContent) {
+    const wrappedContent = wrapWithMarkers(indexContent);
+    if (hasExistingIndex(claudeMdContent)) {
+        const startIdx = claudeMdContent.indexOf(START_MARKER);
+        const endIdx = claudeMdContent.indexOf(END_MARKER) + END_MARKER.length;
+        return (claudeMdContent.slice(0, startIdx) +
+            wrappedContent +
+            claudeMdContent.slice(endIdx));
+    }
+    const separator = claudeMdContent.endsWith('\n') ? '\n' : '\n\n';
+    return claudeMdContent + separator + wrappedContent + '\n';
+}
+const GITIGNORE_ENTRY = '.next-docs/';
+function ensureGitignoreEntry(cwd) {
+    const gitignorePath = path_1.default.join(cwd, '.gitignore');
+    const entryRegex = /^\s*\.next-docs(?:\/.*)?$/;
+    let content = '';
+    if (fs_1.default.existsSync(gitignorePath)) {
+        content = fs_1.default.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 header = content.includes('# next-agents-md')
+        ? ''
+        : '# next-agents-md\n';
+    const newContent = content + (needsNewline ? '\n' : '') + header + `${GITIGNORE_ENTRY}\n`;
+    fs_1.default.writeFileSync(gitignorePath, newContent, 'utf-8');
+    return { path: gitignorePath, updated: true, alreadyPresent: false };
+}
+function detectWorkspace(cwd) {
+    const packageJsonPath = path_1.default.join(cwd, 'package.json');
+    // Check pnpm workspaces (pnpm-workspace.yaml)
+    const pnpmWorkspacePath = path_1.default.join(cwd, 'pnpm-workspace.yaml');
+    if (fs_1.default.existsSync(pnpmWorkspacePath)) {
+        const packages = parsePnpmWorkspace(pnpmWorkspacePath);
+        if (packages.length > 0) {
+            return { isMonorepo: true, type: 'pnpm', packages };
+        }
+    }
+    // Check npm/yarn workspaces (package.json workspaces field)
+    if (fs_1.default.existsSync(packageJsonPath)) {
+        const packages = parsePackageJsonWorkspaces(packageJsonPath);
+        if (packages.length > 0) {
+            return { isMonorepo: true, type: 'npm', packages };
+        }
+    }
+    // Check Lerna (lerna.json)
+    const lernaPath = path_1.default.join(cwd, 'lerna.json');
+    if (fs_1.default.existsSync(lernaPath)) {
+        const packages = parseLernaConfig(lernaPath);
+        if (packages.length > 0) {
+            return { isMonorepo: true, type: 'lerna', packages };
+        }
+    }
+    // Check Nx (nx.json)
+    const nxPath = path_1.default.join(cwd, 'nx.json');
+    if (fs_1.default.existsSync(nxPath)) {
+        const packages = parseNxWorkspace(cwd, packageJsonPath);
+        if (packages.length > 0) {
+            return { isMonorepo: true, type: 'nx', packages };
+        }
+    }
+    return { isMonorepo: false, type: null, packages: [] };
+}
+function parsePnpmWorkspace(filePath) {
+    try {
+        const content = fs_1.default.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        const packages = [];
+        let inPackages = false;
+        for (const line of lines) {
+            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 parsePackageJsonWorkspaces(filePath) {
+    try {
+        const content = fs_1.default.readFileSync(filePath, 'utf-8');
+        const pkg = JSON.parse(content);
+        if (Array.isArray(pkg.workspaces)) {
+            return pkg.workspaces;
+        }
+        if (pkg.workspaces?.packages && Array.isArray(pkg.workspaces.packages)) {
+            return pkg.workspaces.packages;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+function parseLernaConfig(filePath) {
+    try {
+        const content = fs_1.default.readFileSync(filePath, 'utf-8');
+        const config = JSON.parse(content);
+        if (Array.isArray(config.packages)) {
+            return config.packages;
+        }
+        return ['packages/*'];
+    }
+    catch {
+        return [];
+    }
+}
+function parseNxWorkspace(cwd, packageJsonPath) {
+    if (fs_1.default.existsSync(packageJsonPath)) {
+        const packages = parsePackageJsonWorkspaces(packageJsonPath);
+        if (packages.length > 0) {
+            return packages;
+        }
+    }
+    const defaultPatterns = ['apps/*', 'libs/*', 'packages/*'];
+    const existingPatterns = [];
+    for (const pattern of defaultPatterns) {
+        const basePath = path_1.default.join(cwd, pattern.replace('/*', ''));
+        if (fs_1.default.existsSync(basePath)) {
+            existingPatterns.push(pattern);
+        }
+    }
+    return existingPatterns;
+}
+function findNextjsInWorkspace(cwd, patterns) {
+    const packagePaths = expandWorkspacePatterns(cwd, patterns);
+    const versions = [];
+    for (const pkgPath of packagePaths) {
+        const packageJsonPath = path_1.default.join(pkgPath, 'package.json');
+        if (!fs_1.default.existsSync(packageJsonPath))
+            continue;
+        try {
+            const content = fs_1.default.readFileSync(packageJsonPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            const nextVersion = pkg.dependencies?.next || pkg.devDependencies?.next;
+            if (nextVersion) {
+                versions.push(nextVersion.replace(/^[\^~>=<]+/, ''));
+            }
+        }
+        catch {
+            // Skip invalid package.json
+        }
+    }
+    return findHighestVersion(versions);
+}
+function expandWorkspacePatterns(cwd, patterns) {
+    const packagePaths = [];
+    for (const pattern of patterns) {
+        if (pattern.startsWith('!'))
+            continue;
+        if (pattern.includes('*')) {
+            packagePaths.push(...expandGlobPattern(cwd, pattern));
+        }
+        else {
+            const fullPath = path_1.default.join(cwd, pattern);
+            if (fs_1.default.existsSync(fullPath)) {
+                packagePaths.push(fullPath);
+            }
+        }
+    }
+    return [...new Set(packagePaths)];
+}
+function expandGlobPattern(cwd, pattern) {
+    const parts = pattern.split('/');
+    const results = [];
+    function walk(currentPath, partIndex) {
+        if (partIndex >= parts.length) {
+            if (fs_1.default.existsSync(path_1.default.join(currentPath, 'package.json'))) {
+                results.push(currentPath);
+            }
+            return;
+        }
+        const part = parts[partIndex];
+        if (part === '*') {
+            if (!fs_1.default.existsSync(currentPath))
+                return;
+            try {
+                for (const entry of fs_1.default.readdirSync(currentPath)) {
+                    const fullPath = path_1.default.join(currentPath, entry);
+                    if (isDirectory(fullPath)) {
+                        if (partIndex === parts.length - 1) {
+                            if (fs_1.default.existsSync(path_1.default.join(fullPath, 'package.json'))) {
+                                results.push(fullPath);
+                            }
+                        }
+                        else {
+                            walk(fullPath, partIndex + 1);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Permission denied
+            }
+        }
+        else if (part === '**') {
+            walkRecursive(currentPath, results);
+        }
+        else {
+            walk(path_1.default.join(currentPath, part), partIndex + 1);
+        }
+    }
+    walk(cwd, 0);
+    return results;
+}
+function walkRecursive(dir, results) {
+    if (!fs_1.default.existsSync(dir))
+        return;
+    if (fs_1.default.existsSync(path_1.default.join(dir, 'package.json'))) {
+        results.push(dir);
+    }
+    try {
+        for (const entry of fs_1.default.readdirSync(dir)) {
+            if (entry === 'node_modules' || entry.startsWith('.'))
+                continue;
+            const fullPath = path_1.default.join(dir, entry);
+            if (isDirectory(fullPath)) {
+                walkRecursive(fullPath, results);
+            }
+        }
+    }
+    catch {
+        // Permission denied
+    }
+}
+function isDirectory(dirPath) {
+    try {
+        return fs_1.default.statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function findHighestVersion(versions) {
+    if (versions.length === 0)
+        return null;
+    if (versions.length === 1)
+        return versions[0];
+    return versions.reduce((highest, current) => {
+        return compareVersions(current, highest) > 0 ? current : highest;
+    });
+}
+function compareVersions(a, b) {
+    const parseVersion = (v) => {
+        const match = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+        if (!match)
+            return [0, 0, 0];
+        return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
+    };
+    const [aMajor, aMinor, aPatch] = parseVersion(a);
+    const [bMajor, bMinor, bPatch] = parseVersion(b);
+    if (aMajor !== bMajor)
+        return aMajor - bMajor;
+    if (aMinor !== bMinor)
+        return aMinor - bMinor;
+    return aPatch - bPatch;
+}
+//# sourceMappingURL=agents-md.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/codemod",
-  "version": "16.2.0-canary.4",
+  "version": "16.2.0-canary.41",
   "license": "MIT",
   "repository": {
     "type": "git",