@nera-static/nera 1.5.0 → 1.6.0

package/README.md

@@ -16,14 +16,15 @@ 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. |
@@ -41,6 +42,20 @@ 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.
+
 ## Starting from a theme
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.5.0",
+    "version": "1.6.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/scaffold.js

@@ -34,27 +34,46 @@ const CURRENT_DIR = new Set(['.', './'])
 
 export const isCurrentDir = (projectName) => CURRENT_DIR.has(projectName)
 
+// Letters NFKD does not decompose into a base letter plus an accent.
+const LETTER_FOLDS = { ß: 'ss', æ: 'ae', œ: 'oe', ø: 'o', ł: 'l', đ: 'd' }
+
+// npm refuses these names outright, and longer ones than this.
+const NPM_RESERVED = new Set(['node_modules', 'favicon.ico'])
+const NPM_MAX_LENGTH = 214
+
 // The package name for a site scaffolded in place, derived from the folder's
-// basename and normalised until it passes validateProjectName: accents
-// dropped (`Bäckerei` → `backerei`), lower-case, each run of other characters
-// → one `-`, no leading dot, dash or underscore.
+// basename and normalised until it passes validateProjectName and npm's own
+// rules: accents dropped (`Bäckerei` → `backerei`, `Straße` → `strasse`),
+// lower-case, each run of other characters → one `-`, no leading dot, dash or
+// underscore, at most 214 characters. `nera-site` when nothing usable is left.
 export function projectNameFromDir(dir) {
     const name = path
         .basename(path.resolve(dir))
+        .toLowerCase()
+        .replace(/[ßæœøłđ]/g, (c) => LETTER_FOLDS[c])
         .normalize('NFKD')
         .replace(/[\u0300-\u036f]/g, '')
-        .toLowerCase()
         .replace(/[^a-z0-9._-]+/g, '-')
         .replace(/^[._-]+/, '')
-        .replace(/-+$/, '')
-    return name === '' ? 'nera-site' : validateProjectName(name)
+        .slice(0, NPM_MAX_LENGTH)
+        .replace(/[-.]+$/, '')
+    return name === '' || NPM_RESERVED.has(name)
+        ? 'nera-site'
+        : 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(', ')}` +
@@ -124,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)
@@ -195,8 +215,15 @@ export async function scaffoldProject(projectName, options = {}) {
         execFileSync('npm', args, { cwd: targetDir, stdio: 'inherit' })
     }
 
+    // `npm run dev`, not `nera dev`: it works without a global `nera`.
+    const nextSteps = [
+        ...(inPlace ? [] : [`cd ${projectName}`]),
+        ...(install ? [] : ['npm install']),
+        'npm run dev',
+    ]
     console.log('✅ Done!')
-    const cdLine = inPlace ? '' : `  cd ${projectName}\n`
-    console.log(`👉 Next steps:\n${cdLine}  nera dev\n`)
+    console.log(
+        `👉 Next steps:\n${nextSteps.map((l) => `  ${l}\n`).join('')}`
+    )
     return targetDir
 }

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