mikser-io-layouts 11.1.0 → 11.2.0

package/index.js

@@ -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

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.1.0",
+  "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",

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)
+    })
+})