@nera-static/nera 1.0.0 → 1.2.0

package/README.md

@@ -4,6 +4,8 @@ The Nera CLI — scaffold, build, preview and update a [Nera](https://github.com
 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.
 
+📖 **Documentation:** [nera.js.org](https://nera.js.org)
+
 ## Quick start
 
 ```bash
@@ -16,11 +18,12 @@ npm run dev            # or: nera dev
 
 | Command | What it does |
 |---|---|
-| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). |
+| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--theme <name>` to start from a theme. |
 | `nera build` | Render `pages/` → `public/`. |
-| `nera dev` | Build, serve `public/`, and rebuild on change with live reload. |
+| `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. On a legacy cloned site, `nera update --migrate` converts it to the thin model. |
+| `nera validate` | Check the site (layouts, includes, YAML) before publishing; exits non-zero on any error. |
 
 A scaffolded site is a thin project — no vendored engine, no clone. It lists one
 dependency and its scripts call the CLI:
@@ -32,6 +35,26 @@ dependency and its scripts call the CLI:
 }
 ```
 
+## Starting from a theme
+
+```bash
+npx @nera-static/nera new my-site --theme example
+```
+
+This installs the theme (`example` → `@nera-static/theme-example`; a full
+package name such as `@acme/my-theme`, or a local path such as `./my-theme`,
+works too), sets `theme:` in `config/app.yaml`, and leaves out the scaffold's
+starter templates.
+
+That last part matters. A site's own `theme/views/` wins over its theme's views
+**file by file** — that is how you override a single theme template. Without
+`--theme`, `nera new` writes a starter `theme/views/layouts/layout.pug` and
+`theme/views/pages/default.pug`, the same names a theme uses, so a theme added
+later stays hidden behind them. Each starter file carries a
+`//- nera:scaffold-default` first line, and `nera validate` warns
+(`theme-shadowed`) while such a file hides a theme's. Delete it to use the
+theme's version, or delete the marker line to keep yours.
+
 ## Migrating a cloned (legacy) site
 
 Older Nera sites were git clones that vendored the engine under `src/`. Inside
@@ -43,7 +66,17 @@ 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/`.
+`theme/` untouched. Local plugins in `src/plugins/` are moved to `plugins/`;
+add this to `config/app.yaml` so the engine discovers them there:
+
+```yaml
+folders:
+  plugins: ./plugins
+```
+
+A root `views/` and `assets/` (no `theme/` folder) keeps rendering but prints a
+deprecation warning — move them to `theme/views/` and `theme/assets/`, the
+layout `nera new` scaffolds.
 
 ## Requirements
 

package/bin/nera.js

@@ -11,7 +11,7 @@ const [, , command, ...rest] = process.argv
 const usage = `Nera — the static site generator CLI
 
 Usage:
-  nera new <name>    scaffold a new Nera site
+  nera new <name>    scaffold a new Nera site (--theme <name> to start from a theme)
   nera build         render pages/ → public/
   nera dev           build, serve and live-reload
   nera serve         serve the built public/ folder

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.0.0",
+    "version": "1.2.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": {
@@ -42,15 +42,15 @@
         "access": "public"
     },
     "dependencies": {
-        "@nera-static/core": "^4.9.0",
+        "@nera-static/core": "^4.12.0",
         "@nera-static/validate": "^1.0.0",
         "chokidar": "^5.0.0",
         "semver": "^7.8.5",
         "vite": "^8.1.5"
     },
     "devDependencies": {
-        "eslint": "^9.17.0",
+        "eslint": "^10.8.0",
         "husky": "^9.1.7",
-        "vitest": "^3.2.4"
+        "vitest": "^5.0.3"
     }
 }

package/src/commands/dev.js

@@ -1,5 +1,6 @@
 import fssync from 'fs'
-import run from '@nera-static/core'
+import path from 'path'
+import run, { resolveSiteModel } from '@nera-static/core'
 import { startServer } from './serve.js'
 
 // Build once, serve `public/`, then rebuild on any change to the site's
@@ -19,13 +20,8 @@ export async function runDev(args = []) {
 
     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))
+    const watched = new Set(watchTargets())
+    const watcher = chokidar.watch([...watched], { ignoreInitial: true })
 
     // Serialise rebuilds: coalesce changes that land mid-build into one re-run.
     let building = false
@@ -42,22 +38,59 @@ export async function runDev(args = []) {
             console.error('❌ Build error:', err.message)
         }
         building = false
+        // config/app.yaml may now name a different local theme — start
+        // watching it too. A dropped one stays watched; that only costs an
+        // extra rebuild if it is edited.
+        for (const dir of watchTargets()) {
+            if (!watched.has(dir)) {
+                watched.add(dir)
+                watcher.add(dir)
+            }
+        }
         if (queued) {
             queued = false
             await rebuild()
         }
     }
 
-    chokidar
-        .watch(watchDirs, { ignoreInitial: true })
-        .on('all', async (event, filePath) => {
-            console.log(`↻ ${event} ${filePath} — rebuilding`)
-            await rebuild()
-        })
+    watcher.on('all', async (event, filePath) => {
+        console.log(
+            `↻ ${event} ${path.relative(process.cwd(), filePath)} — rebuilding`
+        )
+        await rebuild()
+    })
 
     return server
 }
 
+// What a rebuild depends on: pages/, config/, the site's presentation folder
+// — theme/ in the current layout, or the deprecated root views/ on an
+// unmigrated site — and a LOCAL theme (`theme: ./themes/classic`, or the same
+// via NERA_THEME), which lives outside all of those. The theme is resolved
+// through core, so the watcher follows exactly the spec the build uses. Only
+// the theme's payload folders are watched, never its root: `theme: .` makes
+// the root the site itself, and watching public/ would rebuild forever. An
+// installed theme package under node_modules is left alone: it changes only on
+// npm install, and watching node_modules is expensive.
+export function watchTargets(cwd = process.cwd()) {
+    const dirs = [
+        'pages',
+        'config',
+        fssync.existsSync(path.join(cwd, 'theme')) ? 'theme' : 'views',
+    ].map((d) => path.join(cwd, d))
+
+    const { theme } = resolveSiteModel({ cwd })
+    if (theme && !theme.root.split(path.sep).includes('node_modules')) {
+        dirs.push(
+            theme.viewsRoot,
+            theme.assetsRoot,
+            path.join(theme.root, 'config')
+        )
+    }
+
+    return [...new Set(dirs)].filter((d) => fssync.existsSync(d))
+}
+
 const parsePort = (args) => {
     const i = args.indexOf('--port')
     const val = i >= 0 ? Number(args[i + 1]) : NaN

package/src/commands/new.js

@@ -1,7 +1,23 @@
 import { scaffoldProject } from '../scaffold.js'
 
+// `nera new <name> [--theme <spec> | --theme=<spec>] [--no-install]`
+export function parseNewArgs(args = []) {
+    let projectName
+    let theme
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i]
+        if (arg === '--theme') {
+            theme = args[++i] ?? ''
+        } else if (arg.startsWith('--theme=')) {
+            theme = arg.slice('--theme='.length)
+        } else if (!arg.startsWith('-') && projectName === undefined) {
+            projectName = arg
+        }
+    }
+    return { projectName, theme, install: !args.includes('--no-install') }
+}
+
 export async function runNew(args = []) {
-    const projectName = args.find((a) => !a.startsWith('-'))
-    const install = !args.includes('--no-install')
-    await scaffoldProject(projectName, { install })
+    const { projectName, theme, install } = parseNewArgs(args)
+    await scaffoldProject(projectName, { install, theme })
 }

package/src/scaffold.js

@@ -26,11 +26,54 @@ export function validateProjectName(projectName) {
     return projectName
 }
 
+// What `--theme` accepts, mirroring the three forms `app.theme` takes in
+// @nera-static/core (src/theme.js): a bare name (`example` →
+// @nera-static/theme-example), a full package name (`@acme/my-theme`), or a
+// local path (`./my-theme`). Validated because it lands in app.yaml and, for
+// the package forms, on the npm command line.
+const BARE_THEME = /^[a-z0-9][a-z0-9._-]*$/
+const SCOPED_THEME = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/
+const LOCAL_THEME = /^\.{1,2}(\/[A-Za-z0-9._-]+)*\/?$/
+
+export function validateThemeSpec(theme) {
+    if (
+        typeof theme === 'string' &&
+        (BARE_THEME.test(theme) ||
+            SCOPED_THEME.test(theme) ||
+            LOCAL_THEME.test(theme))
+    ) {
+        return theme
+    }
+    throw new Error(
+        `Invalid theme "${theme}". Use a theme name (example), a package ` +
+            'name (@scope/theme) or a local path (./my-theme).'
+    )
+}
+
+// The npm package a theme spec installs, or null for a local path. Same rule
+// as core's packageName() — keep the two in step.
+export function themePackageName(theme) {
+    if (theme.startsWith('.')) return null
+    return theme.includes('/') || theme.startsWith('@')
+        ? theme
+        : `@nera-static/theme-${theme}`
+}
+
+// Starter templates carry this marker on their first line. With a theme they
+// are left out: site views win over theme views file by file, so a starter
+// layout would hide the theme's own. @nera-static/validate warns on the same
+// marker (`theme-shadowed`) for sites that kept them.
+const SCAFFOLD_MARKER = 'nera:scaffold-default'
+
+const isStarterTemplate = async (file) =>
+    file.endsWith('.pug') &&
+    (await fs.readFile(file, 'utf-8')).includes(SCAFFOLD_MARKER)
+
 // 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) {
+async function copyDir(src, dest, { skipStarters = false } = {}) {
     await fs.mkdir(dest, { recursive: true })
     for (const entry of await fs.readdir(src, { withFileTypes: true })) {
         const from = path.join(src, entry.name)
@@ -39,7 +82,9 @@ async function copyDir(src, dest) {
         const name = entry.name === '_gitignore' ? '.gitignore' : entry.name
         const to = path.join(dest, name)
         if (entry.isDirectory()) {
-            await copyDir(from, to)
+            await copyDir(from, to, { skipStarters })
+        } else if (skipStarters && (await isStarterTemplate(from))) {
+            continue
         } else {
             await fs.copyFile(from, to)
         }
@@ -54,13 +99,35 @@ async function personalize(targetDir, projectName) {
     console.log(`  ✓ Configured project as "${projectName}"`)
 }
 
+// Point the site at its theme: `theme:` in app.yaml (appended, so the
+// template's own lines and comments stay as they are) and, for a package
+// theme, a dependency that `npm install` resolves.
+async function applyTheme(targetDir, theme) {
+    const appYaml = path.join(targetDir, 'config', 'app.yaml')
+    const yaml = await fs.readFile(appYaml, 'utf-8')
+    await fs.writeFile(
+        appYaml,
+        `${yaml.replace(/\n*$/, '\n')}\ntheme: ${theme}\n`
+    )
+
+    const pkgName = themePackageName(theme)
+    if (pkgName) {
+        const pkgPath = path.join(targetDir, 'package.json')
+        const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'))
+        pkg.dependencies = { ...pkg.dependencies, [pkgName]: 'latest' }
+        await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 4)}\n`)
+    }
+    console.log(`  ✓ Using theme "${theme}"${pkgName ? ` (${pkgName})` : ''}`)
+}
+
 // 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
+    const { install = true, cwd = process.cwd(), theme } = options
 
     validateProjectName(projectName)
+    if (theme !== undefined) validateThemeSpec(theme)
 
     const targetDir = path.resolve(cwd, projectName)
     if (fssync.existsSync(targetDir)) {
@@ -68,12 +135,18 @@ export async function scaffoldProject(projectName, options = {}) {
     }
 
     console.log(`📦 Creating a new Nera site in ${targetDir}...`)
-    await copyDir(templateDir(), targetDir)
+    await copyDir(templateDir(), targetDir, { skipStarters: Boolean(theme) })
     await personalize(targetDir, projectName)
+    if (theme) await applyTheme(targetDir, theme)
 
     if (install) {
         console.log('📦 Installing dependencies...')
-        execFileSync('npm', ['install'], { cwd: targetDir, stdio: 'inherit' })
+        // Naming the theme package installs everything else too, and makes npm
+        // replace the `latest` placeholder with a caret range for the version
+        // it resolved.
+        const themePkg = theme ? themePackageName(theme) : null
+        const args = themePkg ? ['install', themePkg] : ['install']
+        execFileSync('npm', args, { cwd: targetDir, stdio: 'inherit' })
     }
 
     console.log('✅ Done!')

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

@@ -1,3 +1,4 @@
+//- nera:scaffold-default — `nera new` starter file. While this line is here, `nera validate` warns if it hides a theme's file of the same name; delete the line once the file is your own.
 <!DOCTYPE html>
 html(lang=app.lang)
   head

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

@@ -1,3 +1,4 @@
+//- nera:scaffold-default — `nera new` starter file. While this line is here, `nera validate` warns if it hides a theme's file of the same name; delete the line once the file is your own.
 extends ../layouts/layout
 
 block content