mikser-io-layouts 11.0.1 → 11.2.0

package/index.js

@@ -19,7 +19,7 @@ import _ from 'lodash'
 import {
     gateChecksum, sweepDeleted, scanSummary,
     checksumsByCollection,
-    checksum as fileChecksum, checksumOf,
+    checksum as fileChecksum, checksumOf, registerSourceChecksum,
     useDatabase,
     writeOutput, reportUnchanged,
     provideService,
@@ -29,7 +29,7 @@ import {
 import { createInspect } from './lib/inspect.js'
 import { createOnProcessed } from './lib/matching.js'
 import { createOnBeforeRender } from './lib/assembly.js'
-import { installSidecarModuleHook } from './lib/sidecar-modules.js'
+import { installSidecarModuleHook, loadSidecarModule } from './lib/sidecar-modules.js'
 import { registerMcpTools } from './lib/mcp.js'
 
 export function layouts(userOptions = {}) {
@@ -106,6 +106,19 @@ export function layouts(userOptions = {}) {
 
         provideService('layouts', {
             inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection }),
+            // A layout's sidecar, loaded the way the render loads it —
+            // same path rule, same digest stamp. Offered as a service because
+            // the alternative is another package importing this one's lib/,
+            // and a second copy of the stamping is a second chance for an
+            // edited sidecar to keep answering from cache.
+            //
+            // Consumers: mikser-io-mcp-app, which invokes a sidecar's `call`,
+            // `read` and `list` exports for an app's actions and data. The
+            // render's own use of the same loader reads `load` and `plugins`.
+            sidecar: (layout) => loadSidecarModule(layout, {
+                layoutsFolder: layoutsFolderNow(),
+                logger: useLogger(),
+            }),
         }, { plugin: 'mikser-io-layouts' })
 
         // Tool registration. Registers against core's tool registry, which
@@ -283,13 +296,27 @@ export function layouts(userOptions = {}) {
         // non-entity, which is why it is a rule and not a guess.
         const isSidecarScript = (rel) => path.extname(rel.replace(/\.js$/, '')) === ''
 
+        // The folder, resolved the same way the onLoaded below resolves it.
+        //
+        // That onLoaded is where `runtime.options.layoutsFolder` gets set, and
+        // a report-only command — mikser_explain, --audit-output — runs in an
+        // onLoaded too. Which of the two runs first is plugin order, so a
+        // recompute that read the option directly worked or threw depending on
+        // it. Derived here instead, so the answer does not depend on the
+        // question's timing.
+        function layoutsFolderNow() {
+            if (runtime.options.layoutsFolder) return runtime.options.layoutsFolder
+            const name = runtime.options.layouts ?? options.layoutsFolder ?? collection
+            return path.isAbsolute(name) ? name : path.join(runtime.options.workingFolder, name)
+        }
+
         async function sidecarInputs() {
-            const scriptPaths = (await globby('**/*.js', { cwd: runtime.options.layoutsFolder }))
+            const scriptPaths = (await globby('**/*.js', { cwd: layoutsFolderNow() }))
                 .filter(isSidecarScript)
             const own = new Map()
             const shared = []
             for (const rel of scriptPaths.sort()) {
-                const sum = await fileChecksum(path.join(runtime.options.layoutsFolder, rel))
+                const sum = await fileChecksum(path.join(layoutsFolderNow(), rel))
                 own.set(rel.replace(/\.js$/, ''), sum)
                 shared.push(`${rel}:${sum}`)
             }
@@ -305,6 +332,29 @@ export function layouts(userOptions = {}) {
             return Buffer.from(`${template}:${sidecar}:${inputs.sharedDigest}`, 'utf8')
         }
 
+        // Tell core how to recompute what it stored.
+        //
+        // The catalog holds the composed value above, not a file hash, so
+        // anything comparing it against a fresh md5 of the template compares
+        // two recipes and always finds them different. mikser_explain did
+        // exactly that and reported `differs: true` for every layout on every
+        // site — a permanent false alarm about files nobody had edited.
+        //
+        // The recipe belongs here, so the recomputation does too. One
+        // function, the same one the gate uses, so the two cannot drift apart.
+        registerSourceChecksum(collection, async (entity) => {
+            // A sidecar is in this collection but is NOT composed: it is
+            // gated on its own bytes above, because it has no template and no
+            // sidecar of its own. Answering with a composed value here would
+            // report every sidecar as diverged — the same false alarm this
+            // registration exists to remove, pointed the other way.
+            //
+            // null means "nothing composed here, use the file hash", which is
+            // exactly right for it.
+            if (entity.type === 'sidecar') return null
+            return checksumOf(await layoutInputBytes(entity.uri, entity.name, await sidecarInputs()))
+        })
+
         // 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() {

package/lib/assembly.js

@@ -30,7 +30,7 @@ import {
     reportError,
 } from 'mikser-io'
 import { compileDestinationTemplate, sanitizeDestination, primaryDestination } from './destination.js'
-import { setSidecarStamp, sidecarHookInstalled } from './sidecar-modules.js'
+import { loadSidecarModule } 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.
@@ -270,19 +270,20 @@ export function createOnBeforeRender({
                 const sidecarTrack = createTrack({ partial: false, meta: true, consumed: true })
                 if (existsSync(sidecarPath)) {
                     try {
-                        // Stamp = the shared sidecar digest, so the URL
-                        // changes exactly when some .js under layoutsFolder
-                        // does. With the resolve hook installed that stamp
-                        // also reaches the sidecar's own imports; without it
-                        // only the entry reloads, so fall back to a
-                        // per-render stamp to keep at least that much.
-                        const stamp = entity.layout.inputs?.shared || ''
-                        setSidecarStamp(stamp)
-                        const entryStamp = sidecarHookInstalled() ? stamp : Date.now();
+                        // Path resolution and stamping live in
+                        // sidecar-modules.js, shared with the apps surface
+                        // that invokes a sidecar's action handlers — one
+                        // implementation, so neither can drift from the
+                        // digest rule that keeps an edited sidecar from
+                        // answering out of cache.
+                        const sidecarModule = await loadSidecarModule(entity.layout, {
+                            layoutsFolder: runtime.options.layoutsFolder,
+                            logger,
+                        });
                         // Semicolon above is load-bearing: without it the
                         // parenthesised destructuring assignment below reads
                         // as a CALL of the preceding expression.
-                        ({ load, plugins = [] } = await import(`${sidecarPath}?stamp=${entryStamp}`))
+                        ({ load, plugins = [] } = sidecarModule ?? {})
                     } catch (err) {
                         logger.error('Layout sidecar %s failed to load: %s', sidecarPath.replace(runtime.options.workingFolder + '/', ''), err.message)
                         throw err

package/lib/sidecar-modules.js

@@ -31,6 +31,8 @@
 // once rather than left to be discovered.
 
 import module from 'node:module'
+import path from 'node:path'
+import { existsSync } from 'node:fs'
 import { pathToFileURL } from 'node:url'
 
 // Feature-detected rather than imported by name: `import { registerHooks }`
@@ -80,3 +82,32 @@ export function setSidecarStamp(next) {
 export function sidecarHookInstalled() {
     return installed
 }
+
+// Load a layout's sidecar module, or null when it has none.
+//
+// One implementation, two callers: the render (which then tracks what the
+// sidecar reads) and the apps surface (which invokes its action handlers).
+// The stamping is the whole reason this is shared — a second copy would drift
+// from the digest rule above and reintroduce the failure that rule exists for:
+// an edited sidecar that keeps answering from cache.
+export async function loadSidecarModule(layout, { layoutsFolder, logger } = {}) {
+    if (!layout?.name || !layoutsFolder) return null
+    const sidecarPath = path.join(layoutsFolder, `${layout.name}.js`)
+    // Existence first, so a real ERR_MODULE_NOT_FOUND from INSIDE the sidecar
+    // — it imports a package that is not installed — is not swallowed as
+    // "this layout has no sidecar".
+    if (!existsSync(sidecarPath)) return null
+
+    const shared = layout.inputs?.shared || ''
+    setSidecarStamp(shared)
+    // With the resolve hook installed the digest reaches the sidecar's own
+    // imports too; without it only the entry reloads, so fall back to a
+    // per-call stamp to keep at least that much.
+    const entryStamp = sidecarHookInstalled() ? shared : Date.now()
+    try {
+        return await import(`${pathToFileURL(sidecarPath).href}?stamp=${entryStamp}`)
+    } catch (err) {
+        logger?.error('Layout sidecar %s failed to load: %s', sidecarPath, err.message)
+        throw err
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "11.0.1",
+  "version": "11.2.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": "^11.0.1",
+    "mikser-io": "^11.1.0",
     "zod": "^4.0.0"
   },
   "dependencies": {
@@ -27,7 +27,7 @@
     "lodash": "^4.17.0"
   },
   "devDependencies": {
-    "mikser-io": "^11.0.1",
+    "mikser-io": "^11.1.0",
     "mikser-io-render-liquid": "^11.0.1",
     "zod": "^4.0.0"
   }

package/test/sidecar-modules.test.js

@@ -23,7 +23,7 @@ import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 
-import { installSidecarModuleHook, setSidecarStamp, sidecarHookInstalled } from '../lib/sidecar-modules.js'
+import { installSidecarModuleHook, setSidecarStamp, sidecarHookInstalled, loadSidecarModule } from '../lib/sidecar-modules.js'
 
 describe('sidecar module identity', () => {
     let root, layoutsFolder
@@ -98,3 +98,51 @@ describe('sidecar module identity', () => {
             "export const icon = 'filter.svg'\n")
     })
 })
+
+// loadSidecarModule — the shared loader. The render path and the apps surface
+// both go through it; a second copy of the path rule or the stamping is a
+// second chance for an edited sidecar to keep answering from cache, which is
+// the failure the whole file above exists for.
+describe('loadSidecarModule', () => {
+    let root, layoutsFolder
+
+    before(async () => {
+        root = await mkdtemp(path.join(tmpdir(), 'sidecar-loader-'))
+        layoutsFolder = path.join(root, 'layouts')
+        await mkdir(layoutsFolder, { recursive: true })
+        await writeFile(path.join(layoutsFolder, 'order.js'),
+            'export const load = () => ({ page: 1 })\n'
+            + 'export const call = async ({ action }) => ({ handled: action })\n'
+            + 'export const read = async ({ uri }) => ({ uri })\n'
+            + 'export const list = async () => [{ uri: "app://order/rows" }]\n')
+        await writeFile(path.join(layoutsFolder, 'plain.js'), 'export const load = () => ({})\n')
+    })
+
+    after(async () => { await rm(root, { recursive: true, force: true }) })
+
+    it('returns the module with every named export a sidecar declares', async () => {
+        const sidecar = await loadSidecarModule({ name: 'order', inputs: { shared: 'd1' } }, { layoutsFolder })
+        assert.equal(typeof sidecar.load, 'function', 'the render reads load')
+        for (const name of ['call', 'read', 'list']) {
+            assert.equal(typeof sidecar[name], 'function', `the apps surface reads ${name}`)
+        }
+        assert.deepEqual(await sidecar.call({ action: 'approve' }), { handled: 'approve' })
+    })
+
+    it('returns null for a layout with no sidecar, rather than throwing', async () => {
+        assert.equal(await loadSidecarModule({ name: 'absent', inputs: {} }, { layoutsFolder }), null)
+    })
+
+    it('returns null when it is asked without a layout or a folder', async () => {
+        assert.equal(await loadSidecarModule(null, { layoutsFolder }), null)
+        assert.equal(await loadSidecarModule({ name: 'order' }, {}), null)
+    })
+
+    it('leaves a sidecar without the apps exports alone', async () => {
+        // Every existing sidecar is this shape. Reading `call` off one must be
+        // undefined, not an error — the apps surface decides what to do.
+        const sidecar = await loadSidecarModule({ name: 'plain', inputs: { shared: 'd1' } }, { layoutsFolder })
+        assert.equal(typeof sidecar.load, 'function')
+        assert.equal(sidecar.call, undefined)
+    })
+})