mikser-io-layouts 1.0.0

package/lib/matching.js

@@ -0,0 +1,212 @@
+// Layout assignment (the matching half of the plugin).
+//
+// onProcessed fires once per cycle. For every CREATE/UPDATE entity in
+// the journal that's NOT a layout itself, we figure out which layouts
+// should render it and stash the result in `entity.layouts` (canonical
+// multi-match) + `entity.layout` (back-compat alias).
+//
+// Three resolution paths, in priority:
+//   1. Author declared (`meta.layout` string OR `meta.layouts` array
+//      — dual key, mutually exclusive).
+//   2. options.match pattern hits → multi-match, every matching
+//      pattern contributes a layout.
+//   3. options.autoLayouts → the peel-ladder fallback (first-wins,
+//      single match by design).
+//
+// onProcessed runs BEFORE onBeforeRender; the layout snapshot stored
+// on entity.layouts here may go stale by render time (frontmatter
+// mutations during onPersist or sidecar load). The assembly phase
+// (lib/assembly.js) re-fetches each layout via findEntity to recover.
+
+import path from 'node:path'
+
+export function createOnProcessed({
+    runtime, useLogger, useJournal,
+    findEntity, matchEntity, collection,
+    OPERATION,
+    options,
+}) {
+    return async function onProcessedHandler(signal) {
+        const logger = useLogger()
+        const { layouts } = runtime.state.layouts
+
+        // Resolve a layout name to the catalog entity (post-front-matter
+        // strip) rather than the state-map entry (raw file bytes). The
+        // state map is just an index — it's populated at sync time with
+        // whatever readLayoutContent returned, before front-matter has
+        // had a chance to lift YAML attributes into meta and strip them
+        // from content. Attaching the raw state-map entry as
+        // entity.layout makes the renderer emit YAML verbatim into the
+        // rendered output (visible bug surfaced via MCP-UI previews).
+        //
+        // Catalog is the single source of truth for content; state map
+        // is just the name → id lookup. Falls back to the state entry
+        // only when the catalog hasn't caught up (sync races, synthetic
+        // test setups where front-matter hasn't been wired).
+        async function resolveLayout(name) {
+            const stateEntry = layouts[name]
+            if (!stateEntry) return undefined
+            return (await findEntity({ id: stateEntry.id })) || stateEntry
+        }
+
+        // Resolve the set of layouts that should render `entity` this
+        // cycle. Returns an array — empty if none matched. Rules:
+        //   1. meta.layout (string) and meta.layouts (array) can't both
+        //      be set; if both → throw, caught and logged below.
+        //   2. Author-declared selection (meta.layout / meta.layouts)
+        //      wins: every named layout is resolved; unknown names get
+        //      a warning but don't break the rest.
+        //   3. No author selection → multi-match across options.match
+        //      patterns. Every matching pattern contributes a layout.
+        //   4. No pattern matched AND options.autoLayouts → fall back
+        //      to the existing peel ladder; first found wins (the
+        //      ladder is a search-by-priority by design, not a list of
+        //      independent matches).
+        async function resolveLayoutsForEntity(entity) {
+            if (entity.meta?.layout && entity.meta?.layouts) {
+                throw new Error(
+                    `Entity ${entity.id}: both 'meta.layout' and 'meta.layouts' are set — pick one.`
+                )
+            }
+            const declared = Array.isArray(entity.meta?.layouts)
+                ? entity.meta.layouts
+                : entity.meta?.layout
+                    ? [entity.meta.layout]
+                    : null
+
+            if (declared) {
+                const resolved = []
+                for (const name of declared) {
+                    const layout = await resolveLayout(name)
+                    if (layout) {
+                        if (!resolved.find(l => l.name === layout.name)) resolved.push(layout)
+                    } else {
+                        logger.warn('Layout not found for %s: %s', entity.collection, entity.id, name)
+                    }
+                }
+                return resolved
+            }
+
+            // Multi-match over config patterns.
+            const matched = []
+            for (const pattern in options.match || []) {
+                if (matchEntity(entity, pattern)) {
+                    const name = options.match[pattern]
+                    const layout = await resolveLayout(name)
+                    if (layout && !matched.find(l => l.name === layout.name)) {
+                        matched.push(layout)
+                    }
+                }
+            }
+
+            // Auto-layout: only as a fallback when no pattern matched.
+            // The peel ladder is intentionally first-wins — it's a
+            // most-specific-name search, not a multi-match.
+            if (matched.length === 0 && options.autoLayouts && entity.id) {
+                const lookupBase = entity.id.replace(`/${entity.collection}/`, '')
+                const dir = path.dirname(lookupBase)
+                const base = path.basename(lookupBase)
+                const chunks = base.split('.')
+                const candidates = []
+                for (let i = chunks.length; i > 0; i--) {
+                    const head = chunks.slice(0, i).join('.')
+                    candidates.push(dir && dir !== '.' ? path.join(dir, head) : head)
+                }
+                const autoLayout = candidates.find(name => layouts[name])
+                if (autoLayout) {
+                    const layout = await resolveLayout(autoLayout)
+                    if (layout) matched.push(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(', '))
+                }
+            }
+
+            return matched
+        }
+
+        for await (let { entity, operation } of useJournal('Layouts processing', [OPERATION.CREATE, OPERATION.UPDATE, OPERATION.DELETE], signal)) {
+            if (entity.collection == collection) continue
+            switch (operation) {
+                case OPERATION.CREATE:
+                case OPERATION.UPDATE:
+                    try {
+                        entity.layouts = await resolveLayoutsForEntity(entity)
+                    } catch (err) {
+                        logger.error('Layout resolution for %s: %s', entity.id, err.message)
+                        entity.layouts = []
+                    }
+                    // Back-compat alias. Most existing downstream code
+                    // reads `entity.layout`; keep it pointing at the
+                    // first matched layout so it stays useful. The
+                    // onBeforeRender task-build phase iterates
+                    // entity.layouts and reassigns entity.layout per
+                    // task to the layout being processed.
+                    entity.layout = entity.layouts[0]
+
+                    // Mirror the matched name(s) into meta so the
+                    // catalog's `meta_layout` index can find this
+                    // entity via "anything with a layout" queries.
+                    // Author-declared cases already have meta.layout
+                    // (or meta.layouts) set; this covers the
+                    // pattern-match / auto-layout paths.
+                    if (entity.layouts.length && !entity.meta?.layout && !entity.meta?.layouts) {
+                        entity.meta = entity.meta || {}
+                        if (entity.layouts.length === 1) {
+                            entity.meta.layout = entity.layouts[0].name
+                        } else {
+                            entity.meta.layouts = entity.layouts.map(l => l.name)
+                        }
+                    }
+
+                    // A render-requested entity (carries useRenderer's
+                    // correlationId) that resolved to no layout will
+                    // silently produce nothing — the caller just gets
+                    // api.js's "did not complete". Surface the real
+                    // reason here, where we authoritatively know no
+                    // layout matched. Gated on correlationId so the
+                    // thousands of normal layout-less content files
+                    // stay quiet.
+                    if (entity.layouts.length === 0 && entity.options?.correlationId) {
+                        logger.warn(
+                            'Render requested for %s but no layout matched — set meta.layout / meta.layouts, add a layouts.match rule, or name it to match a layout (auto-layout). Entities without a layout are not rendered.',
+                            entity.id,
+                        )
+                    }
+
+                    // meta.postprocessor (string) / meta.postprocessors
+                    // (array) override is read at task-build time (in
+                    // onBeforeRender) because the layout entity is
+                    // re-fetched from the catalog there — any mutation
+                    // we did to it here would be reverted by the
+                    // refresh. We just sanity-check the dual key here
+                    // so authors see the error early.
+                    if (entity.meta?.postprocessor && entity.meta?.postprocessors) {
+                        logger.error(
+                            'Entity %s: both meta.postprocessor and meta.postprocessors set — pick one. The chain will fall back to the singular.',
+                            entity.id,
+                        )
+                    }
+
+                    if (entity.layouts.length) {
+                        logger.debug('Layouts matched for %s (%d): %s',
+                            entity.id, entity.layouts.length,
+                            entity.layouts.map(l => l.name).join(', '))
+                    } else if (entity.meta?.href) {
+                        logger.trace('Layout missing for %s: %s', entity.collection, entity.id)
+                    }
+                    break
+                case OPERATION.DELETE:
+                    // Catalog DELETE is the sole source of truth for "this
+                    // entity is no longer in the sitemap" — sitemap lives
+                    // in the catalog (queried via meta_href), so the
+                    // DELETE alone removes it.
+                    break
+            }
+            // Any layout/meta mutation above is auto-persisted by the
+            // useJournal generator when this for-body completes (the
+            // generator JSON.stringifies the entity post-yield and
+            // UPDATEs the row if it diverged from the original).
+        }
+    }
+}

package/lib/mcp.js

@@ -0,0 +1,54 @@
+// 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.
+//
+// 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.
+
+import { z } from 'zod'
+
+export function registerMcpTools({ runtime, useLogger }) {
+    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 logger = useLogger()
+
+    mcp.simpleTool(
+        'mikser_layouts_inspect',
+        'Inspect a layout: template source, references (runtime: precise refClosure from recent renders via the manifest; static: variables / partials / iterations / helpers parsed from source by the renderer plugin), and sample entities currently targeting it. Use this to answer "what does this layout need from an entity" before drafting a preview render — saves a guess-and-render-empty cycle.',
+        {
+            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 })
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            ...result,
+                            notes: [
+                                'references.runtime is the precise answer from manifest snapshots — what the renderer actually touched in recent renders. Empty if the layout has never rendered.',
+                                'references.static is the renderer-plugin AST walk of the template source — what the source mentions, including unexercised conditional branches. Empty when the renderer does not expose parseReferences (markdown / metatext / custom).',
+                                'samples only includes entities with explicit meta.layout. Auto-matched layouts are not listed; use mikser_query_entities with a filename-pattern filter for those.',
+                            ],
+                        }, null, 2),
+                    }],
+                }
+            } catch (err) {
+                logger.error('MCP mikser_layouts_inspect error: %s', err.message)
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: err.message }],
+                }
+            }
+        },
+    )
+
+    logger.debug('MCP tool registered: mikser_layouts_inspect (layouts plugin)')
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "mikser-io-layouts",
+  "version": "1.0.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",
+  "scripts": {
+    "test": "node --no-warnings --test --test-reporter=spec 'test/**/*.test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-layouts.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-layouts/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
+  "peerDependencies": {
+    "mikser-io": "^9.0.0"
+  },
+  "dependencies": {
+    "globby": "^14.0.0",
+    "handlebars": "^4.7.0",
+    "lodash": "^4.17.0",
+    "zod": "^4.4.3"
+  }
+}

package/test/_harness.js

@@ -0,0 +1,243 @@
+// A minimal in-memory harness for testing core plugins.
+//
+// Real plugins call lifecycle registrations (onLoaded, onProcess, onSync, ...)
+// during their factory invocation; the engine later drives those callbacks. In
+// tests we substitute every API surface with a recorder, then drive the
+// callbacks manually with controlled inputs.
+
+import _ from 'lodash'
+import {
+    runtime as realRuntime,
+    matchEntity, normalize, changeExtension, getFormatInfo, checksum, AbortError,
+} from 'mikser-io'
+
+const OPERATION = {
+    CREATE: 'create',
+    UPDATE: 'update',
+    DELETE: 'delete',
+    RENDER: 'render',
+    POSTPROCESS: 'postprocess',
+}
+const ACTION = {
+    CREATE: 'create',
+    UPDATE: 'update',
+    DELETE: 'delete',
+    TRIGGER: 'trigger',
+}
+const TASKS = { INLINE: 'inline', SERIAL: 'serial', WORKER: 'worker' }
+
+export function createHarness({
+    config = {},
+    options = {},
+    state = {},
+    entities = [],
+    journal = [],
+} = {}) {
+    const hookNames = [
+        'load', 'loaded', 'import', 'imported',
+        'process', 'processed', 'persist', 'persisted',
+        'beforeRender', 'render', 'afterRender',
+        'beforePostprocess', 'postprocess', 'afterPostprocess',
+        'finalize', 'finalized', 'cancel', 'cancelled',
+        'complete', 'validate',
+    ]
+    const hooks = Object.fromEntries(hookNames.map(n => [n, []]))
+    const sync = new Map()
+    const watchers = []
+    const renderTasks = []
+    const postprocessTasks = []
+    const progress = []
+    const logs = []
+    const mklog = (level) => (...args) => logs.push({ level, args })
+    const logger = {
+        info: mklog('info'),
+        warn: mklog('warn'),
+        error: mklog('error'),
+        debug: mklog('debug'),
+        trace: mklog('trace'),
+        notice: mklog('notice'),
+    }
+
+    let nextId = 1
+    const journalEntries = journal.map(e => ({ id: nextId++, output: null, context: {}, options: {}, ...e }))
+
+    function addEntry({ entity, operation, context = {}, options = {} }) {
+        journalEntries.push({ id: nextId++, entity, operation, context, options, output: null })
+    }
+
+    // Stub `runtime.catalog` so catalog.js's module-level findEntity /
+    // findEntities / findById / queryEntities / readEntity / expand
+    // walker read from the harness's in-memory entity set. Real
+    // catalog.js's onInitialized sets up an identical shape — a
+    // Map<id, entity> with a no-op save() — but persists to disk; the
+    // stub skips persistence. Pushes/mutations to the input `entities`
+    // array land in the same Map via the constructor below.
+    //
+    // Set on the runtime SINGLETON imported from src/runtime.js — that's
+    // what catalog.js sees. Setting it on the harness-local `runtime`
+    // object below wouldn't help because plugin code imports the
+    // singleton directly. Each createHarness() call overwrites the
+    // singleton's `.catalog`, which is fine because tests don't run in
+    // parallel within a file.
+    const catalogStub = {
+        byId: new Map(entities.filter(e => e?.id).map(e => [e.id, e])),
+        version: 'test',
+        cacheInvalidated: false,
+        // No-op save — the harness never wants disk side-effects.
+        // catalog.js's onFinalized hook calls runtime.catalog.save(),
+        // so any test that drives the full lifecycle would blow up
+        // without this.
+        save: async () => {},
+    }
+    realRuntime.catalog = catalogStub
+
+    const runtime = {
+        options: { workingFolder: '/tmp/test-mikser', plugins: [], ...options },
+        config,
+        state,
+        hooks,
+        engine: { logger },
+        catalog: catalogStub,
+        // Real lifecycle.js attaches these to the runtime via side-effect
+        // on import. The harness doesn't load that module, so reproduce
+        // them here against the in-memory journal.
+        create: async (entity) => addEntry({ operation: OPERATION.CREATE, entity }),
+        update: async (entity) => addEntry({ operation: OPERATION.UPDATE, entity }),
+        delete: async ({ id, collection, type }) =>
+            addEntry({ operation: OPERATION.DELETE, entity: { id, collection, type } }),
+    }
+    function updateEntry({ id, entity, output }) {
+        const entry = journalEntries.find(e => e.id === id)
+        if (!entry) return
+        if (entity !== undefined) entry.entity = entity
+        if (output !== undefined) entry.output = output
+    }
+    async function* useJournal(name, operations, signal) {
+        progress.push({ name, total: journalEntries.length })
+        for (const entry of journalEntries) {
+            if (operations?.length && !operations.includes(entry.operation)) continue
+            if (signal?.aborted) return
+            yield entry
+        }
+    }
+
+    const core = {
+        runtime,
+        useLogger: () => logger,
+
+        // Lifecycle registrations
+        onLoad: (cb) => hooks.load.push(cb),
+        onLoaded: (cb) => hooks.loaded.push(cb),
+        onImport: (cb) => hooks.import.push(cb),
+        onImported: (cb) => hooks.imported.push(cb),
+        onProcess: (cb) => hooks.process.push(cb),
+        onProcessed: (cb) => hooks.processed.push(cb),
+        onPersist: (cb) => hooks.persist.push(cb),
+        onPersisted: (cb) => hooks.persisted.push(cb),
+        onBeforeRender: (cb) => hooks.beforeRender.push(cb),
+        onRender: (cb) => hooks.render.push(cb),
+        onAfterRender: (cb) => hooks.afterRender.push(cb),
+        onBeforePostprocess: (cb) => hooks.beforePostprocess.push(cb),
+        onPostprocess: (cb) => hooks.postprocess.push(cb),
+        onAfterPostprocess: (cb) => hooks.afterPostprocess.push(cb),
+        onFinalize: (cb) => hooks.finalize.push(cb),
+        onFinalized: (cb) => hooks.finalized.push(cb),
+        onCancel: (cb) => hooks.cancel.push(cb),
+        onCancelled: (cb) => hooks.cancelled.push(cb),
+        onComplete: (cb) => hooks.complete.push(cb),
+        onSync: (name, cb) => sync.set(name, cb),
+        onValidate: (operations, cb) => hooks.validate.push({ operations, cb }),
+
+        // Entity helpers — write directly to the journal
+        createEntity: async (entity) => addEntry({ operation: OPERATION.CREATE, entity }),
+        updateEntity: async (entity) => addEntry({ operation: OPERATION.UPDATE, entity }),
+        deleteEntity: async ({ id, collection, type }) =>
+            addEntry({ operation: OPERATION.DELETE, entity: { id, collection, type } }),
+        addEntry,
+        addEntries: async (entries) => entries.forEach(addEntry),
+        updateEntry,
+        useJournal,
+        findEntity: async (query) => {
+            if (!query) return entities[0]
+            if (typeof query === 'function') return entities.find(query)
+            return entities.find(e => Object.entries(query).every(([k, v]) => e[k] === v))
+        },
+        // Synchronous PK lookup mirroring catalog.js's findById. Layouts'
+        // onBeforeRender hydrates dispatch ids through this — the harness
+        // serves from the same in-memory entities array.
+        findById: (id) => entities.find(e => e?.id === id) ?? catalogStub.byId.get(id),
+        findEntities: async (query) => {
+            if (!query) return [...entities]
+            if (typeof query === 'function') return entities.filter(query)
+            return entities.filter(e => Object.entries(query).every(([k, v]) => e[k] === v))
+        },
+        iterateEntities: async function* (query) {
+            // Stub — yields the same set findEntities would return,
+            // one entity at a time. Real impl in catalog.js chunks via
+            // sqlite; the harness doesn't need that fidelity because
+            // unit-test corpora are tiny.
+            const filtered = !query
+                ? [...entities]
+                : (typeof query === 'function'
+                    ? entities.filter(query)
+                    : entities.filter(e => Object.entries(query).every(([k, v]) => e[k] === v)))
+            for (const e of filtered) yield e
+        },
+
+        // Rendering & postprocessing — capture for assertions
+        renderEntities: async (tasks) => renderTasks.push(...tasks),
+        postprocessEntities: async (tasks) => postprocessTasks.push(...tasks),
+        renderEntity: async () => { },
+        postprocessEntity: async () => { },
+
+        // Misc
+        watch: (name, folder) => watchers.push({ name, folder }),
+        schedule: () => { },
+        trackProgress: () => { },
+        updateProgress: () => { },
+        stopProgress: () => { },
+
+        // Utilities (real implementations)
+        matchEntity,
+        normalize,
+        changeExtension,
+        getFormatInfo,
+        checksum,
+        AbortError,
+
+        constants: { OPERATION, ACTION, TASKS },
+    }
+
+    async function runHook(name, ...args) {
+        const callbacks = hooks[name] || []
+        const results = []
+        for (const cb of callbacks) {
+            results.push(await cb(...args))
+        }
+        return results
+    }
+
+    async function runSync(name, payload) {
+        const handler = sync.get(name)
+        if (!handler) return undefined
+        return handler(payload)
+    }
+
+    return {
+        core,
+        runtime,
+        logger,
+        logs,
+        sync,
+        watchers,
+        renderTasks,
+        postprocessTasks,
+        progress,
+        journal: journalEntries,
+        hooks,
+        runHook,
+        runSync,
+        addJournalEntry: addEntry,
+        constants: { OPERATION, ACTION, TASKS },
+    }
+}