mikser-io 7.0.0 → 7.6.0

package/README.md

@@ -116,6 +116,7 @@ The engine is what stays stable — the lifecycle, the catalog, the file-based c
 |---|---|
 | `data` | JSON snapshots of entities / context / catalog, written to disk for static serving |
 | `api` | REST endpoints with sift-backed queries, per-endpoint tokens, optional render, opt-in [per-query disk cache](./documentation/caching.md) for reverse-proxy failover |
+| `preview` | In-memory render cache + `GET /preview/:filename` route. Companion to the [`mikser_preview`](./documentation/mcp.md) MCP tool — transient render bytes served at a clickable URL, no filesystem footprint |
 
 **Integrations:**
 

package/ngrok.ymlt

@@ -0,0 +1,3 @@
+version: 3
+agent:
+  authtoken: 3EcICPaDtSN54h63Y5v8g2zKOJ9_5oMnCdXyPmMmKVXH9ba1c

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "7.0.0",
+	"version": "7.6.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {
@@ -20,14 +20,14 @@
 	"author": "",
 	"license": "ISC",
 	"dependencies": {
-		"@budibase/handlebars-helpers": "^0.14.2",
+		"@budibase/handlebars-helpers": "^0.14.3",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"await-semaphore": "^0.1.3",
-		"axios": "^1.16.0",
+		"axios": "^1.17.0",
 		"chokidar": "^5.0.0",
 		"cli-progress": "^3.12.0",
-		"commander": "^14.0.3",
-		"dayjs": "^1.11.20",
+		"commander": "^15.0.0",
+		"dayjs": "^1.11.21",
 		"deepdash": "^5.3.9",
 		"escape-string-regexp": "^5.0.0",
 		"execa": "^9.6.1",
@@ -43,18 +43,18 @@
 		"minimatch": "^10.2.5",
 		"node-cron": "^4.2.1",
 		"p-map": "^7.0.4",
-		"p-queue": "^9.2.0",
+		"p-queue": "^9.3.0",
 		"pino": "^10.3.1",
 		"pino-pretty": "^13.1.3",
 		"piscina": "^5.1.4",
 		"sift": "^17.1.3",
 		"sqlite3": "^6.0.1",
 		"truncate-stream": "^1.0.2",
-		"yaml": "^2.8.4"
+		"yaml": "^2.9.0"
 	},
 	"optionalDependencies": {
 		"express": "^5.2.1",
-		"puppeteer": "^24.43.0"
+		"puppeteer": "^25.1.0"
 	},
 	"devDependencies": {
 		"fluent-ffmpeg": "^2.1.3",

package/src/api.js

@@ -37,10 +37,20 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
         const remaining = new Map(batch.map(b => [b.correlationId, b]))
         const completedHooks = runtime.hooks.completed
         const hook = async (entry) => {
-            const cid = entry.entity?._correlationId
+            const cid = entry.entity?.options?.correlationId
             if (!cid) return
             const item = remaining.get(cid)
             if (!item) return
+            // Only resolve on the FINAL completion. For postprocessor-
+            // equipped entities the engine fires runtime.complete twice:
+            // once after render (intermediate bytes, entity.origin not
+            // set) and once after postprocess (final bytes, entity.origin
+            // set to the intermediate destination). useRenderer's
+            // contract is "return the pipeline's final output", so we
+            // skip the intermediate fire and wait for the final.
+            const hasPostprocessor = entry.entity?.layout?.postprocessor
+            const isFinal = !hasPostprocessor || entry.entity?.origin != null
+            if (!isFinal) return
             remaining.delete(cid)
             clearTimeout(item.timer)
             item.resolve({ output: entry.output, entity: entry.entity })
@@ -99,13 +109,24 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
      *   skip the final disk write; the bytes still come back via
      *   `output.result` for you to pipe wherever you want (HTTP
      *   response, S3, …). For layouts with a postprocessor (e.g.
-     *   `*.html-pdf.*`), the intermediate file is still written so the
-     *   postprocessor can consume it; only the FINAL output is skipped.
+     *   `*.html-pdf.*`), the intermediate is written to a scratch path
+     *   under `runtime.options.previewFolder` (engine-owned, never
+     *   in outputFolder) so the postprocessor can consume it; only
+     *   the FINAL output is skipped from disk. `output.result` is
+     *   always the FINAL pipeline output — PDF bytes for a
+     *   `*.html-pdf.*` layout, MJML-derived HTML for
+     *   `*.html-mjml.*`, etc., not the intermediate.
      *
      * The rendered output's bytes are always returned in `output.result`
      * regardless of either flag — `save` only affects whether they also
      * end up on disk.
      *
+     * Per-entity engine state (correlation id, control flags) lives at
+     * `entity.options.*` — same noun mikser uses for engine config
+     * (`runtime.options`) and plugin params, scoped to one entity's
+     * pass through the lifecycle. Consumers should not set
+     * `entity.options.correlationId` themselves; useRenderer owns it.
+     *
      * @param {object} entity                - any entity-shaped object
      * @param {object} [opts]
      * @param {number}  [opts.timeout]       - override the default timeout
@@ -116,12 +137,25 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
     async function render(entity, { timeout = defaultTimeout, catalog = true, save = true } = {}) {
         const result = await new Promise((resolve, reject) => {
             const correlationId = randomUUID()
-            const stamped = { ...entity, _correlationId: correlationId }
-            // Only stamp _save when explicitly opting out — keeps the
-            // entity object clean for the common case.
-            if (save === false) stamped._save = false
+            // Engine-set fields live under entity.options. The caller's
+            // render(entity, { save: false }) becomes
+            // entity.options.save = false here — same noun mikser uses
+            // for engine config (runtime.options) and plugin params,
+            // just scoped to one entity's pass through the lifecycle.
+            //
+            // Only set `save` when explicitly opting out — leaves the
+            // entity.options as a clean { correlationId } in the common
+            // case rather than carrying a redundant save:true.
+            const prepared = {
+                ...entity,
+                options: {
+                    ...entity.options,
+                    correlationId,
+                    ...(save === false ? { save: false } : {}),
+                },
+            }
             pending.push({
-                entity: stamped,
+                entity: prepared,
                 correlationId,
                 timeout,
                 resolve,

package/src/engine.js

@@ -75,6 +75,12 @@ export async function setup(options) {
 
         runtime.options.runtimeFolder = path.join(runtime.options.workingFolder, runtime.options.runtimeFolder || 'runtime')
         runtime.options.outputFolder = path.join(runtime.options.workingFolder, runtime.options.outputFolder || 'out')
+        // Scratch path for intermediate render artifacts when a caller
+        // opted out of disk writes via render({ save: false }) but the
+        // layout has a postprocessor that still needs to read the
+        // intermediate. Lives under runtimeFolder so it's engine-owned
+        // and never appears in outputFolder.
+        runtime.options.previewFolder = path.join(runtime.options.runtimeFolder, 'preview')
 
         if (runtime.options.clear) {
             try {
@@ -415,7 +421,22 @@ export async function setup(options) {
                         origin: entity.destination,
                         destination
                     },
-                    options: { postprocessor: options.postprocessor, tasks: options.tasks },
+                    options: {
+                        postprocessor: options.postprocessor,
+                        tasks: options.tasks,
+                        // When the originating render call passed
+                        // `save: false`, the layouts plugin wrote the
+                        // intermediate into runtime.options.previewFolder
+                        // rather than outputFolder. Postprocess plugins
+                        // resolve `entity.origin` against
+                        // `options.outputFolder`, so swap it here so
+                        // they look in the right place. No change for
+                        // normal builds (entity.options.save unset →
+                        // outputFolder).
+                        ...(entity.options?.save === false
+                            ? { outputFolder: runtime.options.previewFolder }
+                            : {}),
+                    },
                     context
                 })
             }

package/src/mcp.js

@@ -22,7 +22,6 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 import packageInfo from '../package.json' with { type: 'json' }
 import runtime from './runtime.js'
-import { onLoaded } from './lifecycle.js'
 
 let pinoLevelToMcp = (pinoLevel) => {
     if (pinoLevel >= 50) return 'error'
@@ -63,8 +62,6 @@ export function createMcpSubstrate() {
     }
 
     const substrate = {
-        // ---- plugin-facing surface (mirrors McpServer) -----------
-
         // The SDK's register* methods take different argument counts
         // (3 for tools, 4 for resources, 3 for prompts). We spread the
         // recorded args verbatim — substrate doesn't peek at the
@@ -97,8 +94,6 @@ export function createMcpSubstrate() {
             return substrate.registerTool(name, { description, inputSchema }, handler)
         },
 
-        // ---- engine-facing surface -------------------------------
-
         // Create a fresh McpServer pre-loaded with every recorded
         // registration. Called by the transport mount per new session.
         _createServer() {
@@ -113,8 +108,6 @@ export function createMcpSubstrate() {
         _detach(server) { activeServers.delete(server) },
         _activeServerCount() { return activeServers.size },
 
-        // ---- notification broadcast ------------------------------
-
         // Send a logging-message notification to every connected
         // client. The SDK's per-session level filtering applies.
         broadcastLog(params) {
@@ -129,8 +122,6 @@ export function createMcpSubstrate() {
             }
         },
 
-        // ---- rolling log buffer ----------------------------------
-
         // Called by wireLoggerToMcp on every log call. Records a
         // monotonic seq number so clients can poll "give me lines
         // since seq=N" against mikser://logs/recent.
@@ -238,13 +229,34 @@ export function createMcpSubstrate() {
         }),
     )
 
+    // mikser://server — single-shot answer to "where do I put output
+    // so the user can see it?" Combines server state (running? on what
+    // URL?) and the path conventions agents should write to for
+    // preview-style outputs.
+    substrate.registerResource(
+        'mikser-server',
+        'mikser://server',
+        {
+            title: 'HTTP server location and preview conventions',
+            description: 'Where the running engine is reachable (URL, MCP path, preview path prefix) and what folder it serves. The single resource an agent needs to answer "where can the user see this output?"',
+            mimeType: 'application/json',
+        },
+        async (uri) => ({
+            contents: [{
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(serverInfo(), null, 2),
+            }],
+        }),
+    )
+
     // Built-in liveness/identity tool. Also ensures tools/list works
     // before any plugin has registered (McpServer only advertises
     // tools/list capability after at least one registration).
     substrate.registerTool(
         'mikser_ping',
         {
-            description: 'Return mikser engine identity and the current lifecycle phase. Use to confirm the connection is live before issuing other tool calls.',
+            description: 'Return mikser engine identity, current lifecycle phase, and (if --server is on) where the HTTP server is reachable. Use to confirm the connection is live before issuing other tool calls and to learn the base URL for preview outputs.',
             inputSchema: {},
         },
         async () => ({
@@ -258,6 +270,7 @@ export function createMcpSubstrate() {
                     workingFolder: runtime.options.workingFolder,
                     outputFolder: runtime.options.outputFolder,
                     activeClients: substrate._activeServerCount(),
+                    server: serverInfo(),
                 }, null, 2),
             }],
         }),
@@ -266,6 +279,41 @@ export function createMcpSubstrate() {
     return substrate
 }
 
+// Derive a stable snapshot of "where outputs are visible to the user."
+// Three cases:
+//   1. --server is on  → engine owns Express, knows port → full URL
+//   2. external app    → caller supplied runtime.options.app; URL not
+//                        visible to engine (port unknown), but the
+//                        outputFolder and path conventions are still
+//                        useful for preview-writing tools
+//   3. no server       → only the static folder layout applies; an
+//                        agent should not try to advertise a URL
+//
+// Kept as a function rather than a const so each call re-reads
+// runtime.options — covers the case where --server flips on after
+// the substrate was created (rare but possible programmatically).
+function serverInfo() {
+    const opts = runtime.options
+    const hasInternalServer = opts.server != null && opts.port != null
+    const hasExternalApp = opts.app && !hasInternalServer
+
+    const base = hasInternalServer
+        ? `http://localhost:${opts.port}`
+        : null
+
+    return {
+        running: hasInternalServer ? 'internal' : (hasExternalApp ? 'external' : 'none'),
+        port: opts.port ?? null,
+        url: base,
+        serves: opts.outputFolder ?? null,
+        mcpPath: opts.mcpPath ?? null,
+        mcpUrl: base && opts.mcpPath ? `${base}${opts.mcpPath}` : null,
+        // Preview URLs are returned directly by mikser_preview (api
+        // plugin), so we don't advertise a path convention here —
+        // doing so would be a lie when the api plugin isn't loaded.
+    }
+}
+
 /**
  * Mount the MCP substrate on an Express app at the given path
  * (default `/mcp`). Each connecting client gets its own
@@ -375,11 +423,15 @@ function pinoLevelNumber(name) {
     return { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 }[name] ?? 30
 }
 
-// Convenience for plugins that want to gate their tool registrations
-// behind "is MCP active?". Equivalent to checking runtime.options.mcp
-// directly but reads better at the call site.
-export function whenMcpActive(callback) {
-    onLoaded(async () => {
-        if (runtime.options.mcp) await callback(runtime.options.mcp)
-    })
-}
+// (whenMcpActive was removed in v7.4.0 — plugins now use the same
+// inline pattern as Express route registration: gate on the runtime
+// option inside whichever lifecycle hook makes sense.
+//
+//   onLoaded(async () => {
+//       if (runtime.options.mcp) {
+//           runtime.options.mcp.simpleTool(...)
+//       }
+//   })
+//
+// Reveals timing, matches the Express pattern, doesn't lock the
+// registration into onLoaded.)

package/src/plugins/api.js

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { access, writeFile, mkdir, rm } from 'node:fs/promises'
+import { access, writeFile, readFile, mkdir, rm } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 import _ from 'lodash'
 import sift from 'sift'
@@ -333,6 +333,11 @@ export default ({
         const globalPageSize = runtime.config.api?.pageSize ?? 10
         const globalRenderTimeout = runtime.config.api?.renderTimeout ?? 30_000
 
+        // Preview workflow (render → cache → URL) lives in its own
+        // plugin (src/plugins/preview.js) as of v7.3.0. The api plugin
+        // stays focused on REST catalog access; preview is a separate
+        // domain. To use mikser_preview, load `preview` alongside `api`.
+
         // cachedEndpoints is hoisted above (shared with onFinalize).
         // Per-endpoint setup loop pushes into it when cache: true is set.
 
@@ -637,9 +642,9 @@ export default ({
                 ep.token ? '[token]' : '[public]')
         }
 
-        // ---- MCP tool registrations -----------------------------------
-        // MCP is in-process: whoever can reach the /mcp transport already
-        // controls the engine. So the tool surface mirrors the *admin*-
+        // MCP tool registrations. MCP is in-process: whoever can reach
+        // the /mcp transport already controls the engine. So the tool
+        // surface mirrors the *admin*-
         // shape (list/query/read/update/delete/render) without the HTTP
         // endpoint's token gate or query scope — the catalog is global.
         // Tools register once (not per HTTP endpoint); plugin-author
@@ -695,11 +700,12 @@ export default ({
 
             mcp.simpleTool(
                 'mikser_read_entity',
-                'Read a single entity by its catalog id (e.g. "/documents/about.md"). Returns the full entity record or null when not found.',
+                'Read a single entity by its catalog id (e.g. "/documents/about.md"). Returns the full entity record or null when not found. Pass include: ["content"] to also fetch the source file content from disk — useful for reading a layout template, document frontmatter+body, or any text-format source without dropping out to the filesystem.',
                 {
                     id: z.string().describe('Catalog id of the entity to read.'),
+                    include: z.array(z.enum(['content'])).optional().describe('Optional list of extra fields to populate. Currently only "content" is supported: reads the file at entity.uri and attaches it as .content (text formats only — md, html, yml, liquid, hbs, eta, json, css, js, svg, xml, mjml).'),
                 },
-                async ({ id }) => {
+                async ({ id, include }) => {
                     try {
                         if (!id) return fail('id is required')
                         const { items } = await runQuery({
@@ -708,7 +714,37 @@ export default ({
                             scope: null,
                             findEntities,
                         })
-                        return ok(items[0] ?? null)
+                        const entity = items[0]
+                        if (!entity) return ok(null)
+
+                        if (include?.includes('content') && entity.uri) {
+                            // Heuristic — read content only for text-like
+                            // formats. Binary types (png, pdf, mp4, etc.)
+                            // get a marker so the caller knows to use a
+                            // different tool (mikser_render, or fetch
+                            // directly) rather than expecting bytes back.
+                            const TEXT_EXTS = new Set([
+                                'md', 'markdown', 'html', 'htm', 'xhtml',
+                                'yml', 'yaml', 'json', 'jsonc',
+                                'txt', 'csv', 'tsv',
+                                'css', 'js', 'mjs', 'cjs', 'ts',
+                                'liquid', 'hbs', 'handlebars', 'eta', 'mustache',
+                                'svg', 'xml', 'mjml', 'rss', 'atom',
+                                'aml',
+                            ])
+                            const ext = path.extname(entity.uri).slice(1).toLowerCase()
+                            if (TEXT_EXTS.has(ext)) {
+                                try {
+                                    entity.content = await readFile(entity.uri, 'utf8')
+                                } catch (err) {
+                                    entity.contentError = err.message
+                                }
+                            } else {
+                                entity.contentSkipped = `Non-text format (.${ext}). Use mikser_render to materialize output or read the file directly at entity.uri.`
+                            }
+                        }
+
+                        return ok(entity)
                     } catch (err) {
                         logger.error('MCP mikser_read_entity error: %s', err.message)
                         return fail(err.message)
@@ -755,7 +791,7 @@ export default ({
 
             mcp.simpleTool(
                 'mikser_render',
-                'Render a transient entity through the engine pipeline (parse → layouts → resources → render → postprocess) and return the produced bytes. Use this for "preview this layout against this data" without writing the entity to disk. Set options.save=false to skip the disk write; options.catalog=false to prune the catalog row after rendering.',
+                'Render a transient entity through the engine pipeline (parse → layouts → resources → render → postprocess) and return the FINAL produced bytes. Use this for "preview this layout against this data" without writing the entity to disk. The returned bytes are the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Set options.save=false to skip the disk write; options.catalog=false to prune the catalog row after rendering.',
                 {
                     entity:  z.record(z.any()).describe('Entity shape with at least { id, collection } and any meta/content the renderer needs.'),
                     options: z.record(z.any()).optional().describe('Renderer options: { save: false, catalog: false, renderer: "...", postprocessor: "..." }.'),
@@ -798,7 +834,7 @@ export default ({
                 },
             )
 
-            logger.info('MCP tools registered: list/read/update/delete/render')
+            logger.info('MCP tools registered: list/read/update/delete/render (api plugin)')
         }
     })
 

package/src/plugins/layouts.js

@@ -1,8 +1,82 @@
 import path from 'node:path'
-import { mkdir, writeFile, unlink, rmdir } from 'node:fs/promises'
+import { mkdir, writeFile, unlink, rmdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { globby } from 'globby'
 import _ from 'lodash'
+import { z } from 'zod'
+
+// Liquid / Handlebars / Eta keywords we don't want surfaced as
+// "variables this layout references." Anything that looks like a path
+// (`document.meta.X`) survives; bare keywords filter out.
+const TEMPLATE_KEYWORDS = new Set([
+    'if', 'else', 'elsif', 'endif', 'unless', 'endunless',
+    'for', 'endfor', 'each', 'break', 'continue', 'in', 'of',
+    'case', 'when', 'endcase', 'switch',
+    'capture', 'endcapture', 'assign', 'include', 'layout', 'block',
+    'endblock', 'comment', 'endcomment', 'raw', 'endraw',
+    'true', 'false', 'nil', 'null', 'and', 'or', 'not', 'with',
+])
+
+// Naive multi-engine template scan. Hits liquid (`{{ X }}`, `{% ... %}`),
+// handlebars (`{{ X }}`, `{{#each X}}`), and eta (`<%= X %>`,
+// `<% for X of Y %>`). Returns up to three buckets:
+//   variables  — bare identifier paths used in output position
+//   includes   — referenced sub-templates (liquid `include` / `layout`)
+//   iterations — `for X in Y` / `each X` shapes so the caller knows
+//                where array fields are expected
+//
+// "Naive" is the right word: regex pass, not an AST walk. False positives
+// possible; per-engine plugins can register smarter parsers later.
+function parseTemplateReferences(source) {
+    const empty = { variables: [], includes: [], iterations: [] }
+    if (typeof source !== 'string' || !source) return empty
+
+    const variables = new Set()
+    const includes = new Set()
+    const iterations = []
+
+    // {{ X.Y.Z }} and <%= X.Y.Z %> — output expressions. Capture leading
+    // identifier path; ignore filters (`| upcase`), pipes, and anything
+    // after a space.
+    const outputExpr = /(?:\{\{=?|<%=)\s*([^}%|]+?)(?:\s*\||\s*\}\}|\s*-?%>)/g
+    for (const m of source.matchAll(outputExpr)) {
+        const expr = m[1].trim()
+        const ident = expr.match(/^[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*/)
+        if (ident && !TEMPLATE_KEYWORDS.has(ident[0])) {
+            variables.add(ident[0])
+        }
+    }
+
+    // Liquid include / layout — sub-template references.
+    for (const m of source.matchAll(/\{%\s*include\s+['"]([^'"]+)['"]/g)) {
+        includes.add(m[1])
+    }
+    for (const m of source.matchAll(/\{%\s*layout\s+['"]([^'"]+)['"]/g)) {
+        includes.add(m[1])
+    }
+
+    // Liquid `{% for X in Y %}` and `{% for X in Y.Z %}`.
+    for (const m of source.matchAll(/\{%\s*for\s+(\w+)\s+in\s+([\w.]+)/g)) {
+        iterations.push({ item: m[1], collection: m[2] })
+        variables.add(m[2])
+    }
+    // Handlebars `{{#each X.Y}}`.
+    for (const m of source.matchAll(/\{\{#each\s+([\w.]+)/g)) {
+        iterations.push({ item: '(each)', collection: m[1] })
+        variables.add(m[1])
+    }
+    // Eta `<% for (const X of Y) { %>` / `<% for X of Y %>`.
+    for (const m of source.matchAll(/<%\s*for\s*\(?\s*(?:const|let|var)?\s*(\w+)\s+of\s+([\w.]+)/g)) {
+        iterations.push({ item: m[1], collection: m[2] })
+        variables.add(m[2])
+    }
+
+    return {
+        variables: Array.from(variables).sort(),
+        includes: Array.from(includes).sort(),
+        iterations,
+    }
+}
 
 export default ({
     runtime,
@@ -370,22 +444,29 @@ export default ({
     onComplete(async ({ entity, options, output }) => {
         const logger = useLogger()
         if (entity.layout && !options?.ignore && output.result != null) {
-            // `_save: false` (stamped by useRenderer when called with
-            // { save: false }) opts out of writing the final output to
-            // disk. The bytes still come back to the caller via
-            // output.result. Strict equality — only the literal `false`
-            // opts out, matching the catalog-flag pattern.
+            // `entity.options.save === false` (set by useRenderer when
+            // called with { save: false }) opts out of writing the
+            // FINAL output to disk. The bytes still come back to the
+            // caller via output.result. Strict equality — only the
+            // literal `false` opts out, matching the catalog-flag pattern.
             //
             // The intermediate file (when a postprocessor will run next)
-            // must still be written so the postprocessor can consume it,
-            // so we only honour `_save: false` for the FINAL output —
-            // detected as either "no postprocessor configured" or "we're
-            // running on the postprocess side already" (origin set).
+            // must still exist somewhere on disk so the postprocessor
+            // can consume it. For save:true, that's outputFolder; for
+            // save:false, that's runtime.options.previewFolder — an
+            // engine-owned scratch path under runtimeFolder, never
+            // exposed in user-visible outputFolder. The postprocess
+            // task's outputFolder is rewritten in engine.js so post
+            // plugins resolve `entity.origin` against the same base.
             const isFinal = !entity.layout.postprocessor || entity.origin != null
-            const skipWrite = entity._save === false && isFinal
+            const previewMode = entity.options?.save === false
+            const skipWrite = previewMode && isFinal
+            const writeBase = (previewMode && !isFinal)
+                ? runtime.options.previewFolder
+                : runtime.options.outputFolder
 
             if (!skipWrite) {
-                const destinationFile = path.join(runtime.options.outputFolder, entity.destination)
+                const destinationFile = path.join(writeBase, entity.destination)
                 await mkdir(path.dirname(destinationFile), { recursive: true })
                 try {
                     await unlink(destinationFile)
@@ -401,7 +482,14 @@ export default ({
                 // wrote to (post plugins that produce the same extension as
                 // the renderer's output — e.g. MJML→HTML on `*.html-mjml.*`
                 // layouts). Otherwise we'd delete our own final file.
-                const originFile = path.join(runtime.options.outputFolder, entity.origin)
+                //
+                // For preview flow (entity.options.save === false) the
+                // intermediate lived in previewFolder; for normal flow
+                // it lived in outputFolder. Pick the right base.
+                const originBase = previewMode
+                    ? runtime.options.previewFolder
+                    : runtime.options.outputFolder
+                const originFile = path.join(originBase, entity.origin)
                 try {
                     await unlink(originFile)
                 } catch { }
@@ -418,6 +506,94 @@ export default ({
         }
     })
 
+    // mikser_inspect_layout lives in the layouts plugin (not core)
+    // because "what does a layout expect?" is layout-specific knowledge.
+    // Follows ADR-0006: domain logic → plugin; the MCP substrate stays
+    // in core.
+    //
+    // Gating on runtime.options.mcp inside onLoaded matches the Express
+    // pattern (gating on runtime.options.app for route mounts) — same
+    // shape, no special wrapper. The check happens once per boot.
+    onLoaded(() => {
+        if (!runtime.options.mcp) return
+        const mcp = runtime.options.mcp
+        mcp.simpleTool(
+            'mikser_inspect_layout',
+            'Inspect a layout: template source, variables it references, the postprocessor it produces, and sample entities currently using it. Use this to answer "what data does this layout need?" 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_list_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 }) => {
+                const logger = useLogger()
+                try {
+                    const layout = await findEntity({ id })
+                    if (!layout || layout.collection !== collection) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: `Layout not found: ${id}` }],
+                        }
+                    }
+
+                    let template = ''
+                    try {
+                        template = await readFile(layout.uri, 'utf8')
+                    } catch (err) {
+                        return {
+                            isError: true,
+                            content: [{
+                                type: 'text',
+                                text: `Layout entity exists but template file unreadable (${layout.uri}): ${err.message}`,
+                            }],
+                        }
+                    }
+
+                    const references = parseTemplateReferences(template)
+
+                    let sampleEntities = []
+                    if (samples > 0) {
+                        const all = await findEntities()
+                        sampleEntities = all
+                            .filter(e => e.meta?.layout === layout.name)
+                            .slice(0, samples)
+                            .map(e => ({ id: e.id, name: e.name, meta: e.meta }))
+                    }
+
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                layout: {
+                                    id: layout.id,
+                                    name: layout.name,
+                                    uri: layout.uri,
+                                    format: layout.format,
+                                    template: layout.template,
+                                    postprocessor: layout.postprocessor ?? null,
+                                },
+                                templateSource: template,
+                                references,
+                                samples: sampleEntities,
+                                notes: [
+                                    'references.variables is a naive regex pass across liquid/handlebars/eta — false positives possible, but covers the common `{{ document.meta.X }}` and `<%= entity.X %>` patterns.',
+                                    'samples only includes entities with explicit meta.layout. Auto-matched layouts are not listed; use mikser_list_entities with a filename-pattern filter for those.',
+                                ],
+                            }, null, 2),
+                        }],
+                    }
+                } catch (err) {
+                    logger.error('MCP mikser_inspect_layout error: %s', err.message)
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text: err.message }],
+                    }
+                }
+            },
+        )
+        const logger = useLogger()
+        logger.info('MCP tool registered: mikser_inspect_layout (layouts plugin)')
+    })
+
     return {
         collection,
         type

package/src/plugins/preview.js

@@ -0,0 +1,206 @@
+// Preview plugin. Owns the "render an entity transiently and surface
+// the bytes at a clickable URL" workflow. Three responsibilities:
+//
+//   1. An in-memory cache (Map<filename, { bytes, mime, expiresAt, size }>)
+//      with LRU eviction past a configurable byte cap.
+//   2. An Express GET /preview/:filename route that serves cache entries.
+//   3. The mikser_preview MCP tool, registered on the substrate when
+//      --mcp is active.
+//
+// Lives outside the api plugin because preview is not a REST catalog
+// concern — it's a render-and-cache workflow whose lifetime is the
+// process, not the catalog. Lives outside core because it's domain
+// (a workflow), not transport substrate. Per ADR-0006: plugin.
+//
+// Composes independently: needs `runtime.options.app` (any Express
+// app — engine-supplied or external) and `useRenderer` (a core helper).
+// Does NOT need the api plugin. Loading just `preview` + `mcp` is
+// a valid combination for AI-driven workflows that skip the REST API.
+//
+// Library-mode surface: this plugin exposes
+//   runtime.options.preview = { store, get, stats }
+// so any plugin or programmatic caller can stash bytes and get a URL
+// back without going through MCP. The mikser_preview tool is a thin
+// wrapper over this surface.
+
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { z } from 'zod'
+import { useRenderer } from '../api.js'
+import { mimeForEntity } from './api.js'
+
+export default ({
+    runtime,
+    onLoaded,
+    useLogger,
+}) => {
+    // Factory-scope cache. One per engine instance. Module-scope would
+    // share across multiple engines in the same Node process, which is
+    // a scenario mikser doesn't really support.
+    const previews = new Map()   // filename → { bytes, mime, expiresAt, size }
+    let bytesInUse = 0
+
+    // Config knobs with sensible defaults. The defaults match the
+    // values 7.2.x shipped under the api plugin so existing callers
+    // see no change in behavior — just a different plugin owner.
+    const config = () => ({
+        maxBytes:    runtime.config.preview?.maxBytes    ?? (100 * 1024 * 1024),
+        defaultTtl:  runtime.config.preview?.defaultTtl  ?? 600,
+        ttlMin:      runtime.config.preview?.ttlMin      ?? 30,
+        ttlMax:      runtime.config.preview?.ttlMax      ?? 3600,
+        path:        runtime.config.preview?.path        ?? '/preview',
+    })
+
+    // Three primitives the rest of the plugin (and library-mode
+    // callers) build on: store(), get(), stats(). All operate against
+    // the closed-over `previews` Map and `bytesInUse` counter.
+    function store({ filename, bytes, mime, ttlMs }) {
+        const size = Buffer.isBuffer(bytes) ? bytes.length : Buffer.byteLength(bytes)
+        const cfg = config()
+        // LRU evict until there's room. JS Map preserves insertion
+        // order — `keys().next().value` is the oldest entry.
+        while (bytesInUse + size > cfg.maxBytes && previews.size > 0) {
+            const oldestKey = previews.keys().next().value
+            const oldest = previews.get(oldestKey)
+            bytesInUse -= oldest.size
+            previews.delete(oldestKey)
+        }
+        previews.set(filename, { bytes, mime, expiresAt: Date.now() + ttlMs, size })
+        bytesInUse += size
+        return { filename, size, expiresAt: Date.now() + ttlMs }
+    }
+
+    function get(filename) {
+        const entry = previews.get(filename)
+        if (!entry) return null
+        if (entry.expiresAt < Date.now()) {
+            bytesInUse -= entry.size
+            previews.delete(filename)
+            return null
+        }
+        // Touch — move to tail for LRU recency.
+        previews.delete(filename)
+        previews.set(filename, entry)
+        return entry
+    }
+
+    function stats() {
+        return {
+            count: previews.size,
+            bytesInUse,
+            maxBytes: config().maxBytes,
+            utilization: bytesInUse / config().maxBytes,
+        }
+    }
+
+    // Expose the cache surface at runtime.options.preview so other
+    // plugins / library callers can use it without going through MCP.
+    // Done at factory-eval time (before any onLoaded fires) so a
+    // later plugin's onLoad / onLoaded can already see it.
+    runtime.options.preview = { store, get, stats }
+
+    // HTTP route: served regardless of whether MCP is on, so previews
+    // are also reachable from library-mode callers that stored bytes
+    // via runtime.options.preview.store() directly.
+    onLoaded(async () => {
+        const logger = useLogger()
+        const app = runtime.options.app
+        if (!app) {
+            // No HTTP app means previews can still be stored
+            // programmatically but the URL won't be reachable. That's
+            // a valid configuration for batch / one-shot uses; we
+            // just don't mount the route.
+            logger.debug('Preview plugin: no runtime.options.app — cache available, route not mounted')
+            return
+        }
+
+        const cfg = config()
+        const routePath = `${cfg.path.replace(/\/$/, '')}/:filename`
+        app.get(routePath, (req, res) => {
+            const entry = get(req.params.filename)
+            if (!entry) {
+                res.status(404).type('text/plain').send('Preview expired or not found')
+                return
+            }
+            res.type(entry.mime).send(entry.bytes)
+        })
+        logger.info('Preview route mounted: %s (cache cap: %d MB)', cfg.path, Math.round(cfg.maxBytes / 1024 / 1024))
+    })
+
+    // Gating on runtime.options.mcp inside onLoaded matches the route-
+    // mount pattern above. Same shape as `if (!app)`: check the flag
+    // in the hook, register if present. No special wrapper needed.
+    onLoaded(() => {
+        if (!runtime.options.mcp) return
+        const mcp = runtime.options.mcp
+        const { render: previewRender } = useRenderer(runtime, {
+            defaultTimeout: runtime.config.preview?.renderTimeout ?? 30_000,
+        })
+
+        mcp.simpleTool(
+            'mikser_preview',
+            'Render an entity through the engine pipeline AND surface the FINAL output as a clickable URL served by the running --server. Use this instead of mikser_render when the user needs to see the result in a browser. The URL serves the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Requires --server. Previews live in memory (not on disk, never under outputFolder) and auto-expire — default 10 minutes, clamped 30..3600 seconds.',
+            {
+                entity:  z.record(z.any()).describe('Entity shape with at least { id, collection } and any meta/content the renderer needs. Same shape as mikser_render.'),
+                options: z.record(z.any()).optional().describe('Renderer options. Same as mikser_render, plus { expiresInSeconds: number = 600 } controlling preview TTL.'),
+            },
+            async ({ entity = {}, options = {} }) => {
+                const logger = useLogger()
+                const ok = (data) => ({
+                    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+                })
+                const fail = (msg) => ({
+                    isError: true,
+                    content: [{ type: 'text', text: msg }],
+                })
+
+                try {
+                    if (!runtime.options.port) {
+                        return fail('mikser_preview requires --server to be running so the preview URL is reachable. Use mikser_render to get raw bytes inline instead.')
+                    }
+
+                    const { expiresInSeconds = config().defaultTtl, ...renderOptions } = options ?? {}
+                    const { output, entity: rendered } = await previewRender(entity, {
+                        ...renderOptions,
+                        save: false,
+                        catalog: false,
+                    })
+                    const result = output?.result
+                    if (result == null) {
+                        return fail('Render produced no output. Check that the entity has a resolvable layout and the layout matched a registered renderer.')
+                    }
+
+                    const destExt = path.extname(rendered.destination || '').slice(1)
+                    const ext = destExt || 'html'
+                    const filename = `${randomUUID()}.${ext}`
+                    const mime = mimeForEntity(rendered) ?? 'application/octet-stream'
+                    const cfg = config()
+                    const ttlSec = Math.max(cfg.ttlMin, Math.min(cfg.ttlMax, expiresInSeconds))
+
+                    store({ filename, bytes: result, mime, ttlMs: ttlSec * 1000 })
+
+                    const url = `http://localhost:${runtime.options.port}${cfg.path}/${filename}`
+                    const bytes = Buffer.isBuffer(result) ? result.length : Buffer.byteLength(result)
+
+                    logger.info('MCP mikser_preview cached %s (%d bytes, ttl %ds): %s', filename, bytes, ttlSec, url)
+
+                    return ok({
+                        previewUrl: url,
+                        mimeType: mime,
+                        bytes,
+                        expiresInSeconds: ttlSec,
+                        instructions: 'Open previewUrl in a browser to view. The preview lives in mikser memory and auto-expires after expiresInSeconds — re-run mikser_preview to refresh.',
+                    })
+                } catch (err) {
+                    logger.error('MCP mikser_preview error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+        )
+
+        const logger = useLogger()
+        logger.info('MCP tool registered: mikser_preview (preview plugin)')
+    })
+
+    return { name: 'preview' }
+}