@nera-static/nera 1.14.1 → 1.16.0

package/README.md

@@ -31,7 +31,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. `--json` prints the result as one JSON object (see [Machine-readable output](#machine-readable-output)). |
 | `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, then create a missing `AGENTS.md`/`CLAUDE.md` and refresh the Nera part of `AGENTS.md` and the `nera` skill (see [Instructions for AI assistants](#instructions-for-ai-assistants)). On a legacy cloned site, `nera update --migrate` converts it to the thin model. |
+| `nera update` | Update the site's Nera packages and raise their caret ranges in `package.json` (and `package-lock.json`) to the installed versions, then create a missing `AGENTS.md`/`CLAUDE.md` and refresh the Nera part of `AGENTS.md` and the `nera` skill (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. `--json` for machine-readable output. |
 | `nera check` | Check the built `public/` for accessibility, privacy and legal-notice problems (see below). Build first. `--json` for machine-readable output. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.14.1",
+    "version": "1.16.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/skills/nera/recipes/business-site.md

@@ -11,12 +11,15 @@ imprint and privacy, with a menu on every page.
    live URL, e.g. `https://example.com`) once the domain is known.
 3. Write one Markdown page per topic, each with `layout: pages/default.pug`,
    a `title` and a `description`: `pages/index.md`, `pages/about.md`,
-   `pages/services.md`, `pages/opening-hours.md`, `pages/contact.md`,
-   `pages/imprint.md`, `pages/privacy.md`. Opening hours fit a Markdown
-   table.
+   `pages/services.md`, `pages/opening-hours.md`, `pages/contact.md`.
+   Opening hours fit a Markdown table. A new site already has
+   `pages/imprint.md` and `pages/privacy.md` as placeholders, linked from
+   the layout's footer: replace their text, or write them if they are
+   missing.
 4. Menu: `npm install @nera-static/plugin-navigation`, list the pages in
    `config/navigation.yaml` (`href` ending in `.html`, `name`; groups such
-   as `main:` and `footer:` for a footer menu with imprint and privacy), run
+   as `main:` and `footer:`; a footer menu replaces the layout's own
+   imprint and privacy links, so keep only one of the two), run
    `npx nera-navigation` and include a menu in
    `theme/views/layouts/layout.pug` (see the plugin README for the mixins).
 5. Contact form: follow [contact-form](contact-form.md).

package/src/commands/update.js

@@ -18,6 +18,78 @@ export function neraDeps(pkg) {
     )
 }
 
+// The caret range `range` raised to the installed `version`, or null when it
+// stays: only a plain `^x.y.z` with x ≥ 1, only upwards, never across a major.
+// Exact, tilde, tag, git and 0.x ranges are the user's choice and stay as
+// they are. `npm update` installs within the range but never rewrites it.
+export function raisedRange(range, version) {
+    const from = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range ?? '')
+    const to = /^(\d+)\.(\d+)\.(\d+)$/.exec(version ?? '')
+    if (!from || !to) return null
+    const [a, b] = [from, to].map((m) => m.slice(1).map(Number))
+    if (a[0] < 1 || a[0] !== b[0]) return null
+    const newer = b[1] > a[1] || (b[1] === a[1] && b[2] > a[2])
+    return newer ? `^${version}` : null
+}
+
+const indentOf = (text) => /^[ \t]+(?=")/m.exec(text)?.[0] ?? '  '
+
+// Raise the site's caret ranges of `names` to what is installed in its
+// node_modules, keeping the file's own indentation, and the same ranges in
+// the root entry of package-lock.json, so the two stay in sync. Returns the
+// changes as [name, from, to].
+export async function raiseRanges(cwd, names) {
+    const pkgPath = path.join(cwd, 'package.json')
+    const text = await fs.readFile(pkgPath, 'utf-8')
+    const pkg = JSON.parse(text)
+    const raised = {}
+    const changes = []
+    for (const field of ['dependencies', 'devDependencies']) {
+        for (const name of names) {
+            const range = pkg[field]?.[name]
+            if (typeof range !== 'string') continue
+            let version
+            try {
+                const installed = path.join(cwd, 'node_modules', ...name.split('/'), 'package.json')
+                version = JSON.parse(await fs.readFile(installed, 'utf-8')).version
+            } catch {
+                continue
+            }
+            const to = raisedRange(range, version)
+            if (to) {
+                pkg[field][name] = to
+                raised[field] = { ...raised[field], [name]: [range, to] }
+                changes.push([name, range, to])
+            }
+        }
+    }
+    if (changes.length === 0) return changes
+    await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, indentOf(text))}\n`)
+
+    const lockPath = path.join(cwd, 'package-lock.json')
+    let lockText
+    try {
+        lockText = await fs.readFile(lockPath, 'utf-8')
+    } catch {
+        return changes
+    }
+    const lock = JSON.parse(lockText)
+    const root = lock.packages?.['']
+    let lockChanged = false
+    for (const [field, entries] of Object.entries(raised)) {
+        for (const [name, [from, to]] of Object.entries(entries)) {
+            if (root?.[field]?.[name] === from) {
+                root[field][name] = to
+                lockChanged = true
+            }
+        }
+    }
+    if (lockChanged) {
+        await fs.writeFile(lockPath, `${JSON.stringify(lock, null, indentOf(lockText))}\n`)
+    }
+    return changes
+}
+
 // A THIN site depends on @nera-static/nera and carries no engine source.
 // A LEGACY site is a clone of the old generator: it vendors the engine under
 // src/ and has no @nera-static/nera dependency — the case `nera update` migrates.
@@ -193,6 +265,9 @@ export async function runUpdate(args = [], options = {}) {
     const targets = neraDeps(pkg)
     console.log(`🔄 Updating Nera packages: ${targets.join(', ')}`)
     runNpm(['update', ...targets], cwd)
+    for (const [name, from, to] of await raiseRanges(cwd, targets)) {
+        console.log(`  ✓ ${name}: ${from} → ${to} in package.json`)
+    }
     await syncAndReportAgentFiles(cwd, templateDir)
     await syncAndReportSkill(cwd, skillDir)
     console.log('✅ Up to date.')

package/template/AGENTS.md

@@ -61,10 +61,9 @@ finds pages the build would skip silently. Run it first.
   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.
+  Without a theme, `theme/views/pages/default.pug` prints it in a `main`
+  element inside `block content`; with a theme, the theme's layout may hold
+  the `<main>`. A page has exactly one `<main>`: check 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:`,
@@ -115,7 +114,8 @@ 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.
+gets deployed: upload its contents to any static web host. Replace the
+imprint and privacy placeholders in `pages/` first, if the site has them.
 
 <!-- nera:site-notes — everything below this line belongs to the site owner; `nera update` keeps it as it is -->
 ## Notes for this site

package/template/config/app.yaml

@@ -6,3 +6,6 @@ translations:
   en:
     app_description: A static site built with Nera
     app_keywords: nera, static site generator
+    skip_to_content: Skip to content
+    imprint: Imprint
+    privacy: Privacy

package/template/pages/imprint.md

@@ -0,0 +1,21 @@
+---
+layout: pages/default.pug
+title: Imprint
+description: Imprint placeholder — replace it with your own legal notice
+---
+# Imprint
+
+**This is a placeholder.** It is not a legal notice. Replace this page with your
+own imprint before you publish the site; if you are unsure what you need, ask a
+lawyer.
+
+## To do
+
+What an imprint typically names (the exact duty depends on your country and on
+what the site does):
+
+- who runs the site: full name, or company name and legal form
+- a postal address where you can be reached
+- fast ways to contact you: email address, and often a phone number
+- the person responsible for the content, if the law asks for one
+- register entries and VAT ID, if your business has them

package/template/pages/privacy.md

@@ -0,0 +1,23 @@
+---
+layout: pages/default.pug
+title: Privacy
+description: Privacy policy placeholder — replace it with your own privacy policy
+---
+# Privacy
+
+**This is a placeholder.** It is not a privacy policy. Replace this page with
+your own privacy policy before you publish the site; if you are unsure what you
+need, ask a lawyer.
+
+## To do
+
+What a privacy policy typically covers (the exact duty depends on your country
+and on what the site does):
+
+- who is responsible for the data processing, and how to contact them
+- what your hosting provider logs (such as IP addresses) and for how long
+- every plugin, form, font, embed or analytics tool that processes visitor
+  data, its purpose and legal basis
+- how long data is kept
+- the visitor's rights (access, correction, deletion, objection) and where to
+  complain

package/template/theme/views/layouts/layout.pug

@@ -9,6 +9,14 @@ html(lang=app.lang)
     meta(name="keywords", content=`${ meta.keywords || t('app_keywords') }`)
     meta(name="generator" content="nera")
     meta(name="robots" content=`${ meta.robots || app.robots }`)
+    style.
+      .skip-link { position: absolute; left: -9999px; }
+      .skip-link:focus { position: static; }
 
   body
+    a.skip-link(href="#main") #{ t('skip_to_content') }
     block content
+    footer
+      a(href="/imprint.html") #{ t('imprint') }
+      = ' · '
+      a(href="/privacy.html") #{ t('privacy') }

package/template/theme/views/pages/default.pug

@@ -2,4 +2,4 @@
 extends ../layouts/layout
 
 block content
-  main !{ content }
+  main#main !{ content }