@next/codemod 16.3.0-canary.50 → 16.3.0-canary.52

package/bin/agents-md.js

@@ -59,8 +59,17 @@ async function runAgentsMd(options) {
         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}`;
+    // Next.js >= 16.2.0 ships its docs inside the published package. When the
+    // installed version matches the requested one, index the bundled docs
+    // directly instead of downloading a copy into .next-docs.
+    const bundledDocs = (0, agents_md_1.getBundledDocsInfo)(cwd);
+    const useBundledDocs = bundledDocs !== null && bundledDocs.version === nextjsVersion;
+    const docsPath = useBundledDocs
+        ? bundledDocs.docsPath
+        : path_1.default.join(cwd, DOCS_DIR_NAME);
+    const docsLinkPath = useBundledDocs
+        ? (0, agents_md_1.getBundledDocsLinkPath)(cwd, bundledDocs.docsPath)
+        : `./${DOCS_DIR_NAME}`;
     let sizeBefore = 0;
     let isNewFile = true;
     let existingContent = '';
@@ -69,14 +78,19 @@ async function runAgentsMd(options) {
         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}`);
+    if (useBundledDocs) {
+        console.log(`\nUsing the docs bundled with Next.js ${picocolors_1.default.cyan(nextjsVersion)} at ${picocolors_1.default.cyan(docsLinkPath)} (no download needed).`);
+    }
+    else {
+        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);
@@ -88,13 +102,15 @@ async function runAgentsMd(options) {
     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);
+    // .next-docs only exists on the download path; bundled docs live in
+    // node_modules, which is already ignored.
+    const gitignoreResult = useBundledDocs ? null : (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) {
+    if (gitignoreResult?.updated) {
         console.log(`${picocolors_1.default.green('✓')} Added ${picocolors_1.default.bold(DOCS_DIR_NAME)} to .gitignore`);
     }
     console.log('');

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

@@ -293,6 +293,123 @@ This is my project documentation.
     }
   }, 30000) // Increase timeout for git clone
 
+  describe('bundled docs (Next.js >= 16.2.0)', () => {
+    // Simulate an install of a Next.js version that ships docs inside the
+    // published package at node_modules/next/dist/docs.
+    function setupBundledNext(projectDir, version) {
+      const nextDir = path.join(projectDir, 'node_modules', 'next')
+      const gettingStartedDir = path.join(
+        nextDir,
+        'dist',
+        'docs',
+        '01-app',
+        '01-getting-started'
+      )
+      fs.mkdirSync(gettingStartedDir, { recursive: true })
+      fs.writeFileSync(
+        path.join(nextDir, 'package.json'),
+        JSON.stringify({ name: 'next', version })
+      )
+      fs.writeFileSync(
+        path.join(nextDir, 'dist', 'docs', 'index.md'),
+        '# Next.js Docs'
+      )
+      fs.writeFileSync(
+        path.join(gettingStartedDir, '01-installation.md'),
+        '# Installation'
+      )
+      fs.writeFileSync(
+        path.join(gettingStartedDir, '02-project-structure.md'),
+        '# Project Structure'
+      )
+    }
+
+    it('indexes bundled docs instead of downloading when installed Next.js ships them', async () => {
+      setupBundledNext(testProjectDir, '16.2.0')
+
+      const originalCwd = process.cwd()
+      process.chdir(testProjectDir)
+
+      try {
+        await runAgentsMd({ output: 'CLAUDE.md' })
+
+        // No .next-docs copy and no .gitignore entry for it
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          false
+        )
+        expect(fs.existsSync(path.join(testProjectDir, '.gitignore'))).toBe(
+          false
+        )
+
+        const claudeMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'CLAUDE.md'),
+          'utf-8'
+        )
+        expect(claudeMdContent).toContain(
+          'root: ./node_modules/next/dist/docs'
+        )
+        expect(claudeMdContent).toContain('01-installation.md')
+
+        const output = consoleOutput.join('\n')
+        expect(output).toContain('bundled with Next.js')
+        expect(output).not.toContain('Downloading')
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it('uses bundled docs when --version matches the installed version', async () => {
+      setupBundledNext(testProjectDir, '16.2.0')
+
+      const originalCwd = process.cwd()
+      process.chdir(testProjectDir)
+
+      try {
+        await runAgentsMd({ version: '16.2.0', output: 'AGENTS.md' })
+
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          false
+        )
+
+        const agentsMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'AGENTS.md'),
+          'utf-8'
+        )
+        expect(agentsMdContent).toContain(
+          'root: ./node_modules/next/dist/docs'
+        )
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it('falls back to downloading when --version differs from the installed version', async () => {
+      setupBundledNext(testProjectDir, '16.2.0')
+
+      const originalCwd = process.cwd()
+      process.chdir(testProjectDir)
+
+      try {
+        await runAgentsMd({ version: '15.0.0', output: 'CLAUDE.md' })
+
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          true
+        )
+
+        const claudeMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'CLAUDE.md'),
+          'utf-8'
+        )
+        expect(claudeMdContent).toContain('root: ./.next-docs')
+
+        const output = consoleOutput.join('\n')
+        expect(output).toContain('Downloading')
+      } finally {
+        process.chdir(originalCwd)
+      }
+    }, 30000) // Increase timeout for git clone
+  })
+
   describe('getNextjsVersion', () => {
     const fixturesDir = path.join(__dirname, 'fixtures/agents-md')
 

package/lib/agents-md.js

@@ -10,6 +10,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNextjsVersion = getNextjsVersion;
+exports.getBundledDocsInfo = getBundledDocsInfo;
+exports.getBundledDocsLinkPath = getBundledDocsLinkPath;
 exports.pullDocs = pullDocs;
 exports.collectDocFiles = collectDocFiles;
 exports.buildDocTree = buildDocTree;
@@ -45,6 +47,36 @@ function getNextjsVersion(cwd) {
         };
     }
 }
+/**
+ * Next.js ships its documentation inside the published package (at
+ * `dist/docs`) since 16.2.0. When the install resolved from `cwd` has
+ * bundled docs, the index can point at them directly instead of
+ * downloading a copy into `.next-docs`.
+ */
+function getBundledDocsInfo(cwd) {
+    try {
+        const nextPkgPath = require.resolve('next/package.json', { paths: [cwd] });
+        const pkg = JSON.parse(fs_1.default.readFileSync(nextPkgPath, 'utf-8'));
+        const docsPath = path_1.default.join(path_1.default.dirname(nextPkgPath), 'dist', 'docs');
+        if (!pkg.version || collectDocFiles(docsPath).length === 0) {
+            return null;
+        }
+        return { docsPath, version: pkg.version };
+    }
+    catch {
+        return null;
+    }
+}
+function getBundledDocsLinkPath(cwd, docsPath) {
+    // Prefer the conventional path when it resolves from the project
+    // (covers hoisted installs; pnpm exposes next via a node_modules symlink).
+    const conventional = path_1.default.join(cwd, 'node_modules', 'next', 'dist', 'docs');
+    if (fs_1.default.existsSync(conventional)) {
+        return './node_modules/next/dist/docs';
+    }
+    const relative = path_1.default.relative(cwd, docsPath).replace(/\\/g, '/');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
 function versionToGitHubTag(version) {
     return version.startsWith('v') ? version : `v${version}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/codemod",
-  "version": "16.3.0-canary.50",
+  "version": "16.3.0-canary.52",
   "license": "MIT",
   "repository": {
     "type": "git",