@nera-static/nera 1.10.1 → 1.11.0

package/README.md

@@ -27,7 +27,7 @@ package is named after the folder (`My Bakery` → `my-bakery`).
 
 | Command | What it does |
 |---|---|
-| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--theme <name>` to start from a theme, `--no-install` to skip `npm install`. `nera new .` scaffolds into the current, empty folder (dotfiles, `AGENTS.md` and `CLAUDE.md` allowed). Every new site also gets the `nera` skill for AI assistants. |
+| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--starter <spec>` to start from a starter kit or `--theme <name>` to start from a theme (not both), `--name "<site name>"` and `--lang <code>` to set `name:` and `lang:` in `config/app.yaml` (a new language gets a copy of the current language's `translations:` entry to translate), `--no-install` to skip `npm install`. On a terminal, without `--starter` or `--yes`, it asks what you are building, the site name and the language; without a terminal it never asks. `nera new .` scaffolds into the current, empty folder (dotfiles, `AGENTS.md` and `CLAUDE.md` allowed). Every new site also gets the `nera` skill for AI assistants. |
 | `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. |
@@ -112,6 +112,56 @@ later stays hidden behind them. Each starter file carries a
 (`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.
 
+## Starter kits
+
+```bash
+npx @nera-static/nera new my-site --starter blank --name "Brot & Zeit" --lang de
+```
+
+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).
+
+`--starter` takes:
+
+- a starter name: `blank` → `@nera-static/starter-blank`;
+- 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`;
+- a local path: `./my-starter`, `../my-starter` or an absolute path.
+
+Packages and GitHub repositories are downloaded with
+`npm pack --ignore-scripts`, so no script of the starter runs. A starter is a
+package whose `package.json` has a `nera.starter` field
+(`{ "label": "…", "description": "…" }`); anything else is refused. One that
+sets `theme:` in its `config/app.yaml` leaves out the scaffold's starter
+templates, as `--theme` does.
+
+Run `nera new my-site` on a terminal and it asks instead:
+
+```text
+What are you building?
+  1) Empty — the base template, no starter
+  2) …
+Choose 1–2 [1]:
+Site name [My Nera Site]:
+Language [en]:
+```
+
+The list comes from the npm registry (packages with the keyword
+`nera-starter`, official `@nera-static/` ones first), or from a short list
+bundled with the CLI when the registry cannot be reached. Enter accepts the
+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.
+
 ## Checking the built site
 
 ```bash

package/bin/nera.js

@@ -13,7 +13,7 @@ const json = rest.includes('--json')
 const usage = `Nera — the static site generator CLI
 
 Usage:
-  nera new <name>    scaffold a new Nera site (--theme <name> to start from a theme, --no-install to skip npm install)
+  nera new <name>    scaffold a new Nera site (--starter <name|package|github-url|./path> to start from a starter kit, --theme <name> to start from a theme, --name "<site name>", --lang <code>, --yes to never ask, --no-install to skip npm install; asks what you are building only on a terminal)
   nera new .         scaffold into the current, empty folder
   nera build         render pages/ → public/ (--check to check the output after, --json for machine-readable output)
   nera dev           build, serve and live-reload

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.10.1",
+    "version": "1.11.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/new.js

@@ -1,23 +1,81 @@
-import { scaffoldProject } from '../scaffold.js'
+import {
+    scaffoldProject,
+    isCurrentDir,
+    validateProjectName,
+    validateThemeSpec,
+    validateSiteName,
+    validateLang,
+} from '../scaffold.js'
+import { validateStarterSpec } from '../starter.js'
 
-// `nera new <name> [--theme <spec> | --theme=<spec>] [--no-install]`
+// Options that take a value, as `--opt <value>` or `--opt=<value>`.
+const VALUE_OPTIONS = { '--theme': 'theme', '--starter': 'starter', '--name': 'name', '--lang': 'lang' }
+
+// `nera new <name> [--starter <spec>] [--theme <spec>] [--name <text>]
+// [--lang <code>] [--yes] [--no-install]`
 export function parseNewArgs(args = []) {
     let projectName
-    let theme
+    const values = {}
     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)
+        const eq = arg.indexOf('=')
+        const flag = eq === -1 ? arg : arg.slice(0, eq)
+        if (Object.hasOwn(VALUE_OPTIONS, flag)) {
+            values[VALUE_OPTIONS[flag]] = eq === -1 ? (args[++i] ?? '') : arg.slice(eq + 1)
         } else if (!arg.startsWith('-') && projectName === undefined) {
             projectName = arg
         }
     }
-    return { projectName, theme, install: !args.includes('--no-install') }
+    return {
+        projectName,
+        ...values,
+        yes: args.includes('--yes'),
+        install: !args.includes('--no-install'),
+    }
+}
+
+// Lazily loaded: the picker and the registry lookup are only needed on a
+// terminal.
+async function defaultPrompt(options) {
+    const [{ runPicker }, { listStarters }] = await Promise.all([
+        import('../prompt.js'),
+        import('../starter.js'),
+    ])
+    return runPicker({ ...options, listStarters, validateSiteName, validateLang })
 }
 
-export async function runNew(args = []) {
-    const { projectName, theme, install } = parseNewArgs(args)
-    await scaffoldProject(projectName, { install, theme })
+// `prompt`, `scaffold` and the streams are injectable for tests.
+export async function runNew(args = [], {
+    stdin = process.stdin,
+    stdout = process.stdout,
+    prompt = defaultPrompt,
+    scaffold = scaffoldProject,
+} = {}) {
+    const { projectName, yes, install, ...rest } = parseNewArgs(args)
+    const options = Object.fromEntries(
+        Object.entries(rest).filter(([, v]) => v !== undefined)
+    )
+
+    const { shouldPrompt } = await import('../prompt.js')
+    if (shouldPrompt({ yes, starter: options.starter, stdin, stdout })) {
+        // Fail on a bad flag before asking anything.
+        if (!isCurrentDir(projectName)) validateProjectName(projectName)
+        if (options.theme !== undefined) validateThemeSpec(options.theme)
+        if (options.name !== undefined) validateSiteName(options.name)
+        if (options.lang !== undefined) validateLang(options.lang)
+        const answers = await prompt({
+            input: stdin,
+            output: stdout,
+            // A theme rules out a starter, so that question is not asked.
+            skip: {
+                starter: options.theme !== undefined,
+                name: options.name !== undefined,
+                lang: options.lang !== undefined,
+            },
+        })
+        Object.assign(options, answers)
+        if (options.starter !== undefined) validateStarterSpec(options.starter)
+    }
+
+    return scaffold(projectName, { ...options, install })
 }

package/src/prompt.js

@@ -0,0 +1,127 @@
+import readline from 'readline'
+
+// The interactive part of `nera new` (ROADMAP-ai.md L5, principle 5). It only
+// collects options; scaffoldProject does the work, the same as with flags.
+
+// Questions are asked only on a terminal, never with --yes, and never once
+// --starter is given.
+export const shouldPrompt = ({ yes, starter, stdin = process.stdin, stdout = process.stdout }) =>
+    Boolean(stdin.isTTY && stdout.isTTY) && !yes && starter === undefined
+
+export const EMPTY_CHOICE = 'Empty — the base template, no starter'
+const TEMPLATE_NAME = 'My Nera Site'
+const TEMPLATE_LANG = 'en'
+
+// One question; Enter (or the end of input) gives ''.
+const ask = (rl, question) =>
+    new Promise((resolve) => {
+        const onClose = () => resolve('')
+        rl.once('close', onClose)
+        rl.question(question, (answer) => {
+            rl.off('close', onClose)
+            resolve(answer.trim())
+        })
+    })
+
+// Ask until `parse` accepts the answer; it returns undefined for "ask again".
+// At the end of input every question takes its default.
+async function askUntil(rl, question, parse) {
+    for (;;) {
+        const answer = rl.ended ? '' : await ask(rl, question)
+        const value = parse(answer)
+        if (value !== undefined) return value
+    }
+}
+
+// Ask "What are you building?", "Site name" and "Language", each skipped when
+// its option is already set (`skip`). Enter keeps the default, which for name
+// and language means "leave app.yaml as the template or the starter has it":
+// the result then has no `name` / `lang`. `listStarters` and `validate*` are
+// passed in so tests need no network and the rules stay in one place.
+// Returns `{ starter?, name?, lang? }`.
+export async function runPicker({
+    input = process.stdin,
+    output = process.stdout,
+    listStarters,
+    validateSiteName,
+    validateLang,
+    skip = {},
+}) {
+    const rl = readline.createInterface({ input, output, terminal: Boolean(output.isTTY) })
+    let cancelled = false
+    rl.once('close', () => {
+        rl.ended = true
+    })
+    rl.on('SIGINT', () => {
+        output.write('\n')
+        cancelled = true
+        rl.close()
+    })
+    const check = () => {
+        if (cancelled) throw new Error('Cancelled — nothing was created.')
+    }
+    const say = (text) => output.write(`${text}\n`)
+    const invalid = (fn, value) => {
+        try {
+            fn(value)
+            return false
+        } catch (err) {
+            say(`  ${err.message}`)
+            return true
+        }
+    }
+
+    try {
+        const result = {}
+
+        if (!skip.starter) {
+            const starters = await listStarters()
+            check()
+            const choices = [
+                { label: EMPTY_CHOICE },
+                ...starters.map((s) => ({
+                    label: s.description ? `${s.name} — ${s.description}` : s.name,
+                    name: s.name,
+                })),
+            ]
+            say('What are you building?')
+            choices.forEach((c, i) => say(`  ${i + 1}) ${c.label}`))
+            const picked = await askUntil(
+                rl,
+                `Choose 1–${choices.length} [1]: `,
+                (answer) => {
+                    if (answer === '') return choices[0]
+                    const byNumber = /^\d+$/.test(answer) ? choices[Number(answer) - 1] : undefined
+                    const found = byNumber ?? choices.find((c) => c.name && c.name === answer)
+                    if (!found) say(`  Please enter a number from 1 to ${choices.length}.`)
+                    return found
+                }
+            )
+            check()
+            if (picked.name) result.starter = picked.name
+        }
+
+        const fromStarter = result.starter !== undefined
+        if (!skip.name) {
+            const shown = fromStarter ? 'the starter\'s' : TEMPLATE_NAME
+            const name = await askUntil(rl, `Site name [${shown}]: `, (answer) =>
+                answer === '' ? '' : invalid(validateSiteName, answer) ? undefined : answer
+            )
+            check()
+            if (name !== '') result.name = name
+        }
+
+        if (!skip.lang) {
+            const shown = fromStarter ? 'the starter\'s' : TEMPLATE_LANG
+            const lang = await askUntil(rl, `Language [${shown}]: `, (answer) =>
+                answer === '' ? '' : invalid(validateLang, answer) ? undefined : answer
+            )
+            check()
+            if (lang !== '') result.lang = lang
+        }
+
+        return result
+    } finally {
+        rl.close()
+    }
+}

package/src/scaffold.js

@@ -4,6 +4,13 @@ import fssync from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { skillSourceDir, syncSkill } from './skill.js'
+import {
+    applyStarter,
+    fetchStarter as defaultFetchStarter,
+    readStarterManifest,
+    starterSetsTheme,
+    validateStarterSpec,
+} from './starter.js'
 
 // Directory-safe and npm-safe: no separators, no traversal, no leading dot or
 // dash, nothing the shell could reinterpret. Deliberately stricter than npm's
@@ -183,6 +190,99 @@ async function applyTheme(targetDir, theme) {
     console.log(`  ✓ Using theme "${theme}"${pkgName ? ` (${pkgName})` : ''}`)
 }
 
+// `--name`: any non-empty text without line breaks. It is written as a JSON
+// string, which is also valid YAML, so `:`, `#` and quotes are safe.
+export function validateSiteName(name) {
+    if (typeof name === 'string' && name.trim() !== '' && !/[\0-\x1f\x7f]/.test(name)) {
+        return name
+    }
+    throw new Error(
+        `Invalid site name ${JSON.stringify(name)}. Give a name on one line, ` +
+            'e.g. --name "Brot & Zeit".'
+    )
+}
+
+// `--lang`: a BCP 47-style language tag (`de`, `en`, `pt-BR`).
+const LANG = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/
+
+export function validateLang(lang) {
+    if (typeof lang === 'string' && LANG.test(lang)) return lang
+    throw new Error(
+        `Invalid language "${lang}". Use a language code such as en, de or pt-BR.`
+    )
+}
+
+// Set a top-level `key: value` line in an app.yaml text: replace the first
+// one, or append it if there is none. Every other line, comment and nested
+// block (translations:) stays as it is. `value` is written verbatim.
+export function setAppValue(yaml, key, value) {
+    const line = new RegExp(`^${key}:.*$`, 'm')
+    if (line.test(yaml)) return yaml.replace(line, () => `${key}: ${value}`)
+    return `${yaml.replace(/\n*$/, '\n')}${key}: ${value}\n`
+}
+
+// Give a new language its own entry in the block-style `translations:` of an
+// app.yaml text, copied from language `from`: core's `t(key)` falls back to
+// the key itself, so a site switched to `de` with only an `en` block would
+// render `app_description` on every page without its own description.
+// Line-based like setAppValue; returns the text unchanged when there is no
+// such block, `from` has no entry, or `to` already has one.
+export function addLangTranslations(yaml, from, to) {
+    const lines = yaml.split('\n')
+    const start = lines.findIndex((l) => /^translations:[ \t]*(#.*)?$/.test(l))
+    if (start === -1 || !from || from === to) return yaml
+    let end = start + 1
+    while (end < lines.length && (lines[end].trim() === '' || /^[ \t]/.test(lines[end]))) end++
+    while (end > start + 1 && lines[end - 1].trim() === '') end--
+
+    // The line `  <lang>:` inside the block, or -1. Codes are validated
+    // (letters, digits, dashes), so they are safe in a RegExp.
+    const entry = (lang) => {
+        const re = new RegExp(`^[ \\t]+${lang}:[ \\t]*(#.*)?$`)
+        for (let i = start + 1; i < end; i++) if (re.test(lines[i])) return i
+        return -1
+    }
+    if (entry(to) !== -1) return yaml
+    const fromStart = entry(from)
+    if (fromStart === -1) return yaml
+
+    const indent = lines[fromStart].match(/^[ \t]+/)[0]
+    let fromEnd = fromStart + 1
+    while (
+        fromEnd < end &&
+        (lines[fromEnd].trim() === '' || lines[fromEnd].match(/^[ \t]*/)[0].length > indent.length)
+    ) fromEnd++
+    while (lines[fromEnd - 1].trim() === '') fromEnd--
+    const copy = [`${indent}${to}:`, ...lines.slice(fromStart + 1, fromEnd)]
+    return [...lines.slice(0, end), ...copy, ...lines.slice(end)].join('\n')
+}
+
+async function applyNameAndLang(targetDir, { name, lang }) {
+    if (name === undefined && lang === undefined) return
+    const appYaml = path.join(targetDir, 'config', 'app.yaml')
+    let yaml = await fs.readFile(appYaml, 'utf-8')
+    const oldLang = yaml.match(/^lang:[ \t]*["']?([A-Za-z0-9-]+)["']?[ \t]*(#.*)?$/m)?.[1]
+    if (name !== undefined) yaml = setAppValue(yaml, 'name', JSON.stringify(name))
+    let copied = false
+    if (lang !== undefined) {
+        yaml = setAppValue(yaml, 'lang', lang)
+        const withLang = addLangTranslations(yaml, oldLang, lang)
+        copied = withLang !== yaml
+        yaml = withLang
+    }
+    await fs.writeFile(appYaml, yaml)
+    const set = [
+        ...(name !== undefined ? [`name ${JSON.stringify(name)}`] : []),
+        ...(lang !== undefined ? [`language "${lang}"`] : []),
+    ]
+    console.log(`  ✓ Set the site's ${set.join(' and ')} in config/app.yaml`)
+    if (copied) {
+        console.log(
+            `  ✓ Copied the "${oldLang}" translations to "${lang}" in config/app.yaml — translate them there`
+        )
+    }
+}
+
 // The Nera skill for AI assistants, in both folders the clients read
 // (.agents/skills/nera, .claude/skills/nera). Meant to be committed, and
 // refreshed by `nera update`.
@@ -193,15 +293,34 @@ async function addSkill(targetDir) {
     )
 }
 
-// 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.
+// 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.
 export async function scaffoldProject(projectName, options = {}) {
-    const { install = true, cwd = process.cwd(), theme } = options
+    const {
+        install = true,
+        cwd = process.cwd(),
+        theme,
+        starter,
+        name,
+        lang,
+        fetchStarter = defaultFetchStarter,
+    } = options
 
+    // Everything is checked before anything is written.
     const inPlace = isCurrentDir(projectName)
     if (!inPlace) validateProjectName(projectName)
     if (theme !== undefined) validateThemeSpec(theme)
+    if (starter !== undefined) validateStarterSpec(starter)
+    if (starter !== undefined && theme !== undefined) {
+        throw new Error(
+            'A starter brings its own theme; use --starter or --theme, not both.'
+        )
+    }
+    if (name !== undefined) validateSiteName(name)
+    if (lang !== undefined) validateLang(lang)
 
     const targetDir = path.resolve(cwd, inPlace ? '.' : projectName)
     if (inPlace) {
@@ -211,17 +330,45 @@ export async function scaffoldProject(projectName, options = {}) {
     }
     const packageName = inPlace ? projectNameFromDir(targetDir) : projectName
 
-    console.log(`📦 Creating a new Nera site in ${targetDir}...`)
-    await copyDir(templateDir(), targetDir, { skipStarters: Boolean(theme) })
-    await personalize(targetDir, packageName)
-    if (theme) await applyTheme(targetDir, theme)
-    await addSkill(targetDir)
+    // The starter is fetched and checked before the site folder exists, so a
+    // download error or a package that is no starter leaves nothing behind.
+    const fetched = starter === undefined ? null : await fetchStarter(starter, { cwd })
+    let readme = null
+    try {
+        if (fetched) await readStarterManifest(fetched.dir, starter)
+        const skipStarters = Boolean(theme) || (fetched ? await starterSetsTheme(fetched.dir) : false)
+        const before = inPlace ? new Set(await fs.readdir(targetDir)) : null
+
+        console.log(`📦 Creating a new Nera site in ${targetDir}...`)
+        try {
+            await copyDir(templateDir(), targetDir, { skipStarters })
+            await personalize(targetDir, packageName)
+            if (theme) await applyTheme(targetDir, theme)
+            if (fetched) readme = await applyStarter(targetDir, fetched.dir)
+            await applyNameAndLang(targetDir, { name, lang })
+            await addSkill(targetDir)
+        } catch (err) {
+            if (!inPlace) {
+                await fs.rm(targetDir, { recursive: true, force: true })
+                throw err
+            }
+            const written = (await fs.readdir(targetDir)).filter((n) => !before.has(n))
+            err.message +=
+                written.length > 0
+                    ? ` Already written to the current folder: ${written.join(', ')}. ` +
+                      'Remove them before running `nera new .` again.'
+                    : ''
+            throw err
+        }
+    } finally {
+        await fetched?.cleanup()
+    }
 
     if (install) {
         console.log('📦 Installing dependencies...')
         // Naming the theme package installs everything else too, and makes npm
         // replace the `latest` placeholder with a caret range for the version
-        // it resolved.
+        // 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' })
@@ -234,6 +381,7 @@ export async function scaffoldProject(projectName, options = {}) {
         'npm run dev',
     ]
     console.log('✅ Done!')
+    if (readme) console.log(`\n${readme.replace(/\n*$/, '')}\n`)
     console.log(
         `👉 Next steps:\n${nextSteps.map((l) => `  ${l}\n`).join('')}`
     )

package/src/starter.js

@@ -0,0 +1,261 @@
+import { execFileSync } from 'child_process'
+import fs from 'fs/promises'
+import fssync from 'fs'
+import os from 'os'
+import path from 'path'
+import { BUNDLED_STARTERS } from './starters.js'
+
+// What `--starter` accepts (ROADMAP-ai.md L5), validated before anything is
+// written because the package forms end up on the npm command line:
+//   blank                                  → @nera-static/starter-blank
+//   @acme/starter-x, nera-starter-x        → verbatim
+//   https://github.com/o/r[.git][#ref]     → github:o/r[#ref]
+//   github:o/r[#ref]                       → verbatim
+//   ./x, ../x, /abs/x                      → read in place
+const BARE_STARTER = /^[a-z0-9][a-z0-9._-]*$/
+const SCOPED_STARTER = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/
+const UNSCOPED_STARTER = /^nera-starter-[a-z0-9][a-z0-9._-]*$/
+const GH_OWNER = '[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?'
+const GH_REPO = '[A-Za-z0-9._-]+?'
+const GH_REF = '[A-Za-z0-9._][A-Za-z0-9._/-]*'
+const GITHUB_URL = new RegExp(
+    `^https://github\\.com/(${GH_OWNER})/(${GH_REPO})(?:\\.git)?(?:#(${GH_REF}))?$`
+)
+const GITHUB_SHORT = new RegExp(
+    `^github:(${GH_OWNER})/(${GH_REPO})(?:\\.git)?(?:#(${GH_REF}))?$`
+)
+// LOCAL_THEME in scaffold.js, plus absolute paths.
+const LOCAL_STARTER = /^(?:\.{1,2}(?:\/[A-Za-z0-9._-]+)*|(?:\/[A-Za-z0-9._-]+)+)\/?$/
+
+const isLocal = (spec) => LOCAL_STARTER.test(spec)
+
+export function validateStarterSpec(spec) {
+    if (
+        typeof spec === 'string' &&
+        (BARE_STARTER.test(spec) ||
+            SCOPED_STARTER.test(spec) ||
+            UNSCOPED_STARTER.test(spec) ||
+            GITHUB_URL.test(spec) ||
+            GITHUB_SHORT.test(spec) ||
+            isLocal(spec))
+    ) {
+        return spec
+    }
+    throw new Error(
+        `Invalid starter "${spec}". Use a starter name (blank), a package ` +
+            'name (@scope/starter-x or nera-starter-x), a GitHub URL ' +
+            '(https://github.com/owner/repo#ref or github:owner/repo) or a ' +
+            'local path (./my-starter).'
+    )
+}
+
+// Where a (valid) spec comes from: a folder read in place, or a spec for
+// `npm pack`.
+export function starterSource(spec) {
+    validateStarterSpec(spec)
+    if (isLocal(spec)) return { kind: 'local', path: spec }
+    const gh = spec.match(GITHUB_URL) ?? spec.match(GITHUB_SHORT)
+    if (gh) {
+        const [, owner, repo, ref] = gh
+        return { kind: 'npm', spec: `github:${owner}/${repo}${ref ? `#${ref}` : ''}` }
+    }
+    if (spec.startsWith('@') || UNSCOPED_STARTER.test(spec)) {
+        return { kind: 'npm', spec }
+    }
+    return { kind: 'npm', spec: `@nera-static/starter-${spec}` }
+}
+
+const downloadError = (spec, npmSpec, err) => {
+    const said = String(err?.stderr ?? '')
+        .split('\n')
+        .find((l) => /^npm (error|ERR!) /.test(l) && !/ (code|errno) |A complete log/.test(l))
+    return new Error(
+        `Could not download the starter "${spec}" (npm pack ${npmSpec} failed` +
+            `${said ? `: ${said.replace(/^npm (error|ERR!)\s*/, '')}` : ''}). ` +
+            'Check the starter name for typos and your network connection, ' +
+            'then run `nera new` again.'
+    )
+}
+
+// Download a package or GitHub starter into a temp folder: `npm pack` (with
+// --ignore-scripts, so a git dependency's `prepare` never runs) and `tar`.
+// npm tarballs unpack to `package/`. The temp folder is gone on failure, and
+// `cleanup()` removes it after use. `exec` is injectable for tests.
+export async function packStarter(npmSpec, { spec = npmSpec, exec = execFileSync } = {}) {
+    console.log(`📦 Downloading the starter "${spec}"...`)
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'nera-starter-'))
+    const cleanup = () => fs.rm(tmp, { recursive: true, force: true })
+    try {
+        const packDir = path.join(tmp, 'pack')
+        const outDir = path.join(tmp, 'out')
+        await fs.mkdir(packDir)
+        await fs.mkdir(outDir)
+        try {
+            exec(
+                'npm',
+                ['pack', npmSpec, '--ignore-scripts', '--pack-destination', packDir],
+                { stdio: 'pipe', encoding: 'utf-8' }
+            )
+        } catch (err) {
+            throw downloadError(spec, npmSpec, err)
+        }
+        const tarball = (await fs.readdir(packDir)).find((n) => n.endsWith('.tgz'))
+        if (!tarball) throw downloadError(spec, npmSpec)
+        exec('tar', ['-xzf', path.join(packDir, tarball), '-C', outDir], {
+            stdio: 'pipe',
+        })
+        return { dir: path.join(outDir, 'package'), cleanup }
+    } catch (err) {
+        await cleanup()
+        throw err
+    }
+}
+
+// The starter as a folder on disk plus a `cleanup()`. A local path is read in
+// place (relative to `cwd`) and needs no cleanup.
+export async function fetchStarter(spec, { cwd = process.cwd(), pack = packStarter } = {}) {
+    const source = starterSource(spec)
+    if (source.kind === 'local') {
+        const dir = path.resolve(cwd, source.path)
+        if (!fssync.existsSync(dir)) {
+            throw new Error(
+                `Starter folder "${spec}" not found (looked in ${dir}). ` +
+                    'Check the path; a local starter is a folder with a package.json.'
+            )
+        }
+        return { dir, cleanup: async () => {} }
+    }
+    return pack(source.spec, { spec })
+}
+
+// The starter's package.json. Only a package with a `nera.starter` field is a
+// starter; anything else is refused before the site is written.
+export async function readStarterManifest(dir, spec = dir) {
+    let pkg
+    try {
+        pkg = JSON.parse(await fs.readFile(path.join(dir, 'package.json'), 'utf-8'))
+    } catch {
+        throw new Error(
+            `"${spec}" is not a Nera starter: it has no readable package.json. ` +
+                'A starter is a folder whose package.json has a `nera.starter` field.'
+        )
+    }
+    const starter = pkg?.nera?.starter
+    if (!starter || typeof starter !== 'object') {
+        throw new Error(
+            `"${spec}" is not a Nera starter: its package.json has no ` +
+                '`nera.starter` field.'
+        )
+    }
+    return pkg
+}
+
+// Does the starter's config/app.yaml pick a theme? Then the base template's
+// own views (nera:scaffold-default) are left out, as with `--theme`.
+export async function starterSetsTheme(dir) {
+    try {
+        const yaml = await fs.readFile(path.join(dir, 'config', 'app.yaml'), 'utf-8')
+        return /^theme:[ \t]*[^\s#]/m.test(yaml)
+    } catch {
+        return false
+    }
+}
+
+// The only parts of a starter copied into the site. Never its package.json,
+// AGENTS.md, CLAUDE.md, .claude/, .agents/, node_modules/ or anything else.
+export const STARTER_ENTRIES = ['pages', 'config', 'theme', 'assets', 'plugins', '.neraignore']
+
+// The site's own CLI dependency is never replaced by a starter's.
+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.
+export async function applyStarter(targetDir, starterDir) {
+    const pkg = await readStarterManifest(starterDir)
+    const notLink = async (src) => !(await fs.lstat(src)).isSymbolicLink()
+    for (const entry of STARTER_ENTRIES) {
+        const from = path.join(starterDir, entry)
+        if (!fssync.existsSync(from) || !(await notLink(from))) continue
+        await fs.cp(from, path.join(targetDir, entry), {
+            recursive: true,
+            force: true,
+            filter: notLink,
+        })
+    }
+
+    const deps = Object.fromEntries(
+        Object.entries(pkg.dependencies ?? {}).filter(
+            ([name, range]) => name !== OWN_PACKAGE && typeof range === 'string'
+        )
+    )
+    if (Object.keys(deps).length > 0) {
+        const pkgPath = path.join(targetDir, 'package.json')
+        const site = JSON.parse(await fs.readFile(pkgPath, 'utf-8'))
+        site.dependencies = { ...site.dependencies, ...deps }
+        await fs.writeFile(pkgPath, `${JSON.stringify(site, null, 4)}\n`)
+    }
+
+    const label = pkg.nera.starter.label ?? pkg.name
+    console.log(`  ✓ Applied the "${label}" starter${pkg.name ? ` (${pkg.name})` : ''}`)
+
+    try {
+        return await fs.readFile(path.join(starterDir, 'README.md'), 'utf-8')
+    } catch {
+        return null
+    }
+}
+
+const REGISTRY_SEARCH =
+    'https://registry.npmjs.org/-/v1/search?text=keywords:nera-starter&size=50'
+const OFFICIAL_PREFIX = '@nera-static/'
+const OFFICIAL_STARTER_PREFIX = '@nera-static/starter-'
+
+// The name the picker shows and `--starter` takes: the bare name for an
+// official starter, the full package name otherwise.
+const displayName = (pkg) =>
+    pkg.startsWith(OFFICIAL_STARTER_PREFIX) ? pkg.slice(OFFICIAL_STARTER_PREFIX.length) : pkg
+
+// Only results whose shown name leads back to the same package: an unscoped
+// `cool-site` would otherwise be offered as `cool-site`, which `--starter`
+// reads as @nera-static/starter-cool-site.
+const roundTrips = ({ name, package: pkg }) => {
+    try {
+        return starterSource(name).spec === pkg
+    } catch {
+        return false
+    }
+}
+
+// The starters on npm (keyword `nera-starter`), official ones first, then
+// alphabetically: `[{ name, package, description }]`. Labels come from the
+// search result's description; manifests are not fetched. On any failure
+// (offline, timeout, non-200, bad JSON) the bundled list is returned instead.
+export async function listStarters({ fetch = globalThis.fetch, timeout = 3000 } = {}) {
+    try {
+        const res = await fetch(REGISTRY_SEARCH, { signal: AbortSignal.timeout(timeout) })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const body = await res.json()
+        if (!Array.isArray(body?.objects)) throw new Error('unexpected response')
+        const seen = new Set()
+        return body.objects
+            .map((o) => o?.package)
+            .filter((p) => typeof p?.name === 'string' && !seen.has(p.name) && seen.add(p.name))
+            .map((p) => ({
+                name: displayName(p.name),
+                package: p.name,
+                description: typeof p.description === 'string' ? p.description : '',
+            }))
+            .filter(roundTrips)
+            .sort((a, b) => {
+                const official = (s) => (s.package.startsWith(OFFICIAL_PREFIX) ? 0 : 1)
+                return official(a) - official(b) || a.package.localeCompare(b.package)
+            })
+    } catch {
+        return BUNDLED_STARTERS.map(({ name, package: pkg, label, description }) => ({
+            name,
+            package: pkg,
+            description: label ? `${label}: ${description}` : description,
+        }))
+    }
+}

package/src/starters.js

@@ -0,0 +1,12 @@
+// The official starters `nera new` offers when the npm registry cannot be
+// reached. Hand-kept: add each official @nera-static/starter-* here once it
+// is published, so the offline list never names a package that does not
+// exist.
+export const BUNDLED_STARTERS = [
+    {
+        name: 'blank',
+        package: '@nera-static/starter-blank',
+        label: 'Blank',
+        description: 'The smallest Nera starter: one page, one layout.',
+    },
+]