@nera-static/nera 1.11.1 → 1.13.0

package/README.md

@@ -122,13 +122,15 @@ A starter kit is a whole ready-to-edit site: sample pages, config, optional
 site-level `theme/` overrides, assets and the theme and plugins it depends on.
 `nera new` copies its `pages/`, `config/`, `theme/`, `assets/`, `plugins/` and
 `.neraignore` over the base template, adds its `dependencies` to the site's
-`package.json`, applies `--name` / `--lang`, installs, and prints the starter's
-README. After that the site owns the files; a starter has no update path (the
-theme it depends on still updates through npm).
+`package.json`, applies `--name` / `--lang`, installs, and prints the
+`## First steps` section of the starter's README (nothing, when it has none).
+After that the site owns the files; a starter has no update path (the theme it
+depends on still updates through npm).
 
 `--starter` takes:
 
-- a starter name: `blank` → `@nera-static/starter-blank`;
+- a starter name: `blank` → `@nera-static/starter-blank`, `blog` →
+  `@nera-static/starter-blog`;
 - a package name: `@acme/starter-shop`, or unscoped `nera-starter-shop`;
 - a GitHub URL: `https://github.com/owner/repo` (optionally `.git`, `#ref`),
   or `github:owner/repo#ref`;
@@ -159,8 +161,9 @@ default. Every question has a flag (`--starter`, `--name`, `--lang`); with
 `--yes`, or without a terminal (scripts, CI, AI agents), nothing is asked and
 `nera new` scaffolds the base template.
 
-The official starters are coming: `@nera-static/starter-blank` is the first,
-more will follow. Until they are on npm, use a local path or your own package.
+The official starters: `blank` (`@nera-static/starter-blank`, one accessible
+layout, no theme) and `blog` (`@nera-static/starter-blog`, a blog on
+`@nera-static/theme-blog` with tags, an archive, an Atom feed and a sitemap).
 
 ## Checking the built site
 
@@ -283,7 +286,7 @@ layout `nera new` scaffolds.
 
 ## Requirements
 
-Node.js 20.19 or later, or 22.12 or later.
+Node.js 22.12 or later (its bundled npm 10.9 or later).
 
 ## License
 

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.11.1",
+    "version": "1.13.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": {
-        "nera": "./bin/nera.js"
+        "nera": "bin/nera.js"
     },
     "files": [
         "bin",
@@ -30,14 +30,14 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/seebaermichi/nera-cli.git"
+        "url": "git+https://github.com/seebaermichi/nera-cli.git"
     },
     "bugs": {
         "url": "https://github.com/seebaermichi/nera-cli/issues"
     },
     "homepage": "https://github.com/seebaermichi/nera-cli#readme",
     "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=22.12.0"
     },
     "publishConfig": {
         "access": "public"

package/src/commands/new.js

@@ -1,4 +1,6 @@
 import {
+    assertNpmCanInstall,
+    probeNpmVersion,
     scaffoldProject,
     isCurrentDir,
     validateProjectName,
@@ -44,12 +46,13 @@ async function defaultPrompt(options) {
     return runPicker({ ...options, listStarters, validateSiteName, validateLang })
 }
 
-// `prompt`, `scaffold` and the streams are injectable for tests.
+// `prompt`, `scaffold`, `npmVersion` and the streams are injectable for tests.
 export async function runNew(args = [], {
     stdin = process.stdin,
     stdout = process.stdout,
     prompt = defaultPrompt,
     scaffold = scaffoldProject,
+    npmVersion = probeNpmVersion,
 } = {}) {
     const { projectName, yes, install, ...rest } = parseNewArgs(args)
     const options = Object.fromEntries(
@@ -63,6 +66,9 @@ export async function runNew(args = [], {
         if (options.theme !== undefined) validateThemeSpec(options.theme)
         if (options.name !== undefined) validateSiteName(options.name)
         if (options.lang !== undefined) validateLang(options.lang)
+        // An npm that would crash on install is refused before the
+        // questions too; scaffoldProject checks again for every caller.
+        if (install) assertNpmCanInstall(npmVersion())
         const answers = await prompt({
             input: stdin,
             output: stdout,

package/src/scaffold.js

@@ -293,11 +293,49 @@ async function addSkill(targetDir) {
     )
 }
 
+// npm before 10.9 (bundled with Node < 22.12) crashes in arborist on the
+// optional peer chain of vite 8, which every site installs (ROADMAP-ai.md,
+// slice 5, "the Node floor"). Checked before anything is written or asked.
+const MIN_NPM = [10, 9, 0]
+
+const defaultExecNpm = (args, options) => execFileSync('npm', args, options)
+
+// The installed npm's version, or null when it cannot be read (no npm on the
+// PATH, an unparseable answer): then nothing is refused, and `npm install`
+// reports its own error.
+export function probeNpmVersion(execNpm = defaultExecNpm) {
+    try {
+        const out = execNpm(['--version'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        const version = String(out).trim()
+        return /^\d+\.\d+\.\d+/.test(version) ? version : null
+    } catch {
+        return null
+    }
+}
+
+// Throws when `version` is an npm that cannot install a site; null passes.
+export function assertNpmCanInstall(version) {
+    if (version === null) return
+    const parts = version.split(/[.-]/).slice(0, 3).map(Number)
+    const i = parts.findIndex((n, j) => n !== MIN_NPM[j])
+    if (i === -1 || parts[i] > MIN_NPM[i]) return
+    throw new Error(
+        `npm ${version} cannot install a Nera site: it crashes on vite's ` +
+            'dependencies. Use Node.js 22.12 or later, which bundles npm 10.9, ' +
+            'or update npm with `npm i -g npm@10.9`, then run `nera new` ' +
+            'again. Nothing was written.'
+    )
+}
+
 // Scaffold a thin Nera site: copy the template, lay a starter kit over it if
 // one is given, name it, and (by default) install its dependencies. The one
 // code path for flags, the interactive picker and the future MCP tool
 // (ROADMAP-ai.md principle 4): everything comes in as plain options.
-// `fetchStarter(spec, { cwd })` → `{ dir, cleanup }` is injectable for tests.
+// `fetchStarter(spec, { cwd })` → `{ dir, cleanup }` and `execNpm(args,
+// options)` (execFileSync's shape) are injectable for tests.
 export async function scaffoldProject(projectName, options = {}) {
     const {
         install = true,
@@ -307,6 +345,7 @@ export async function scaffoldProject(projectName, options = {}) {
         name,
         lang,
         fetchStarter = defaultFetchStarter,
+        execNpm = defaultExecNpm,
     } = options
 
     // Everything is checked before anything is written.
@@ -321,6 +360,7 @@ export async function scaffoldProject(projectName, options = {}) {
     }
     if (name !== undefined) validateSiteName(name)
     if (lang !== undefined) validateLang(lang)
+    if (install) assertNpmCanInstall(probeNpmVersion(execNpm))
 
     const targetDir = path.resolve(cwd, inPlace ? '.' : projectName)
     if (inPlace) {
@@ -371,7 +411,7 @@ export async function scaffoldProject(projectName, options = {}) {
         // it resolved. A starter's dependencies are already in package.json.
         const themePkg = theme ? themePackageName(theme) : null
         const args = themePkg ? ['install', themePkg] : ['install']
-        execFileSync('npm', args, { cwd: targetDir, stdio: 'inherit' })
+        execNpm(args, { cwd: targetDir, stdio: 'inherit' })
     }
 
     // `npm run dev`, not `nera dev`: it works without a global `nera`.
@@ -381,7 +421,7 @@ export async function scaffoldProject(projectName, options = {}) {
         'npm run dev',
     ]
     console.log('✅ Done!')
-    if (readme) console.log(`\n${readme.replace(/\n*$/, '')}\n`)
+    if (readme) console.log(`\n${readme}\n`)
     console.log(
         `👉 Next steps:\n${nextSteps.map((l) => `  ${l}\n`).join('')}`
     )

package/src/starter.js

@@ -170,7 +170,7 @@ const OWN_PACKAGE = '@nera-static/nera'
 
 // Lay the starter over a scaffolded site, file by file (the starter wins),
 // and merge its `dependencies` into the site's package.json. Symlinks are not
-// copied. Returns the starter's README text, or null.
+// copied. Returns the "First steps" section of the starter's README, or null.
 export async function applyStarter(targetDir, starterDir) {
     const pkg = await readStarterManifest(starterDir)
     const notLink = async (src) => !(await fs.lstat(src)).isSymbolicLink()
@@ -200,12 +200,48 @@ export async function applyStarter(targetDir, starterDir) {
     console.log(`  ✓ Applied the "${label}" starter${pkg.name ? ` (${pkg.name})` : ''}`)
 
     try {
-        return await fs.readFile(path.join(starterDir, 'README.md'), 'utf-8')
+        return firstStepsSection(await fs.readFile(path.join(starterDir, 'README.md'), 'utf-8'))
     } catch {
         return null
     }
 }
 
+const FIRST_STEPS = /^## +first steps *#* *$/i
+const SECTION_END = /^#{1,2} /
+const FENCE = /^ {0,3}(`{3,}|~{3,})/
+
+// The `## First steps` section of a starter README, from its heading to the
+// next `#`/`## ` heading or the end, trimmed; null when there is none. Headings
+// inside fenced code blocks do not count. Line endings come back as `\n`.
+export function firstStepsSection(readme) {
+    const lines = readme.replace(/\r\n?/g, '\n').split('\n')
+    let fence = null
+    let start = -1
+    let end = lines.length
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]
+        const marker = FENCE.exec(line)?.[1]
+        if (fence) {
+            // A fence closes on the same character, at least as long, alone on its line.
+            const closes = marker && marker[0] === fence[0] && marker.length >= fence.length
+            if (closes && line.trim() === marker) fence = null
+            continue
+        }
+        if (marker) {
+            fence = marker
+            continue
+        }
+        if (start < 0) {
+            if (FIRST_STEPS.test(line)) start = i
+        } else if (SECTION_END.test(line)) {
+            end = i
+            break
+        }
+    }
+    if (start < 0) return null
+    return lines.slice(start, end).join('\n').trim()
+}
+
 const REGISTRY_SEARCH =
     'https://registry.npmjs.org/-/v1/search?text=keywords:nera-starter&size=50'
 const OFFICIAL_PREFIX = '@nera-static/'

package/src/starters.js

@@ -9,4 +9,10 @@ export const BUNDLED_STARTERS = [
         label: 'Blank',
         description: 'The smallest Nera starter: a home page, imprint and privacy placeholders, and one accessible layout. No theme, no plugins, no JavaScript.',
     },
+    {
+        name: 'blog',
+        package: '@nera-static/starter-blog',
+        label: 'Blog',
+        description: 'A ready-to-edit Nera blog on @nera-static/theme-blog: three sample posts, tags, an archive by year, prev/next, an Atom feed, a sitemap, code blocks, navigation, responsive images, social links and imprint and privacy placeholders. No JavaScript.',
+    },
 ]

package/template/package.json

@@ -6,7 +6,9 @@
     "scripts": {
         "dev": "nera dev",
         "build": "nera build",
-        "serve": "nera serve"
+        "serve": "nera serve",
+        "validate": "nera validate",
+        "check": "nera build --check"
     },
     "dependencies": {
         "@nera-static/nera": "^1.0.0"