@nera-static/nera 1.8.0 → 1.9.0

package/README.md

@@ -28,12 +28,12 @@ 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. `nera new .` scaffolds into the current, empty folder (dotfiles, `AGENTS.md` and `CLAUDE.md` allowed). |
-| `nera build` | Render `pages/` → `public/`. With `--check`, then run `nera check` on the result — one command for CI. |
+| `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` (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. |
-| `nera check` | Check the built `public/` for accessibility, privacy and legal-notice problems (see below). Build first. |
+| `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:
@@ -161,6 +161,36 @@ links are found by their text in German and English only (*Impressum*,
 WCAG criterion or law behind each rule, are in the
 [`@nera-static/validate` README](https://github.com/seebaermichi/nera-validate#checking-the-built-output).
 
+## Machine-readable output
+
+`nera validate --json`, `nera check --json` and `nera build --check --json`
+print exactly one JSON object on stdout and nothing else, for an AI agent or a
+script to parse:
+
+```json
+{
+  "ok": true,
+  "results": [
+    {
+      "file": "public/index.html",
+      "line": 26,
+      "severity": "warning",
+      "rule": "a11y-skip-link",
+      "message": "the first focusable element is not a skip link — …"
+    }
+  ]
+}
+```
+
+`results` is the validator's list as it is, in the same order (`severity` is
+`error` or `warning`); `ok` is `true` exactly when the exit code is `0`, so
+warnings alone keep it `true`. When the command cannot run — no `public/` for
+`nera check`, a failed build, a config the validator cannot read — stdout holds
+`{ "ok": false, "error": "<message>", "results": [] }` and the exit code is `1`.
+Every log line (the build log, plugin output) goes to stderr, and the exit code
+is the same as without `--json`. `nera build --json` without `--check` prints
+`{ "ok": true, "results": [] }` after a successful build.
+
 ## Migrating a cloned (legacy) site
 
 Older Nera sites were git clones that vendored the engine under `src/`. Inside

package/bin/nera.js

@@ -8,18 +8,19 @@ import { runValidate } from '../src/commands/validate.js'
 import { runCheck } from '../src/commands/check.js'
 
 const [, , command, ...rest] = process.argv
+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)
   nera new .         scaffold into the current, empty folder
-  nera build         render pages/ → public/ (--check to check the output after)
+  nera build         render pages/ → public/ (--check to check the output after, --json for machine-readable output)
   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
-  nera check         check the built public/ (accessibility, privacy, legal hints)
+  nera validate      check the site (layouts, includes, YAML) before publish (--json for machine-readable output)
+  nera check         check the built public/ (accessibility, privacy, legal hints) (--json for machine-readable output)
 `
 
 try {
@@ -40,10 +41,10 @@ try {
         await runUpdate(rest)
         break
     case 'validate':
-        process.exit(runValidate())
+        process.exitCode = runValidate({ json })
         break
     case 'check':
-        process.exit(runCheck())
+        process.exitCode = runCheck({ json })
         break
     default:
         console.log(usage)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.8.0",
+    "version": "1.9.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/build.js

@@ -1,12 +1,23 @@
 import run from '@nera-static/core'
+import { validateOutput } from '@nera-static/validate'
 import { runCheck } from './check.js'
+import { runJson } from '../json-output.js'
 
 // 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. With `--check`, the fresh output
 // is then checked as by `nera check` — one command for CI. Returns the exit
-// code: the check's, or 0 for a plain build.
+// code: the check's, or 0 for a plain build. With `--json`, the build log goes
+// to stderr and stdout holds one object: the check's `{ ok, results }`, empty
+// results without `--check`, or the failure (see json-output.js).
 export async function runBuild(args = []) {
+    const check = args.includes('--check')
+    if (args.includes('--json')) {
+        return runJson(async () => {
+            await run()
+            return check ? validateOutput({ cwd: process.cwd() }) : []
+        })
+    }
     await run()
-    return args.includes('--check') ? runCheck() : 0
+    return check ? runCheck() : 0
 }

package/src/commands/check.js

@@ -1,11 +1,14 @@
 import { validateOutput, hasErrors, formatOutputResults } from '@nera-static/validate'
+import { runJson } from '../json-output.js'
 
 // Check the built output in public/ — accessibility, privacy and legal-notice
 // hints — and print the results. `nera validate` checks the sources; this checks
 // what the build produced, so it needs a build first: validateOutput throws
 // "run `nera build` first" when public/ is missing or holds no HTML. Returns the
-// exit code (1 on any error, 0 otherwise), like runValidate.
-export function runCheck({ cwd = process.cwd() } = {}) {
+// exit code (1 on any error, 0 otherwise), like runValidate. With `json`, it
+// prints one JSON object instead, the error included (see json-output.js).
+export function runCheck({ cwd = process.cwd(), json = false } = {}) {
+    if (json) return runJson(() => validateOutput({ cwd }))
     const results = validateOutput({ cwd })
     console.log(formatOutputResults(results))
     return hasErrors(results) ? 1 : 0

package/src/commands/validate.js

@@ -1,9 +1,12 @@
 import { validateSite, hasErrors, formatResults } from '@nera-static/validate'
+import { runJson } from '../json-output.js'
 
 // 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() } = {}) {
+// stays testable; the bin turns the return value into the exit. With `json`, it
+// prints one `{ ok, results }` object instead (see json-output.js).
+export function runValidate({ cwd = process.cwd(), json = false } = {}) {
+    if (json) return runJson(() => validateSite({ cwd }))
     const results = validateSite({ cwd })
     console.log(formatResults(results))
     return hasErrors(results) ? 1 : 0

package/src/json-output.js

@@ -0,0 +1,57 @@
+import { hasErrors } from '@nera-static/validate'
+
+// `--json` mode, shared by `nera validate`, `nera check` and `nera build`: stdout
+// holds exactly one JSON object and nothing else, so an agent can parse it whole.
+// While `body` runs, console.log/info/debug and raw stdout writes (the engine's
+// build log, plugin output) go to stderr; they are restored afterwards. `body`
+// returns the validator's results, directly or as a promise. The object is
+// `{ ok, results }`, or `{ ok: false, error, results: [] }` when `body` throws —
+// the error is reported here, not rethrown. Returns the exit code, the same one
+// text mode ends with: 1 on any error, 0 otherwise. A sync body keeps the call
+// sync.
+export function runJson(body) {
+    const restore = routeLogsToStderr()
+    const finish = (value) => {
+        restore()
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+        return value.ok ? 0 : 1
+    }
+    const report = (results) => ({ ok: !hasErrors(results), results })
+    const failure = (error) => ({ ok: false, error: error.message, results: [] })
+
+    let pending
+    try {
+        pending = body()
+    } catch (error) {
+        return finish(failure(error))
+    }
+    if (typeof pending?.then === 'function') {
+        return pending.then(
+            (results) => finish(report(results)),
+            (error) => finish(failure(error))
+        )
+    }
+    return finish(report(pending))
+}
+
+// Point console.log/info/debug and process.stdout.write at stderr. Returns the
+// function that puts the originals back.
+function routeLogsToStderr() {
+    const saved = {
+        log: console.log,
+        info: console.info,
+        debug: console.debug,
+        write: process.stdout.write,
+    }
+    const toStderr = (...args) => console.error(...args)
+    console.log = toStderr
+    console.info = toStderr
+    console.debug = toStderr
+    process.stdout.write = (...args) => process.stderr.write(...args)
+    return () => {
+        console.log = saved.log
+        console.info = saved.info
+        console.debug = saved.debug
+        process.stdout.write = saved.write
+    }
+}

package/template/AGENTS.md

@@ -35,6 +35,10 @@ Markdown file.
 - `npx nera build --check` — build, then check the built `public/` for
   accessibility, privacy and legal issues (`npx nera check` checks without
   building)
+- `npx nera validate --json`, `npx nera check --json` and
+  `npx nera build --check --json` print one JSON object on stdout,
+  `{ "ok", "results": [{ file, line, severity, rule, message }] }`, with
+  the same exit code; the build log goes to stderr
 
 ## After every change