Unverified Commit 814eb91e authored by David Alexandru Ilie's avatar David Alexandru Ilie Committed by GitHub

Prevent malformed agent rules marker rewrites

parent 0b7e96f4
...@@ -478,10 +478,15 @@ export async function runUpgrade( ...@@ -478,10 +478,15 @@ export async function runUpgrade(
} }
try { try {
if (refreshAgentRulesBlock(cwd) === 'refreshed') { const agentRulesResult = refreshAgentRulesBlock(cwd)
if (agentRulesResult === 'refreshed') {
console.log( console.log(
`${pc.green('✔')} Refreshed the managed agent-rules block in AGENTS.md / CLAUDE.md to match the upgraded Next.js.` `${pc.green('✔')} Refreshed the managed agent-rules block in AGENTS.md / CLAUDE.md to match the upgraded Next.js.`
) )
} else if (agentRulesResult === 'malformed') {
console.warn(
'Skipped refreshing AGENTS.md / CLAUDE.md because the Next.js agent-rules markers are malformed. Repair or remove the managed marker pair before retrying.'
)
} }
} catch { } catch {
// The block refresh is best-effort — never fail the upgrade over it. // The block refresh is best-effort — never fail the upgrade over it.
......
...@@ -5,7 +5,10 @@ const fs = require('fs') ...@@ -5,7 +5,10 @@ const fs = require('fs')
const path = require('path') const path = require('path')
const os = require('os') const os = require('os')
const { runAgentsMd } = require('../../bin/agents-md') const { runAgentsMd } = require('../../bin/agents-md')
const { getNextjsVersion } = require('../../lib/agents-md') const {
getNextjsVersion,
refreshAgentRulesBlock,
} = require('../../lib/agents-md')
/** /**
* TRUE E2E TESTS * TRUE E2E TESTS
...@@ -193,6 +196,27 @@ This is my project documentation. ...@@ -193,6 +196,27 @@ This is my project documentation.
} }
}) })
it('reports malformed managed markers without rewriting the file', () => {
const nextDir = path.join(testProjectDir, 'node_modules', 'next')
const generatorDir = path.join(nextDir, 'dist', 'server', 'lib')
fs.mkdirSync(generatorDir, { recursive: true })
fs.writeFileSync(
path.join(nextDir, 'package.json'),
JSON.stringify({ name: 'next', version: '16.3.0' })
)
fs.writeFileSync(
path.join(generatorDir, 'generate-agent-files.js'),
`exports.writeAgentFiles = () => ({ agentsMd: 'malformed', claudeMd: 'skipped' })`
)
const content = '<!-- BEGIN:nextjs-agent-rules -->\n# User rules\n'
const filePath = path.join(testProjectDir, 'AGENTS.md')
fs.writeFileSync(filePath, content)
expect(refreshAgentRulesBlock(testProjectDir)).toBe('malformed')
expect(fs.readFileSync(filePath, 'utf-8')).toBe(content)
})
it('works when run from a subdirectory', async () => { it('works when run from a subdirectory', async () => {
const originalCwd = process.cwd() const originalCwd = process.cwd()
......
...@@ -16,6 +16,7 @@ interface NextjsVersionResult { ...@@ -16,6 +16,7 @@ interface NextjsVersionResult {
} }
const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->' const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
const AGENT_RULES_END_MARKER = '<!-- END:nextjs-agent-rules -->'
/** /**
* After an upgrade, refresh the managed agent-rules block in * After an upgrade, refresh the managed agent-rules block in
...@@ -27,18 +28,20 @@ const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->' ...@@ -27,18 +28,20 @@ const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
* always the one shipped with that version — this codemod never * always the one shipped with that version — this codemod never
* carries its own copy. Returns `'refreshed'` when a file was * carries its own copy. Returns `'refreshed'` when a file was
* rewritten, `'current'` when the block was already up to date, and * rewritten, `'current'` when the block was already up to date, and
* `'skipped'` when there is nothing to do: the project never adopted * `'malformed'` when markers require manual repair. Returns `'skipped'`
* the managed block, or the installed Next.js predates the generator * when there is nothing to do: the project never adopted the managed
* (< 16.3). * block, or the installed Next.js predates the generator (< 16.3).
*/ */
export function refreshAgentRulesBlock( export function refreshAgentRulesBlock(
cwd: string cwd: string
): 'refreshed' | 'current' | 'skipped' { ): 'refreshed' | 'current' | 'skipped' | 'malformed' {
const hostsBlock = ['AGENTS.md', 'CLAUDE.md'].some((file) => { const hostsBlock = ['AGENTS.md', 'CLAUDE.md'].some((file) => {
try { try {
return fs const content = fs.readFileSync(path.join(cwd, file), 'utf-8')
.readFileSync(path.join(cwd, file), 'utf-8') return (
.includes(AGENT_RULES_START_MARKER) content.includes(AGENT_RULES_START_MARKER) ||
content.includes(AGENT_RULES_END_MARKER)
)
} catch { } catch {
return false return false
} }
...@@ -58,6 +61,9 @@ export function refreshAgentRulesBlock( ...@@ -58,6 +61,9 @@ export function refreshAgentRulesBlock(
} }
const result = writeAgentFiles(cwd) const result = writeAgentFiles(cwd)
if (result.agentsMd === 'malformed' || result.claudeMd === 'malformed') {
return 'malformed'
}
return result.agentsMd === 'updated' || result.claudeMd === 'updated' return result.agentsMd === 'updated' || result.claudeMd === 'updated'
? 'refreshed' ? 'refreshed'
: 'current' : 'current'
......
...@@ -35,23 +35,58 @@ ${AGENT_RULES_END_MARKER}` ...@@ -35,23 +35,58 @@ ${AGENT_RULES_END_MARKER}`
const CLAUDE_MD_CONTENT = `@AGENTS.md\n` const CLAUDE_MD_CONTENT = `@AGENTS.md\n`
export type AgentFileAction = 'created' | 'updated' | 'unchanged' | 'skipped' export type AgentFileAction =
| 'created'
| 'updated'
| 'unchanged'
| 'skipped'
| 'malformed'
export interface AgentFilesResult { export interface AgentFilesResult {
agentsMd: AgentFileAction agentsMd: AgentFileAction
claudeMd: AgentFileAction claudeMd: AgentFileAction
} }
type AgentRulesMarkerState =
| { kind: 'absent' }
| { kind: 'malformed' }
| { kind: 'valid'; start: number; end: number }
function findMarkerIndexes(content: string, marker: string): number[] {
const indexes: number[] = []
let offset = 0
while (true) {
const index = content.indexOf(marker, offset)
if (index === -1) return indexes
indexes.push(index)
offset = index + marker.length
}
}
/** /**
* Returns the managed block (markers included) found in `content`, or * A managed block is valid only when it has exactly one ordered marker pair.
* `null` when the markers are absent or malformed. * Treat every other marker layout as malformed so a later write cannot
* reinterpret user-authored text as part of the managed block.
*/ */
function parseAgentRulesMarkers(content: string): AgentRulesMarkerState {
const starts = findMarkerIndexes(content, AGENT_RULES_START_MARKER)
const ends = findMarkerIndexes(content, AGENT_RULES_END_MARKER)
if (starts.length === 0 && ends.length === 0) return { kind: 'absent' }
if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0]) {
return { kind: 'malformed' }
}
return { kind: 'valid', start: starts[0], end: ends[0] }
}
function extractAgentRulesBlock(content: string): string | null { function extractAgentRulesBlock(content: string): string | null {
const start = content.indexOf(AGENT_RULES_START_MARKER) const markers = parseAgentRulesMarkers(content)
if (start === -1) return null if (markers.kind !== 'valid') return null
const end = content.indexOf(AGENT_RULES_END_MARKER, start) return content.slice(
if (end === -1) return null markers.start,
return content.slice(start, end + AGENT_RULES_END_MARKER.length) markers.end + AGENT_RULES_END_MARKER.length
)
} }
/** /**
...@@ -95,12 +130,14 @@ export function writeAgentFiles(projectDir: string): AgentFilesResult { ...@@ -95,12 +130,14 @@ export function writeAgentFiles(projectDir: string): AgentFilesResult {
const agentsMdExists = fs.existsSync(agentsMdPath) const agentsMdExists = fs.existsSync(agentsMdPath)
const claudeMdExists = fs.existsSync(claudeMdPath) const claudeMdExists = fs.existsSync(claudeMdPath)
const claudeMdContent = claudeMdExists ? tryReadFile(claudeMdPath) : null
const agentsMdContent = agentsMdExists ? tryReadFile(agentsMdPath) : null
const claudeMdHostsBlock = const claudeMdHostsBlock =
claudeMdExists && claudeMdContent !== null &&
(tryReadFile(claudeMdPath)?.includes(AGENT_RULES_START_MARKER) ?? false) parseAgentRulesMarkers(claudeMdContent).kind !== 'absent'
const agentsMdHostsBlock = const agentsMdHostsBlock =
agentsMdExists && agentsMdContent !== null &&
(tryReadFile(agentsMdPath)?.includes(AGENT_RULES_START_MARKER) ?? false) parseAgentRulesMarkers(agentsMdContent).kind !== 'absent'
if (agentsMdExists && (agentsMdHostsBlock || !claudeMdHostsBlock)) { if (agentsMdExists && (agentsMdHostsBlock || !claudeMdHostsBlock)) {
return { return {
...@@ -136,6 +173,9 @@ function tryReadFile(filePath: string): string | null { ...@@ -136,6 +173,9 @@ function tryReadFile(filePath: string): string | null {
function upsertFile(filePath: string, block: string): AgentFileAction { function upsertFile(filePath: string, block: string): AgentFileAction {
const existing = fs.readFileSync(filePath, 'utf-8') const existing = fs.readFileSync(filePath, 'utf-8')
if (parseAgentRulesMarkers(existing).kind === 'malformed') {
return 'malformed'
}
const updated = upsertAgentRulesBlock(existing, block) const updated = upsertAgentRulesBlock(existing, block)
if (updated === existing) return 'unchanged' if (updated === existing) return 'unchanged'
fs.writeFileSync(filePath, updated, 'utf-8') fs.writeFileSync(filePath, updated, 'utf-8')
...@@ -160,12 +200,11 @@ function upsertAgentRulesBlock(existing: string, block: string): string { ...@@ -160,12 +200,11 @@ function upsertAgentRulesBlock(existing: string, block: string): string {
existing = stripLegacyAgentRulesBlock(existing, eol) existing = stripLegacyAgentRulesBlock(existing, eol)
const startIdx = existing.indexOf(AGENT_RULES_START_MARKER) const markers = parseAgentRulesMarkers(existing)
const endIdx = existing.indexOf(AGENT_RULES_END_MARKER)
if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) { if (markers.kind === 'valid') {
const before = existing.slice(0, startIdx) const before = existing.slice(0, markers.start)
const after = existing.slice(endIdx + AGENT_RULES_END_MARKER.length) const after = existing.slice(markers.end + AGENT_RULES_END_MARKER.length)
const replaced = before + normalizedBlock + after const replaced = before + normalizedBlock + after
return replaced === existing ? existing : replaced return replaced === existing ? existing : replaced
} }
......
...@@ -530,6 +530,17 @@ export async function startServer( ...@@ -530,6 +530,17 @@ export async function startServer(
`Generated ${generated.join(' and ')} for AI agents. Set \`agentRules: false\` in next.config to disable.` `Generated ${generated.join(' and ')} for AI agents. Set \`agentRules: false\` in next.config to disable.`
) )
} }
const malformedFile =
result.agentsMd === 'malformed'
? 'AGENTS.md'
: result.claudeMd === 'malformed'
? 'CLAUDE.md'
: null
if (malformedFile) {
Log.warn(
`Skipped updating ${malformedFile} because its Next.js agent-rules markers are malformed. Repair or remove the managed marker pair, or set \`agentRules: false\` in next.config to disable.`
)
}
} }
} }
} }
......
...@@ -5,6 +5,7 @@ import path from 'path' ...@@ -5,6 +5,7 @@ import path from 'path'
import { writeAgentFiles } from 'next/dist/server/lib/generate-agent-files' import { writeAgentFiles } from 'next/dist/server/lib/generate-agent-files'
const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->' const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
const AGENT_RULES_END_MARKER = '<!-- END:nextjs-agent-rules -->'
/** /**
* The canonical block as the version under test generates it, * The canonical block as the version under test generates it,
...@@ -17,6 +18,89 @@ function currentAgentRulesBlock(): string { ...@@ -17,6 +18,89 @@ function currentAgentRulesBlock(): string {
return fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf-8').trimEnd() return fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf-8').trimEnd()
} }
function runAgentRulesWrite(content: string) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-rules-write-'))
const filePath = path.join(dir, 'AGENTS.md')
fs.writeFileSync(filePath, content)
try {
const firstResult = writeAgentFiles(dir)
const afterFirstWrite = fs.readFileSync(filePath, 'utf-8')
const secondResult = writeAgentFiles(dir)
const afterSecondWrite = fs.readFileSync(filePath, 'utf-8')
return { firstResult, afterFirstWrite, secondResult, afterSecondWrite }
} finally {
fs.rmSync(dir, { recursive: true, force: true })
}
}
describe('agent-rules marker safety', () => {
it.each([
['start marker only', `${AGENT_RULES_MARKER}\n# User rules\n`],
['end marker only', `# User rules\n${AGENT_RULES_END_MARKER}\n`],
[
'reversed markers',
`${AGENT_RULES_END_MARKER}\n# User rules\n${AGENT_RULES_MARKER}\n`,
],
[
'nested start marker',
`${AGENT_RULES_MARKER}\n# User rules\n${AGENT_RULES_MARKER}\n${AGENT_RULES_END_MARKER}\n`,
],
[
'duplicate blocks',
`${AGENT_RULES_MARKER}\nfirst\n${AGENT_RULES_END_MARKER}\n${AGENT_RULES_MARKER}\nsecond\n${AGENT_RULES_END_MARKER}\n`,
],
[
'extra end marker',
`${AGENT_RULES_MARKER}\n# User rules\n${AGENT_RULES_END_MARKER}\n${AGENT_RULES_END_MARKER}\n`,
],
])('does not modify a file with a malformed %s', (_name, content) => {
const result = runAgentRulesWrite(content)
expect(result.firstResult).toEqual({
agentsMd: 'malformed',
claudeMd: 'skipped',
})
expect(result.secondResult).toEqual(result.firstResult)
expect(result.afterFirstWrite).toBe(content)
expect(result.afterSecondWrite).toBe(content)
})
it.each([
['LF', '\n'],
['CRLF', '\r\n'],
])('updates one valid block idempotently with %s endings', (_name, eol) => {
const content = [
'# Team rules',
'',
AGENT_RULES_MARKER,
'stale managed content',
AGENT_RULES_END_MARKER,
'',
'# More team rules',
'',
].join(eol)
const result = runAgentRulesWrite(content)
expect(result.firstResult).toEqual({
agentsMd: 'updated',
claudeMd: 'skipped',
})
expect(result.secondResult).toEqual({
agentsMd: 'unchanged',
claudeMd: 'skipped',
})
expect(result.afterSecondWrite).toBe(result.afterFirstWrite)
expect(result.afterFirstWrite).toContain('# Team rules')
expect(result.afterFirstWrite).toContain('# More team rules')
expect(result.afterFirstWrite).not.toContain('stale managed content')
expect(result.afterFirstWrite.split(AGENT_RULES_MARKER)).toHaveLength(2)
if (eol === '\r\n') {
expect(result.afterFirstWrite).not.toMatch(/(^|[^\r])\n/)
}
})
})
describe('agent-rules auto-generate on next dev (agent detected)', () => { describe('agent-rules auto-generate on next dev (agent detected)', () => {
const { next } = nextTestSetup({ const { next } = nextTestSetup({
files: __dirname, files: __dirname,
...@@ -147,6 +231,36 @@ Stale body from an older Next.js. ...@@ -147,6 +231,36 @@ Stale body from an older Next.js.
}) })
}) })
describe('agent-rules auto-generate on next dev (AGENTS.md has malformed markers)', () => {
const { next } = nextTestSetup({
files: __dirname,
env: { CLAUDECODE: '1' },
skipStart: true,
})
const originalContent = `${AGENT_RULES_MARKER}\n# User-authored rules without an end marker\n`
beforeAll(async () => {
await next.patchFile('AGENTS.md', originalContent)
await next.start()
})
it('preserves the file and reports how to recover across restarts', async () => {
await next.fetch('/')
const filePath = path.join(next.testDir, 'AGENTS.md')
expect(fs.readFileSync(filePath, 'utf-8')).toBe(originalContent)
expect(next.cliOutput).toContain(
'Skipped updating AGENTS.md because its Next.js agent-rules markers are malformed.'
)
expect(next.cliOutput).toContain('agentRules: false')
await next.stop()
await next.start()
await next.fetch('/')
expect(fs.readFileSync(filePath, 'utf-8')).toBe(originalContent)
})
})
describe('agent-rules auto-generate on next dev (AGENTS.md exists without marker)', () => { describe('agent-rules auto-generate on next dev (AGENTS.md exists without marker)', () => {
const { next } = nextTestSetup({ const { next } = nextTestSetup({
files: __dirname, files: __dirname,
......
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