mikser-io-layouts 2.15.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)

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.15.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 () => {