Unverified Commit d3d30cf8 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

Add future defaults upgrade coverage for `next upgrade --ai` (#98643)

Stacked on #98640.

This PR adds `next upgrade --ai="future"` flag, which is targeted to
help users leverage agents to upgrade their app to adopt the future
defaults when available. Just like latest version upgrade, it covers
running codemods and a migration checklist for major-to-major upgrades
to support breaking changes more reliably.

This PR currently covers Cache Components only for the future default.
parent 457dfaa5
...@@ -39,6 +39,9 @@ to step 2 only after every check completes and finds no equivalent work. ...@@ -39,6 +39,9 @@ to step 2 only after every check completes and finds no equivalent work.
## 2. Make a checklist ## 2. Make a checklist
If the Next.js version is unchanged, make the checklist from the Future Defaults
adoption references in the prompt instead of the version-migration guides below.
- [ ] Read `./codemods.md` and the applicable `./version-<major>.md` files for - [ ] Read `./codemods.md` and the applicable `./version-<major>.md` files for
every crossed major, or the target major for a same-major upgrade. every crossed major, or the target major for a same-major upgrade.
- [ ] For version 14 and later, include the **Review migration checklist** - [ ] For version 14 and later, include the **Review migration checklist**
...@@ -48,6 +51,9 @@ to step 2 only after every check completes and finds no equivalent work. ...@@ -48,6 +51,9 @@ to step 2 only after every check completes and finds no equivalent work.
## 3. Upgrade and repair ## 3. Upgrade and repair
If the Next.js version is unchanged, follow the Future Defaults adoption
references in the prompt instead of the codemod steps below.
- [ ] Run the exact command prepared for this upgrade: - [ ] Run the exact command prepared for this upgrade:
```text ```text
...@@ -74,6 +80,9 @@ to step 2 only after every check completes and finds no equivalent work. ...@@ -74,6 +80,9 @@ to step 2 only after every check completes and finds no equivalent work.
## 5. Commit and deliver ## 5. Commit and deliver
For adoption without a version change, group commits by the Future Default being
adopted instead of by crossed major.
- [ ] Commit the final diff in ascending major order, with one commit for each - [ ] Commit the final diff in ascending major order, with one commit for each
crossed major. Each commit contains that major's surviving final-target crossed major. Each commit contains that major's surviving final-target
changes. Do not add transitional changes solely to make an intermediate changes. Do not add transitional changes solely to make an intermediate
......
.next/
*.tsbuildinfo
__agent_eval__/
eval-evidence/
node_modules/
next-env.d.ts
!package-lock.json
You may edit this application and create local commits. Do not push or create pull requests. Use npm. Preserve the behavior described in README.md.
import { futureChecks } from './checks/EVAL'
futureChecks({ trigger: 'direct' })
Run `next upgrade --ai future` for this app and complete the upgrade.
# Next.js 16 Future storefront
This App Router storefront already runs the target Next.js version. It lists
products, renders product detail routes, and shows an account greeting from the
request's `display-name` cookie. Cookie values must stay isolated between
visitors, and product pages must preserve useful shared layout content while
resolving the requested product.
Keep the existing Next.js version and complete Cache Components adoption without
leaving temporary route opt-outs or Cache Components adoption TODOs. Use
`npm run typecheck`, `npm run build`, and `npm start` to verify the app.
import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'
export default async function AccountPage() {
const cookieStore = await cookies()
const displayName = cookieStore.get('display-name')?.value ?? 'Guest'
return (
<main>
<h1>Account</h1>
<p>Welcome back, {displayName}.</p>
</main>
)
}
import type { ReactNode } from 'react'
import Link from 'next/link'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>
<nav>
<Link href="/">Products</Link> <Link href="/account">Account</Link>
</nav>
{children}
</body>
</html>
)
}
import Link from 'next/link'
import { products } from '@/lib/products'
export default function Page() {
return (
<main>
<h1>Northstar Supply</h1>
<ul>
{products.map((product) => (
<li key={product.slug}>
<Link href={`/products/${product.slug}`}>{product.name}</Link>
</li>
))}
</ul>
</main>
)
}
import { notFound } from 'next/navigation'
import { getProduct } from '@/lib/products'
export const dynamic = 'force-static'
export default async function ProductPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const product = getProduct(slug)
if (!product) notFound()
return (
<main>
<h1>Product</h1>
<article>
<h2>{product.name}</h2>
<p>{product.description}</p>
</article>
</main>
)
}
../../../shared/future-checks.ts
\ No newline at end of file
export const products = [
{
slug: 'field-notes',
name: 'Field Notes',
description: 'Weatherproof notes for long days outside.',
},
{
slug: 'trail-light',
name: 'Trail Light',
description: 'A compact light with a warm reading mode.',
},
]
export function getProduct(slug: string) {
return products.find((product) => product.slug === slug)
}
/** @type {import('next').NextConfig} */
const nextConfig = {}
export default nextConfig
{
"name": "future-cache-components-same-version",
"private": true,
"type": "module",
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"next": "16.3.5",
"react": "19.1.0",
"react-dom": "19.1.0"
},
"devDependencies": {
"@types/node": "20.17.7",
"@types/react": "19.1.2",
"@types/react-dom": "19.1.2",
"typescript": "5.8.3",
"vitest": "3.1.3",
"@vitejs/plugin-react": "4.4.1",
"vite-tsconfig-paths": "5.1.4"
}
}
{
"compilerOptions": {
"target": "ES2017",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"module": "esnext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"incremental": true,
"plugins": [{ "name": "next" }],
"paths": { "@/*": ["./*"] }
},
"include": [
"next-env.d.ts",
"app/**/*.ts",
"app/**/*.tsx",
"lib/**/*.ts",
".next/types/**/*.ts"
],
"exclude": ["node_modules"]
}
.next/
*.tsbuildinfo
__agent_eval__/
eval-evidence/
node_modules/
next-env.d.ts
!package-lock.json
You may edit this application and create local commits. Do not push or create pull requests. Use npm. Preserve the behavior described in README.md.
import { futureChecks } from './checks/EVAL'
futureChecks({ trigger: 'direct' })
Run `next upgrade --ai future` for this app and complete the upgrade.
# Next.js 13 Future storefront
This App Router storefront starts on Next.js 13. It lists products, renders
product detail routes, and shows an account greeting from the request's
`display-name` cookie. Cookie values must stay isolated between visitors, and
product pages must preserve useful shared layout content while resolving the
requested product.
Upgrade through Next.js 16 and complete Cache Components adoption without
leaving temporary route opt-outs or Cache Components adoption TODOs. Use
`npm run typecheck`, `npm run build`, and `npm start` to verify the app.
import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'
export default function AccountPage() {
const cookieStore = cookies()
const displayName = cookieStore.get('display-name')?.value ?? 'Guest'
return (
<main>
<h1>Account</h1>
<p>Welcome back, {displayName}.</p>
</main>
)
}
import type { ReactNode } from 'react'
import Link from 'next/link'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>
<nav>
<Link href="/">Products</Link> <Link href="/account">Account</Link>
</nav>
{children}
</body>
</html>
)
}
import Link from 'next/link'
import { products } from '@/lib/products'
export default function Page() {
return (
<main>
<h1>Northstar Supply</h1>
<ul>
{products.map((product) => (
<li key={product.slug}>
<Link href={`/products/${product.slug}`}>{product.name}</Link>
</li>
))}
</ul>
</main>
)
}
import { notFound } from 'next/navigation'
import { getProduct } from '@/lib/products'
export const dynamic = 'force-static'
export default function ProductPage({ params }: { params: { slug: string } }) {
const product = getProduct(params.slug)
if (!product) notFound()
return (
<main>
<h1>Product</h1>
<article>
<h2>{product.name}</h2>
<p>{product.description}</p>
</article>
</main>
)
}
../../../shared/future-checks.ts
\ No newline at end of file
export const products = [
{
slug: 'field-notes',
name: 'Field Notes',
description: 'Weatherproof notes for long days outside.',
},
{
slug: 'trail-light',
name: 'Trail Light',
description: 'A compact light with a warm reading mode.',
},
]
export function getProduct(slug: string) {
return products.find((product) => product.slug === slug)
}
/** @type {import('next').NextConfig} */
const nextConfig = {}
export default nextConfig
{
"name": "future-cache-components",
"private": true,
"type": "module",
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"next": "13.5.11",
"react": "18.2.0",
"react-dom": "18.2.0"
},
"devDependencies": {
"@types/node": "20.17.7",
"@types/react": "18.2.79",
"@types/react-dom": "18.2.25",
"typescript": "5.8.3",
"vitest": "3.1.3",
"@vitejs/plugin-react": "4.4.1",
"vite-tsconfig-paths": "5.1.4"
}
}
{
"compilerOptions": {
"target": "ES2017",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"module": "esnext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"incremental": true,
"plugins": [{ "name": "next" }],
"paths": { "@/*": ["./*"] }
},
"include": [
"next-env.d.ts",
"app/**/*.ts",
"app/**/*.tsx",
"lib/**/*.ts",
".next/types/**/*.ts"
],
"exclude": ["node_modules"]
}
import { appendFileSync, readFileSync } from 'node:fs'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
const tools = dirname(dirname(fileURLToPath(import.meta.url)))
const realFetch = globalThis.fetch
const { target } = JSON.parse(
readFileSync(join(tools, 'security/assessment.json'), 'utf8')
)
globalThis.fetch = async (input, init) => {
const url = String(input)
let value
if (url.startsWith('https://api.github.com/advisories?')) {
value = []
} else if (url === 'https://registry.npmjs.org/next/latest') {
value = {
version: target,
engines: { node: '>=20.9.0' },
}
} else {
return realFetch(input, init)
}
appendFileSync(
join(tools, 'assessment.jsonl'),
JSON.stringify({ url, value }) + '\n'
)
return Response.json(value)
}
import { join } from 'node:path'
import type { Sandbox } from '@vercel/agent-eval'
import { setupUpgradeScenario } from '../security/setup'
export async function setupFuture(sandbox: Sandbox) {
const fixture = process.env.NEXT_UPGRADE_EVAL_CASE
const scenarios: Record<string, { source: string; target: string }> = {
'future-cache-components': {
source: '13.5.11',
target: '16.3.5',
},
'future-cache-components-same-version': {
source: '16.3.5',
target: '16.3.5',
},
}
const scenario = fixture ? scenarios[fixture] : undefined
if (!scenario) throw new Error('Unknown Future Defaults eval case')
await setupUpgradeScenario(sandbox, {
fixturePrefix: 'future-',
assessmentPath: join(__dirname, 'assessment.mjs'),
assessment: scenario,
installedVersion: undefined,
skillInstructionsPath: join(
__dirname,
'../../../skills/next-cache-components-adoption/SKILL.md'
),
})
}
#!/usr/bin/env node #!/usr/bin/env node
import { spawnSync } from 'node:child_process' import { spawnSync } from 'node:child_process'
import { appendFileSync, existsSync, realpathSync } from 'node:fs' import { appendFileSync, existsSync, readFileSync, realpathSync } from 'node:fs'
import { dirname, join } from 'node:path' import { dirname, join } from 'node:path'
import { fileURLToPath, pathToFileURL } from 'node:url' import { fileURLToPath, pathToFileURL } from 'node:url'
...@@ -8,15 +8,24 @@ const tools = dirname(fileURLToPath(import.meta.url)) ...@@ -8,15 +8,24 @@ const tools = dirname(fileURLToPath(import.meta.url))
const args = process.argv.slice(2) const args = process.argv.slice(2)
const executable = join(tools, 'next/node_modules/next/dist/bin/next') const executable = join(tools, 'next/node_modules/next/dist/bin/next')
const assessment = join(tools, 'security/assessment.mjs') const assessment = join(tools, 'security/assessment.mjs')
const assessmentConfig = join(tools, 'security/assessment.json')
if (existsSync(assessmentConfig)) {
const { source } = JSON.parse(readFileSync(assessmentConfig, 'utf8'))
if (source) process.env.__NEXT_VERSION = source
}
appendFileSync( appendFileSync(
join(tools, 'invocations.jsonl'), join(tools, 'invocations.jsonl'),
JSON.stringify({ JSON.stringify({
args, args,
executable: realpathSync(executable), executable: realpathSync(executable),
cwd: process.cwd(), cwd: process.cwd(),
packageRunner: process.env.NEXT_UPGRADE_EVAL_PACKAGE_RUNNER, ...(args[0] === 'upgrade'
requestedPackage: process.env.NEXT_UPGRADE_EVAL_REQUESTED_PACKAGE, ? {
packageRunner: process.env.NEXT_UPGRADE_EVAL_PACKAGE_RUNNER,
requestedPackage: process.env.NEXT_UPGRADE_EVAL_REQUESTED_PACKAGE,
}
: {}),
}) + '\n' }) + '\n'
) )
......
...@@ -2,6 +2,7 @@ import type { ExperimentConfig } from '@vercel/agent-eval' ...@@ -2,6 +2,7 @@ import type { ExperimentConfig } from '@vercel/agent-eval'
import { setupUpgrade } from './fixture' import { setupUpgrade } from './fixture'
import { setupSecurity } from '../security/setup' import { setupSecurity } from '../security/setup'
import { setupLatest } from '../latest/setup' import { setupLatest } from '../latest/setup'
import { setupFuture } from '../future/setup'
export function upgradeExperiment( export function upgradeExperiment(
harness: 'codex' | 'claude-code' harness: 'codex' | 'claude-code'
...@@ -10,6 +11,7 @@ export function upgradeExperiment( ...@@ -10,6 +11,7 @@ export function upgradeExperiment(
if (!fixture) throw new Error('Select one upgrade eval case') if (!fixture) throw new Error('Select one upgrade eval case')
const security = fixture.startsWith('security-') const security = fixture.startsWith('security-')
const latest = fixture.startsWith('latest-') const latest = fixture.startsWith('latest-')
const future = fixture.startsWith('future-')
return { return {
agent: `vercel-ai-gateway/${harness}`, agent: `vercel-ai-gateway/${harness}`,
...@@ -20,12 +22,13 @@ export function upgradeExperiment( ...@@ -20,12 +22,13 @@ export function upgradeExperiment(
}, },
evals: fixture, evals: fixture,
earlyExit: false, earlyExit: false,
timeout: 1800, timeout: future ? 3600 : 1800,
copyFiles: 'changed', copyFiles: 'changed',
setup: async (sandbox) => { setup: async (sandbox) => {
const setup = await setupUpgrade(sandbox) const setup = await setupUpgrade(sandbox)
if (security) await setupSecurity(sandbox) if (security) await setupSecurity(sandbox)
if (latest) await setupLatest(sandbox) if (latest) await setupLatest(sandbox)
if (future) await setupFuture(sandbox)
return setup return setup
}, },
} }
......
...@@ -26,6 +26,26 @@ const record = (event) => ...@@ -26,6 +26,26 @@ const record = (event) =>
JSON.stringify(event) + '\n' JSON.stringify(event) + '\n'
) )
if (
config.routeBuildToCandidate &&
runner === 'npm' &&
['run', 'run-script'].includes(args[0]) &&
args[1] === 'build'
) {
const separator = args.indexOf('--')
const result = spawnSync(
process.execPath,
[
join(tools, 'entry.mjs'),
'build',
...(separator === -1 ? [] : args.slice(separator + 1)),
],
{ stdio: 'inherit', env: process.env }
)
if (result.error) throw result.error
process.exit(result.status ?? 1)
}
if (runner === 'git' && args[0] === 'remote' && args.includes('-v')) { if (runner === 'git' && args[0] === 'remote' && args.includes('-v')) {
process.stdout.write( process.stdout.write(
`origin\t${config.repository} (fetch)\norigin\t${config.repository} (push)\n` `origin\t${config.repository} (fetch)\norigin\t${config.repository} (push)\n`
...@@ -115,10 +135,25 @@ const requestedPackage = invocation?.requestedPackage ...@@ -115,10 +135,25 @@ const requestedPackage = invocation?.requestedPackage
const executable = invocation?.executable const executable = invocation?.executable
const invocationArgs = invocation?.args const invocationArgs = invocation?.args
if (
config.skillInstructions &&
invocationArgs?.[0] === 'use' &&
requestedPackage?.startsWith('skills@')
) {
appendFileSync(
join(tools, 'skill-runs.jsonl'),
JSON.stringify({ requestedPackage, args: invocationArgs }) + '\n'
)
process.stdout.write(readFileSync(config.skillInstructions, 'utf8'))
process.exit(0)
}
if ( if (
invocationArgs && invocationArgs &&
(requestedPackage === '@next/codemod@canary' || (requestedPackage === '@next/codemod@canary' ||
requestedPackage === `@next/codemod@${config.codemodVersion}`) && requestedPackage === `@next/codemod@${config.codemodVersion}` ||
(config.skillInstructions &&
requestedPackage === '@next/codemod@latest')) &&
(!executable || ['codemod', 'next-codemod'].includes(executable)) (!executable || ['codemod', 'next-codemod'].includes(executable))
) { ) {
record({ record({
......
...@@ -71,6 +71,8 @@ export async function setupUpgradeScenario( ...@@ -71,6 +71,8 @@ export async function setupUpgradeScenario(
assessmentPath: string assessmentPath: string
assessment: object assessment: object
installedVersion: string | undefined installedVersion: string | undefined
routeBuildToCandidate?: boolean
skillInstructionsPath?: string
} }
) { ) {
const run = async (command: string, args: string[]) => { const run = async (command: string, args: string[]) => {
...@@ -110,6 +112,14 @@ export async function setupUpgradeScenario( ...@@ -110,6 +112,14 @@ export async function setupUpgradeScenario(
join(__dirname, 'prepare-candidate.mjs'), join(__dirname, 'prepare-candidate.mjs'),
'utf8' 'utf8'
), ),
...(options.skillInstructionsPath
? {
[`${security}/skill-instructions.md`]: readFileSync(
options.skillInstructionsPath,
'utf8'
),
}
: {}),
[config]: `[url "file://${remote}"]\n\tinsteadOf = ${repository}\n`, [config]: `[url "file://${remote}"]\n\tinsteadOf = ${repository}\n`,
[`${toolsDirectory}/baseline.json`]: JSON.stringify({ head: baseline }), [`${toolsDirectory}/baseline.json`]: JSON.stringify({ head: baseline }),
}) })
...@@ -144,6 +154,10 @@ export async function setupUpgradeScenario( ...@@ -144,6 +154,10 @@ export async function setupUpgradeScenario(
prepareFixture: Boolean(options.installedVersion), prepareFixture: Boolean(options.installedVersion),
remote, remote,
repository, repository,
routeBuildToCandidate: options.routeBuildToCandidate,
skillInstructions: options.skillInstructionsPath
? `${security}/skill-instructions.md`
: undefined,
}), }),
[join(bin, 'npm')]: [join(bin, 'npm')]:
`#!/bin/sh\nexec node ${security}/package-runner.mjs npm "$@"\n`, `#!/bin/sh\nexec node ${security}/package-runner.mjs npm "$@"\n`,
......
import { afterAll, beforeAll, expect, test, vi } from 'vitest'
import { environment } from '@vercel/agent-eval/eval'
import { execFileSync, spawn, type ChildProcess } from 'node:child_process'
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
type FutureChecksOptions = {
trigger: 'direct' | 'nudge'
}
export function futureChecks(options: FutureChecksOptions) {
void options
const tools = '/tmp/next-upgrade-eval'
const { source: sourceVersion, target: targetVersion } = JSON.parse(
readFileSync(join(tools, 'security/assessment.json'), 'utf8')
) as { source: string; target: string }
const npm = JSON.parse(
readFileSync(join(tools, 'package-runner.json'), 'utf8')
).npm as string
const evidence = join(process.cwd(), 'eval-evidence')
const git = (...args: string[]) =>
execFileSync('git', args, { encoding: 'utf8' }).trim()
let baseline: string
let cwd: string
let server: ChildProcess | undefined
let serverOutput = ''
let url = ''
beforeAll(async () => {
baseline = JSON.parse(
readFileSync(join(tools, 'baseline.json'), 'utf8')
).head
expect(
JSON.parse(git('show', `${baseline}:package.json`)).dependencies.next
).toBe(sourceVersion)
const manifest = JSON.parse(readFileSync('package.json', 'utf8'))
expect(manifest.dependencies.next).toBe(targetVersion)
const config = readFileSync('next.config.js', 'utf8')
expect(config).toMatch(/cacheComponents\s*:\s*true/)
const sourceFiles = git(
'ls-files',
'--cached',
'--others',
'--exclude-standard',
'app',
'lib'
)
.split('\n')
.filter((file) => /^(?:app|lib)\/.*\.[cm]?[jt]sx?$/.test(file))
const source = sourceFiles
.map((file) => readFileSync(file, 'utf8'))
.join('\n')
expect(source).not.toMatch(
/export\s+(?:const|var|let)\s+(?:dynamic|revalidate|fetchCache)\s*=/
)
expect(source).not.toMatch(
/export\s+(?:const|var|let)\s+instant\s*=\s*false/
)
expect(source).not.toMatch(/TODO:\s*Cache Components adoption/)
cwd = process.cwd()
server = spawn(npm, ['run', 'dev', '--', '--port', '0'], {
cwd,
stdio: ['ignore', 'pipe', 'pipe'],
env: { ...process.env, NEXT_TELEMETRY_DISABLED: '1' },
})
server.stdout!.on('data', (chunk) => {
serverOutput += chunk.toString()
})
server.stderr!.on('data', (chunk) => {
serverOutput += chunk.toString()
})
await vi.waitFor(
() => {
url = serverOutput.match(/http:\/\/localhost:\d+/)?.[0] ?? ''
expect(url).not.toBe('')
},
{ timeout: 30000 }
)
}, 600000)
afterAll(() => {
server?.kill('SIGTERM')
mkdirSync(evidence, { recursive: true })
writeFileSync(join(evidence, 'committed-server.log'), serverOutput)
for (const name of [
'assessment.jsonl',
'codemod-runs.jsonl',
'invocations.jsonl',
'provider.jsonl',
'skill-runs.jsonl',
]) {
if (existsSync(join(tools, name))) {
writeFileSync(join(evidence, name), readFileSync(join(tools, name)))
}
}
})
test('does not publish the migration', () => {
expect(
execFileSync(
'git',
['--git-dir', join(tools, 'origin.git'), 'rev-parse', 'main'],
{ encoding: 'utf8' }
).trim()
).toBe(baseline)
})
test('preserves request-specific and dynamic-route behavior', async () => {
await Promise.all(
['Alice', 'Bob'].map(async (name) => {
const response = await fetch(`${url}/account`, {
headers: { cookie: `display-name=${name}` },
})
expect(response.status).toBe(200)
const html = (await response.text()).replace(/<!--.*?-->/g, '')
expect(html).toContain(`Welcome back, ${name}.`)
})
)
const product = await fetch(`${url}/products/field-notes`)
expect(product.status).toBe(200)
expect(await product.text()).toContain('Field Notes')
})
test('leaves meaningful Cache Components boundaries', async () => {
await expect(environment).toSatisfyCriterion(
`Cache Components is fully enabled with no temporary route opt-outs. The account page still reads its cookie at request time beneath meaningful Suspense or loading UI so values cannot leak between visitors. The dynamic product page resolves params below a meaningful Suspense boundary while preserving useful route-independent shell content.`
)
})
}
...@@ -588,7 +588,7 @@ program ...@@ -588,7 +588,7 @@ program
.addOption( .addOption(
new Option( new Option(
'--ai, --experimental-ai [type]', '--ai, --experimental-ai [type]',
'Upgrade with AI to security or latest. Defaults to security.' 'Upgrade with AI to security, latest, or future. Defaults to security.'
).conflicts('revision') ).conflicts('revision')
) )
.action(async (directory, options) => { .action(async (directory, options) => {
......
This diff is collapsed.
import type { NextConfigComplete } from '../../server/config-shared'
export type UpgradeDocument = `docs/${string}.md` | `skills/${string}/SKILL.md`
type FutureDefault = {
name: string
availableSince: string
isAdopted(config: NextConfigComplete): boolean
adoptionDoc: readonly UpgradeDocument[]
optimizationDoc: readonly UpgradeDocument[]
}
export const futureDefaults = [
// TODO: Add `partialPrefetching` after the Cache Components Future Default
// workflow is proven end to end.
{
name: 'Cache Components',
availableSince: '16.3.0',
isAdopted: (config) => config.cacheComponents === true,
adoptionDoc: [
'docs/01-app/02-guides/migrating-to-cache-components.md',
'skills/next-cache-components-adoption/SKILL.md',
],
optimizationDoc: ['skills/next-cache-components-optimizer/SKILL.md'],
},
] as const satisfies readonly FutureDefault[]
export type FutureDefaultEntry = (typeof futureDefaults)[number]
import { readFile } from 'fs/promises' import { readFile } from 'fs/promises'
import { createRequire } from 'module' import { createRequire } from 'module'
import { join } from 'path' import { join } from 'path'
import { resetEnv } from '@next/env'
import semver from 'next/dist/compiled/semver' import semver from 'next/dist/compiled/semver'
import loadConfig from '../../server/config'
import { PHASE_INFO } from '../../shared/lib/constants'
import { futureDefaults, type FutureDefaultEntry } from './future-defaults'
type UpgradePreparation = type UpgradePreparation =
| { status: 'unaffected'; reason: string } | { status: 'unaffected'; reason: string }
...@@ -10,23 +14,32 @@ type UpgradePreparation = ...@@ -10,23 +14,32 @@ type UpgradePreparation =
installedVersion: string installedVersion: string
targetVersion: string targetVersion: string
references: string[] references: string[]
futureDefaults: FutureDefaultEntry[]
} }
export async function prepareUpgrade( export async function prepareUpgrade(
directory: string, directory: string,
targetRequest: string = 'security' targetRequest: string = 'security'
): Promise<UpgradePreparation> { ): Promise<UpgradePreparation> {
if (targetRequest !== 'security' && targetRequest !== 'latest') { if (
targetRequest !== 'security' &&
targetRequest !== 'latest' &&
targetRequest !== 'future'
) {
throw new Error( throw new Error(
`Unsupported AI upgrade type ${JSON.stringify(targetRequest)}. Expected "security" or "latest".` `Unsupported AI upgrade type ${JSON.stringify(targetRequest)}. Expected "security", "latest", or "future".`
) )
} }
// Resolve from the app: the invoking canary is only the upgrade tooling. // Resolve from the app: the invoking canary is only the upgrade tooling.
const requireFromApp = createRequire(join(directory, 'package.json')) const requireFromApp = createRequire(join(directory, 'package.json'))
const { version: installedVersion } = JSON.parse( const installedNext = JSON.parse(
await readFile(requireFromApp.resolve('next/package.json'), 'utf8') await readFile(requireFromApp.resolve('next/package.json'), 'utf8')
) ) as {
version: string
engines: { node: string | undefined } | undefined
}
const installedVersion = installedNext.version
if (!semver.valid(installedVersion)) { if (!semver.valid(installedVersion)) {
throw new Error('Could not determine the installed Next.js version.') throw new Error('Could not determine the installed Next.js version.')
...@@ -39,7 +52,7 @@ export async function prepareUpgrade( ...@@ -39,7 +52,7 @@ export async function prepareUpgrade(
) )
} }
if (targetRequest === 'latest') { if (targetRequest === 'latest' || targetRequest === 'future') {
const url = `${NPM_REGISTRY}next/latest` const url = `${NPM_REGISTRY}next/latest`
const { value } = await fetchJSON(url) const { value } = await fetchJSON(url)
const release = value as { const release = value as {
...@@ -55,32 +68,83 @@ export async function prepareUpgrade( ...@@ -55,32 +68,83 @@ export async function prepareUpgrade(
throw new Error('Could not determine the latest stable Next.js version.') throw new Error('Could not determine the latest stable Next.js version.')
} }
if (semver.eq(release.version, installedVersion)) { const targetVersion =
targetRequest === 'future' && semver.gt(installedVersion, release.version)
? installedVersion
: release.version
const nodeRange =
targetVersion === installedVersion
? (installedNext.engines?.node ?? null)
: (release.engines?.node ?? null)
if (
targetRequest === 'latest' &&
semver.eq(release.version, installedVersion)
) {
return { return {
status: 'unaffected', status: 'unaffected',
reason: `Next.js ${installedVersion} is already the latest stable release.`, reason: `Next.js ${installedVersion} is already the latest stable release.`,
} }
} }
if (semver.lt(release.version, installedVersion)) { if (
targetRequest === 'latest' &&
semver.lt(release.version, installedVersion)
) {
return { return {
status: 'unaffected', status: 'unaffected',
reason: `Next.js ${installedVersion} is newer than the latest stable release ${release.version}.`, reason: `Next.js ${installedVersion} is newer than the latest stable release ${release.version}.`,
} }
} }
const nodeRange = release.engines?.node ?? null
if (!nodeRange || !semver.satisfies(process.versions.node, nodeRange)) { if (!nodeRange || !semver.satisfies(process.versions.node, nodeRange)) {
throw new Error( throw new Error(
`Next.js ${release.version} requires Node.js ${nodeRange ?? '(version unavailable)'}. Update Node.js before continuing.` `Next.js ${targetVersion} requires Node.js ${nodeRange ?? '(version unavailable)'}. Update Node.js before continuing.`
)
}
let pendingFutureDefaults: FutureDefaultEntry[] = []
if (targetRequest === 'future') {
const securitySnapshot = await readSecuritySnapshot(targetVersion)
if (
securitySnapshot?.ranges.some((range) =>
semver.satisfies(targetVersion, range)
)
) {
throw new Error(
`Next.js ${targetVersion} is affected by an active advisory.`
)
}
const config = await loadConfig(PHASE_INFO, directory, {
silent: true,
}).finally(resetEnv)
pendingFutureDefaults = futureDefaults.filter(
(futureDefault) =>
semver.gte(targetVersion, futureDefault.availableSince) &&
!futureDefault.isAdopted(config)
) )
if (
targetVersion === installedVersion &&
pendingFutureDefaults.length === 0
) {
return {
status: 'unaffected',
reason: `Next.js ${installedVersion} is current and all available Future Defaults are enabled.`,
}
}
} }
return { return {
status: 'ready', status: 'ready',
installedVersion, installedVersion,
targetVersion: release.version, targetVersion,
references: [url], references: [url],
futureDefaults: pendingFutureDefaults,
} }
} }
...@@ -107,6 +171,7 @@ export async function prepareUpgrade( ...@@ -107,6 +171,7 @@ export async function prepareUpgrade(
installedVersion, installedVersion,
targetVersion: selected.version, targetVersion: selected.version,
references: snapshot.references, references: snapshot.references,
futureDefaults: [],
} }
} }
......
import { access, cp, mkdtemp, readFile, rm, stat, writeFile } from 'fs/promises' import { EventEmitter } from 'events'
import {
access,
cp,
mkdir,
mkdtemp,
readFile,
rm,
stat,
writeFile,
} from 'fs/promises'
import * as Log from 'next/dist/build/output/log' import * as Log from 'next/dist/build/output/log'
import cliSelect from 'next/dist/compiled/cli-select' import cliSelect from 'next/dist/compiled/cli-select'
import { spawnNextUpgrade } from 'next/dist/cli/next-upgrade' import { spawnNextUpgrade } from 'next/dist/cli/next-upgrade'
...@@ -14,6 +24,7 @@ import { getAgentName } from 'next/dist/telemetry/agent-name' ...@@ -14,6 +24,7 @@ import { getAgentName } from 'next/dist/telemetry/agent-name'
jest.mock('fs/promises', () => ({ jest.mock('fs/promises', () => ({
access: jest.fn(), access: jest.fn(),
cp: jest.fn(), cp: jest.fn(),
mkdir: jest.fn(),
mkdtemp: jest.fn(), mkdtemp: jest.fn(),
readFile: jest.fn(), readFile: jest.fn(),
rm: jest.fn(), rm: jest.fn(),
...@@ -33,6 +44,7 @@ jest.mock('next/dist/compiled/cli-select', () => ({ ...@@ -33,6 +44,7 @@ jest.mock('next/dist/compiled/cli-select', () => ({
__esModule: true, __esModule: true,
default: jest.fn(), default: jest.fn(),
})) }))
jest.mock('next/dist/compiled/cross-spawn', () => jest.fn())
jest.mock('next/dist/lib/find-pages-dir', () => ({ jest.mock('next/dist/lib/find-pages-dir', () => ({
findDir: jest.fn(), findDir: jest.fn(),
})) }))
...@@ -62,6 +74,7 @@ jest.mock('next/dist/telemetry/agent-name', () => ({ ...@@ -62,6 +74,7 @@ jest.mock('next/dist/telemetry/agent-name', () => ({
})) }))
const createSpinner = require('next/dist/build/spinner').default as jest.Mock const createSpinner = require('next/dist/build/spinner').default as jest.Mock
const crossSpawn = require('next/dist/compiled/cross-spawn') as jest.Mock
const restoreDescriptors: Array<() => void> = [] const restoreDescriptors: Array<() => void> = []
function normalizedBootstrapCalls(): string[][] { function normalizedBootstrapCalls(): string[][] {
...@@ -70,6 +83,21 @@ function normalizedBootstrapCalls(): string[][] { ...@@ -70,6 +83,21 @@ function normalizedBootstrapCalls(): string[][] {
.mock.calls.map(([message]) => [String(message).replace(/\\+/g, '/')]) .mock.calls.map(([message]) => [String(message).replace(/\\+/g, '/')])
} }
function normalizedFileWriteCalls() {
return jest
.mocked(writeFile)
.mock.calls.map(([path, ...args]) => [
String(path).replace(/\\+/g, '/'),
...args,
])
}
function normalizedWriteFileCalls() {
return normalizedFileWriteCalls().filter(([path]) =>
String(path).includes('/skills/')
)
}
function overrideTTY(target: NodeJS.ReadStream | NodeJS.WriteStream): void { function overrideTTY(target: NodeJS.ReadStream | NodeJS.WriteStream): void {
const descriptor = Object.getOwnPropertyDescriptor(target, 'isTTY') const descriptor = Object.getOwnPropertyDescriptor(target, 'isTTY')
restoreDescriptors.push(() => { restoreDescriptors.push(() => {
...@@ -108,10 +136,12 @@ describe('agentic upgrade prompts', () => { ...@@ -108,10 +136,12 @@ describe('agentic upgrade prompts', () => {
'https://api.github.com/advisories?affects=next', 'https://api.github.com/advisories?affects=next',
'https://registry.npmjs.org/next', 'https://registry.npmjs.org/next',
], ],
futureDefaults: [],
}) })
jest.mocked(mkdtemp).mockResolvedValue('/tmp/next-upgrade-test') jest.mocked(mkdtemp).mockResolvedValue('/tmp/next-upgrade-test')
jest.mocked(cp).mockResolvedValue(undefined) jest.mocked(cp).mockResolvedValue(undefined)
jest.mocked(readFile).mockResolvedValue('Run <codemod-command>') jest.mocked(readFile).mockResolvedValue('Run <codemod-command>')
jest.mocked(mkdir).mockResolvedValue(undefined)
jest.mocked(rm).mockResolvedValue(undefined) jest.mocked(rm).mockResolvedValue(undefined)
jest.mocked(writeFile).mockResolvedValue(undefined) jest.mocked(writeFile).mockResolvedValue(undefined)
jest.mocked(getAgentName).mockResolvedValue('codex') jest.mocked(getAgentName).mockResolvedValue('codex')
...@@ -315,6 +345,7 @@ describe('agentic upgrade prompts', () => { ...@@ -315,6 +345,7 @@ describe('agentic upgrade prompts', () => {
installedVersion: '16.2.12', installedVersion: '16.2.12',
targetVersion: '16.3.5', targetVersion: '16.3.5',
references: ['https://registry.npmjs.org/next/latest'], references: ['https://registry.npmjs.org/next/latest'],
futureDefaults: [],
}) })
await spawnNextUpgrade('/workspace/app', { await spawnNextUpgrade('/workspace/app', {
...@@ -338,4 +369,173 @@ describe('agentic upgrade prompts', () => { ...@@ -338,4 +369,173 @@ describe('agentic upgrade prompts', () => {
] ]
`) `)
}) })
it('adds temporary Future Default instructions to the migration prompt', async () => {
jest.mocked(prepareUpgrade).mockResolvedValue({
status: 'ready',
installedVersion: '16.2.0',
targetVersion: '16.4.0',
references: ['https://registry.npmjs.org/next/latest'],
futureDefaults: [
{
name: 'Cache Components',
availableSince: '16.3.0',
isAdopted: jest.fn(() => false),
adoptionDoc: [
'docs/01-app/02-guides/migrating-to-cache-components.md',
'skills/next-cache-components-adoption/SKILL.md',
],
optimizationDoc: ['skills/next-cache-components-optimizer/SKILL.md'],
},
],
})
crossSpawn.mockImplementation(() => {
const child = new EventEmitter() as EventEmitter & {
stdout: EventEmitter & { setEncoding: jest.Mock }
stderr: EventEmitter & { setEncoding: jest.Mock }
}
child.stdout = Object.assign(new EventEmitter(), {
setEncoding: jest.fn(),
})
child.stderr = Object.assign(new EventEmitter(), {
setEncoding: jest.fn(),
})
process.nextTick(() => {
child.stdout.emit('data', 'Adopt Cache Components safely.\n')
child.emit('close', 0)
})
return child
})
await spawnNextUpgrade('/workspace/app', {
revision: 'latest',
verbose: false,
ai: 'future',
})
expect(crossSpawn).toHaveBeenCalledTimes(1)
expect(normalizedFileWriteCalls()).toContainEqual([
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade.md',
expect.stringMatching(
/^Run npx @next\/codemod@\S+ upgrade 16\.4\.0 --yes --skip-adoption$/
),
])
expect({
prompt: normalizedBootstrapCalls(),
savedInstructions: normalizedWriteFileCalls(),
}).toMatchInlineSnapshot(`
{
"prompt": [
[
"Read and follow every applicable instruction in "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade.md" before proceeding.
We're upgrading the app in "/workspace/app" from Next.js 16.2.0 to 16.4.0 because the Future policy applies the latest stable release and adopts its Future Defaults.
After completing and verifying the version migration, adopt these Future Defaults in order:
- Cache Components
- Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/migrating-to-cache-components.md".
- Read and follow "/tmp/next-upgrade-test/skills/next-cache-components-adoption/PROMPT.md".
Complete each adoption. Temporary opt-outs and TODO markers are intermediate work only; do not stop until they are removed and the adoption is fully verified.
References:
- https://registry.npmjs.org/next/latest",
],
],
"savedInstructions": [
[
"/tmp/next-upgrade-test/skills/next-cache-components-adoption/PROMPT.md",
"Adopt Cache Components safely.
",
],
],
}
`)
})
it('includes the shared preflight without a version migration when current', async () => {
jest.mocked(prepareUpgrade).mockResolvedValue({
status: 'ready',
installedVersion: '16.4.0',
targetVersion: '16.4.0',
references: ['https://registry.npmjs.org/next/latest'],
futureDefaults: [
{
name: 'Cache Components',
availableSince: '16.3.0',
isAdopted: jest.fn(() => false),
adoptionDoc: [
'docs/01-app/02-guides/migrating-to-cache-components.md',
'skills/next-cache-components-adoption/SKILL.md',
],
optimizationDoc: ['skills/next-cache-components-optimizer/SKILL.md'],
},
],
})
crossSpawn.mockImplementation(() => {
const child = new EventEmitter() as EventEmitter & {
stdout: EventEmitter & { setEncoding: jest.Mock }
stderr: EventEmitter & { setEncoding: jest.Mock }
}
child.stdout = Object.assign(new EventEmitter(), {
setEncoding: jest.fn(),
})
child.stderr = Object.assign(new EventEmitter(), {
setEncoding: jest.fn(),
})
process.nextTick(() => {
child.stdout.emit('data', 'Adopt Cache Components safely.\n')
child.emit('close', 0)
})
return child
})
await spawnNextUpgrade('/workspace/app', {
revision: 'latest',
verbose: false,
ai: 'future',
})
expect(
jest
.mocked(cp)
.mock.calls.map(([source, destination]) =>
[String(source), String(destination)].map((path) =>
path.replace(/\\+/g, '/')
)
)
).toEqual(
expect.arrayContaining([
[
expect.stringContaining('/docs/01-app/02-guides/upgrading'),
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading',
],
])
)
expect(readFile).not.toHaveBeenCalled()
expect(normalizedFileWriteCalls()).not.toContainEqual([
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade.md',
expect.anything(),
])
expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(`
[
[
"Read and follow every applicable instruction in "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade.md" before proceeding.
We're adopting the Future Defaults available to the app in "/workspace/app", which already uses Next.js 16.4.0.
Adopt these Future Defaults in order:
- Cache Components
- Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/migrating-to-cache-components.md".
- Read and follow "/tmp/next-upgrade-test/skills/next-cache-components-adoption/PROMPT.md".
Complete each adoption. Temporary opt-outs and TODO markers are intermediate work only; do not stop until they are removed and the adoption is fully verified.
References:
- https://registry.npmjs.org/next/latest",
],
]
`)
})
}) })
...@@ -2,6 +2,12 @@ import { mkdtemp, mkdir, rm, writeFile } from 'fs/promises' ...@@ -2,6 +2,12 @@ import { mkdtemp, mkdir, rm, writeFile } from 'fs/promises'
import { tmpdir } from 'os' import { tmpdir } from 'os'
import { join } from 'path' import { join } from 'path'
import { prepareUpgrade } from 'next/dist/lib/upgrade/prepare-upgrade' import { prepareUpgrade } from 'next/dist/lib/upgrade/prepare-upgrade'
import loadConfig from 'next/dist/server/config'
jest.mock('next/dist/server/config', () => ({
__esModule: true,
default: jest.fn(),
}))
describe('prepare latest upgrade', () => { describe('prepare latest upgrade', () => {
const directories: string[] = [] const directories: string[] = []
...@@ -14,7 +20,7 @@ describe('prepare latest upgrade', () => { ...@@ -14,7 +20,7 @@ describe('prepare latest upgrade', () => {
await writeFile(join(directory, 'package.json'), '{}') await writeFile(join(directory, 'package.json'), '{}')
await writeFile( await writeFile(
join(directory, 'node_modules/next/package.json'), join(directory, 'node_modules/next/package.json'),
JSON.stringify({ version }) JSON.stringify({ version, engines: { node: '>=18' } })
) )
return directory return directory
} }
...@@ -31,6 +37,55 @@ describe('prepare latest upgrade', () => { ...@@ -31,6 +37,55 @@ describe('prepare latest upgrade', () => {
) )
} }
function mockFutureMetadata(vulnerableVersions: string) {
global.fetch = jest.fn(async (input) => {
const url = String(input)
if (url === 'https://registry.npmjs.org/next/latest') {
return Response.json({
version: '16.4.0',
engines: { node: '>=18' },
})
}
if (url.startsWith('https://api.github.com/advisories?')) {
return new Response(null, { status: 500 })
}
if (url === 'https://registry.npmjs.org/next') {
return Response.json({
versions: {
'16.2.0': { version: '16.2.0' },
'16.4.0': { version: '16.4.0' },
},
})
}
if (
url === 'https://registry.npmjs.org/-/npm/v1/security/advisories/bulk'
) {
return Response.json({
next: [
{
id: 1,
url: 'https://github.com/advisories/GHSA-next-test',
severity: 'high',
vulnerable_versions: vulnerableVersions,
},
],
})
}
throw new Error(`Unexpected request: ${url}`)
})
}
beforeEach(() => {
jest.mocked(loadConfig).mockResolvedValue({
cacheComponents: false,
} as never)
})
afterEach(async () => { afterEach(async () => {
global.fetch = originalFetch global.fetch = originalFetch
await Promise.all( await Promise.all(
...@@ -77,4 +132,40 @@ describe('prepare latest upgrade', () => { ...@@ -77,4 +132,40 @@ describe('prepare latest upgrade', () => {
reason: 'Next.js 18.0.0 is newer than the latest stable release 17.1.0.', reason: 'Next.js 18.0.0 is newer than the latest stable release 17.1.0.',
}) })
}) })
it('allows a Future target outside npm fallback advisory ranges', async () => {
const directory = await createApp('16.2.0')
mockFutureMetadata('<16.3.0')
await expect(prepareUpgrade(directory, 'future')).resolves.toEqual(
expect.objectContaining({
status: 'ready',
installedVersion: '16.2.0',
targetVersion: '16.4.0',
})
)
})
it('blocks a Future target inside npm fallback advisory ranges', async () => {
const directory = await createApp('16.2.0')
mockFutureMetadata('<=16.4.0')
await expect(prepareUpgrade(directory, 'future')).rejects.toThrow(
'Next.js 16.4.0 is affected by an active advisory.'
)
})
it('uses the adapter to detect an adopted Future Default', async () => {
const directory = await createApp('16.4.0')
jest.mocked(loadConfig).mockResolvedValue({
cacheComponents: true,
} as never)
mockFutureMetadata('<16.3.0')
await expect(prepareUpgrade(directory, 'future')).resolves.toEqual({
status: 'unaffected',
reason:
'Next.js 16.4.0 is current and all available Future Defaults are enabled.',
})
})
}) })
...@@ -161,9 +161,9 @@ describe('security upgrade nudge', () => { ...@@ -161,9 +161,9 @@ describe('security upgrade nudge', () => {
}) })
describe('latest nudge release selection', () => { describe('latest nudge release selection', () => {
const { getLatestUpgradeVersion: readLatestUpgradeVersion } = const { getLatestUpgradeVersion: readLatestUpgradeVersion } =
jest.requireActual< jest.requireActual<typeof import('next/dist/lib/upgrade/prepare-upgrade')>(
typeof import('../../packages/next/src/lib/upgrade/prepare-upgrade') 'next/dist/lib/upgrade/prepare-upgrade'
>('../../packages/next/src/lib/upgrade/prepare-upgrade') )
afterEach(() => { afterEach(() => {
jest.restoreAllMocks() jest.restoreAllMocks()
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment