mikser-io 6.21.4 → 6.23.0

package/README.md

@@ -4,7 +4,23 @@
 
 # Mikser
 
-Mikser is a content engine for Node.js built around a strict lifecycle, a composable plugin system, and direct control over every output. Every document, asset, and template flows through the same deterministic pipeline. Plugins hook in at any phase; nothing runs outside the cycle. It scales from a single markdown blog to a multi-language, multi-format publishing platform — and stays predictable in both directions.
+**Mikser is the content layer of your application.** Business logic, user accounts, transactions live in their own services; mikser handles the parts that *are* content — pages, docs, the published catalog, multi-format outputs. The SDKs are the seam between them.
+
+Built for Node.js around a strict lifecycle, a composable plugin system, and direct control over every output. Every document, asset, and template flows through the same deterministic pipeline. Plugins hook in at any phase; nothing runs outside the cycle. It scales from a single markdown blog to a multi-language, multi-format publishing platform — and stays predictable in both directions.
+
+## Where it fits
+
+Mikser is a focused component, not a backend. Think of it like a database in your stack: defined surface, content-shaped responsibilities, the app code lives separately and reaches in through a small typed interface.
+
+| | Strapi / Payload / Sanity / Contentful | Mikser as content layer |
+|---|---|---|
+| **Role** | "Be the backend" — content + relationships + sometimes business logic | One component of the app, specifically the content piece |
+| **Boundary** | Soft — they invite business logic into the CMS (computed fields, hooks, workflows) | Hard — files in, rendered output out; business logic isn't here |
+| **Coupling** | App tied to the CMS vendor | App owns business logic independently; the content source can be swapped |
+| **Storage** | Vendor's database, vendor's schema | Plain `.md` / `.yml` files on disk — diffable, portable, takeable on day one and year ten |
+| **Migration risk** | High when the vendor reinvents itself (Strapi v3→v4, etc.) | Content is files, business logic is yours — neither is exposed to the other's churn |
+
+Build mikser into the parts of your application that are content-shaped. Keep the rest where it belongs.
 
 ## Why mikser
 
@@ -14,7 +30,7 @@ Mikser is a content engine for Node.js built around a strict lifecycle, a compos
 
 **Concurrent rendering.** Renders fan out across a worker pool that keeps every CPU core hot. Multi-format outputs (HTML, PDF, MJML email, etc.) generate in parallel from the same source.
 
-**One lifecycle, everything composes.** Plugins hook into 20+ named lifecycle phases. A search-indexing plugin shares the same journal iteration as a CMS plugin and an email-rendering plugin — no glue code, no orchestration layer.
+**One lifecycle, everything composes.** Plugins hook into 20+ named lifecycle phases. A search-indexing plugin shares the same journal iteration as an email-rendering plugin and a PDF-postprocessing plugin — no glue code, no orchestration layer. The engine doesn't know which plugins are loaded; plugins don't have to know about each other.
 
 **Run anywhere.** The same CLI handles one-shot builds, watch-mode dev loops, and a long-running HTTP server with a shared Express app. `npx mikser` ships a static site; `mikser --watch` is the dev loop; `mikser --server` exposes a live admin/API.
 
@@ -22,9 +38,27 @@ Mikser is a content engine for Node.js built around a strict lifecycle, a compos
 
 **Open source.** MIT-licensed, on GitHub, no telemetry, no auth wall, no SaaS dependency. What you see is what runs.
 
-## Plugin ecosystem
+## Built for AI-assisted development
+
+Files-as-source isn't just a portability story — it makes the project unusually friendly to AI coding agents. Most setups lose time configuring an agent's access to the data: tokens, schemas, MCP servers, sandboxed query environments. Mikser sidesteps all of it because the content is text files the agent can already read with the tools it already has.
+
+**Zero infra friction for discovery.** An agent can `rg "type: product"` across the content tree to find every product doc in a second. No DB connection, no API token, no schema file to parse.
+
+**The schema emerges from examples, not a definition file.** Front-matter shows what fields exist *in the docs that exist*. Markdown + YAML are overwhelmingly well-represented in AI training data, so the model "speaks" them fluently and infers structure from real documents better than from a schema definition.
 
-Plugins are independent npm packages — install only what a project actually uses.
+**Determinism shortens the iteration loop.** Save a file → watcher fires → predictable rebuild. No DB triggers, no surprise cache invalidation, no API quotas. The agent's mental model of "what happens next" can be precise instead of probabilistic.
+
+**The SDK's `.d.ts` is the read-side contract.** When the agent writes frontend query code, the operator subset and envelope shape are right there in types — a step-change for code generation quality versus "go read the REST API docs."
+
+**Plugin-by-example.** Authoring a new plugin? There are 15+ existing ones in the same shape to pattern-match against. Convention is dense enough that new plugins look like the old ones without coaching.
+
+The honest caveat: this advantage is real on **content-shaped work** — adding pages, restructuring collections, generating new layouts, building frontends. It doesn't make mikser better for non-content tasks (concurrency bugs in the worker pool, database tuning elsewhere in your stack); those are plain Node debugging like anywhere else. The visibility advantage also degrades past ~10k documents — at that scale the agent queries via the SDK instead of grepping the tree, which is still good but less "see everything at once."
+
+## Plugins on top of the engine
+
+The engine is what stays stable — the lifecycle, the catalog, the file-based content model. Plugins are independent npm packages sitting on the plugin API: some are essential to the SSG workflow, some give external systems HTTP access to the catalog, some are integrations that earn their keep on real projects, and some are probes that test how far the lifecycle stretches without touching the core. Install what a project needs; drop what it doesn't.
+
+**Core — sources, layouts, renderers, postprocessors:**
 
 | Plugin | What it does |
 |---|---|
@@ -34,12 +68,38 @@ Plugins are independent npm packages — install only what a project actually us
 | `render-resource`, `render-asset`, `render-href` | Resource / asset / link rewriting at render time |
 | `post-pdf` | HTML → PDF via headless Chromium |
 | `post-mjml` | MJML email markup → inbox-safe HTML |
-| `data` | JSON snapshots of entities / context / catalog over HTTP |
-| `api` | REST endpoints — list / get / create / update / delete / render |
+
+**HTTP access to the catalog:**
+
+| Plugin | What it does |
+|---|---|
+| `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 |
+
+**Integrations:**
+
+| Plugin | What it does |
+|---|---|
 | `vector` | OpenAI embeddings + semantic search (sqlite-vec or pgvector) |
-| `decap` | [Decap CMS](https://decapcms.org/) mounted in the same process |
 | `archive`, `mapper`, `live`, `aml` | Specialty integrations |
 
+**Integration probes** — wrap a substantial external project as a plugin to confirm the lifecycle is open enough to host it without core changes. Treat these as feasibility evidence, not as a statement about where mikser is heading:
+
+| Plugin | What it does |
+|---|---|
+| `decap` | Mounts [Decap CMS](https://decapcms.org/) inside the same Express server — admin UI + local proxy backend + bake-to-`out/` for static deploys (~150 lines, zero engine changes) |
+
+## Client SDKs
+
+The `api` and `vector` plugins are paired with small client-side SDKs so a frontend (or another Node app) can talk to a running mikser server without rolling its own `fetch` glue. Zero dependencies, runs in browsers / Node 18+ / Deno / Bun / Workers.
+
+| Package | For the plugin | What you get |
+|---|---|---|
+| [`mikser-io-sdk-api`](https://github.com/almero-digital-marketing/mikser-io-sdk-api) | `api` | `entities(name).list / query / urlFor / pages / update / delete / render` — Mongo-style filter operators backed by sift, sort, projection, pagination |
+| [`mikser-io-sdk-vector`](https://github.com/almero-digital-marketing/mikser-io-sdk-vector) | `vector` | `vector(storeName).findSimilar(text, { limit })` — semantic search hits with the original mapped object attached |
+
+Each SDK ships TypeScript declarations so client projects get autocomplete on filters, envelopes, and the `MikserError` thrown on non-2xx responses. Install only the one(s) a project needs.
+
 ## Quick Start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "6.21.4",
+	"version": "6.23.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {
@@ -46,6 +46,7 @@
 		"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"

package/src/engine.js

@@ -47,6 +47,8 @@ export async function setup(options) {
             .option('-t --trace', 'display trace statements')
             .option('-e --runtime-folder <folder>', 'set mikser runtime folder relative to working folder', 'runtime')
             .option('-s --server [port]', 'start an Express server on the given port (defaults to 3001)')
+            .option('--cors [origin]', 'restrict server CORS to a specific origin (default *)')
+            .option('--no-cors', 'disable server CORS headers')
 
         Object.assign(runtime.options, options || runtime.engine.commander.parse(process.argv).opts())
         runtime.options.info = true
@@ -117,6 +119,32 @@ export async function setup(options) {
                 ? 3001
                 : Number(runtime.options.server) || 3001
             logger.info('Server starting on port %d', runtime.options.port)
+
+            // CORS — a server exists to be fetched, and in dev the
+            // frontend is almost always on a different origin (a dev
+            // server on another port, a separate domain). So CORS is ON
+            // by default with Access-Control-Allow-Origin: *. The token
+            // on /api (not CORS) is what gates mutations, and '*' can't
+            // carry credentials, so this is low-risk. Pin it down with
+            // --cors <origin> / config.server.cors, or disable entirely
+            // with --no-cors / config.server.cors:false (recommended for
+            // private/admin deployments). Mounted first so it covers
+            // static routes and every plugin router.
+            // Default on (?? true) so programmatic setup({ server }) —
+            // which bypasses commander's --no-cors default — matches the
+            // CLI. Explicit false (config or --no-cors) still disables.
+            const corsOrigin = runtime.config.server?.cors ?? runtime.options.cors ?? true
+            if (corsOrigin) {
+                const origin = corsOrigin === true ? '*' : String(corsOrigin)
+                runtime.options.app.use((req, res, next) => {
+                    res.header('Access-Control-Allow-Origin', origin)
+                    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
+                    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+                    if (req.method === 'OPTIONS') return res.sendStatus(204)
+                    next()
+                })
+                logger.info('CORS enabled: %s', origin)
+            }
         }
     })
 

package/src/plugins/api.js

@@ -1,7 +1,123 @@
 import path from 'node:path'
 import { access } from 'node:fs/promises'
+import _ from 'lodash'
+import sift from 'sift'
 import { useRenderer, useCollection } from '../api.js'
 
+// Mongo-style operators recognised in URL query params as `<path>.$<op>=...`.
+// $in / $nin take comma-separated values; $exists takes a truthy/falsy
+// string; everything else coerces the value (numbers, booleans, null) and
+// hands it to sift. Anything sift accepts works on the POST body path too.
+const QUERY_OPS = new Set([
+    'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'exists', 'regex',
+])
+
+function coerceScalar(v) {
+    if (typeof v !== 'string') return v
+    if (v === 'true') return true
+    if (v === 'false') return false
+    if (v === 'null') return null
+    if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v)
+    return v
+}
+
+function coerceForOp(value, op) {
+    if (op === 'in' || op === 'nin') {
+        return String(value).split(',').map(s => coerceScalar(s.trim()))
+    }
+    if (op === 'exists') return value === 'true' || value === '1'
+    if (op === 'regex') return String(value)
+    return coerceScalar(value)
+}
+
+// "name,-date" → { name: 1, date: -1 }
+function parseSortString(spec) {
+    const sort = {}
+    if (!spec) return sort
+    for (const raw of String(spec).split(',')) {
+        const t = raw.trim()
+        if (!t) continue
+        if (t.startsWith('-')) sort[t.slice(1)] = -1
+        else sort[t.replace(/^\+/, '')] = 1
+    }
+    return sort
+}
+
+// "id,meta.title" → ['id', 'meta.title']
+function parseFieldsString(spec) {
+    if (!spec) return null
+    return String(spec).split(',').map(s => s.trim()).filter(Boolean)
+}
+
+// Reserved query-string keys that aren't filter fields.
+const RESERVED = new Set(['page', 'limit', 'skip', 'sort', 'fields'])
+
+function parseQueryString(params) {
+    const filter = {}
+    let page = 1, limit, skip, sort, fields
+    for (const [key, raw] of Object.entries(params)) {
+        if (key === 'page')   { page = Math.max(1, parseInt(raw) || 1); continue }
+        if (key === 'limit')  { limit = parseInt(raw); continue }
+        if (key === 'skip')   { skip = parseInt(raw); continue }
+        if (key === 'sort')   { sort = parseSortString(raw); continue }
+        if (key === 'fields') { fields = parseFieldsString(raw); continue }
+
+        // <path>.$<op>=... groups under the same dotted-path key so
+        // multiple operators on one field compose:
+        // meta.price.$gt=10&meta.price.$lt=50 → { 'meta.price': { $gt:10, $lt:50 } }
+        // We use dotted keys (Mongo-style) rather than nested objects so
+        // sift treats them as path matchers, not deep-equality.
+        const m = key.match(/^(.+)\.\$([a-zA-Z]+)$/)
+        if (m && QUERY_OPS.has(m[2])) {
+            const [, fieldPath, op] = m
+            const ops = (filter[fieldPath] && typeof filter[fieldPath] === 'object' && !Array.isArray(filter[fieldPath]))
+                ? filter[fieldPath]
+                : {}
+            ops[`$${op}`] = coerceForOp(raw, op)
+            filter[fieldPath] = ops
+        } else {
+            filter[key] = coerceScalar(raw)
+        }
+    }
+    return { filter, page, limit, skip, sort, fields }
+}
+
+// Apply filter → endpoint scope → sort → skip/limit → projection.
+// `findEntities()` returns the live in-memory catalog; for ≤100k docs the
+// per-request scan is plenty fast. Backing this with an index becomes
+// interesting past that — same endpoint contract.
+async function runQuery({ filter, sort, fields, skip, limit, scope, findEntities }) {
+    let all = await findEntities()
+    if (scope) all = all.filter(scope)
+
+    if (filter && Object.keys(filter).length) {
+        const match = sift(filter)
+        all = all.filter(match)
+    }
+
+    const total = all.length
+
+    if (sort && Object.keys(sort).length) {
+        const entries = Object.entries(sort)
+        all.sort((a, b) => {
+            for (const [key, dir] of entries) {
+                const av = _.get(a, key)
+                const bv = _.get(b, key)
+                if (av == null && bv == null) continue
+                if (av == null) return 1
+                if (bv == null) return -1
+                if (av < bv) return -dir
+                if (av > bv) return dir
+            }
+            return 0
+        })
+    }
+
+    let items = all.slice(skip, skip + limit)
+    if (fields?.length) items = items.map(e => _.pick(e, fields))
+    return { items, total }
+}
+
 // MIME type lookup used when streaming a postprocessor's output back over
 // HTTP. The renderer's output extension lives on entity.destination
 // (assigned by the layouts plugin), so we use it as the source of truth.
@@ -64,11 +180,36 @@ export async function sendRenderOutput(res, output, entity) {
     return res.json(result)
 }
 
+// Subscription bookkeeping shared across all endpoints. Each entry holds
+// the live Express response, the compiled sift filter, the endpoint
+// scope, and a heartbeat timer. Per-cycle the onFinalized hook iterates
+// the journal and dispatches matching changes to every subscription.
+const subscriptions = new Map()
+let subscriptionCounter = 0
+
+function sseInit(res) {
+    res.setHeader('Content-Type', 'text/event-stream')
+    res.setHeader('Cache-Control', 'no-cache, no-transform')
+    res.setHeader('Connection', 'keep-alive')
+    res.setHeader('X-Accel-Buffering', 'no')  // disable nginx buffering
+    if (typeof res.flushHeaders === 'function') res.flushHeaders()
+}
+
+function sseSend(res, eventName, payload) {
+    try {
+        res.write(`event: ${eventName}\n`)
+        res.write(`data: ${JSON.stringify(payload)}\n\n`)
+    } catch { /* connection dropped — cleanup runs via 'close' */ }
+}
+
 export default ({
     runtime,
     onLoaded,
+    onFinalize,
     useLogger,
+    useJournal,
     findEntities,
+    constants: { OPERATION },
 }) => {
     onLoaded(async () => {
         const logger = useLogger()
@@ -86,99 +227,251 @@ export default ({
             )
         }
 
+        const endpoints = runtime.config.api?.endpoints
+        if (!endpoints || !Object.keys(endpoints).length) {
+            logger.warn('Api plugin loaded but no endpoints configured (api.endpoints) — nothing to mount')
+            return
+        }
+
         const { default: express } = await import('express').catch(() => {
             throw new Error('Express is required for the api plugin — run: npm install express')
         })
 
-        const router = express.Router()
-        router.use(express.json())
+        const base = runtime.config.api?.base ?? '/api'
+        const globalPageSize = runtime.config.api?.pageSize ?? 10
+        const globalRenderTimeout = runtime.config.api?.renderTimeout ?? 30_000
 
-        const token = runtime.config.api?.token
-        const auth = (req, res, next) => {
-            if (!token) return next()
-            if (req.headers.authorization === `Bearer ${token}`) return next()
-            res.status(401).json({ error: 'Unauthorized' })
-        }
+        // The plugin mirrors the vector / data plugin shape: a named map
+        // of endpoints, each with its own optional `token`, `query`
+        // scope, allowed `operations`, and overrides for pageSize /
+        // renderTimeout. Each endpoint mounts under <base>/<name>.
+        //
+        //   api.endpoints.public  { query: e => e.meta?.published, operations: ['list'] }
+        //   api.endpoints.admin   { token: '...', operations: ['list','update','delete','render'] }
+        for (const [name, ep] of Object.entries(endpoints)) {
+            const router = express.Router()
+            router.use(express.json())
 
-        // Reuse the transport-agnostic primitives from src/api.js so the
-        // library entry point and the Api endpoints share the exact same
-        // batching/timeouts/error semantics.
-        const { render } = useRenderer(runtime, {
-            defaultTimeout: runtime.config.api?.renderTimeout ?? 30_000,
-        })
+            // Operations default to the safer shape when no token is set
+            // (read-only) and full access when token-gated. `subscribe`
+            // holds an open SSE connection per client — opt in for
+            // public endpoints; included in the token-gated default
+            // because tokens already gate the trust. Explicit
+            // `operations` always wins.
+            const defaultOps = ep.token
+                ? ['list', 'update', 'delete', 'render', 'subscribe']
+                : ['list']
+            const allowedOps = new Set(ep.operations ?? defaultOps)
 
-        router.get('/entities', async (req, res) => {
-            try {
-                const { page: rawPage, limit: rawLimit, ...filter } = req.query
-                const page = Math.max(1, parseInt(rawPage) || 1)
-                const limit = Math.min(100, Math.max(1, parseInt(rawLimit) || (runtime.config.api?.pageSize ?? 10)))
-                const query = Object.keys(filter).length ? filter : undefined
-
-                const all = await findEntities(query)
-                const total = all.length
-                const totalPages = Math.ceil(total / limit)
-                const items = all.slice((page - 1) * limit, page * limit)
-
-                res.json({
-                    items,
-                    page,
-                    limit,
-                    total,
-                    totalPages,
-                    hasNext: page < totalPages,
-                    hasPrev: page > 1,
-                })
-            } catch (err) {
-                logger.error('Api list error: %s', err.message)
-                res.status(500).json({ error: err.message })
-            }
-        })
+            const query = typeof ep.query === 'function' ? ep.query : null
+            const pageSize = ep.pageSize ?? globalPageSize
+            const renderTimeout = ep.renderTimeout ?? globalRenderTimeout
 
-        router.put('/entities', auth, async (req, res) => {
-            try {
-                const { collection, relativePath, content = '' } = req.body
-                await useCollection(runtime, collection).write(relativePath, content)
-                res.status(202).json({ ok: true })
-            } catch (err) {
-                logger.error('Api update error: %s', err.message)
-                res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
+            const auth = (req, res, next) => {
+                if (!ep.token) return next()
+                if (req.headers.authorization === `Bearer ${ep.token}`) return next()
+                res.status(401).json({ error: 'Unauthorized' })
             }
-        })
 
-        router.delete('/entities', auth, async (req, res) => {
-            try {
-                const { collection, relativePath } = req.body
-                await useCollection(runtime, collection).remove(relativePath)
-                res.status(202).json({ ok: true })
-            } catch (err) {
-                logger.error('Api delete error: %s', err.message)
-                res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
+            const allow = (op) => (req, res, next) => {
+                if (!allowedOps.has(op)) {
+                    return res.status(403).json({
+                        error: `Operation '${op}' is not allowed on endpoint '${name}'`,
+                    })
+                }
+                next()
             }
-        })
 
-        router.post('/render', auth, async (req, res) => {
-            try {
-                // Body shape mirrors the JS API: entity fields at top
-                // level, control flags grouped under `options`. Forwarded
-                // straight to render(entity, options). Defaults match
-                // mikser's lifecycle (save and keep the catalog row);
-                // strict opt-outs via the literal `false`:
-                //   options.catalog: false → prune the catalog row
-                //   options.save:    false → skip the final disk write
-                //                            (bytes still in the response)
-                const { options = {}, ...entityShape } = req.body
-                const { output, entity } = await render(entityShape, options)
-                await sendRenderOutput(res, output, entity)
-            } catch (err) {
-                logger.error('Api render error: %s', err.message)
-                if (!res.headersSent) {
+            // Reuse the transport-agnostic primitives from src/api.js so
+            // the library entry point and the HTTP endpoints share the
+            // exact same batching/timeouts/error semantics. One renderer
+            // per endpoint so per-endpoint renderTimeout overrides land.
+            const { render } = useRenderer(runtime, { defaultTimeout: renderTimeout })
+
+            router.get('/entities', allow('list'), auth, async (req, res) => {
+                try {
+                    const parsed = parseQueryString(req.query)
+                    const limit = Math.min(100, Math.max(1, parsed.limit ?? pageSize))
+                    const skip = parsed.skip ?? (parsed.page - 1) * limit
+
+                    const { items, total } = await runQuery({
+                        filter: parsed.filter,
+                        sort: parsed.sort,
+                        fields: parsed.fields,
+                        skip,
+                        limit,
+                        scope: query,
+                        findEntities,
+                    })
+
+                    const page = Math.floor(skip / limit) + 1
+                    const totalPages = Math.ceil(total / limit) || 1
+                    res.json({
+                        items, page, limit, total, totalPages,
+                        hasNext: skip + limit < total,
+                        hasPrev: skip > 0,
+                    })
+                } catch (err) {
+                    logger.error('Api[%s] list error: %s', name, err.message)
                     res.status(500).json({ error: err.message })
                 }
-            }
-        })
+            })
 
-        const base = runtime.config.api?.base ?? '/api'
-        app.use(base, router)
-        logger.info('Api mounted: %s', base)
+            // POST /entities/query — body-based query for anything that
+            // doesn't fit cleanly in a URL: $and/$or, nested operators,
+            // regex, projections, etc. Same shape as a Mongo find.
+            router.post('/entities/query', allow('list'), auth, async (req, res) => {
+                try {
+                    const { filter = {}, sort, fields, page: rawPage = 1, limit: rawLimit, skip: rawSkip } = req.body ?? {}
+                    const limit = Math.min(100, Math.max(1, rawLimit ?? pageSize))
+                    const skip = rawSkip ?? (Math.max(1, parseInt(rawPage) || 1) - 1) * limit
+
+                    const { items, total } = await runQuery({
+                        filter, sort, fields, skip, limit,
+                        scope: query,
+                        findEntities,
+                    })
+
+                    const page = Math.floor(skip / limit) + 1
+                    const totalPages = Math.ceil(total / limit) || 1
+                    res.json({
+                        items, page, limit, total, totalPages,
+                        hasNext: skip + limit < total,
+                        hasPrev: skip > 0,
+                    })
+                } catch (err) {
+                    logger.error('Api[%s] query error: %s', name, err.message)
+                    res.status(500).json({ error: err.message })
+                }
+            })
+
+            // GET /entities/subscribe — open an SSE stream. Each subsequent
+            // process cycle (file-watcher fired OR programmatic API write)
+            // emits create/update/delete events for entities matching the
+            // subscription's filter and the endpoint's scope. Heartbeats
+            // every 25s keep proxies happy. Connection close cleans up.
+            router.get('/entities/subscribe', allow('subscribe'), auth, (req, res) => {
+                let filterFn = null
+                try {
+                    const parsed = parseQueryString(req.query)
+                    if (Object.keys(parsed.filter).length) filterFn = sift(parsed.filter)
+                } catch (err) {
+                    return res.status(400).json({ error: `Invalid filter: ${err.message}` })
+                }
+
+                sseInit(res)
+                const subscriptionId = `sub_${Date.now()}_${++subscriptionCounter}`
+                sseSend(res, 'init', { subscriptionId, endpoint: name })
+
+                // Heartbeat — silent enough to not confuse the SDK but
+                // frequent enough that idle proxies don't kill the
+                // connection.
+                const heartbeat = setInterval(() => sseSend(res, 'heartbeat', {}), 25_000)
+                if (typeof heartbeat.unref === 'function') heartbeat.unref()
+
+                subscriptions.set(subscriptionId, {
+                    endpointName: name,
+                    scope: query,
+                    filter: filterFn,
+                    res,
+                })
+
+                req.on('close', () => {
+                    clearInterval(heartbeat)
+                    subscriptions.delete(subscriptionId)
+                    logger.debug('Api[%s] subscription closed: %s', name, subscriptionId)
+                })
+
+                logger.debug('Api[%s] subscription opened: %s', name, subscriptionId)
+            })
+
+            router.put('/entities', allow('update'), auth, async (req, res) => {
+                try {
+                    const { collection, relativePath, content = '' } = req.body
+                    await useCollection(runtime, collection).write(relativePath, content)
+                    res.status(202).json({ ok: true })
+                } catch (err) {
+                    logger.error('Api[%s] update error: %s', name, err.message)
+                    res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
+                }
+            })
+
+            router.delete('/entities', allow('delete'), auth, async (req, res) => {
+                try {
+                    const { collection, relativePath } = req.body
+                    await useCollection(runtime, collection).remove(relativePath)
+                    res.status(202).json({ ok: true })
+                } catch (err) {
+                    logger.error('Api[%s] delete error: %s', name, err.message)
+                    res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
+                }
+            })
+
+            router.post('/render', allow('render'), auth, async (req, res) => {
+                try {
+                    // Body shape mirrors the JS API: entity fields at top
+                    // level, control flags grouped under `options`. Forwarded
+                    // straight to render(entity, options). Defaults match
+                    // mikser's lifecycle (save and keep the catalog row);
+                    // strict opt-outs via the literal `false`:
+                    //   options.catalog: false → prune the catalog row
+                    //   options.save:    false → skip the final disk write
+                    //                            (bytes still in the response)
+                    const { options = {}, ...entityShape } = req.body
+                    // When the endpoint declares a scope, reject anything
+                    // outside it BEFORE pushing through the renderer.
+                    if (query && !query(entityShape)) {
+                        return res.status(403).json({ error: 'Entity is outside this endpoint\'s scope' })
+                    }
+                    const { output, entity } = await render(entityShape, options)
+                    await sendRenderOutput(res, output, entity)
+                } catch (err) {
+                    logger.error('Api[%s] render error: %s', name, err.message)
+                    if (!res.headersSent) {
+                        res.status(500).json({ error: err.message })
+                    }
+                }
+            })
+
+            app.use(`${base}/${name}`, router)
+            logger.info('Api endpoint mounted: %s/%s (ops=[%s] %s)',
+                base, name, [...allowedOps].join(','),
+                ep.token ? '[token]' : '[public]')
+        }
+    })
+
+    // Dispatcher: once per lifecycle cycle, walk the journal and push
+    // matching CREATE/UPDATE/DELETE events to every active subscription
+    // (regardless of which endpoint opened it). Each subscription has
+    // its own scope + filter; we apply both before sending. Empty when
+    // nothing's subscribed, so it costs ~nothing in normal builds.
+    //
+    // Hook onFinalize, NOT onFinalized — journal.js registers its own
+    // clearJournal callback on onFinalized at module load, which runs
+    // before plugin onFinalized hooks. By Finalize we still have the
+    // cycle's journal entries; by Finalized they're already gone.
+    onFinalize(async (signal) => {
+        if (!subscriptions.size) return
+        const logger = useLogger()
+        const evMap = {
+            [OPERATION.CREATE]: 'create',
+            [OPERATION.UPDATE]: 'update',
+            [OPERATION.DELETE]: 'delete',
+        }
+        for await (const { operation, entity } of useJournal(
+            'Api subscriptions',
+            [OPERATION.CREATE, OPERATION.UPDATE, OPERATION.DELETE],
+            signal,
+        )) {
+            for (const [subId, sub] of subscriptions) {
+                if (sub.scope && !sub.scope(entity)) continue
+                if (sub.filter && !sub.filter(entity)) continue
+                const payload = operation === OPERATION.DELETE
+                    ? { id: entity.id }
+                    : { id: entity.id, entity }
+                sseSend(sub.res, evMap[operation], payload)
+                logger.trace('Api subscription %s %s: %s', subId, evMap[operation], entity.id)
+            }
+        }
     })
 }