@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/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
+ })