@nera-static/nera 1.5.1 → 1.7.0

package/README.md

@@ -16,18 +16,19 @@ npm run dev            # or: nera dev
 
 Already in the folder the site should live in? `nera new .` scaffolds into the
 current folder instead. The folder must be empty apart from dotfiles such as
-`.git` (an existing `.gitignore` is kept), and the package is named after the
-folder (`My Bakery` → `my-bakery`).
+`.git` and an `AGENTS.md`/`CLAUDE.md` an AI assistant may have written first
+(an existing `.gitignore`, `AGENTS.md` or `CLAUDE.md` is kept), and the
+package is named after the folder (`My Bakery` → `my-bakery`).
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--theme <name>` to start from a theme. `nera new .` scaffolds into the current, empty folder. |
+| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--theme <name>` to start from a theme. `nera new .` scaffolds into the current, empty folder (dotfiles, `AGENTS.md` and `CLAUDE.md` allowed). |
 | `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. |
 
@@ -41,6 +42,36 @@ dependency and its scripts call the CLI:
 }
 ```
 
+## Instructions for AI assistants
+
+Every scaffolded site carries an `AGENTS.md`, the file Codex, Cursor, Copilot
+and other assistants read first, and a `CLAUDE.md` holding the single line
+`@AGENTS.md`, so Claude Code loads the same text. `AGENTS.md` covers what
+Nera is, the folder map, the commands, the common traps, and the check loop:
+`nera validate`, then `nera build --check`, after every change.
+
+It ends with a **Notes for this site** section for your own instructions —
+brand voice, pages not to touch, where the site is deployed. It starts below
+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.5.1",
+    "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.')
 }

package/src/scaffold.js

@@ -62,11 +62,18 @@ export function projectNameFromDir(dir) {
         : validateProjectName(name)
 }
 
+// Files an AI assistant may have written before running `nera new .`. They
+// do not make the folder count as non-empty, and the user's copy is kept.
+// Exact names only, matched case-sensitively.
+const AGENT_FILES = new Set(['AGENTS.md', 'CLAUDE.md'])
+
 // In-place scaffolding only goes ahead in an empty folder. Dotfiles such as
 // `.git` or an editor folder do not count: `git init` first is the usual way
-// to start a project.
+// to start a project. Neither do AGENT_FILES.
 async function assertEmptyDir(dir) {
-    const entries = (await fs.readdir(dir)).filter((n) => !n.startsWith('.'))
+    const entries = (await fs.readdir(dir)).filter(
+        (n) => !n.startsWith('.') && !AGENT_FILES.has(n)
+    )
     if (entries.length > 0) {
         throw new Error(
             `The current folder is not empty (${entries.slice(0, 3).join(', ')}` +
@@ -136,8 +143,9 @@ async function copyDir(src, dest, { skipStarters = false } = {}) {
         } else if (skipStarters && (await isStarterTemplate(from))) {
             continue
         } else if (fssync.existsSync(to)) {
-            // Only in place, and then only a dotfile such as .gitignore can be
-            // there already (assertEmptyDir): the user's copy wins.
+            // Only in place, and then only a dotfile such as .gitignore, or
+            // AGENTS.md / CLAUDE.md, can be there already (assertEmptyDir):
+            // the user's copy wins.
             console.log(`  • Kept your existing ${path.basename(to)}`)
         } else {
             await fs.copyFile(from, to)

package/template/AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on this site. People are welcome to
+read them too.
+
+## What this is
+
+This site is built with [Nera](https://nera.js.org), a static site generator:
+Markdown pages plus Pug templates in, plain HTML out. Nera is not Eleventy,
+Hugo, Astro or Jekyll, so do not apply their conventions here. The docs are
+at https://nera.js.org.
+
+## Folder map
+
+- `pages/` — the content: one Markdown file with YAML frontmatter per page
+- `theme/views/` — the Pug templates (`layouts/`, `pages/`, and `vendor/`
+  for copied plugin templates)
+- `theme/assets/` — CSS, JavaScript, images and fonts, copied into
+  `public/` on every build
+- `config/` — YAML settings: `app.yaml` for the site, `<plugin>.yaml` for
+  each plugin
+- `src/plugins/<name>/index.js` — local plugins for this site only (optional;
+  another folder can be set with `folders.plugins` in `config/app.yaml`)
+- `public/` — the generated site. **Never edit it**: every build deletes it
+  and writes it again
+
+## Commands
+
+- `npm run dev` — build, serve on http://localhost:3000 and rebuild on
+  every change
+- `npm run build` — render `pages/` into `public/`
+- `npx nera validate` — check pages, layouts, includes and YAML before a build
+- `npx nera build --check` — build, then check the built `public/` for
+  accessibility, privacy and legal issues (`npx nera check` checks without
+  building)
+
+## After every change
+
+1. Run `npx nera validate` and fix every error it reports.
+2. Run `npx nera build --check` and fix what it reports.
+
+`nera validate` names the file and line of a broken layout or include and
+finds pages the build would skip silently. Run it first.
+
+## How Nera works (and where it trips agents up)
+
+- **Pages are Markdown.** Write prose in Markdown, not HTML. Page structure
+  and markup shared between pages belong in `theme/views/`.
+- **URLs end in `.html`.** `pages/a/b.md` becomes `public/a/b.html` and is
+  linked as `/a/b.html`; `pages/index.md` is `/index.html`. There are no
+  pretty URLs such as `/a/b/`.
+- **A page needs `layout`.** The `layout` key in a page's frontmatter names a
+  file under `theme/views/`; the pages this site was created with use
+  `pages/default.pug`. A page without `layout` is not rendered and the build
+  says nothing; `nera validate` warns (`layout-missing`). Renaming or deleting
+  a layout breaks every page that uses it.
+- **The page body.** The rendered Markdown reaches the template as `content`.
+  Without a theme, `theme/views/pages/default.pug` prints it with
+  `main !{ content }` inside `block content`; with a theme, the theme's layout
+  may already hold the `<main>`. A page has exactly one `<main>`: check the
+  layout and the page template before adding one.
+- **`public/` is wiped on every build.** Put source files in `pages/`,
+  `theme/` or `config/`; anything written into `public/` by hand is lost.
+- **Site files override theme files.** If `config/app.yaml` sets `theme:`,
+  the layouts come from that theme (a package or a folder), and a file in
+  `theme/views/` or `theme/assets/` replaces the theme's file at the same
+  path.
+- **Translations.** Templates call `t('key')`, which reads
+  `translations.<lang>.key` from `config/app.yaml` (the page's `lang`, else
+  the site's).
+
+## Plugins: look for one before writing a feature
+
+Features come from npm packages named `@nera-static/plugin-*`. Install one with
+`npm install`, and Nera loads it on the next build; there is nothing to
+register. Most read optional settings from `config/<name>.yaml` (the plugin's
+README shows the keys). Plugin catalog:
+https://github.com/seebaermichi/nera/blob/main/PLUGINS.md
+
+Check the catalog before hand-writing navigation, a contact form, tags, search,
+pagination or image handling. Two that sites often need:
+
+- `@nera-static/plugin-contact-form` — a contact form that opens the visitor's
+  mail client (`mailto:`). No backend and no form service; configured in
+  `config/contact-form.yaml`.
+- `@nera-static/plugin-navigation` — menus from `config/navigation.yaml`.
+
+Plugin templates are not used automatically. Copy them into the site first,
+then include them by hand in your own template:
+
+- `npx nera-contact-form` copies the form to
+  `theme/views/vendor/plugin-contact-form/` (and its script to
+  `theme/assets/js/`); include it with
+  `include /vendor/plugin-contact-form/contact-form`
+- `npx nera-navigation` copies the menus to
+  `theme/views/vendor/plugin-navigation/`
+
+The copy is skipped when the target folder already exists, so later plugin
+updates do not reach it; `--force` overwrites the copy.
+
+## Preview
+
+`npm run dev` keeps running until it is stopped. If you start it in the
+background, stop that process yourself when you are done, by its process ID.
+Never kill processes by name (`pkill -f nera`), which stops other people's
+servers too. If port 3000 is taken, the server picks another one and prints
+the URL.
+
+## Getting online
+
+`npm run build` writes the finished site into `public/`. That folder is what
+gets deployed: upload its contents to any static web host.
+
+<!-- nera:site-notes — everything below this line belongs to the site owner; `nera update` keeps it as it is -->
+## Notes for this site
+
+Add what an agent should know about this particular site: its audience, tone,
+languages, pages that must not change, the hosting.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md