mikser-io 7.8.2 → 7.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "7.8.2",
+	"version": "7.10.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {

package/src/api.js

@@ -7,6 +7,31 @@ import { writeFile, unlink, mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import './lifecycle.js' // side-effect: attaches runtime.create / update / delete
 
+// Build the error thrown when a submitted entity goes through a full
+// process cycle but never renders. useRenderer can't see *why* — by the
+// time it gives up, the journal is cleared — but it knows what it
+// submitted, so it branches on whether a layout was even requested and
+// points at the log line carrying the authoritative reason (the layouts
+// plugin warns when a render-requested entity matches no layout).
+//
+// `.status = 422` (Unprocessable Entity): the request was well-formed
+// but the entity can't be rendered as submitted. The API endpoint reads
+// err.status (defaulting to 500) so a no-layout render returns a client
+// error, not a server fault.
+function incompleteRenderError(entity) {
+    const id = entity?.id ?? '<unknown>'
+    const msg = entity?.meta?.layout
+        ? `Render did not complete for ${id}: it requested layout "${entity.meta.layout}" ` +
+          `but produced no output. Check the log for a "Layout not found" warning (the name ` +
+          `may not exist) or a "Render error" (the layout matched but threw).`
+        : `Render did not complete for ${id}: the entity has no meta.layout and matched no ` +
+          `layout, so nothing rendered it. Set meta.layout, add a layouts.match rule, or name ` +
+          `it to match a layout (auto-layout).`
+    const err = new Error(msg)
+    err.status = 422
+    return err
+}
+
 /**
  * Bind to the runtime and return an on-demand renderer that pipelines
  * concurrent calls into the minimum number of `runtime.process()` cycles.
@@ -79,7 +104,7 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
         } finally {
             for (const item of remaining.values()) {
                 clearTimeout(item.timer)
-                item.reject(new Error(`Render did not complete for ${item.entity.id}`))
+                item.reject(incompleteRenderError(item.entity))
             }
             const idx = completedHooks.indexOf(hook)
             if (idx >= 0) completedHooks.splice(idx, 1)

package/src/engine.js

@@ -131,7 +131,7 @@ export async function setup(options) {
             runtime.options.port = runtime.options.server === true
                 ? 3001
                 : Number(runtime.options.server) || 3001
-            logger.info('Server starting on port %d', runtime.options.port)
+            logger.debug('Server starting on port %d', runtime.options.port)
 
             // Trust-proxy: when mikser is behind a reverse proxy
             // (nginx, Caddy, an Express app, ngrok with edge), the
@@ -211,7 +211,7 @@ export async function setup(options) {
                 // workers, useLogger consumers) gains the side-channel
                 // automatically — no second logger to thread through.
                 wireLoggerToMcp(runtime.engine.logger, runtime.options.mcp)
-                logger.info('MCP substrate ready (mounts at %s when server is up)', runtime.options.mcpPath)
+                logger.debug('MCP substrate ready (mounts at %s when server is up)', runtime.options.mcpPath)
             } catch (err) {
                 logger.error('Failed to enable MCP: %s', err.message)
             }

package/src/plugins/api.js

@@ -627,7 +627,9 @@ export default ({
                 } catch (err) {
                     logger.error('Api[%s] render error: %s', name, err.message)
                     if (!res.headersSent) {
-                        res.status(500).json({ error: err.message })
+                        // useRenderer tags an unrenderable entity (no layout)
+                        // with err.status = 422; everything else is a 500.
+                        res.status(err.status ?? 500).json({ error: err.message })
                     }
                 }
             })

package/src/plugins/assets.js

@@ -1,5 +1,7 @@
 import path from 'node:path'
 import { mkdir, writeFile, unlink, rm, readFile, symlink, } from 'fs/promises'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { globby } from 'globby'
 import _ from 'lodash'
 import map from 'p-map'
@@ -42,6 +44,50 @@ export default ({
         return entityPresets
     }
 
+    // Resolve a preset name to an importable module location. Local
+    // files in presetsFolder win; names with no local file fall back to
+    // an npm package named `mikser-io-preset-<name>`, resolved from the
+    // project's node_modules. Mirrors how postprocess.js resolves
+    // post-* plugins — local override first, then the npm convention.
+    // Returns { uri, watchable } or null when neither exists.
+    //
+    // `watchable` distinguishes the two lifetimes: local presets are
+    // re-imported (cache-busted) on every load so watch-mode edits take
+    // effect; npm presets are versioned by their package, imported once.
+    function resolvePreset(name) {
+        const local = path.join(runtime.options.presetsFolder, `${name}.js`)
+        if (existsSync(local)) {
+            return { uri: local, watchable: true }
+        }
+        try {
+            const require = createRequire(path.join(runtime.options.workingFolder, 'package.json'))
+            const uri = require.resolve(`mikser-io-preset-${name}`)
+            return { uri, watchable: false }
+        } catch {
+            return null
+        }
+    }
+
+    // Import a preset module and build its catalog entity. One place for
+    // the (revision, format, options) export contract so onImport and
+    // onSync stay in sync. Cache-busts local presets so watch-mode edits
+    // reload; npm presets import once (their version is the cache key).
+    async function buildPreset({ name, uri, watchable }) {
+        const cacheBust = watchable ? `?stamp=${Date.now()}` : ''
+        const { revision = 1, format, options } = await import(`${uri}${cacheBust}`)
+        return {
+            id: `/presets/${name}`,
+            collection,
+            type,
+            uri,
+            name,
+            source: uri,
+            format,
+            checksum: revision,
+            options,
+        }
+    }
+
     async function getRevisions(entity) {
         let revisions = await globby(`${entity.destination.replaceAll('(', '\\(').replaceAll(')', '\\)')}.*.md5`, {
             cwd: path.join(runtime.options.assetsFolder, entity.preset.name),
@@ -147,26 +193,16 @@ export default ({
         const logger = useLogger()
         const { presets } = runtime.state.assets
 
+        // Watch only fires for files in presetsFolder, so these are
+        // always local presets — watchable: true.
         const name = relativePath.replace(path.extname(relativePath), '')
         const uri = path.join(runtime.options.presetsFolder, relativePath)
-        const source = uri
 
         let synced = true
         switch (action) {
             case ACTION.CREATE:
                 try {
-                    const { revision = 1, format, options } = await import(`${uri}?stamp=${Date.now()}`)
-                    const preset = {
-                        id: path.join('/presets', relativePath),
-                        collection,
-                        type,
-                        uri,
-                        name: relativePath.replace(path.extname(relativePath), ''),
-                        source,
-                        format,
-                        checksum: revision,
-                        options
-                    }
+                    const preset = await buildPreset({ name, uri, watchable: true })
                     presets[name] = preset
                     await createEntity(preset)
                 } catch (err) {
@@ -176,19 +212,12 @@ export default ({
                 break
             case ACTION.UPDATE:
                 try {
-                    const { revision = 1, format, options } = await import(`${uri}?stamp=${Date.now()}`)
-                    const preset = {
-                        id: path.join('/presets', relativePath),
-                        collection,
-                        type,
-                        uri,
-                        name: relativePath.replace(path.extname(relativePath), ''),
-                        checksum: revision,
-                        source,
-                        format,
-                        options
-                    }
-                    if (!preset[name]) {
+                    const preset = await buildPreset({ name, uri, watchable: true })
+                    // Was `!preset[name]` — a typo for `!presets[name]`
+                    // that made every UPDATE take the create branch
+                    // (preset[name] is always undefined). Fixed: only
+                    // re-emit when the revision actually changed.
+                    if (!presets[name]) {
                         presets[name] = preset
                         await createEntity(preset)
                     } else if (presets[name].checksum != preset.checksum) {
@@ -218,33 +247,45 @@ export default ({
         const logger = useLogger()
         const { presets } = runtime.state.assets
 
+        // Local presets: scan the presets folder. Loads every *.js
+        // there, keyed by filename. Local always wins.
         const paths = await globby('*.js', { cwd: runtime.options.presetsFolder })
         for (let relativePath of paths) {
+            const name = relativePath.replace(path.extname(relativePath), '')
             const uri = path.join(runtime.options.presetsFolder, relativePath)
-            const source = uri
             try {
-                const { revision = 1, format, options } = await import(`${uri}?stamp=${Date.now()}`)
-                const name = relativePath.replace(path.extname(relativePath), '')
-
-                const preset = {
-                    id: path.join('/presets', relativePath),
-                    collection,
-                    type,
-                    uri,
-                    name: relativePath.replace(path.extname(relativePath), ''),
-                    source,
-                    format,
-                    checksum: revision,
-                    options,
-                    options
-                }
-
+                const preset = await buildPreset({ name, uri, watchable: true })
                 await createEntity(preset)
                 presets[name] = preset
             } catch (err) {
                 logger.error(err, 'Preset loading error: %s', uri)
             }
         }
+
+        // npm presets: any preset name referenced in config that no
+        // local file already provided resolves to an npm package
+        // `mikser-io-preset-<name>`. Config is the source of truth for
+        // which presets a project uses; this fills the names a folder
+        // scan can't (the code lives in node_modules, not presets/).
+        for (const name of Object.keys(runtime.config.assets?.presets || {})) {
+            if (presets[name]) continue   // a local file already loaded it
+            const resolved = resolvePreset(name)
+            if (!resolved) {
+                logger.error(
+                    'Preset not found: %s (no presets/%s.js, no npm package mikser-io-preset-%s)',
+                    name, name, name,
+                )
+                continue
+            }
+            try {
+                const preset = await buildPreset({ name, uri: resolved.uri, watchable: resolved.watchable })
+                await createEntity(preset)
+                presets[name] = preset
+                logger.debug('Preset loaded from npm: mikser-io-preset-%s', name)
+            } catch (err) {
+                logger.error(err, 'Preset loading error (npm): mikser-io-preset-%s', name)
+            }
+        }
     })
 
     onProcessed(async (signal) => {

package/src/plugins/layouts.js

@@ -304,6 +304,19 @@ export default ({
                     if (entity.meta?.layout && !entity.layout) {
                         logger.warn('Layout not found for %s: %s', entity.collection, entity.id)
                     }
+                    // 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.layout && entity.options?.correlationId) {
+                        logger.warn(
+                            'Render requested for %s but no layout matched — set meta.layout, add a layouts.match rule, or name it to match a layout (auto-layout). Entities without a layout are not rendered.',
+                            entity.id,
+                        )
+                    }
 
                     if (entity.layout && entity.meta?.postprocessor) {
                         entity.layout.postprocessor = entity.meta.postprocessor