mikser-io-layouts 1.0.0 → 2.3.0

package/README.md

@@ -30,9 +30,11 @@ export default {
 
 ## Factory options
 
+Every value below is the **default**; pass an option only to change it.
+
 ```js
 layouts({
-  layoutsFolder: 'layouts',    // default: 'layouts'
+  layoutsFolder: 'layouts',
 
   // Each pattern that matches contributes a render task. Multi-match:
   // an entity at /blog/welcome.md matches both '@/blog/*' (post) AND
@@ -44,10 +46,21 @@ layouts({
   },
 
   autoLayouts: true,           // Auto-match by name (single-match fallback; see below)
-  cleanUrls: true              // /page.html → /page/index.html
+  cleanUrls: true,             // /page → /page/index.html, so the served URL is /page/
 })
 ```
 
+`cleanUrls` already special-cases names ending in `index` (`index` stays
+`/index.html`, it does not become `/index/index.html`). Reaching for a
+`destination:` template to get pretty URLs reinvents this — and breaks index
+pages, because the template fully overrides the transform.
+
+`match` has no default: with no patterns and `autoLayouts` on, layouts are
+found by name.
+
+```js
+```
+
 ## Per-entity selection — `meta.layout` / `meta.layouts`
 
 An entity can override match-based assignment via frontmatter:
@@ -82,6 +95,29 @@ Cross-directory auto-matching is intentionally not supported — pair `posts/art
 
 A layout's frontmatter can declare a `destination:` template. The template is Handlebars (path-shaped — substitutions only, no body rendering); it gets `{ entity }` as the context, is compiled once and cached, and the result is path-sanitized (`..` segments rejected). This fully overrides the default `entity.name + .format` derivation (and the cleanUrls folder transform).
 
+A small set of path-shaping helpers is available, so a destination can be
+derived from *part* of a value rather than only interpolating whole ones:
+
+| helper | |
+| --- | --- |
+| `after v sep` / `before v sep` | split at the **first** separator |
+| `afterLast v sep` / `beforeLast v sep` | split at the **last** separator |
+| `replace v search replacement` | literal, every occurrence — not a regex |
+| `dirname v` / `basename v` | POSIX path parts |
+| `lower v` / `upper v` | case |
+
+The case they exist for is per-language output roots. With three languages in
+one catalog under `documents/{lang}/…`, `entity.name` is `bg/kontakti` and each
+language wants its own document root:
+
+```yaml
+destination: /{{ after entity.name '/' }}/index.html   # → /kontakti/index.html
+```
+
+They are registered on an **isolated** Handlebars instance, so nothing appears
+in your own `renderHbs` layouts. Anything more than path slicing belongs in the
+layout's `.js` sidecar rather than in a template.
+
 ```yaml
 # layouts/post-card.html.hbs
 ---

package/index.js

@@ -19,6 +19,7 @@ import _ from 'lodash'
 import {
     gateChecksum, sweepDeleted, scanSummary,
     checksumsByCollection,
+    checksum as fileChecksum, checksumOf,
     useDatabase,
 } from 'mikser-io'
 
@@ -27,7 +28,16 @@ import { createOnProcessed } from './lib/matching.js'
 import { createOnBeforeRender } from './lib/assembly.js'
 import { registerMcpTools } from './lib/mcp.js'
 
-export function layouts(options = {}) {
+export function layouts(userOptions = {}) {
+    // cleanUrls DEFAULTS TO TRUE. It previously had no default, so unset it
+    // was falsy and pages landed at `hera.html` instead of `hera/index.html`
+    // — while the README's options block presented `cleanUrls: true` in a way
+    // that reads as a defaults table. There was no warning, the site worked,
+    // and the wrong URL shape was everywhere: the kind of thing discovered
+    // after canonical tags and hreflang are wired against the shape you
+    // assumed. Defaulting it matches both the README and what almost every
+    // site wants; pass `cleanUrls: false` for flat output.
+    const options = { cleanUrls: true, ...userOptions }
     return ({
         runtime,
         onLoaded,
@@ -95,7 +105,29 @@ export function layouts(options = {}) {
 
         onSync(collection, async ({ action, context }) => {
             if (!context.relativePath) return false
+            const logger = useLogger()
             const { relativePath } = context
+
+            // A .js file under the layouts folder is a SIDECAR (or something
+            // a sidecar imports), never a layout. It used to have its `.js`
+            // stripped and be created as an entity, which produced a phantom
+            // `/layouts/page` — holding JS source as its content — beside the
+            // real `/layouts/page.liquid`.
+            //
+            // Sidecars are inputs to a layout's checksum instead (see
+            // sidecarInputs above), so the right response to one changing is
+            // to re-run the layouts scan: it recomputes every composite and
+            // emits an UPDATE for whichever layouts actually moved, which is
+            // what makes their dependents re-render.
+            if (_.endsWith(relativePath, '.js') && isSidecarScript(relativePath)) {
+                logger.debug('Layouts sidecar changed (%s) — rescanning layouts', relativePath)
+                await rescanLayouts()
+                return
+            }
+
+            // A JS-authored layout (post.hbs.js) keeps its historical
+            // behaviour: the trailing .js is dropped so the id is
+            // /layouts/post.hbs.
             let id = path.join(`/${collection}`, relativePath)
             if (_.endsWith(id, '.js')) id = id.replace(new RegExp('.js$'), '')
 
@@ -187,10 +219,72 @@ export function layouts(options = {}) {
             }
         })
 
-        onImport(async () => {
+        // A layout's `.js` sidecar is where a mikser site's data layer lives,
+        // and it was the one file in the project that could be edited without
+        // effect: `.js` is excluded from the scan below, so the sidecar was
+        // not an entity, not watched as an input, and not part of any hash.
+        // Nothing depended on it, so nothing re-rendered — silently, and
+        // looking exactly like a bug in your own code.
+        //
+        // Fixed by folding sidecars into the LAYOUT's checksum rather than
+        // making them entities. A sidecar is an input to a layout, not a
+        // thing a site has; giving it an entity would put JS source in the
+        // catalog and (via the id-stripping in onSync) a phantom
+        // `/layouts/page` alongside the real `/layouts/page.liquid`.
+        //
+        // Two components:
+        //   own     — the layout's own sidecar, `<name>.js`
+        //   shared  — every OTHER .js under the folder, as one digest
+        //
+        // `shared` is coarse on purpose: a sidecar's own imports
+        // (layouts/lib/context.js and friends) would otherwise need a module
+        // graph walk. Treating any shared .js change as invalidating every
+        // layout is what the folder can afford — tens of files, not
+        // thousands — and it is predictable, which a partial graph walk
+        // would not be.
+        // NOT every .js under the folder is a sidecar. `post.hbs.js` is a
+        // LAYOUT — a template written as JS, whose id drops the trailing .js
+        // to become /layouts/post.hbs. `post.js` is the sidecar for layout
+        // `post`. The discriminator is whether stripping `.js` leaves a
+        // further extension:
+        //
+        //   post.js        → post        no extension  → sidecar
+        //   lib/context.js → lib/context no extension  → sidecar-adjacent
+        //   post.hbs.js    → post.hbs    .hbs          → layout, leave alone
+        //
+        // Getting this wrong turns every JS-authored layout into a
+        // non-entity, which is why it is a rule and not a guess.
+        const isSidecarScript = (rel) => path.extname(rel.replace(/\.js$/, '')) === ''
+
+        async function sidecarInputs() {
+            const scriptPaths = (await globby('**/*.js', { cwd: runtime.options.layoutsFolder }))
+                .filter(isSidecarScript)
+            const own = new Map()
+            const shared = []
+            for (const rel of scriptPaths.sort()) {
+                const sum = await fileChecksum(path.join(runtime.options.layoutsFolder, rel))
+                own.set(rel.replace(/\.js$/, ''), sum)
+                shared.push(`${rel}:${sum}`)
+            }
+            return { own, sharedDigest: shared.length ? checksumOf(shared.join('\n')) : '' }
+        }
+
+        // The value the checksum gate compares. Passed as `bytes` so the gate
+        // keeps owning the --force / cache-invalidated / prior-checksum
+        // logic instead of this plugin reimplementing it.
+        async function layoutInputBytes(uri, name, inputs) {
+            const template = await fileChecksum(uri)
+            const sidecar = inputs.own.get(name) ?? ''
+            return Buffer.from(`${template}:${sidecar}:${inputs.sharedDigest}`, 'utf8')
+        }
+
+        // Named so onSync can re-run it when a sidecar changes. A function
+        // declaration, so it is hoisted above the onSync registration above.
+        async function rescanLayouts() {
             const { layouts } = runtime.state.layouts
             const logger = useLogger()
             const paths = await globby('**/*', { cwd: runtime.options.layoutsFolder, ignore: ['**/*.js'] })
+            const inputs = await sidecarInputs()
             const scanned = new Set()
             const stats = { emitted: 0, skipped: 0, deleted: 0 }
 
@@ -212,7 +306,11 @@ export function layouts(options = {}) {
                 const id = path.join('/layouts', relativePath)
                 scanned.add(id)
 
-                const chksum = await gateChecksum(uri, id, { priorChecksums })
+                const name = relativePath.replace(path.extname(relativePath), '')
+                const chksum = await gateChecksum(uri, id, {
+                    priorChecksums,
+                    bytes: await layoutInputBytes(uri, name, inputs),
+                })
                 if (chksum === null) {
                     stats.skipped++
                     continue
@@ -225,6 +323,15 @@ export function layouts(options = {}) {
                     type,
                     content: await readLayoutContent(uri),
                     checksum: chksum,
+                    // Declared so inputHashOf folds the sidecars into this
+                    // layout's input hash. Without it the gate checksum
+                    // moves but the hash does not — an entity that has
+                    // content is hashed on {meta, content} — so consumers
+                    // still skip and the sidecar edit reaches nothing.
+                    inputs: {
+                        sidecar: inputs.own.get(name) ?? null,
+                        shared: inputs.sharedDigest || null,
+                    },
                 }
                 Object.assign(layout, await getFormatInfo(relativePath))
                 layouts[layout.name] = layout
@@ -250,7 +357,9 @@ export function layouts(options = {}) {
             // protection as CSV-emitted documents).
 
             logger.info(scanSummary({ cap: 'Layouts', loaded: paths.length, ...stats }))
-        })
+        }
+
+        onImport(rescanLayouts)
 
         // Matching + assembly are extracted to lib/ for cognitive load
         // (~185 + ~360 lines respectively). They still close over the

package/lib/assembly.js

@@ -26,7 +26,7 @@ import {
     queryContext,
     useDatabase,
 } from 'mikser-io'
-import { compileDestinationTemplate, sanitizeDestination } from './destination.js'
+import { compileDestinationTemplate, sanitizeDestination, primaryDestination } from './destination.js'
 
 export function createOnBeforeRender({
     runtime, useLogger, useJournal,
@@ -342,28 +342,13 @@ export function createOnBeforeRender({
                         }
                     }
                 } else {
-                    if (destinationTemplate) {
-                        entity.destination = sanitizeDestination(destinationTemplate({ entity }))
-                    } else if (!_.endsWith(entity.name, entity.format)) {
-                        // cleanUrls turns `foo` into `foo/index.html` so the
-                        // served URL is `/foo/`. Skip the transform when the
-                        // layout declares a postprocessor — the HTML render
-                        // is a throwaway stepping stone (a PDF stepping
-                        // stone has no served URL), and leaving it flat
-                        // means engine.onPostprocess's plain extension swap
-                        // produces `/foo.<ext>` naturally. Postprocess is
-                        // decoupled from cleanUrls by where the decision
-                        // gets made — not by the engine knowing about it.
-                        if (options.cleanUrls
-                            && !_.endsWith(entity.name, 'index')
-                            && entity.layout.format == 'html'
-                            && !entity.layout.postprocessor
-                        ) {
-                            entity.destination = path.join(entity.destination, `index.${entity.layout.format}`)
-                        } else {
-                            entity.destination += `.${entity.layout.format}`
-                        }
-                    }
+                    // Same derivation onProcessed persists onto the catalog
+                    // entity — one function, so a stored destination and the
+                    // file actually written cannot disagree. Drift here would
+                    // produce links pointing at files that are not there.
+                    entity.destination = primaryDestination({
+                        entity, layout: entity.layout, options, endsWith: _.endsWith,
+                    })
                     if (entity.destination) {
                         queueTask(entity, {
                             renderer: entity.layout.template,

package/lib/destination.js

@@ -11,9 +11,48 @@ import handlebars from 'handlebars'
 
 const destinationTemplateCache = new Map()
 
+// An ISOLATED Handlebars instance. Registering helpers on the shared default
+// export would leak them into anything else in the process using handlebars —
+// including a project's own renderHbs layouts, where a helper named `replace`
+// appearing from nowhere would be a genuinely confusing surprise.
+const hbs = handlebars.create()
+
+const str = (value) => (value == null ? '' : String(value))
+
+// A destination template can only interpolate whole values without these, so
+// a path cannot be derived from PART of entity.name. The case that needs it:
+// a catalog holding three languages under documents/{lang}/…, where
+// entity.name is `bg/kontakti` and the wanted destination is
+// `/kontakti/index.html` — name minus the language segment. Without helpers
+// that is inexpressible, and the workarounds are a sidecar mutating the
+// entity mid-assembly (a side effect where there should be none) or one
+// documents() per language (which empties the catalog of the other languages
+// and breaks the hreflang and language switcher that needed one catalog).
+//
+// Deliberately a small, path-shaped set. These are for slicing a path, not a
+// template language: anything more belongs in the layout's .js sidecar.
+const helpers = {
+    // `{{ after entity.name '/' }}`  bg/kontakti → kontakti
+    after:      (value, sep) => { const s = str(value); const i = s.indexOf(str(sep)); return i < 0 ? s : s.slice(i + str(sep).length) },
+    // `{{ before entity.name '/' }}` bg/kontakti → bg
+    before:     (value, sep) => { const s = str(value); const i = s.indexOf(str(sep)); return i < 0 ? s : s.slice(0, i) },
+    afterLast:  (value, sep) => { const s = str(value); const i = s.lastIndexOf(str(sep)); return i < 0 ? s : s.slice(i + str(sep).length) },
+    beforeLast: (value, sep) => { const s = str(value); const i = s.lastIndexOf(str(sep)); return i < 0 ? s : s.slice(0, i) },
+    // Literal, every occurrence — NOT a regex, because a destination is a
+    // path and a stray metacharacter should not silently change the match.
+    replace:    (value, search, replacement) => str(value).split(str(search)).join(str(replacement)),
+    dirname:    (value) => path.posix.dirname(str(value)),
+    basename:   (value, ext) => path.posix.basename(str(value), typeof ext === 'string' ? ext : undefined),
+    lower:      (value) => str(value).toLowerCase(),
+    upper:      (value) => str(value).toUpperCase(),
+}
+for (const [name, fn] of Object.entries(helpers)) hbs.registerHelper(name, fn)
+
+export const destinationHelpers = Object.keys(helpers)
+
 export function compileDestinationTemplate(template) {
     if (!destinationTemplateCache.has(template)) {
-        destinationTemplateCache.set(template, handlebars.compile(template))
+        destinationTemplateCache.set(template, hbs.compile(template))
     }
     return destinationTemplateCache.get(template)
 }
@@ -31,3 +70,45 @@ export function sanitizeDestination(p) {
     }
     return leading + normalized
 }
+
+// The PRIMARY destination for an entity under one layout — page 1 of a
+// paginated set, or the only output of an unpaginated one.
+//
+// Extracted so it can run in TWO places that must agree:
+//
+//   onProcessed (matching.js)  persists it onto the catalog entity, because
+//                              the catalog is only ever written through the
+//                              journal and onProcessed is where that happens.
+//                              Without this, entity.destination existed only
+//                              as a per-render-task field and was never
+//                              stored — so runtime.href() had nothing to
+//                              resolve a TARGET page's URL from, and returned
+//                              the whole entity instead of { url }.
+//   onBeforeRender (assembly)  derives each task's destination, including the
+//                              per-page variants this function does not cover.
+//
+// Two copies of this derivation would drift, and the failure mode of drift is
+// a URL that resolves to a file that is not there.
+export function primaryDestination({ entity, layout, options = {}, endsWith }) {
+    const template = layout?.meta?.destination
+    if (template) {
+        return sanitizeDestination(compileDestinationTemplate(template)({ entity }))
+    }
+    // A name already carrying its format is a passthrough — the source file
+    // IS the output shape (e.g. `robots.txt`).
+    if (endsWith(entity.name, entity.format)) return entity.destination ?? null
+
+    const base = '/' + entity.name
+    // cleanUrls turns `foo` into `foo/index.html` so the served URL is
+    // `/foo/`. Skipped when the layout declares a postprocessor: that HTML
+    // render is a throwaway stepping stone with no served URL, and leaving
+    // it flat lets the engine's extension swap produce `/foo.<ext>`.
+    if (options.cleanUrls
+        && !endsWith(entity.name, 'index')
+        && layout?.format === 'html'
+        && !layout?.postprocessor
+    ) {
+        return path.posix.join(base, `index.${layout.format}`)
+    }
+    return `${base}.${layout?.format}`
+}

package/lib/matching.js

@@ -20,12 +20,63 @@
 
 import path from 'node:path'
 
+import _ from 'lodash'
+import { primaryDestination } from './destination.js'
+import { reportWarning } from 'mikser-io'
+
 export function createOnProcessed({
     runtime, useLogger, useJournal,
     findEntity, matchEntity, collection,
     OPERATION,
     options,
 }) {
+    // A `match` pattern that selects nothing is silent — no warn, no debug —
+    // and the build goes green with those pages simply absent. The patterns
+    // run against entity.name, so on a localized site they carry real content
+    // ('@/*/{aparati,devices}/index'); adding a language means adding its
+    // segment, and missing one loses a whole section while the other
+    // languages still look right.
+    //
+    // Tallied across the process, reported once. Same reasoning as the
+    // assets-preset case in core: a deliberate declaration that selected
+    // nothing is essentially always a mistake, and it is exactly what the
+    // author cannot see.
+    const matchTally = { evaluated: 0, hit: new Set(), reported: false }
+
+    function reportUnmatchedPatterns(logger) {
+        if (matchTally.reported) return
+        const patterns = Object.keys(options.match || {})
+        if (!patterns.length || !matchTally.evaluated) return
+        matchTally.reported = true
+
+        for (const pattern of patterns) {
+            if (matchTally.hit.has(pattern)) continue
+            // Phrased as what was observed: an incremental cycle only
+            // re-evaluates changed entities, so a pattern can legitimately
+            // match nothing in a run of three. The count lets the reader
+            // tell that apart from a typo.
+            // The name/id rule is the thing people get wrong, and it is not
+            // what it looks like: matchEntity() globs entity.name ONLY for a
+            // pattern beginning '@/' — every other pattern globs entity.id,
+            // which carries the '/<collection>/' prefix and the extension.
+            // So 'post' does NOT match a document named 'post'; '@/post' and
+            // '/documents/post.md' both do.
+            const onName = pattern.startsWith('@/')
+            reportWarning('layout-pattern-no-match', {
+                pattern, layout: options.match[pattern], evaluated: matchTally.evaluated,
+                matchedAgainst: onName ? 'name' : 'id',
+            })
+            logger.warn(
+                'Layout pattern %j (→ %j) matched none of the %d entities evaluated. ' +
+                'It is matched against entity.%s%s. On an incremental run unchanged ' +
+                'entities are not re-evaluated; use --force to check the whole catalog.',
+                pattern, options.match[pattern], matchTally.evaluated,
+                onName ? 'name' : 'id',
+                onName ? '' : " — prefix a pattern with '@/' to match entity.name instead, " +
+                             'since an id looks like /<collection>/<name>.<ext>')
+        }
+    }
+
     return async function onProcessedHandler(signal) {
         const logger = useLogger()
         const { layouts } = runtime.state.layouts
@@ -79,7 +130,13 @@ export function createOnProcessed({
                 for (const name of declared) {
                     const layout = await resolveLayout(name)
                     if (layout) {
-                        if (!resolved.find(l => l.name === layout.name)) resolved.push(layout)
+                        // meta.layout / meta.layouts in the document's own
+                        // frontmatter. Labelled so --explain says the choice
+                        // came from the content, not from config — which is
+                        // where you would otherwise go looking.
+                        if (!resolved.find(l => l.name === layout.name)) {
+                            resolved.push({ ...layout, matchedBy: 'meta.layout' })
+                        }
                     } else {
                         logger.warn('Layout not found for %s: %s', entity.collection, entity.id, name)
                     }
@@ -89,12 +146,20 @@ export function createOnProcessed({
 
             // Multi-match over config patterns.
             const matched = []
+            matchTally.evaluated++
             for (const pattern in options.match || []) {
                 if (matchEntity(entity, pattern)) {
+                    matchTally.hit.add(pattern)
                     const name = options.match[pattern]
                     const layout = await resolveLayout(name)
                     if (layout && !matched.find(l => l.name === layout.name)) {
-                        matched.push(layout)
+                        // Record WHICH pattern claimed it. With several
+                        // patterns able to match one entity, "why did this
+                        // page get that layout" is otherwise only answerable
+                        // by re-running the matcher by hand — and it is the
+                        // question asked whenever the answer is surprising.
+                        // Surfaced by `mikser --explain`.
+                        matched.push({ ...layout, matchedBy: pattern })
                     }
                 }
             }
@@ -115,7 +180,11 @@ export function createOnProcessed({
                 const autoLayout = candidates.find(name => layouts[name])
                 if (autoLayout) {
                     const layout = await resolveLayout(autoLayout)
-                    if (layout) matched.push(layout)
+                    // Labelled so `mikser --explain` can distinguish "a
+                    // pattern you wrote chose this" from "the name happened
+                    // to match a layout file" — a distinction that decides
+                    // whether the fix is in the config or in a filename.
+                    if (layout) matched.push({ ...layout, matchedBy: 'auto-layout' })
                     logger.debug('Auto layout matched %s -> %s for %s', entity.name, autoLayout, entity.id)
                 } else {
                     logger.trace('Auto layout no match for %s tried: %s', entity.id, candidates.join(', '))
@@ -150,6 +219,34 @@ export function createOnProcessed({
                     // Author-declared cases already have meta.layout
                     // (or meta.layouts) set; this covers the
                     // pattern-match / auto-layout paths.
+                    // Persist the primary destination.
+                    //
+                    // entity.destination used to exist ONLY as a field the
+                    // render-task builder set per task, and was never written
+                    // back — so the catalog had none, and runtime.href()
+                    // (which needs the TARGET's destination to make a
+                    // relative URL) fell through and returned the whole
+                    // entity instead of { url }. The catalog is only written
+                    // through the journal, and this hook is where that
+                    // happens, so it has to be derived here.
+                    //
+                    // "Primary" means page 1 / the sole output of the FIRST
+                    // matched layout — the same choice entity.layout already
+                    // makes. Paginated pages 2..n keep their own per-task
+                    // destinations; a single stored field cannot describe
+                    // several outputs, and the one a link should point at is
+                    // the first.
+                    if (entity.layouts.length) {
+                        try {
+                            const destination = primaryDestination({
+                                entity, layout: entity.layouts[0], options, endsWith: _.endsWith,
+                            })
+                            if (destination) entity.destination = destination
+                        } catch (err) {
+                            logger.warn('Destination for %s: %s', entity.id, err.message)
+                        }
+                    }
+
                     if (entity.layouts.length && !entity.meta?.layout && !entity.meta?.layouts) {
                         entity.meta = entity.meta || {}
                         if (entity.layouts.length === 1) {
@@ -208,5 +305,8 @@ export function createOnProcessed({
             // generator JSON.stringifies the entity post-yield and
             // UPDATEs the row if it diverged from the original).
         }
+
+        // After the journal is drained, so `evaluated` is the whole cycle.
+        reportUnmatchedPatterns(logger)
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "1.0.0",
+  "version": "2.3.0",
   "description": "SSG-flavor task-production policy for mikser-io. Multi-match layout assignment, per-layout destinations, postprocess chain attachment, layout inspection.",
   "main": "index.js",
   "type": "module",
@@ -18,12 +18,15 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
   "peerDependencies": {
-    "mikser-io": "^9.0.0"
+    "mikser-io": "^9.14.0"
   },
   "dependencies": {
     "globby": "^14.0.0",
     "handlebars": "^4.7.0",
     "lodash": "^4.17.0",
     "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "mikser-io": "file:../mikser-io"
   }
 }

package/test/unit.test.js

@@ -1,5 +1,6 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
+import { format } from 'node:util'
 import { mkdtemp, rm, access, mkdir, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
@@ -122,6 +123,74 @@ describe('layouts plugin', () => {
         })
     })
 
+    it('warns once about a match pattern that selected nothing', async () => {
+        // A pattern selecting zero entities used to be completely silent —
+        // no warn, no debug — so a typo'd or missing language segment lost a
+        // whole section while the build went green.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+            })
+            layouts({
+                autoLayouts: false,
+                match: {
+                    // matchEntity globs entity.name only for '@/' patterns;
+                    // everything else globs entity.id. Both forms here, so
+                    // the test pins the real rule rather than the loose
+                    // "patterns match name" summary.
+                    '@/post':            'post',      // matches name
+                    '/documents/post.md': 'post',      // matches id
+                    'nonesuch/*':        'section',   // matches neither
+                },
+            })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'section.hbs' } })
+
+            const doc = { id: '/documents/post.md', collection: 'documents', name: 'post', format: 'md', meta: {} }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            const warnings = h.logs.filter(l =>
+                l.level === 'warn' && l.args.join(' ').includes('Layout pattern'))
+            assert.equal(warnings.length, 1, `expected one warning, got ${warnings.length}`)
+            // The harness records (format, ...args) unformatted, so render it
+            // the way the logger would before asserting on the message.
+            const text = format(...warnings[0].args)
+            assert.match(text, /nonesuch/, 'names the pattern that matched nothing')
+            assert.ok(!text.includes("'post'"), 'must not name the pattern that DID match')
+            assert.match(text, /matched against entity\.id/, 'names the field this pattern is matched against')
+            assert.match(text, /'@\/'/, "points at the '@/' prefix for name matching")
+            assert.match(text, /--force/, 'tells the reader how to check the whole catalog')
+        })
+    })
+
+    it('does not repeat the pattern warning on a second cycle', async () => {
+        // Watch mode runs onProcessed per cycle; a warning per cycle would be
+        // noise, so it is reported once per process.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+            })
+            layouts({ autoLayouts: false, match: { 'nonesuch/*': 'section' } })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'section.hbs' } })
+
+            for (const id of [1, 2]) {
+                h.journal.push({
+                    id,
+                    entity: { id: `/documents/p${id}.md`, collection: 'documents', name: `p${id}`, format: 'md', meta: {} },
+                    operation: 'create', context: {}, options: {}, output: null,
+                })
+                await h.runHook('processed', { aborted: false })
+            }
+
+            const warnings = h.logs.filter(l =>
+                l.level === 'warn' && l.args.join(' ').includes('Layout pattern'))
+            assert.equal(warnings.length, 1, 'warned once, not once per cycle')
+        })
+    })
+
     it('warns when a render-requested entity (carries correlationId) matches no layout', async () => {
         await withTempWorking(async (workingFolder) => {
             const h = createHarness({
@@ -644,7 +713,9 @@ describe('layouts plugin: multi-layouts (collision)', () => {
 
             assert.equal(h.renderTasks.length, 2, 'one task per layout, different extensions')
             const destinations = h.renderTasks.map(t => t.entity.destination).sort()
-            assert.deepEqual(destinations, ['/blog/welcome.eml', '/blog/welcome.html'])
+            // cleanUrls defaults to true and applies to `html` ONLY, so the
+            // page folds into a folder while the email keeps its flat name.
+            assert.deepEqual(destinations, ['/blog/welcome.eml', '/blog/welcome/index.html'])
         })
     })
 })
@@ -714,3 +785,236 @@ describe('layouts plugin: multi-layouts (destination template)', () => {
         })
     })
 })
+
+describe('layouts plugin: destination is persisted (mikser-io#1)', () => {
+    // entity.destination used to exist only as a per-render-task field and
+    // was never written back, so the catalog had none — and runtime.href(),
+    // which needs the TARGET's destination to build a relative URL, fell
+    // through and returned the whole entity instead of { url }.
+    async function processOne({ layoutFile, entity, options }) {
+        return withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+            })
+            layouts(options)(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: layoutFile } })
+            h.journal.push({ id: 1, entity, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+            return entity
+        })
+    }
+
+    const doc = (name) => ({
+        id: `/documents/${name}.md`, collection: 'documents', name, format: 'md', meta: {},
+    })
+
+    it('stamps a cleanUrls destination onto the entity', async () => {
+        const out = await processOne({
+            layoutFile: 'page.hbs',
+            entity: { ...doc('contacts'), meta: { layout: 'page' } },
+            options: { cleanUrls: true },
+        })
+        assert.equal(out.destination, '/contacts/index.html')
+    })
+
+    it('stamps a flat destination when cleanUrls is off', async () => {
+        const out = await processOne({
+            layoutFile: 'page.hbs',
+            entity: { ...doc('contacts'), meta: { layout: 'page' } },
+            options: { cleanUrls: false },
+        })
+        assert.equal(out.destination, '/contacts.html')
+    })
+
+    it('leaves an index page flat — cleanUrls already special-cases it', async () => {
+        const out = await processOne({
+            layoutFile: 'page.hbs',
+            entity: { ...doc('index'), meta: { layout: 'page' } },
+            options: { cleanUrls: true },
+        })
+        assert.equal(out.destination, '/index.html')
+    })
+
+    it('is absent when no layout matched, rather than a bogus path', async () => {
+        const out = await processOne({
+            layoutFile: 'page.hbs',
+            entity: doc('orphan'),
+            options: { autoLayouts: false, match: {} },
+        })
+        assert.equal(out.destination, undefined)
+    })
+})
+
+describe('layouts plugin: cleanUrls default (layouts#1)', () => {
+    // It had no default, so unset it was falsy and pages landed at
+    // `hera.html` — while the README's options block read as a defaults
+    // table showing `cleanUrls: true`. No warning, site works, wrong URL
+    // shape everywhere.
+    async function destinationFor(options) {
+        return withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+            })
+            layouts(options)(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'page.hbs' } })
+            const entity = {
+                id: '/documents/hera.md', collection: 'documents', name: 'hera',
+                format: 'md', meta: { layout: 'page' },
+            }
+            h.journal.push({ id: 1, entity, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+            return entity.destination
+        })
+    }
+
+    it('defaults to on', async () => {
+        assert.equal(await destinationFor({}), '/hera/index.html')
+    })
+
+    it('false still gives flat output', async () => {
+        assert.equal(await destinationFor({ cleanUrls: false }), '/hera.html')
+    })
+
+    it('explicit true is the same as the default', async () => {
+        assert.equal(await destinationFor({ cleanUrls: true }), '/hera/index.html')
+    })
+})
+
+describe('layouts plugin: destination template helpers (layouts#3)', () => {
+    // Without helpers a template can only interpolate whole values, so a
+    // path cannot be derived from PART of entity.name — which blocks
+    // per-language output roots on a catalog holding several languages.
+    const render = async (tpl, entity) => {
+        const { compileDestinationTemplate } = await import('../lib/destination.js')
+        return compileDestinationTemplate(tpl)({ entity })
+    }
+
+    it('strips a leading language segment — the case that needed this', async () => {
+        assert.equal(
+            await render("/{{ after entity.name '/' }}/index.html", { name: 'bg/kontakti' }),
+            '/kontakti/index.html')
+    })
+
+    it('keeps the rest of a nested path intact', async () => {
+        assert.equal(
+            await render("/{{ after entity.name '/' }}/index.html", { name: 'bg/web/booking' }),
+            '/web/booking/index.html')
+    })
+
+    it('replace is literal, not a regex', async () => {
+        // A destination is a path; a stray metacharacter must not silently
+        // change what matches.
+        assert.equal(await render("/{{ replace entity.name '.' '-' }}", { name: 'a.b.c' }), '/a-b-c')
+        assert.equal(await render("/{{ replace entity.name 'a.c' 'X' }}", { name: 'abc' }), '/abc')
+    })
+
+    it('covers the path-shaping set', async () => {
+        assert.equal(await render('/{{ before entity.name "/" }}', { name: 'bg/x' }), '/bg')
+        assert.equal(await render('/{{ afterLast entity.name "/" }}', { name: 'a/b/c' }), '/c')
+        assert.equal(await render('/{{ beforeLast entity.name "/" }}', { name: 'a/b/c' }), '/a/b')
+        assert.equal(await render('/{{ dirname entity.name }}', { name: 'a/b/c' }), '/a/b')
+        assert.equal(await render('/{{ basename entity.name }}', { name: 'a/b/c' }), '/c')
+        assert.equal(await render('/{{ lower entity.name }}', { name: 'A/B' }), '/a/b')
+        assert.equal(await render('/{{ upper entity.name }}', { name: 'a' }), '/A')
+    })
+
+    it('handles a missing value without emitting "undefined" into a path', async () => {
+        assert.equal(await render("/{{ after entity.nope '/' }}x", { name: 'a' }), '/x')
+    })
+
+    it('does not register helpers on the shared handlebars instance', async () => {
+        // Registering on the default export would leak `replace` into a
+        // project's own renderHbs layouts, appearing from nowhere.
+        const handlebars = (await import('handlebars')).default
+        for (const name of ['after', 'before', 'replace', 'dirname', 'basename']) {
+            assert.equal(handlebars.helpers[name], undefined, `${name} leaked globally`)
+        }
+    })
+
+    it('still rejects path traversal after helpers run', async () => {
+        const { compileDestinationTemplate, sanitizeDestination } = await import('../lib/destination.js')
+        const out = compileDestinationTemplate("/{{ after entity.name '/' }}")({ entity: { name: 'x/../../etc/passwd' } })
+        assert.throws(() => sanitizeDestination(out), /path-traversal/)
+    })
+})
+
+describe('layouts plugin: a sidecar is a tracked input (layouts#4)', () => {
+    // The sidecar is where a mikser site's data layer lives, and it was the
+    // one file that could be edited without effect: `.js` is excluded from
+    // the scan, so it was not an entity, not watched as an input, and not
+    // part of any hash. Nothing depended on it, so nothing re-rendered —
+    // silently, looking exactly like a bug in your own code.
+    async function scan(files, { existing = [] } = {}) {
+        return withTempWorking(async (workingFolder) => {
+            const layoutsFolder = path.join(workingFolder, 'layouts')
+            await mkdir(path.join(layoutsFolder, 'lib'), { recursive: true })
+            for (const [rel, body] of Object.entries(files)) {
+                await writeFile(path.join(layoutsFolder, rel), body)
+            }
+            const h = createHarness({
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+                entities: existing,
+            })
+            layouts()(h.core)
+            await h.runHook('loaded')
+            await h.runHook('import')
+            const created = h.journal.filter(e => ['create', 'update'].includes(e.operation))
+            return { h, layoutsFolder, emitted: created.map(e => e.entity), checksums:
+                Object.fromEntries(created.map(e => [e.entity.name, e.entity.checksum])) }
+        })
+    }
+
+    it('folds the sidecar into the layout checksum, so editing it changes the hash', async () => {
+        const before = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({ a: 1 })' })
+        const after  = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({ a: 2 })' })
+        assert.ok(before.checksums.page, 'the layout was emitted')
+        assert.notEqual(before.checksums.page, after.checksums.page,
+                        'a sidecar edit must change the layout checksum')
+    })
+
+    it('an unchanged sidecar leaves the checksum alone', async () => {
+        const a = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({})' })
+        const b = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({})' })
+        assert.equal(a.checksums.page, b.checksums.page)
+    })
+
+    it('a SHARED script under the folder invalidates every layout', async () => {
+        // A sidecar's own imports (layouts/lib/context.js and friends) would
+        // otherwise need a module-graph walk. Treating any shared .js change
+        // as invalidating every layout is what a layouts folder can afford,
+        // and it is predictable — which a partial graph walk would not be.
+        const before = await scan({
+            'page.liquid': '<p>x</p>', 'post.liquid': '<p>y</p>',
+            'lib/context.js': 'export const chrome = 1',
+        })
+        const after = await scan({
+            'page.liquid': '<p>x</p>', 'post.liquid': '<p>y</p>',
+            'lib/context.js': 'export const chrome = 2',
+        })
+        assert.notEqual(before.checksums.page, after.checksums.page)
+        assert.notEqual(before.checksums.post, after.checksums.post)
+    })
+
+    it('does not make an entity out of a sidecar', async () => {
+        // Giving it one would put JS source in the catalog, and via onSync's
+        // id-stripping produce a phantom /layouts/page beside the real
+        // /layouts/page.liquid.
+        const { emitted } = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({})' })
+        assert.deepEqual(emitted.map(e => e.id).sort(), ['/layouts/page.liquid'])
+    })
+
+    it('still treats a JS-AUTHORED layout as a layout, not a sidecar', async () => {
+        // post.hbs.js is a template written as JS; its id drops the trailing
+        // .js. Only a .js whose remaining name has no extension is a sidecar.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({ options: { workingFolder, outputFolder: path.join(workingFolder, 'out') } })
+            layouts()(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs.js' } })
+            const entry = h.journal.find(e => e.operation === 'create')
+            assert.equal(entry.entity.id, '/layouts/post.hbs')
+        })
+    })
+})