@nera-static/nera 1.6.0 → 1.7.0

package/README.md

@@ -28,7 +28,7 @@ package is named after the folder (`My Bakery` → `my-bakery`).
 | `nera build` | Render `pages/` → `public/`. With `--check`, then run `nera check` on the result — one command for CI. |
 | `nera dev` | Build, serve `public/`, and rebuild on change with live reload. Watches `pages/`, `config/`, `theme/` and a local theme (`theme: ./themes/<name>`). |
 | `nera serve` | Serve the already-built `public/` folder. |
-| `nera update` | Update the site's Nera packages. On a legacy cloned site, `nera update --migrate` converts it to the thin model. |
+| `nera update` | Update the site's Nera packages, then create a missing `AGENTS.md`/`CLAUDE.md` and refresh the Nera part of `AGENTS.md` (see [Instructions for AI assistants](#instructions-for-ai-assistants)). On a legacy cloned site, `nera update --migrate` converts it to the thin model. |
 | `nera validate` | Check the site's sources (layouts, includes, YAML) before publishing; exits non-zero on any error. |
 | `nera check` | Check the built `public/` for accessibility, privacy and legal-notice problems (see below). Build first. |
 
@@ -56,6 +56,22 @@ the marker line `<!-- nera:site-notes … -->`; keep that line in place. The
 part above it is Nera's and may be replaced by a later Nera version; your
 notes below it are yours.
 
+`nera update` keeps both files current, with no extra flag. After the
+packages are updated (and after `nera update --migrate`) it:
+
+- creates `AGENTS.md` and `CLAUDE.md` when they are missing, so a site made
+  before 1.6.0 gets them too;
+- replaces only the part of `AGENTS.md` above the first line starting with
+  `<!-- nera:site-notes`, taking the new text from the installed
+  `@nera-static/nera`'s template; the marker line and everything below it
+  stay byte for byte as they are;
+- leaves an `AGENTS.md` without that line alone and prints a hint: copy the
+  marker line from the template directly above your own notes to opt in;
+- never touches an existing `CLAUDE.md`.
+
+A file is written only when its content changes, so running `nera update`
+again changes nothing.
+
 ## Starting from a theme
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "description": "The Nera CLI — scaffold, build, preview and update a Nera static site with one command over the @nera-static/core engine",
     "type": "module",
     "bin": {

package/src/agent-files.js

@@ -0,0 +1,83 @@
+import fs from 'fs/promises'
+import path from 'path'
+
+// Start of the ownership line in AGENTS.md. Everything above the first line
+// that starts with it is Nera's and is refreshed by `nera update`; that line
+// and everything below it belong to the site owner and are kept byte for byte.
+export const SITE_NOTES_MARKER = '<!-- nera:site-notes'
+
+// Offset of the first line that starts with SITE_NOTES_MARKER, or -1.
+// Only a match at a line start counts, so the marker quoted inside a line
+// never moves the split.
+function markerOffset(text) {
+    if (text.startsWith(SITE_NOTES_MARKER)) return 0
+    const at = text.indexOf(`\n${SITE_NOTES_MARKER}`)
+    return at === -1 ? -1 : at + 1
+}
+
+async function readIfExists(file) {
+    try {
+        return await fs.readFile(file, 'utf-8')
+    } catch (err) {
+        if (err.code === 'ENOENT') return null
+        throw err
+    }
+}
+
+// The site's AGENTS.md with its Nera part replaced by the template's. The
+// template's line endings follow the site's, so a CRLF checkout stays CRLF.
+// null when the site file has no marker: then none of it is Nera's to touch.
+function spliceAgents(siteText, templateHead) {
+    const at = markerOffset(siteText)
+    if (at === -1) return null
+    const eol = siteText.slice(0, at).includes('\r\n') ? '\r\n' : '\n'
+    return templateHead.replace(/\r?\n/g, eol) + siteText.slice(at)
+}
+
+// Bring a site's AGENTS.md and CLAUDE.md in line with the scaffold template
+// in templateDir: create what is missing, refresh the Nera part of an
+// AGENTS.md that has the marker, leave a marker-less AGENTS.md and any
+// existing CLAUDE.md alone. Writes only on change, so a repeated run is a
+// no-op. Returns one { file, action } per file, action being `created`,
+// `updated`, `unchanged` or `skipped`; printing is the caller's job.
+export async function syncAgentFiles({ cwd = process.cwd(), templateDir }) {
+    const template = await fs.readFile(path.join(templateDir, 'AGENTS.md'), 'utf-8')
+    const templateAt = markerOffset(template)
+    if (templateAt === -1) {
+        throw new Error(
+            `The template's AGENTS.md (${templateDir}) has no ` +
+                `\`${SITE_NOTES_MARKER}\` line. This is a packaging bug in ` +
+                '@nera-static/nera, not a problem with your site.'
+        )
+    }
+
+    const agentsPath = path.join(cwd, 'AGENTS.md')
+    const agents = await readIfExists(agentsPath)
+    let agentsAction
+    if (agents === null) {
+        await fs.writeFile(agentsPath, template)
+        agentsAction = 'created'
+    } else {
+        const next = spliceAgents(agents, template.slice(0, templateAt))
+        if (next === null) {
+            agentsAction = 'skipped'
+        } else if (next === agents) {
+            agentsAction = 'unchanged'
+        } else {
+            await fs.writeFile(agentsPath, next)
+            agentsAction = 'updated'
+        }
+    }
+
+    const claudePath = path.join(cwd, 'CLAUDE.md')
+    let claudeAction = 'unchanged'
+    if ((await readIfExists(claudePath)) === null) {
+        await fs.copyFile(path.join(templateDir, 'CLAUDE.md'), claudePath)
+        claudeAction = 'created'
+    }
+
+    return [
+        { file: 'AGENTS.md', action: agentsAction },
+        { file: 'CLAUDE.md', action: claudeAction },
+    ]
+}

package/src/commands/update.js

@@ -2,6 +2,8 @@ import { execFileSync } from 'child_process'
 import fs from 'fs/promises'
 import fssync from 'fs'
 import path from 'path'
+import { syncAgentFiles, SITE_NOTES_MARKER } from '../agent-files.js'
+import { templateDir as packageTemplateDir } from '../scaffold.js'
 
 const defaultRunNpm = (npmArgs, cwd) =>
     execFileSync('npm', npmArgs, { cwd, stdio: 'inherit' })
@@ -45,7 +47,46 @@ function printLegacyGuidance() {
     console.log('\n👉 Run `nera update --migrate` to do it.')
 }
 
-async function migrateLegacy(cwd, pkg, runNpm) {
+// The scaffold template whose AGENTS.md / CLAUDE.md the site is synced to:
+// the one in the site's installed @nera-static/nera (read after npm has
+// updated it), so the instructions match the Nera version the site runs even
+// when a global or older `nera` performs the update. Falls back to the
+// running package's template when nothing is installed there or the installed
+// version predates 1.6.0, which shipped no AGENTS.md.
+export function agentTemplateDir(cwd, fallbackDir) {
+    const installed = path.join(cwd, 'node_modules', '@nera-static', 'nera', 'template')
+    return fssync.existsSync(path.join(installed, 'AGENTS.md')) ? installed : fallbackDir
+}
+
+const AGENT_FILE_MESSAGES = {
+    created: (file) => `  ✓ Created ${file}`,
+    updated: (file) => `  ✓ Refreshed the Nera part of ${file}`,
+    // Neutral on purpose: an existing CLAUDE.md is kept without comparing it.
+    unchanged: (file) => `  ✓ ${file} unchanged`,
+    skipped: (file) => `  ⚠️  Left ${file} alone: it has no \`${SITE_NOTES_MARKER}\` line`,
+}
+
+async function syncAndReportAgentFiles(cwd, fallbackDir) {
+    const dir = agentTemplateDir(cwd, fallbackDir)
+    const results = await syncAgentFiles({ cwd, templateDir: dir })
+    for (const { file, action } of results) {
+        console.log(AGENT_FILE_MESSAGES[action](file))
+    }
+    if (results.some(({ action }) => action === 'skipped')) {
+        // Relative inside the site, absolute for a global or npx-cached CLI,
+        // where a relative path would be a long run of `../`.
+        const template = path.join(dir, 'AGENTS.md')
+        const relative = path.relative(cwd, template)
+        const source = relative.startsWith('..') ? template : relative
+        console.log(
+            `   To let \`nera update\` keep Nera's instructions current, copy the \`${SITE_NOTES_MARKER}\`` +
+                ` line from ${source} directly above your own notes. Everything above that` +
+                ' line is then Nera\'s and is replaced on update; the line and everything below it stay yours.'
+        )
+    }
+}
+
+async function migrateLegacy(cwd, pkg, runNpm, templateDir) {
     console.log('🔧 Migrating this cloned site to the thin @nera-static/nera model...')
 
     pkg.dependencies = {
@@ -89,6 +130,7 @@ async function migrateLegacy(cwd, pkg, runNpm) {
 
     console.log('📦 Installing...')
     runNpm(['install'], cwd)
+    await syncAndReportAgentFiles(cwd, templateDir)
 
     console.log('✅ Migrated. Run `nera dev` to start.')
     if (movedPlugins) {
@@ -100,7 +142,13 @@ async function migrateLegacy(cwd, pkg, runNpm) {
 }
 
 export async function runUpdate(args = [], options = {}) {
-    const { cwd = process.cwd(), runNpm = defaultRunNpm } = options
+    // templateDir: the fallback scaffold template for AGENTS.md / CLAUDE.md
+    // (see agentTemplateDir); injectable so tests need no installed package.
+    const {
+        cwd = process.cwd(),
+        runNpm = defaultRunNpm,
+        templateDir = packageTemplateDir(),
+    } = options
 
     const pkg = JSON.parse(
         await fs.readFile(path.join(cwd, 'package.json'), 'utf-8')
@@ -109,7 +157,7 @@ export async function runUpdate(args = [], options = {}) {
 
     if (kind === 'legacy') {
         if (args.includes('--migrate') || args.includes('--yes')) {
-            await migrateLegacy(cwd, pkg, runNpm)
+            await migrateLegacy(cwd, pkg, runNpm, templateDir)
         } else {
             printLegacyGuidance()
         }
@@ -126,5 +174,6 @@ export async function runUpdate(args = [], options = {}) {
     const targets = neraDeps(pkg)
     console.log(`🔄 Updating Nera packages: ${targets.join(', ')}`)
     runNpm(['update', ...targets], cwd)
+    await syncAndReportAgentFiles(cwd, templateDir)
     console.log('✅ Up to date.')
 }