@nera-static/nera 1.14.0 → 1.15.0

package/README.md

@@ -31,17 +31,21 @@ 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. |
 
 A scaffolded site is a thin project — no vendored engine, no clone. It lists one
-dependency and its scripts call the CLI:
+dependency, a caret range starting at the version of the CLI that created it,
+and its scripts call the CLI:
 
 ```jsonc
 {
-  "scripts": { "dev": "nera dev", "build": "nera build", "serve": "nera serve" },
-  "dependencies": { "@nera-static/nera": "^1.0.0" }
+  "scripts": {
+    "dev": "nera dev", "build": "nera build", "serve": "nera serve",
+    "validate": "nera validate", "check": "nera build --check"
+  },
+  "dependencies": { "@nera-static/nera": "^1.14.1" }
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.14.0",
+    "version": "1.15.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/commands/update.js

@@ -3,7 +3,7 @@ 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'
+import { ownRange, templateDir as packageTemplateDir } from '../scaffold.js'
 import { installedSkillDir, skillSourceDir, syncSkill } from '../skill.js'
 
 const defaultRunNpm = (npmArgs, cwd) =>
@@ -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.
@@ -107,7 +179,7 @@ async function migrateLegacy(cwd, pkg, runNpm, templateDir, skillDir) {
 
     pkg.dependencies = {
         ...pkg.dependencies,
-        '@nera-static/nera': '^1.0.0',
+        '@nera-static/nera': ownRange(),
     }
 
     pkg.scripts = {
@@ -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/src/scaffold.js

@@ -138,6 +138,14 @@ const isStarterTemplate = async (file) =>
 export const templateDir = () =>
     path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'template')
 
+// The range a new or migrated site depends on: this CLI's own version, so the
+// site never claims to work with an older one that lacks what set it up
+// (starters, `nera check`, the `validate`/`check` scripts).
+export const ownRange = () => {
+    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+    return `^${JSON.parse(fssync.readFileSync(pkgPath, 'utf-8')).version}`
+}
+
 async function copyDir(src, dest, { skipStarters = false } = {}) {
     await fs.mkdir(dest, { recursive: true })
     for (const entry of await fs.readdir(src, { withFileTypes: true })) {
@@ -165,6 +173,7 @@ async function personalize(targetDir, projectName) {
     const pkgPath = path.join(targetDir, 'package.json')
     const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'))
     pkg.name = projectName
+    pkg.dependencies = { ...pkg.dependencies, '@nera-static/nera': ownRange() }
     await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 4)}\n`)
     console.log(`  ✓ Configured project as "${projectName}"`)
 }