@nera-static/core 4.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +231 -0
- package/index.js +3 -0
- package/package.json +83 -0
- package/src/core.js +227 -0
- package/src/index.js +101 -0
- package/src/render.js +299 -0
- package/src/resolve.js +59 -0
- package/src/setup-plugins.js +237 -0
- package/src/site-model.js +64 -0
- package/src/theme.js +268 -0
- package/src/watch-assets.js +29 -0
package/src/theme.js
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
import fs from 'fs'
|
|
2
|
+
import path from 'path'
|
|
3
|
+
import yaml from 'yaml'
|
|
4
|
+
import { createRequire } from 'module'
|
|
5
|
+
import { fileURLToPath } from 'url'
|
|
6
|
+
import { satisfies, validRange } from 'semver'
|
|
7
|
+
|
|
8
|
+
// Theme discovery (ROADMAP-themes.md §1).
|
|
9
|
+
//
|
|
10
|
+
// `app.theme` accepts three forms, and every one resolves to a THEME ROOT whose
|
|
11
|
+
// payload — `views/`, `assets/`, `config/` — sits directly at that root, with no
|
|
12
|
+
// inner `theme/` wrapper (§1b, revised 2026-07-23). A theme package contains
|
|
13
|
+
// nothing but the theme, so its package root already *is* the theme root:
|
|
14
|
+
//
|
|
15
|
+
// docs → @nera-static/theme-docs (bare name, scoped prefix)
|
|
16
|
+
// @acme/my-theme → verbatim (contains `/` or `@`)
|
|
17
|
+
// . / ./path/to/it → path relative to cwd (local, in-dev or private)
|
|
18
|
+
//
|
|
19
|
+
// A missing `theme:` key returns null and the generator renders exactly as it
|
|
20
|
+
// does today. A `theme:` that cannot be resolved throws — a theme set but not
|
|
21
|
+
// found means every layout is missing, and the build would otherwise produce an
|
|
22
|
+
// unstyled site with exit code 0 (the "fail loudly" decision, §1a).
|
|
23
|
+
//
|
|
24
|
+
// The returned `config` is the theme's `config/theme.yaml` defaults deep-merged
|
|
25
|
+
// with the site's optional `config/theme.yaml` (§1c). The pipeline exposes the
|
|
26
|
+
// whole result to templates as `app.theme = { name, package, config }`.
|
|
27
|
+
export function resolveTheme({ app, cwd = process.cwd() } = {}) {
|
|
28
|
+
const spec = app?.theme
|
|
29
|
+
if (!spec) return null
|
|
30
|
+
|
|
31
|
+
const isLocal = spec.startsWith('.')
|
|
32
|
+
const root = isLocal
|
|
33
|
+
? path.resolve(cwd, spec)
|
|
34
|
+
: resolvePackageRoot(spec, cwd)
|
|
35
|
+
|
|
36
|
+
// The theme root IS the payload root — no wrapper to append (§1b, revised).
|
|
37
|
+
const viewsRoot = path.join(root, 'views')
|
|
38
|
+
const assetsRoot = path.join(root, 'assets')
|
|
39
|
+
|
|
40
|
+
if (!fs.existsSync(viewsRoot)) {
|
|
41
|
+
throw new Error(
|
|
42
|
+
`theme: "${spec}" resolved to ${root}, but ${viewsRoot} does not exist`
|
|
43
|
+
)
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const config = loadThemeConfig(root, app, cwd)
|
|
47
|
+
|
|
48
|
+
return {
|
|
49
|
+
name: spec,
|
|
50
|
+
package: isLocal ? null : packageName(spec),
|
|
51
|
+
root,
|
|
52
|
+
viewsRoot,
|
|
53
|
+
assetsRoot,
|
|
54
|
+
config,
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// §1c: the theme package ships `config/theme.yaml` (at its root) with real
|
|
59
|
+
// defaults; the site's `config/theme.yaml` (at the site's config folder — config
|
|
60
|
+
// stays out of `theme/`) is optional and deep-merges OVER those defaults.
|
|
61
|
+
//
|
|
62
|
+
// This is a DELIBERATE divergence from the plugin `getConfig` contract, where
|
|
63
|
+
// the site's file is read wholesale with no merge. Here the merge IS the point
|
|
64
|
+
// (§1c): a site changing one token inherits the rest, and still receives tokens
|
|
65
|
+
// the theme adds later. Do not "fix" this for consistency — a missing site file
|
|
66
|
+
// is fine (all defaults inherited), and everything stays synchronous.
|
|
67
|
+
function loadThemeConfig(root, app, cwd) {
|
|
68
|
+
const themeDefaults = readYaml(path.join(root, 'config', 'theme.yaml'))
|
|
69
|
+
// Mirror the site config lookup the rest of the pipeline uses: the config
|
|
70
|
+
// folder from app.folders (set by loadAppData), resolved against cwd. A bare
|
|
71
|
+
// `config` default covers callers that resolve a theme before folders merge.
|
|
72
|
+
const configFolder = app?.folders?.config || 'config'
|
|
73
|
+
const siteOverrides = readYaml(path.resolve(cwd, configFolder, 'theme.yaml'))
|
|
74
|
+
|
|
75
|
+
return deepMerge(themeDefaults, siteOverrides)
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// Parse a YAML file to a plain object, tolerating absence and malformed content
|
|
79
|
+
// the same warn-and-continue way loadAppData does — a broken theme.yaml must not
|
|
80
|
+
// abort the build, it just contributes nothing to the merge.
|
|
81
|
+
function readYaml(file) {
|
|
82
|
+
if (!fs.existsSync(file)) return {}
|
|
83
|
+
try {
|
|
84
|
+
return yaml.parse(fs.readFileSync(file, 'utf-8')) || {}
|
|
85
|
+
} catch (err) {
|
|
86
|
+
console.warn(`⚠️ Nera: failed to parse ${file}: ${err.message}`)
|
|
87
|
+
return {}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// Deep merge for §1c: objects merge per key, arrays are replaced wholesale, the
|
|
92
|
+
// override (site) wins at every leaf. Pure and synchronous — returns a fresh
|
|
93
|
+
// object and mutates neither argument.
|
|
94
|
+
export function deepMerge(base, override) {
|
|
95
|
+
if (!isPlainObject(base) || !isPlainObject(override)) return override
|
|
96
|
+
|
|
97
|
+
const out = { ...base }
|
|
98
|
+
for (const key of Object.keys(override)) {
|
|
99
|
+
out[key] =
|
|
100
|
+
isPlainObject(base[key]) && isPlainObject(override[key])
|
|
101
|
+
? deepMerge(base[key], override[key])
|
|
102
|
+
: override[key]
|
|
103
|
+
}
|
|
104
|
+
return out
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function isPlainObject(value) {
|
|
108
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value)
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// A bare name is expanded to the @nera-static/theme-<name> convention; anything
|
|
112
|
+
// scoped or slashed is used verbatim, so third-party themes work too.
|
|
113
|
+
function packageName(spec) {
|
|
114
|
+
return spec.includes('/') || spec.startsWith('@')
|
|
115
|
+
? spec
|
|
116
|
+
: `@nera-static/theme-${spec}`
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// Locate an installed theme on disk. A theme has no JS entry point, so it cannot
|
|
120
|
+
// be import()ed; instead resolve its package.json from the site's node_modules
|
|
121
|
+
// and take the directory — that dirname is the theme root directly (§1b). Theme
|
|
122
|
+
// packages expose "./package.json" in exports (or omit exports entirely)
|
|
123
|
+
// precisely so this resolves.
|
|
124
|
+
function resolvePackageRoot(spec, cwd) {
|
|
125
|
+
const pkg = packageName(spec)
|
|
126
|
+
// Resolve from the site (cwd), like every other lookup in the pipeline —
|
|
127
|
+
// the theme is a dependency of the site, not of the generator.
|
|
128
|
+
const requireFromSite = createRequire(path.join(cwd, 'package.json'))
|
|
129
|
+
|
|
130
|
+
try {
|
|
131
|
+
return path.dirname(requireFromSite.resolve(`${pkg}/package.json`))
|
|
132
|
+
} catch {
|
|
133
|
+
throw new Error(
|
|
134
|
+
`theme: "${spec}" — package ${pkg} is not installed. ` +
|
|
135
|
+
`Run: npm install ${pkg}`
|
|
136
|
+
)
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// §5: compatibility declarations. A theme declares what it supports two ways,
|
|
141
|
+
// and a mismatch has two different severities:
|
|
142
|
+
//
|
|
143
|
+
// generator (nera.generator range) → FAIL the build (non-cosmetic)
|
|
144
|
+
// plugins (peerDependencies) → WARN, keep rendering (cosmetic)
|
|
145
|
+
//
|
|
146
|
+
// The generator check FAILS because a theme built against a newer generator may
|
|
147
|
+
// use an app.* key, a Pug feature or a resolution behaviour the running one does
|
|
148
|
+
// not have — that breaks rendering, not just styling, and npm cannot catch it
|
|
149
|
+
// (the generator is git-cloned, not an npm package; §7). The plugin check only
|
|
150
|
+
// WARNS because the failure is cosmetic: the plugin still renders correct markup,
|
|
151
|
+
// the theme just lacks CSS for BEM class names a newer major introduced. npm
|
|
152
|
+
// already surfaces peer conflicts at install; the build-time check is a soft
|
|
153
|
+
// nudge, so it must never abort.
|
|
154
|
+
//
|
|
155
|
+
// Everything here is synchronous, and a theme that declares neither field (or a
|
|
156
|
+
// themeless site, which never calls this) is entirely unaffected.
|
|
157
|
+
export function checkThemeCompatibility(
|
|
158
|
+
theme,
|
|
159
|
+
{ cwd = process.cwd(), generatorVersion = readGeneratorVersion() } = {}
|
|
160
|
+
) {
|
|
161
|
+
if (!theme) return
|
|
162
|
+
|
|
163
|
+
const themePkg = readThemePackageJson(theme.root)
|
|
164
|
+
|
|
165
|
+
checkGeneratorCompatibility(theme, themePkg, generatorVersion)
|
|
166
|
+
checkPluginCompatibility(theme, themePkg, cwd)
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// The generator's OWN version, read from the generator's package.json — NOT the
|
|
170
|
+
// site's package.json `version`, which is a clone-flow artefact (mergePackageJson
|
|
171
|
+
// copies it in) and, after the generator becomes an npm package (§8), would be a
|
|
172
|
+
// different number than the generator's. Reading the generator's own manifest is
|
|
173
|
+
// the one source that stays correct across that change (the §5 "trap").
|
|
174
|
+
export function readGeneratorVersion() {
|
|
175
|
+
// theme.js lives in <generator>/src, so the manifest is one level up.
|
|
176
|
+
const here = path.dirname(fileURLToPath(import.meta.url))
|
|
177
|
+
const pkgPath = path.resolve(here, '..', 'package.json')
|
|
178
|
+
try {
|
|
179
|
+
return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version
|
|
180
|
+
} catch {
|
|
181
|
+
return null
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// Read a theme package's package.json off its root; tolerate absence/malformed
|
|
186
|
+
// content the warn-and-continue way, so a theme without a manifest (e.g. a bare
|
|
187
|
+
// local folder used in development) simply declares no compatibility and passes.
|
|
188
|
+
function readThemePackageJson(root) {
|
|
189
|
+
if (!root) return {}
|
|
190
|
+
const file = path.join(root, 'package.json')
|
|
191
|
+
if (!fs.existsSync(file)) return {}
|
|
192
|
+
try {
|
|
193
|
+
return JSON.parse(fs.readFileSync(file, 'utf-8')) || {}
|
|
194
|
+
} catch (err) {
|
|
195
|
+
console.warn(`⚠️ Nera: failed to parse ${file}: ${err.message}`)
|
|
196
|
+
return {}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// nera.generator: a plain semver range, standard npm semantics — chosen so the
|
|
201
|
+
// day the generator becomes an npm package (§8) the value moves verbatim into
|
|
202
|
+
// peerDependencies and this check becomes redundant, not wrong (§5). A range
|
|
203
|
+
// that excludes the running generator throws, failing the build with a non-zero
|
|
204
|
+
// exit (the same fail-loudly path resolveTheme uses for a missing theme).
|
|
205
|
+
function checkGeneratorCompatibility(theme, themePkg, generatorVersion) {
|
|
206
|
+
const range = themePkg?.nera?.generator
|
|
207
|
+
if (!range) return // no declaration → nothing to enforce
|
|
208
|
+
|
|
209
|
+
if (!validRange(range)) {
|
|
210
|
+
// A malformed range is the theme author's bug, not the site's — warn
|
|
211
|
+
// rather than fail so it cannot brick every site that installs the theme.
|
|
212
|
+
console.warn(
|
|
213
|
+
`⚠️ Nera: theme "${theme.name}" declares an invalid ` +
|
|
214
|
+
`nera.generator range "${range}" — ignoring it.`
|
|
215
|
+
)
|
|
216
|
+
return
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// Can't read our own version (should not happen) → skip rather than
|
|
220
|
+
// false-fail a build over a missing manifest.
|
|
221
|
+
if (!generatorVersion) return
|
|
222
|
+
|
|
223
|
+
if (!satisfies(generatorVersion, range)) {
|
|
224
|
+
throw new Error(
|
|
225
|
+
`theme "${theme.name}" requires Nera generator ${range}, but this ` +
|
|
226
|
+
`generator is ${generatorVersion}. Update the generator ` +
|
|
227
|
+
'(nera update) or install a theme version compatible with ' +
|
|
228
|
+
`${generatorVersion}.`
|
|
229
|
+
)
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// peerDependencies: the plugins whose BEM class names the theme's CSS targets
|
|
234
|
+
// (§4 — a theme never ships views/vendor, so its entire plugin-facing surface is
|
|
235
|
+
// CSS against class names). A plugin installed at a version OUTSIDE the declared
|
|
236
|
+
// range warns: the plugin still renders correct markup, the theme just may lack
|
|
237
|
+
// CSS for it. A plugin the site does not install at all is silent — there is
|
|
238
|
+
// nothing to mis-style, and npm already flagged any genuine unmet peer at install.
|
|
239
|
+
function checkPluginCompatibility(theme, themePkg, cwd) {
|
|
240
|
+
const peers = themePkg?.peerDependencies
|
|
241
|
+
if (!peers) return
|
|
242
|
+
|
|
243
|
+
for (const [name, range] of Object.entries(peers)) {
|
|
244
|
+
const installed = installedVersion(name, cwd)
|
|
245
|
+
if (!installed) continue // not used by this site → no styling to break
|
|
246
|
+
if (validRange(range) && !satisfies(installed, range)) {
|
|
247
|
+
console.warn(
|
|
248
|
+
`⚠️ Nera: theme "${theme.name}" targets ${name}@"${range}" ` +
|
|
249
|
+
`for its styling, but ${name}@${installed} is installed — ` +
|
|
250
|
+
`some ${name} output may be unstyled. Check the theme's ` +
|
|
251
|
+
'changelog for a compatible version.'
|
|
252
|
+
)
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
// The installed version of a dependency, resolved from the SITE (cwd) exactly
|
|
258
|
+
// like resolvePackageRoot — the plugins are the site's dependencies, not the
|
|
259
|
+
// generator's. Returns null when the package is not installed or unreadable.
|
|
260
|
+
function installedVersion(name, cwd) {
|
|
261
|
+
const requireFromSite = createRequire(path.join(cwd, 'package.json'))
|
|
262
|
+
try {
|
|
263
|
+
const pkgPath = requireFromSite.resolve(`${name}/package.json`)
|
|
264
|
+
return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || null
|
|
265
|
+
} catch {
|
|
266
|
+
return null
|
|
267
|
+
}
|
|
268
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import chokidar from 'chokidar'
|
|
2
|
+
import fs from 'fs'
|
|
3
|
+
import { copyFolder } from './render.js'
|
|
4
|
+
import path from 'path'
|
|
5
|
+
import dotenv from 'dotenv'
|
|
6
|
+
|
|
7
|
+
dotenv.config()
|
|
8
|
+
|
|
9
|
+
// Mirror the presentation probe in core.js (ROADMAP-themes.md §1b): a site's own
|
|
10
|
+
// assets live under theme/ in the revised layout, falling back to the legacy
|
|
11
|
+
// root assets/ so an unmigrated site still watches the right folder.
|
|
12
|
+
const sourceFolder = fs.existsSync('theme')
|
|
13
|
+
? path.resolve('theme/assets')
|
|
14
|
+
: path.resolve('assets')
|
|
15
|
+
const distFolder = path.resolve('public')
|
|
16
|
+
|
|
17
|
+
// Read the site's .neraignore from the site root ('.'), matching the render
|
|
18
|
+
// pipeline — it stays there even though assets now live under theme/assets.
|
|
19
|
+
const initialCopy = () => copyFolder(sourceFolder, distFolder, '.')
|
|
20
|
+
|
|
21
|
+
// Initial copy
|
|
22
|
+
await initialCopy()
|
|
23
|
+
|
|
24
|
+
chokidar
|
|
25
|
+
.watch(sourceFolder, { ignoreInitial: true })
|
|
26
|
+
.on('all', async (event, filePath) => {
|
|
27
|
+
console.log(`[watch-assets] ${event} → ${filePath}`)
|
|
28
|
+
await initialCopy()
|
|
29
|
+
})
|