mikser-io-layouts 2.13.0 → 3.1.0

package/index.js

@@ -22,6 +22,8 @@ import {
     checksum as fileChecksum, checksumOf,
     useDatabase,
     writeOutput, reportUnchanged,
+    provideService,
+    cliOption,
 } from 'mikser-io'
 
 import { createInspect } from './lib/inspect.js'
@@ -87,20 +89,28 @@ export function layouts(userOptions = {}) {
         // The old `runtime.state.layouts.sitemap` in-memory map + `uriIndex`
         // are gone: every entity's "sitemap presence" IS its catalog row.
 
-        // Expose the layouts inspection surface for other plugins (the
-        // mikser-io-mcp plugin wraps inspect() as the mikser_layouts_inspect
-        // tool). Done at factory-eval time — before any onLoaded fires — so
-        // a later plugin's onLoaded can see it. Matches the preview plugin
-        // pattern (`runtime.options.preview = { store, get, stats, config }`).
-        runtime.options.layouts = {
+        // Offer the inspection surface as a service. A consumer asks core
+        // for 'layouts' and never names this package; before, it read
+        // runtime.options.layouts directly, which coupled the two through an
+        // object neither owns and cost the `--layouts` flag its name.
+        //
+        // Provided at factory-eval time — before any hook runs — so a
+        // consumer's onLoaded sees it whatever the plugin order.
+        // The flag this package could not have until runtime.options.layouts
+        // stopped holding an API object: commander derives the property from
+        // the long flag, so `--layouts` would have landed a folder string on
+        // top of inspect(), after the load phase, breaking a consumer three
+        // plugins away.
+        cliOption('--layouts <folder>',
+            'folder holding the layout templates, relative to the working folder (default: layouts)')
+
+        provideService('layouts', {
             inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection }),
-        }
+        }, { plugin: 'mikser-io-layouts' })
 
-        // MCP tool registration. Gated on runtime.options.mcp — when the
-        // mcp plugin isn't loaded, this is a no-op (vector / schemas /
-        // preview use the same pattern). The mcp plugin must be FIRST
-        // in the plugins array for this to fire; that constraint is
-        // documented in mikser-io's CLAUDE.md.
+        // Tool registration. Registers against core's tool registry, which
+        // exists whether or not the mcp plugin is installed — so there is no
+        // gate to write and no ordering rule to obey.
         onLoaded(async () => {
             registerMcpTools({ runtime, useLogger, findEntity, findEntities, useDatabase, collection })
         })
@@ -199,13 +209,18 @@ export function layouts(userOptions = {}) {
                 layouts: {},
             }
 
-            // Folder name resolved here (config override or default to the
-            // collection name) and used immediately to build the absolute
-            // path. No need to keep the bare folder-name string on
-            // runtime.options — runtime.options.layoutsFolder is the only
-            // useful form downstream.
-            const layoutsFolderName = options.layoutsFolder || collection
-            runtime.options.layoutsFolder = path.join(runtime.options.workingFolder, layoutsFolderName)
+            // --layouts wins, then the config, then the collection name.
+            //
+            // Read HERE rather than at construction: the option table is not
+            // parsed until every plugin has been constructed and had its
+            // chance to declare, so a value read in the factory is always
+            // undefined. An absolute value is taken as given; anything else
+            // is relative to the working folder, like every other folder flag.
+            const layoutsFolderName =
+                runtime.options.layouts ?? options.layoutsFolder ?? collection
+            runtime.options.layoutsFolder = path.isAbsolute(layoutsFolderName)
+                ? layoutsFolderName
+                : path.join(runtime.options.workingFolder, layoutsFolderName)
             runtime.options.layoutsStateFolder = path.join(runtime.options.outputFolder, 'state')
 
             logger.debug('Layouts folder: %s', runtime.options.layoutsFolder)
@@ -311,8 +326,43 @@ export function layouts(userOptions = {}) {
             // and they stay out of the layouts NAME map so nothing resolves a
             // template to one. Rendering is not a risk either: layout matching
             // skips this collection outright.
-            const sidecarPaths = (await globby('**/*.js', { cwd: runtime.options.layoutsFolder }))
-                .filter(isSidecarScript)
+            const allScripts = await globby('**/*.js', { cwd: runtime.options.layoutsFolder })
+            const sidecarPaths = allScripts.filter(isSidecarScript)
+
+            // A `.js` that nothing will ever read.
+            //
+            // A sidecar is named after the LAYOUT, and a layout's name drops
+            // BOTH extensions: `robots.txt.liquid` is the layout `robots`, so
+            // its sidecar is `robots.js`. Write `robots.txt.js` and it is
+            // claimed by nothing — isSidecarScript rejects it because
+            // stripping `.js` leaves `.txt`, and the layout glob ignores every
+            // `.js` outright. The file is simply invisible: it does not fail,
+            // it never runs, and the layout renders with empty `data`.
+            //
+            // Downstream that shipped `Sitemap: /sitemap.xml` as a relative
+            // reference in a robots.txt — which in a robots.txt means nothing
+            // — on a green build.
+            //
+            // Only when a layout sits beside it under the same stem, which is
+            // what makes this a misnaming rather than a stray file. A dotted
+            // module a sidecar imports (`lib/data.json.js`) is claimed by
+            // nothing either, and is nobody's mistake; flagging it would be
+            // the noise that gets this line filtered out.
+            for (const script of allScripts) {
+                if (isSidecarScript(script)) continue
+                const stem = script.replace(/\.js$/, '')
+                const layout = paths.find(candidate =>
+                    candidate === stem || candidate.startsWith(`${stem}.`))
+                if (!layout) continue
+                const name = path.basename(stem, path.extname(stem))
+                logger.warn({ code: 'layout-sidecar-misnamed', script, layout },
+                    'layouts/%s is not loaded as a sidecar and nothing else reads it. A sidecar is '
+                    + 'named after the LAYOUT, and %s is the layout `%s` — both extensions are '
+                    + 'dropped — so its sidecar has to be %s.js. The layout renders with empty data '
+                    + 'until it is renamed.',
+                    script, layout, name, path.join(path.dirname(stem) === '.' ? '' : path.dirname(stem), name))
+            }
+
             const inputs = await sidecarInputs()
             const scanned = new Set()
             const stats = { emitted: 0, skipped: 0, deleted: 0 }

package/lib/assembly.js

@@ -27,10 +27,21 @@ import {
     observeConsumed,
     queryContext,
     useDatabase,
+    reportError,
 } from 'mikser-io'
 import { compileDestinationTemplate, sanitizeDestination, primaryDestination } from './destination.js'
 import { setSidecarStamp, sidecarHookInstalled } from './sidecar-modules.js'
 
+// What the sidecar actually returned, for a message a reader can act on.
+// `[object Object]` and `` are the two least useful things to print here.
+function describePages(value) {
+    if (Array.isArray(value)) return `an array of ${value.length}`
+    if (value === null) return 'null'
+    if (typeof value === 'object') return `an object with keys ${Object.keys(value).join(', ') || '(none)'}`
+    if (typeof value === 'number') return `the number ${value}`
+    return `a ${typeof value} (${JSON.stringify(value)})`
+}
+
 export function createOnBeforeRender({
     runtime, useLogger, useJournal,
     findById, findEntity, findEntities,
@@ -350,6 +361,56 @@ export function createOnBeforeRender({
                     : null
 
                 if (data?.pages) {
+                    // `pages` is the pagination COUNT, and only a count.
+                    //
+                    // The guard above is truthiness and the loop below is
+                    // `page < data.pages`, so a sidecar returning anything
+                    // truthy that is not a positive number passed the first
+                    // and ran zero times in the second. `{ pages: [] }`
+                    // coerces to 0; `{ pages: [{…}] }` coerces to NaN. Both
+                    // produced NO page: no file, no error, no warning, not
+                    // counted in `Rendered:`, no manifest snapshot — a green
+                    // build with the page simply absent, and --audit-output
+                    // cannot see it either because an entity that never
+                    // rendered has no snapshot to be missing.
+                    //
+                    // `pages` is also the obvious name for the list in a
+                    // sitemap, which is exactly where it lands.
+                    //
+                    // Thrown rather than reinterpreted. The key has one
+                    // meaning; guessing a second from the value's type is how
+                    // a name comes to mean two things depending on what you
+                    // put in it. This fails the render for this entity, which
+                    // is counted, recorded and named.
+                    if (!Number.isInteger(data.pages) || data.pages < 1) {
+                        // Reported, not thrown. This runs in onBeforeRender,
+                        // a lifecycle hook rather than a render, so an
+                        // exception here tears the whole build down with a
+                        // stack trace — one mistyped sidecar stopping every
+                        // other page, which trades a silent failure for a
+                        // total one.
+                        //
+                        // reportError, not logger.error. This entity could
+                        // not be turned into output, which is what a render
+                        // error IS — so it is counted in `errors`, recorded in
+                        // mikser_failures, and makes a one-shot build exit 1.
+                        // A coded logger.error would register as a fault, and
+                        // a fault leaves the build green: "🟢 Mikser completed"
+                        // beside a red line and exit 0 is the same green build
+                        // the report was about.
+                        const message =
+                            `sidecar returned \`pages\` as ${describePages(data.pages)}. `
+                            + '`pages` is the pagination COUNT — a positive integer — and is reserved '
+                            + 'in the data a layout receives, so a list cannot be passed under it. '
+                            + 'Rename it (`items`, `entries`, `urls`) and the layout renders once '
+                            + 'with that list available.'
+                        reportError(entity, new Error(message), { layout: entity.layout?.name ?? null })
+                        logger.error({ code: 'layout-pages-not-a-count', id: entity.id,
+                            layout: entity.layout?.name ?? null },
+                            'Layout %s: %s — %s produced no output.',
+                            entity.layout?.name ?? '?', message, entity.id)
+                        continue
+                    }
                     if (!_.endsWith(entity.name, entity.format)) {
                         // Loop bound is `< data.pages` (not `data.pages - 1`).
                         // With 4 pages and the old bound, iteration only ran
@@ -409,6 +470,19 @@ export function createOnBeforeRender({
                                  sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
                                  sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                         }
+                    } else {
+                        // Pagination was asked for, and nothing was queued.
+                        //
+                        // The guard exists so an entity whose name already
+                        // carries its format is not expanded twice, but it
+                        // shares the shape that made the type confusion above
+                        // so expensive: no task, no message, output absent on
+                        // a green build. Whatever the right handling is, it is
+                        // not silence.
+                        logger.warn({ code: 'layout-pagination-skipped', id: entity.id },
+                            'Pagination was requested for %s (pages: %d) but its name already ends '
+                            + 'with its format (%s), so no page was produced.',
+                            entity.id, data.pages, entity.format)
                     }
                 } else {
                     // Same derivation onProcessed persists onto the catalog

package/lib/mcp.js

@@ -1,44 +1,47 @@
-// MCP tool surface for layouts. Registered against the mcp substrate
-// at `runtime.options.mcp` when present — same gating pattern other
-// siblings use (vector, schemas, preview). When mcp isn't loaded, the
-// registration is a no-op.
+// The tool surface for layouts. Registered against the ENGINE's tool
+// registry, which exists whether or not the mcp plugin is installed — so
+// there is no `if (!runtime.options.mcp) return` gate to write, and no rule
+// about where mcp sits in the plugins array.
 //
-// One tool: `mikser_layouts_inspect`. Surfaces the inspect() primitive
-// already exposed at `runtime.options.layouts.inspect`. The schema and
-// author-facing description live here because they're MCP-flavor; the
-// underlying data shape is owned by lib/inspect.js.
+// The engine stores BARE names; the mcp plugin prefixes on the way out, so a
+// session still sees `mikser_layouts_inspect` and the CLI sees
+// `layouts_inspect`. One registration, both surfaces.
+//
+// Surfaces the inspect() primitive this package offers as the `layouts`
+// service. The schema and author-facing description live here because
+// they're MCP-flavor; the underlying data shape is owned by lib/inspect.js.
 
 import { z } from 'zod'
+import { registerTool, useService } from 'mikser-io'
 
 export function registerMcpTools({ runtime, useLogger, findEntity, findEntities, useDatabase, collection }) {
-    const mcp = runtime.options.mcp
-    if (!mcp) return   // mcp plugin not loaded — nothing to register
-    if (!runtime.options.layouts?.inspect) return   // shouldn't happen if we run after our own inspect setup, but defensive
+    const layouts = useService('layouts')
+    if (!layouts?.inspect) return   // our own factory has not run yet
 
     const logger = useLogger()
-
-    mcp.simpleTool(
-        'mikser_layouts_inspect',
-        'Inspect a layout and everything it pulls in. Answers "what does this layout need from a document" '
-        + 'before you write one — which saves a guess-and-render-empty cycle, and is the only way to catch a '
-        + 'mistyped key before it ships a page with a section silently missing.\n\n'
-        + 'START WITH references.contract.meta. It is the list of document meta keys the WHOLE layout tree '
-        + 'consumes, resolved through includes and renamings into the vocabulary a document actually writes — '
-        + 'so `data.meta.hero.tags` in a partial three files down comes back as `hero.tags`. Compare it against '
-        + 'the meta you are about to write: a key in the contract with no value is a gap, and a key you wrote '
-        + 'that appears nowhere in it is usually a typo.\n\n'
-        + 'Check references.contract.complete before trusting a comparison. When false, some branch could not be '
-        + 'read and references.contract.incomplete names each one with a reason.\n\n'
-        + 'Also returns the template source, sample entities targeting the layout, and both reference views: '
-        + 'runtime (what recent renders actually touched) and static (what the source mentions, including '
-        + 'branches no render has taken).',
+    registerTool('layouts_inspect',
         {
-            id: z.string().describe('Layout id, e.g. "/layouts/reports/royalty.html-pdf.liquid". Use mikser_query_entities with { collection: "layouts" } to discover ids.'),
-            samples: z.number().int().min(0).max(10).optional().describe('How many existing entities currently using this layout to include as data-shape examples. Default 3. Only entities with explicit meta.layout match; auto-matched layouts are not surfaced.'),
+            description: 'Inspect a layout and everything it pulls in. Answers "what does this layout need from a document" '
+                + 'before you write one — which saves a guess-and-render-empty cycle, and is the only way to catch a '
+                + 'mistyped key before it ships a page with a section silently missing.\n\n'
+                + 'START WITH references.contract.meta. It is the list of document meta keys the WHOLE layout tree '
+                + 'consumes, resolved through includes and renamings into the vocabulary a document actually writes — '
+                + 'so `data.meta.hero.tags` in a partial three files down comes back as `hero.tags`. Compare it against '
+                + 'the meta you are about to write: a key in the contract with no value is a gap, and a key you wrote '
+                + 'that appears nowhere in it is usually a typo.\n\n'
+                + 'Check references.contract.complete before trusting a comparison. When false, some branch could not be '
+                + 'read and references.contract.incomplete names each one with a reason.\n\n'
+                + 'Also returns the template source, sample entities targeting the layout, and both reference views: '
+                + 'runtime (what recent renders actually touched) and static (what the source mentions, including '
+                + 'branches no render has taken).',
+            inputSchema: {
+                id: z.string().describe('Layout id, e.g. "/layouts/reports/royalty.html-pdf.liquid". Use mikser_query_entities with { collection: "layouts" } to discover ids.'),
+                samples: z.number().int().min(0).max(10).optional().describe('How many existing entities currently using this layout to include as data-shape examples. Default 3. Only entities with explicit meta.layout match; auto-matched layouts are not surfaced.'),
+            },
         },
         async ({ id, samples = 3 }) => {
             try {
-                const result = await runtime.options.layouts.inspect(id, { samples })
+                const result = await layouts.inspect(id, { samples })
                 return {
                     content: [{
                         type: 'text',
@@ -127,7 +130,10 @@ function distance(a, b) {
 }
 
 export function registerCheckTool({ runtime, findEntity, findEntities, useDatabase, collection, logger }) {
-    const mcp = runtime.options.mcp
+    // Resolved here rather than in the handlers: this runs from onLoaded, by
+    // which point every factory — including our own, which provides it — has
+    // run.
+    const layouts = useService('layouts')
 
     const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] })
 
@@ -258,7 +264,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
     // the entity names one. `schemaKey` is the plugin's own config — commonly
     // `meta.layout`, so a layout and its schema share a name.
     const schemaFor = (entity) => {
-        const api = runtime.options.schemas
+        const api = useService('schemas')
         if (!api?.lookup) return null
         const key = runtime.options.schemasKey ?? runtime.options.schemaKey ?? 'meta.schema'
         const name = key.split('.').reduce((o, k) => o?.[k], entity)
@@ -382,35 +388,35 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
             return [...(affected ?? [])].filter(cid => cid !== entity.id).sort()
         } catch { return [] }
     }
-
-    mcp.simpleTool(
-        'mikser_check_entity',
-        'Check a document against the contract of the layout that renders it, BEFORE the mistake ships.\n\n'
-        + 'A mistyped key does not fail a build. The section it named simply does not render, the page goes out '
-        + 'with a hole in it, and every signal reads clean. This is the check that catches it.\n\n'
-        + 'It classifies the entity first, because not every document is a page. `kind` is one of:\n'
-        + '  page   — renders through a layout; checked against that layout\'s contract.\n'
-        + '  data   — never renders, but other entities pull it in through a query. Reports who consumes it. '
-        + 'A missing key here surfaces as a hole in THOSE pages, not in this file, and no amount of building '
-        + 'will make it render.\n'
-        + '  unreferenced — never renders and nothing in the catalog reads it. Not an error: the catalog is '
-        + 'readable over the API, so an external consumer may depend on it.\n\n'
-        + 'For a page, read `missing` first — keys the layout consumes UNCONDITIONALLY that this document has '
-        + 'no value for. That is the only list meaning "this is probably wrong". Then `likelyTypos`, which '
-        + 'pairs a key you wrote against a key the layout wanted within two edits; a typo produces both at '
-        + 'once, which is far stronger than either alone.\n\n'
-        + 'Everything else means "you may want to look", never "this is broken": `missingOptional` is guarded '
-        + 'by the layout and safe to omit, `unused` may be consumed by a different layout, and '
-        + '`unresolvedSections` names a section that matched no template under this layout.\n\n'
-        + 'The contract is scoped to the partials this entity ACTUALLY rendered with. Unscoped, a page using '
-        + 'two of twenty sections would be checked against all twenty and a real omission would be one line in '
-        + 'three hundred.\n\n'
-        + 'Check `reliable` before trusting an absence.',
+    registerTool('check_entity',
         {
-            id: z.string().describe('Entity id, e.g. "/documents/en/index.md".'),
-            layout: z.string().optional()
-                .describe('Layout id to check against. Omit to use the layout this entity last rendered with, '
-                    + 'which is what the manifest recorded rather than a prediction.'),
+            description: 'Check a document against the contract of the layout that renders it, BEFORE the mistake ships.\n\n'
+                + 'A mistyped key does not fail a build. The section it named simply does not render, the page goes out '
+                + 'with a hole in it, and every signal reads clean. This is the check that catches it.\n\n'
+                + 'It classifies the entity first, because not every document is a page. `kind` is one of:\n'
+                + '  page   — renders through a layout; checked against that layout\'s contract.\n'
+                + '  data   — never renders, but other entities pull it in through a query. Reports who consumes it. '
+                + 'A missing key here surfaces as a hole in THOSE pages, not in this file, and no amount of building '
+                + 'will make it render.\n'
+                + '  unreferenced — never renders and nothing in the catalog reads it. Not an error: the catalog is '
+                + 'readable over the API, so an external consumer may depend on it.\n\n'
+                + 'For a page, read `missing` first — keys the layout consumes UNCONDITIONALLY that this document has '
+                + 'no value for. That is the only list meaning "this is probably wrong". Then `likelyTypos`, which '
+                + 'pairs a key you wrote against a key the layout wanted within two edits; a typo produces both at '
+                + 'once, which is far stronger than either alone.\n\n'
+                + 'Everything else means "you may want to look", never "this is broken": `missingOptional` is guarded '
+                + 'by the layout and safe to omit, `unused` may be consumed by a different layout, and '
+                + '`unresolvedSections` names a section that matched no template under this layout.\n\n'
+                + 'The contract is scoped to the partials this entity ACTUALLY rendered with. Unscoped, a page using '
+                + 'two of twenty sections would be checked against all twenty and a real omission would be one line in '
+                + 'three hundred.\n\n'
+                + 'Check `reliable` before trusting an absence.',
+            inputSchema: {
+                id: z.string().describe('Entity id, e.g. "/documents/en/index.md".'),
+                layout: z.string().optional()
+                    .describe('Layout id to check against. Omit to use the layout this entity last rendered with, '
+                        + 'which is what the manifest recorded rather than a prediction.'),
+            },
         },
         async ({ id, layout }) => {
             const entity = await findEntity({ id })
@@ -527,7 +533,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
             // statically to every section in the project, so an unscoped
             // contract for a two-section page is the union of the catalogue and
             // a real omission is one line in three hundred.
-            const inspected = await runtime.options.layouts.inspect(layoutId, {
+            const inspected = await layouts.inspect(layoutId, {
                 samples: 0,
                 partials: usedPartials && usedPartials.length ? usedPartials : null,
             })
@@ -576,7 +582,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 // section look dead, and one such page reported 118 of them
                 // while its longer sibling reported none. The document's only
                 // difference was using fewer sections.
-                const wide = await runtime.options.layouts.inspect(layoutId, { samples: 0 })
+                const wide = await layouts.inspect(layoutId, { samples: 0 })
                 const anyLayout = new Set([
                     ...(wide.references?.contract?.meta ?? []),
                     ...observed,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.13.0",
+  "version": "3.1.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,7 +18,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
   "peerDependencies": {
-    "mikser-io": "^9.40.0",
+    "mikser-io": "^10.0.0",
     "zod": "^4.0.0"
   },
   "dependencies": {

package/test/_harness.js

@@ -9,6 +9,7 @@ import _ from 'lodash'
 import {
     runtime as realRuntime,
     matchEntity, normalize, changeExtension, getFormatInfo, checksum, AbortError,
+    resetServices,
 } from 'mikser-io'
 
 const OPERATION = {
@@ -33,6 +34,10 @@ export function createHarness({
     entities = [],
     journal = [],
 } = {}) {
+    // A fresh harness is a fresh world, and the service registry is module
+    // state that would otherwise carry the previous test's provider into this
+    // one — where providing it again is (correctly) an error.
+    resetServices()
     const hookNames = [
         'load', 'loaded', 'import', 'imported',
         'process', 'processed', 'persist', 'persisted',

package/test/check-entity.test.js

@@ -16,6 +16,7 @@ import path from 'node:path'
 import { createInspect } from '../lib/inspect.js'
 import { registerCheckTool } from '../lib/mcp.js'
 import * as liquid from 'mikser-io-render-liquid'
+import { provideService, resetServices, invokeTool } from 'mikser-io'
 
 // Shaped like a real project: a page shell with chrome, and sections dispatched
 // through a registry. The registry is the reason scoping matters — statically it
@@ -129,15 +130,22 @@ before(async () => {
                 : new Set()),
         },
     }
-    runtime.options.layouts = {
-        inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection: 'layouts' }),
+    // Each fixture activates itself immediately before it is used. The tool
+    // registry is one global list now, so a later describe's registration
+    // replaces an earlier one — and one test here deliberately reaches back
+    // to the no-schema fixture from inside the schema describe.
+    const activate = () => {
+        resetServices()
+        provideService('layouts', {
+            inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection: 'layouts' }),
+        })
+        registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
+                            collection: 'layouts', logger: { debug() {} } })
+    }
+    check = async (id) => {
+        activate()
+        return JSON.parse((await invokeTool('check_entity', { id })).content[0].text)
     }
-    const registry = new Map()
-    runtime.options.mcp = { simpleTool: (name, _d, _s, handler) => registry.set(name, handler) }
-    registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
-                        collection: 'layouts', logger: { debug() {} } })
-
-    check = async (id) => JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
 })
 
 after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
@@ -346,15 +354,19 @@ describe('mikser_check_entity: with a declared schema', () => {
             options: { schemas: { lookup: (n) => (n === 'article' ? schema : undefined), names: () => ['article'] } },
             renderers: new Map([['liquid', { parseReferences: liquid.parseReferences }]]),
         }
-        runtime.options.layouts = {
-            inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection: 'layouts' }),
+        const activate = () => {
+            resetServices()
+            provideService('layouts', {
+                inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection: 'layouts' }),
+            })
+            provideService('schemas', runtime.options.schemas)
+            registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
+                                collection: 'layouts', logger: { debug() {} } })
+        }
+        checkWithSchema = async (id) => {
+            activate()
+            return JSON.parse((await invokeTool('check_entity', { id })).content[0].text)
         }
-        const registry = new Map()
-        runtime.options.mcp = { simpleTool: (n, _d, _s, h) => registry.set(n, h) }
-        registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
-                            collection: 'layouts', logger: { debug() {} } })
-        checkWithSchema = async (id) =>
-            JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
     })
 
     after(async () => { if (dir2) await rm(dir2, { recursive: true, force: true }) })
@@ -442,17 +454,20 @@ describe('mikser_check_entity: peer comparison', () => {
         const findEntities = async (q) => entities.filter(e =>
             Object.entries(q ?? {}).every(([k, v]) => k.split('.').reduce((o, x) => o?.[x], e) === v))
         const runtime = { options: {}, renderers: new Map() }
-        runtime.options.layouts = { inspect: async () => ({ references: {} }) }
-        const registry = new Map()
-        runtime.options.mcp = { simpleTool: (n, _d, _s, h) => registry.set(n, h) }
-        registerCheckTool({
-            runtime, findEntity, findEntities,
-            // No snapshots: these never render, so they are data documents.
-            useDatabase: () => ({ handle: { prepare: () => ({ all: () => [], get: () => undefined }) } }),
-            collection: 'layouts', logger: { debug() {} },
-        })
-        peerCheck = async (id) =>
-            JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
+        const activate = () => {
+            resetServices()
+            provideService('layouts', { inspect: async () => ({ references: {} }) })
+            registerCheckTool({
+                runtime, findEntity, findEntities,
+                // No snapshots: these never render, so they are data documents.
+                useDatabase: () => ({ handle: { prepare: () => ({ all: () => [], get: () => undefined }) } }),
+                collection: 'layouts', logger: { debug() {} },
+            })
+        }
+        peerCheck = async (id) => {
+            activate()
+            return JSON.parse((await invokeTool('check_entity', { id })).content[0].text)
+        }
     })
 
     it('reports a key most siblings carry and this record lacks', async () => {

package/test/unit.test.js

@@ -6,7 +6,7 @@ import { tmpdir } from 'node:os'
 import path from 'node:path'
 
 import { layouts } from '../index.js'
-import { frontMatter } from 'mikser-io'
+import { frontMatter, useService } from 'mikser-io'
 import { createHarness } from './_harness.js'
 
 async function withTempWorking(fn) {
@@ -30,10 +30,42 @@ describe('layouts plugin', () => {
         assert.equal(h.hooks.beforeRender.length, 1)
         assert.equal(h.hooks.complete.length, 1)
         assert.ok(h.sync.has('layouts'))
-        // The inspect primitive is exposed at factory-eval — before any
-        // onLoaded fires — so plugins listed after layouts in the
-        // plugins array can see it during their own onLoaded.
-        assert.equal(typeof h.runtime.options.layouts?.inspect, 'function')
+        // The inspect primitive is offered at factory-eval — before any
+        // onLoaded fires — so a consumer sees it during its own onLoaded
+        // whatever the plugin order.
+        assert.equal(typeof useService('layouts')?.inspect, 'function')
+    })
+
+    it('puts the layouts folder where --layouts says', async () => {
+        // The flag could not exist while runtime.options.layouts held the
+        // inspect API: commander names an option after its long flag, so this
+        // would have overwritten that object after the load phase and broken
+        // a consumer somewhere else entirely.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({ options: {
+                workingFolder, outputFolder: path.join(workingFolder, 'out'), layouts: 'tmpl' } })
+            layouts()(h.core)
+            await h.runHook('loaded')
+            assert.equal(h.runtime.options.layoutsFolder, path.join(workingFolder, 'tmpl'))
+        })
+    })
+
+    it('lets --layouts win over the config, and takes an absolute path as given', async () => {
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({ options: {
+                workingFolder, outputFolder: path.join(workingFolder, 'out'), layouts: 'from-cli' } })
+            layouts({ layoutsFolder: 'from-config' })(h.core)
+            await h.runHook('loaded')
+            assert.equal(h.runtime.options.layoutsFolder, path.join(workingFolder, 'from-cli'))
+        })
+        await withTempWorking(async (workingFolder) => {
+            const absolute = path.join(workingFolder, 'elsewhere')
+            const h = createHarness({ options: {
+                workingFolder, outputFolder: path.join(workingFolder, 'out'), layouts: absolute } })
+            layouts()(h.core)
+            await h.runHook('loaded')
+            assert.equal(h.runtime.options.layoutsFolder, absolute)
+        })
     })
 
     it('initializes runtime.state.layouts on onLoaded with empty maps', async () => {