@nera-static/nera 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Michael Becker]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @nera-static/nera
+
+The Nera CLI — scaffold, build, preview and update a [Nera](https://github.com/seebaermichi/nera)
+static site with a single command. It runs over the [`@nera-static/core`](https://github.com/seebaermichi/nera)
+engine and is the one package a Nera site depends on.
+
+## Quick start
+
+```bash
+npx @nera-static/nera new my-site
+cd my-site
+npm run dev            # or: nera dev
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). |
+| `nera build` | Render `pages/` → `public/`. |
+| `nera dev` | Build, serve `public/`, and rebuild on change with live reload. |
+| `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. |
+
+A scaffolded site is a thin project — no vendored engine, no clone. It lists one
+dependency and its scripts call the CLI:
+
+```jsonc
+{
+  "scripts": { "dev": "nera dev", "build": "nera build", "serve": "nera serve" },
+  "dependencies": { "@nera-static/nera": "^1.0.0" }
+}
+```
+
+## Migrating a cloned (legacy) site
+
+Older Nera sites were git clones that vendored the engine under `src/`. Inside
+such a site run:
+
+```bash
+nera update --migrate
+```
+
+It adds `@nera-static/nera`, rewrites the scripts, removes the vendored `src/`
+engine and root `index.js`, and installs — leaving your `pages/`, `config/` and
+`theme/` untouched. Local plugins in `src/plugins/` are moved to `plugins/`.
+
+## Requirements
+
+Node.js >= 20.
+
+## License
+
+MIT

package/bin/nera.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { runNew } from '../src/commands/new.js'
+import { runBuild } from '../src/commands/build.js'
+import { runDev } from '../src/commands/dev.js'
+import { runServe } from '../src/commands/serve.js'
+import { runUpdate } from '../src/commands/update.js'
+import { runValidate } from '../src/commands/validate.js'
+
+const [, , command, ...rest] = process.argv
+
+const usage = `Nera — the static site generator CLI
+
+Usage:
+  nera new <name>    scaffold a new Nera site
+  nera build         render pages/ → public/
+  nera dev           build, serve and live-reload
+  nera serve         serve the built public/ folder
+  nera update        update Nera packages (or migrate a cloned site with --migrate)
+  nera validate      check the site (layouts, includes, YAML) before publish
+`
+
+try {
+    switch (command) {
+    case 'new':
+        await runNew(rest)
+        break
+    case 'build':
+        await runBuild(rest)
+        break
+    case 'dev':
+        await runDev(rest)
+        break
+    case 'serve':
+        await runServe(rest)
+        break
+    case 'update':
+        await runUpdate(rest)
+        break
+    case 'validate':
+        process.exit(runValidate())
+        break
+    default:
+        console.log(usage)
+        // No command → help (exit 0); an unknown command → error (exit 1).
+        process.exit(command ? 1 : 0)
+    }
+} catch (error) {
+    console.error('❌', error.message)
+    process.exit(1)
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@nera-static/nera",
+    "version": "1.0.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"
+    },
+    "files": [
+        "bin",
+        "src",
+        "template"
+    ],
+    "scripts": {
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "test": "vitest",
+        "prepare": "husky"
+    },
+    "keywords": [
+        "nera",
+        "static-site-generator",
+        "cli",
+        "scaffolding",
+        "ssg",
+        "jamstack"
+    ],
+    "author": "Michael Becker",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "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.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@nera-static/core": "^4.9.0",
+        "@nera-static/validate": "^1.0.0",
+        "chokidar": "^5.0.0",
+        "semver": "^7.8.5",
+        "vite": "^8.1.5"
+    },
+    "devDependencies": {
+        "eslint": "^9.17.0",
+        "husky": "^9.1.7",
+        "vitest": "^3.2.4"
+    }
+}

package/src/commands/build.js

@@ -0,0 +1,8 @@
+import run from '@nera-static/core'
+
+// Render the current site (pages/ → public/) using the shared engine. `run`
+// reads config and folders relative to the current working directory, so this
+// builds whichever site the CLI is invoked in.
+export async function runBuild() {
+    await run()
+}

package/src/commands/dev.js

@@ -0,0 +1,65 @@
+import fssync from 'fs'
+import run from '@nera-static/core'
+import { startServer } from './serve.js'
+
+// Build once, serve `public/`, then rebuild on any change to the site's
+// sources. `run()` already copies assets as part of a build, so a single
+// watcher over pages/, config/ and the presentation folder covers everything —
+// no separate asset-copy watcher (this replaces the old `concurrently` script
+// that chained render + vite + watch-assets + nodemon).
+//
+// This is the code form of the previous npm-script orchestration. chokidar is
+// imported lazily so loading this module does not require it to be installed.
+export async function runDev(args = []) {
+    const port = parsePort(args)
+
+    await run()
+    const server = await startServer(port)
+    server.printUrls()
+
+    const { default: chokidar } = await import('chokidar')
+
+    // Presentation lives under theme/ in the current layout, or the deprecated
+    // root views/ on an unmigrated site — watch whichever exists.
+    const watchDirs = [
+        'pages',
+        'config',
+        fssync.existsSync('theme') ? 'theme' : 'views',
+    ].filter((d) => fssync.existsSync(d))
+
+    // Serialise rebuilds: coalesce changes that land mid-build into one re-run.
+    let building = false
+    let queued = false
+    const rebuild = async () => {
+        if (building) {
+            queued = true
+            return
+        }
+        building = true
+        try {
+            await run()
+        } catch (err) {
+            console.error('❌ Build error:', err.message)
+        }
+        building = false
+        if (queued) {
+            queued = false
+            await rebuild()
+        }
+    }
+
+    chokidar
+        .watch(watchDirs, { ignoreInitial: true })
+        .on('all', async (event, filePath) => {
+            console.log(`↻ ${event} ${filePath} — rebuilding`)
+            await rebuild()
+        })
+
+    return server
+}
+
+const parsePort = (args) => {
+    const i = args.indexOf('--port')
+    const val = i >= 0 ? Number(args[i + 1]) : NaN
+    return Number.isInteger(val) ? val : 3000
+}

package/src/commands/new.js

@@ -0,0 +1,7 @@
+import { scaffoldProject } from '../scaffold.js'
+
+export async function runNew(args = []) {
+    const projectName = args.find((a) => !a.startsWith('-'))
+    const install = !args.includes('--no-install')
+    await scaffoldProject(projectName, { install })
+}

package/src/commands/serve.js

@@ -0,0 +1,26 @@
+// Serve the already-built `public/` folder with Vite (static preview, no
+// rebuild). Vite is imported lazily so merely loading this module — as the CLI
+// dispatcher and the tests do — does not require Vite to be installed; it is
+// only needed when `serve`/`dev` actually run.
+
+const parsePort = (args) => {
+    const i = args.indexOf('--port')
+    const val = i >= 0 ? Number(args[i + 1]) : NaN
+    return Number.isInteger(val) ? val : 3000
+}
+
+export async function startServer(port = 3000, open = true) {
+    const { createServer } = await import('vite')
+    const server = await createServer({
+        root: 'public',
+        server: { port, open, watch: { usePolling: true } },
+    })
+    await server.listen()
+    return server
+}
+
+export async function runServe(args = []) {
+    const server = await startServer(parsePort(args))
+    server.printUrls()
+    return server
+}

package/src/commands/update.js

@@ -0,0 +1,130 @@
+import { execFileSync } from 'child_process'
+import fs from 'fs/promises'
+import fssync from 'fs'
+import path from 'path'
+
+const defaultRunNpm = (npmArgs, cwd) =>
+    execFileSync('npm', npmArgs, { cwd, stdio: 'inherit' })
+
+// The Nera packages a site consumes, so `nera update` bumps only those and
+// leaves the user's other dependencies alone.
+export function neraDeps(pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+    return Object.keys(deps).filter(
+        (name) => name === '@nera-static/nera' || name.startsWith('@nera-static/')
+    )
+}
+
+// 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.
+export function classifyProject(pkg, cwd = process.cwd()) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+    if (deps['@nera-static/nera']) return 'thin'
+
+    const vendorsEngine =
+        fssync.existsSync(path.join(cwd, 'src', 'core.js')) &&
+        fssync.existsSync(path.join(cwd, 'src', 'render.js'))
+    if (vendorsEngine) return 'legacy'
+
+    return 'unknown'
+}
+
+function printLegacyGuidance() {
+    console.log(
+        '🔧 This is a legacy Nera site — a clone that vendors the engine under `src/`.'
+    )
+    console.log(
+        '   `nera update` can convert it to the thin @nera-static/nera model:'
+    )
+    console.log('     • add @nera-static/nera as a dependency')
+    console.log('     • rewrite scripts to `nera build`/`dev`/`serve`')
+    console.log('     • remove the vendored `src/` engine and root `index.js`')
+    console.log('     • run `npm install`')
+    console.log('   Your pages/, config/ and theme/ are left untouched.')
+    console.log('\n👉 Run `nera update --migrate` to do it.')
+}
+
+async function migrateLegacy(cwd, pkg, runNpm) {
+    console.log('🔧 Migrating this cloned site to the thin @nera-static/nera model...')
+
+    pkg.dependencies = {
+        ...pkg.dependencies,
+        '@nera-static/nera': '^1.0.0',
+    }
+
+    pkg.scripts = {
+        ...pkg.scripts,
+        dev: 'nera dev',
+        build: 'nera build',
+        serve: 'nera serve',
+    }
+    // Generator-only scripts that no longer apply in the thin model.
+    for (const s of ['render', 'preserve', 'watch:assets', 'start', 'dev:old']) {
+        delete pkg.scripts[s]
+    }
+    // The `nera.version` stamp existed only because a cloned engine had no npm
+    // version; npm now tracks it.
+    delete pkg.nera
+
+    await fs.writeFile(
+        path.join(cwd, 'package.json'),
+        `${JSON.stringify(pkg, null, 4)}\n`
+    )
+    console.log('  ✓ Rewrote package.json (dependency + scripts)')
+
+    // A site's own local plugins must survive — move them out of the engine
+    // folder before it is deleted, and tell the user how to re-point discovery.
+    const srcPlugins = path.join(cwd, 'src', 'plugins')
+    let movedPlugins = false
+    if (fssync.existsSync(srcPlugins)) {
+        await fs.rename(srcPlugins, path.join(cwd, 'plugins'))
+        movedPlugins = true
+        console.log('  ✓ Moved src/plugins → plugins/')
+    }
+
+    await fs.rm(path.join(cwd, 'src'), { recursive: true, force: true })
+    await fs.rm(path.join(cwd, 'index.js'), { force: true })
+    console.log('  ✓ Removed the vendored engine (src/, index.js)')
+
+    console.log('📦 Installing...')
+    runNpm(['install'], cwd)
+
+    console.log('✅ Migrated. Run `nera dev` to start.')
+    if (movedPlugins) {
+        console.log(
+            '⚠️  Local plugins moved to plugins/. Add `folders:\\n  plugins: ./plugins`' +
+                ' to config/app.yaml so the engine discovers them (see ROADMAP-core.md).'
+        )
+    }
+}
+
+export async function runUpdate(args = [], options = {}) {
+    const { cwd = process.cwd(), runNpm = defaultRunNpm } = options
+
+    const pkg = JSON.parse(
+        await fs.readFile(path.join(cwd, 'package.json'), 'utf-8')
+    )
+    const kind = classifyProject(pkg, cwd)
+
+    if (kind === 'legacy') {
+        if (args.includes('--migrate') || args.includes('--yes')) {
+            await migrateLegacy(cwd, pkg, runNpm)
+        } else {
+            printLegacyGuidance()
+        }
+        return
+    }
+
+    if (kind === 'unknown') {
+        throw new Error(
+            'This does not look like a Nera site — no @nera-static/nera ' +
+                'dependency and no vendored engine under src/.'
+        )
+    }
+
+    const targets = neraDeps(pkg)
+    console.log(`🔄 Updating Nera packages: ${targets.join(', ')}`)
+    runNpm(['update', ...targets], cwd)
+    console.log('✅ Up to date.')
+}

package/src/commands/validate.js

@@ -0,0 +1,10 @@
+import { validateSite, hasErrors, formatResults } from '@nera-static/validate'
+
+// Validate the current site and print the results. Returns the process exit code
+// (1 on any error, 0 otherwise) rather than calling process.exit itself, so it
+// stays testable; the bin turns the return value into the exit.
+export function runValidate({ cwd = process.cwd() } = {}) {
+    const results = validateSite({ cwd })
+    console.log(formatResults(results))
+    return hasErrors(results) ? 1 : 0
+}

package/src/scaffold.js

@@ -0,0 +1,82 @@
+import { execFileSync } from 'child_process'
+import fs from 'fs/promises'
+import fssync from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+// Directory-safe and npm-safe: no separators, no traversal, no leading dot or
+// dash, nothing the shell could reinterpret. Deliberately stricter than npm's
+// own package-name rules, because this value is also a directory name.
+const VALID_PROJECT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+export function validateProjectName(projectName) {
+    if (typeof projectName !== 'string' || projectName.trim() === '') {
+        throw new Error(
+            'Project name is required. Usage: nera new <project-name>'
+        )
+    }
+
+    if (!VALID_PROJECT_NAME.test(projectName)) {
+        throw new Error(
+            `Invalid project name "${projectName}". Use letters, digits, dots, ` +
+                'dashes and underscores only, starting with a letter or digit.'
+        )
+    }
+
+    return projectName
+}
+
+// The scaffold template ships inside this package (package.json `files`).
+export const templateDir = () =>
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'template')
+
+async function copyDir(src, dest) {
+    await fs.mkdir(dest, { recursive: true })
+    for (const entry of await fs.readdir(src, { withFileTypes: true })) {
+        const from = path.join(src, entry.name)
+        // `_gitignore` → `.gitignore`: npm strips a literal .gitignore from the
+        // published tarball, so the template ships it under an underscore name.
+        const name = entry.name === '_gitignore' ? '.gitignore' : entry.name
+        const to = path.join(dest, name)
+        if (entry.isDirectory()) {
+            await copyDir(from, to)
+        } else {
+            await fs.copyFile(from, to)
+        }
+    }
+}
+
+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
+    await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 4)}\n`)
+    console.log(`  ✓ Configured project as "${projectName}"`)
+}
+
+// Scaffold a thin Nera site: copy the template, name it, and (by default)
+// install its single dependency, @nera-static/nera. No git clone, no vendored
+// engine — the opposite of the old installer's clone-and-strip flow.
+export async function scaffoldProject(projectName, options = {}) {
+    const { install = true, cwd = process.cwd() } = options
+
+    validateProjectName(projectName)
+
+    const targetDir = path.resolve(cwd, projectName)
+    if (fssync.existsSync(targetDir)) {
+        throw new Error(`Target directory "${projectName}" already exists.`)
+    }
+
+    console.log(`📦 Creating a new Nera site in ${targetDir}...`)
+    await copyDir(templateDir(), targetDir)
+    await personalize(targetDir, projectName)
+
+    if (install) {
+        console.log('📦 Installing dependencies...')
+        execFileSync('npm', ['install'], { cwd: targetDir, stdio: 'inherit' })
+    }
+
+    console.log('✅ Done!')
+    console.log(`👉 Next steps:\n  cd ${projectName}\n  nera dev\n`)
+    return targetDir
+}

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+public
+.env
+.npmrc
+.vite

package/template/config/app.yaml

@@ -0,0 +1,8 @@
+lang: en
+name: My Nera Site
+robots: index,follow
+
+translations:
+  en:
+    app_description: A static site built with Nera
+    app_keywords: nera, static site generator

package/template/package.json

@@ -0,0 +1,14 @@
+{
+    "name": "nera-site",
+    "version": "1.0.0",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "dev": "nera dev",
+        "build": "nera build",
+        "serve": "nera serve"
+    },
+    "dependencies": {
+        "@nera-static/nera": "^1.0.0"
+    }
+}

package/template/pages/index.md

@@ -0,0 +1,19 @@
+---
+layout: pages/default.pug
+title: Home
+description: Welcome to a site built with Nera
+keywords: nera, static site generator
+---
+# Welcome to Nera
+
+This page was scaffolded by `nera new` and rendered by `nera build`. Edit
+`pages/index.md` to change this content, and `theme/views/` to change the layout.
+
+## Next steps
+
+- `nera dev` — build and preview with live reload
+- `nera build` — render `pages/` into `public/`
+- Add a plugin: install any `@nera-static/plugin-*` package and configure it under `config/`
+
+See the [plugin catalog](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md)
+for what you can add.

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

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+html(lang=app.lang)
+  head
+    meta(charset="UTF-8")
+    meta(name="viewport", content="width=device-width, initial-scale=1.0")
+    title #{ meta.title } | #{ app.name }
+    meta(name="description", content=`${ meta.description || t('app_description') }`)
+    meta(name="keywords", content=`${ meta.keywords || t('app_keywords') }`)
+    meta(name="generator" content="nera")
+    meta(name="robots" content=`${ meta.robots || app.robots }`)
+
+  body
+    block content

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

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