@nera-static/core 4.12.0 → 4.13.0

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/README.md CHANGED
@@ -88,15 +88,17 @@ const model = resolveSiteModel({ cwd: '/path/to/site' })
88
88
 
89
89
  Plugins are discovered from two places: local directories under the configured plugins folder (`folders.plugins`, default `./src/plugins`; a thin site sets `./plugins`), and any dependency in the **site's** `package.json` whose name starts with **`@nera-static/plugin-`** (excluding the `@nera-static/plugin-utils` library).
90
90
 
91
- A plugin is an ESM module exporting either or both hooks — no registration, no base class:
91
+ A plugin is an ESM module exporting any of these hooks — no registration, no base class:
92
92
 
93
93
  ```js
94
94
  export function getAppData({ app, pagesData }) { /* return a new app object */ }
95
95
  export function getMetaData({ app, pagesData }) { /* return a new pagesData array */ }
96
+ export function getAssets({ app, pagesData }) { /* return [{ from, to }] to copy into public/ */ }
96
97
  ```
97
98
 
98
99
  - `getAppData` runs first and must return a **plain object**; `getMetaData` must return an **array**. A wrong return type is discarded with a warning and the build continues.
99
100
  - Results are threaded: `getMetaData` sees the `app` that `getAppData` returned.
101
+ - `getAssets` (core ≥ 4.13.0) is for plugins that produce files. It runs after every plugin's `getAppData`/`getMetaData`, in plugin order, with the final `app`/`pagesData`, and returns an array of `{ from, to }`: `from` an absolute file or directory, `to` a path relative to `public/` (for a file, the target file path; for a directory, the folder its contents go into). Core copies them after the theme's assets and before the site's (theme → plugins → site, so the site wins a collision), unfiltered by `.neraignore`, and before `base_path` rewriting and asset hashing, which therefore cover them. A non-array result, or an entry with a missing/relative `from` or an absolute or `public/`-escaping `to`, is skipped with a warning; a `from` that does not exist is skipped at copy time.
100
102
  - Both hooks are awaited (generator ≥ 4.3.0), but keeping them synchronous is the safe default.
101
103
  - Config is read from the **user's site** (`config/<name>.yaml` via `getConfig`), not from the plugin package; supply per-key JS fallbacks.
102
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nera-static/core",
3
- "version": "4.12.0",
3
+ "version": "4.13.0",
4
4
  "description": "The Nera static site generator engine — the build pipeline and the layered theme/view resolver, importable by the Nera CLI, @nera-static/validate and tooling",
5
5
  "main": "./src/index.js",
6
6
  "exports": {
package/src/index.js CHANGED
@@ -2,6 +2,7 @@ import { loadAppData, getPagesData, defaultSettings } from './core.js'
2
2
  import { getPluginsData } from './setup-plugins.js'
3
3
  import {
4
4
  copyFolder,
5
+ copyPluginAssets,
5
6
  deleteFolder,
6
7
  createHtmlFiles,
7
8
  rewriteAssetUrls,
@@ -68,6 +69,10 @@ const run = async (settings = defaultSettings) => {
68
69
  if (theme) {
69
70
  await copyFolder(theme.assetsRoot, dist, null)
70
71
  }
72
+ // Plugin assets (`getAssets`) sit between the two: they override the
73
+ // theme and the site overrides them. Unfiltered like the theme pass — the
74
+ // payload is plugin-controlled.
75
+ await copyPluginAssets(data.assets, dist)
71
76
  await copyFolder(assets, dist, '.')
72
77
 
73
78
  // Subdirectory deploys: prefix root-absolute URLs inside copied assets that
package/src/render.js CHANGED
@@ -365,6 +365,38 @@ export const copyFolder = async (sourceFolder, targetFolder, ignoreBase) => {
365
365
  }
366
366
  }
367
367
 
368
+ // Copy the entries plugins returned from `getAssets` (already validated by
369
+ // setup-plugins.js#validateAsset) into `targetFolder`. A directory `from` has
370
+ // its contents copied into `to`; a file `from` is copied to the file path `to`.
371
+ // A `from` that does not exist is skipped with a warning, the build continues.
372
+ // No `.neraignore` filtering: the payload is plugin-controlled.
373
+ export const copyPluginAssets = async (assets = [], targetFolder) => {
374
+ for (const { from, to, plugin } of assets) {
375
+ const target = path.join(targetFolder, to)
376
+ let stat
377
+
378
+ try {
379
+ stat = await fs.stat(from)
380
+ } catch {
381
+ console.warn(
382
+ `⚠️ Plugin "${plugin}" asset not found, skipped: ${from}`
383
+ )
384
+ continue
385
+ }
386
+
387
+ if (stat.isDirectory()) {
388
+ await copyFolder(from, target, null)
389
+ } else if (to === '') {
390
+ console.warn(
391
+ `⚠️ Plugin "${plugin}" asset ${from} is a file and needs a file path as "to", skipped`
392
+ )
393
+ } else {
394
+ await fs.mkdir(path.dirname(target), { recursive: true })
395
+ await fs.copyFile(from, target)
396
+ }
397
+ }
398
+ }
399
+
368
400
  // The layered view resolver (`makeLayeredResolver`/`resolveEntry`) now lives in
369
401
  // `./resolve.js` so `@nera-static/validate` can reuse the exact same logic; it
370
402
  // is imported at the top of this file.
@@ -227,11 +227,84 @@ export async function getPluginsData(
227
227
  }
228
228
 
229
229
  //
230
- // 6. Return final
230
+ // 6. Collect plugin assets
231
+ //
232
+ // After every getAppData/getMetaData has run, so each plugin sees the final
233
+ // app/pagesData and knows which files it produced. Core copies them into
234
+ // public/ between the theme and the site asset passes (src/index.js).
235
+ const assets = []
236
+
237
+ for (const plugin of ordered) {
238
+ const mod = plugin.module
239
+
240
+ if (typeof mod.getAssets !== 'function') continue
241
+
242
+ const result = await mod.getAssets({ app: appData, pagesData })
243
+ if (!Array.isArray(result)) {
244
+ console.warn(
245
+ `⚠️ Plugin "${plugin.name}" getAssets returned invalid format, skipping.`
246
+ )
247
+ continue
248
+ }
249
+
250
+ for (const entry of result) {
251
+ const asset = validateAsset(entry)
252
+ if (typeof asset === 'string') {
253
+ console.warn(
254
+ `⚠️ Plugin "${plugin.name}" getAssets entry skipped: ${asset}`
255
+ )
256
+ continue
257
+ }
258
+ assets.push({ ...asset, plugin: plugin.name })
259
+ }
260
+ }
261
+
262
+ //
263
+ // 7. Return final
231
264
  //
232
265
  return {
233
266
  app: appData,
234
267
  pagesData,
235
268
  plugins: ordered.map((p) => p.module),
269
+ assets,
236
270
  }
237
271
  }
272
+
273
+ /**
274
+ * Validate one `getAssets` entry. Returns the normalized `{ from, to }`, or a
275
+ * string saying why the entry is skipped.
276
+ *
277
+ * `from` must be an absolute path (file or directory). `to` is relative to
278
+ * public/ and may not be absolute or climb out of it; `''`/`'.'` mean public/
279
+ * itself. Backslashes are accepted so a plugin may pass `path.join` output on
280
+ * Windows.
281
+ */
282
+ export function validateAsset(entry) {
283
+ if (!entry || typeof entry !== 'object') {
284
+ return 'not an object'
285
+ }
286
+
287
+ const { from, to } = entry
288
+
289
+ if (typeof from !== 'string' || from === '') {
290
+ return 'missing "from"'
291
+ }
292
+ if (!path.isAbsolute(from)) {
293
+ return `"from" must be an absolute path (${from})`
294
+ }
295
+ if (typeof to !== 'string') {
296
+ return `missing "to" (from ${from})`
297
+ }
298
+
299
+ const slashed = to.replace(/\\/g, '/')
300
+ if (path.isAbsolute(to) || slashed.startsWith('/') || /^[a-zA-Z]:/.test(to)) {
301
+ return `"to" must be relative to public/ (${to})`
302
+ }
303
+
304
+ const normalized = path.posix.normalize(slashed || '.')
305
+ if (normalized === '..' || normalized.startsWith('../')) {
306
+ return `"to" escapes public/ (${to})`
307
+ }
308
+
309
+ return { from, to: normalized === '.' ? '' : normalized.replace(/\/$/, '') }
310
+ }