mikser-io 9.25.0 → 9.26.0

package/docs/diagnostics.md

@@ -261,6 +261,50 @@ without touching files whose bytes did not move, so it is cheap to reach
 for and its `unchanged` count tells you how much of the catalog was stale
 by suspicion rather than in fact.
 
+## Over a transport
+
+Everything above assumes a shell on the machine. Three of these questions
+are also answerable from a running server, which is what CI, a dashboard,
+an SDK, or an agent speaking MCP actually has.
+
+**MCP** — `mikser_explain`, `mikser_build_report`, `mikser_verify`,
+alongside the existing `mikser_refs_*`, `mikser_layouts_inspect` and the
+`mikser://logs/recent` resource.
+
+**REST** — on the `api` plugin, gated on their own `diagnostics`
+operation:
+
+```
+GET <endpoint>/explain?reference=/documents/en/page.md
+GET <endpoint>/report
+GET <endpoint>/verify
+```
+
+```js
+api({ endpoints: {
+    ops: { token: process.env.OPS_TOKEN, operations: ['diagnostics'] },
+} })
+```
+
+`diagnostics` is in **no** default operation set, and that is deliberate
+rather than tidy: these responses carry absolute filesystem paths, layout
+ids and raw error text. Folding them into `list` would leak engine
+internals through every endpoint that only meant to publish content, and
+adding them to the token default would do it silently on upgrade.
+
+`/verify` answers `200` whether the verdict is `OK`, `WARN` or `FAIL` —
+the check ran, and that is its answer. A status code would conflate "drift
+found" with "request failed", so a CI gate reads `verdict`, which mirrors
+the CLI's exit vocabulary.
+
+The build report is recorded only when something can read it: `--json`, or
+a transport that asked for it. It describes the LAST cycle — a watch
+server clears it as each new cycle starts, so "what did that rebuild do"
+does not become "everything since boot".
+
+There is no transport for `--force`. A forced rebuild of a large site is a
+denial-of-service knob rather than a diagnostic, and it stays on the CLI.
+
 ## The database
 
 Everything mikser knows lives in one SQLite file at

package/index.js

@@ -3,6 +3,10 @@ export * as constants from './src/constants.js'
 export * from './src/utils.js'
 export * from './src/auth.js'
 export * from './src/report.js'
+// The diagnostics behind --explain. Exported so a transport — the MCP tool
+// surface, the api plugin's routes — can serve the same structured report the
+// CLI formats, rather than each one reimplementing the question.
+export * from './src/explain.js'
 export * from './src/lifecycle.js'
 export * from './src/database/index.js'
 export * from './src/journal.js'

package/package.json

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

package/src/catalog.js

@@ -226,6 +226,13 @@ async function applyJournalMutations() {
                     logger.trace('Database %s %s: %s', entity.collection, operation, entity.id)
                     stmtDelete.run(entity.id)
                     // FK ON DELETE CASCADE handles mikser_refs cleanup.
+                    // mikser_failures is cleared explicitly rather than by
+                    // cascade — see manifest.clearFailures for why it cannot
+                    // be a foreign key. Left behind, one row for a deleted
+                    // entity keeps the dispatch set non-empty for the life of
+                    // the database, so layouts' idle-cycle early-out never
+                    // fires again.
+                    runtime.manifest?.clearFailures(entity.id)
                     cacheEvict(entity.id)
                     break
             }

package/src/manager.js

@@ -2,12 +2,32 @@ import runtime from './runtime.js'
 import chokidar from 'chokidar'
 import cron from 'node-cron'
 import { onProcess, onFinalized } from './lifecycle.js'
+import { resetReport } from './report.js'
 import { useLogger } from './engine.js'
 import { ACTION } from './constants.js'
 import { junkFilter } from './utils.js'
 
 const tasks = []
 
+// The watch-cycle trigger, in one place rather than four copies.
+//
+// Debounced by a second so a burst of file events becomes one cycle. The
+// report is cleared as the cycle STARTS, not when it is scheduled, so it
+// always describes the cycle that just ran: without this it accumulates for
+// the life of a watch process, and "what did the last rebuild do" becomes
+// "here is everything since boot, find the end yourself".
+//
+// Not done inside runtime.process(): the first cycle's `gated` count is
+// recorded during import, which runs BEFORE process(), so resetting there
+// would wipe it out of a one-shot build's report.
+function scheduleProcess() {
+    clearTimeout(runtime.engine.processTimeout)
+    runtime.engine.processTimeout = setTimeout(() => {
+        resetReport()
+        runtime.process()
+    }, 1000)
+}
+
 export async function createdHook(name, context) {
     if (!runtime.started) return
 
@@ -18,8 +38,7 @@ export async function createdHook(name, context) {
     })
 
     if (synced) {
-        clearTimeout(runtime.engine.processTimeout)
-        runtime.engine.processTimeout = setTimeout(() => runtime.process(), 1000)
+        scheduleProcess()
     }
 }
 
@@ -33,8 +52,7 @@ export async function updatedHook(name, context) {
     })
 
     if (synced) {
-        clearTimeout(runtime.engine.processTimeout)
-        runtime.engine.processTimeout = setTimeout(() => runtime.process(), 1000)
+        scheduleProcess()
     }
 }
 
@@ -48,8 +66,7 @@ export async function triggeredHook(name, context) {
     })
 
     if (synced) {
-        clearTimeout(runtime.engine.processTimeout)
-        runtime.engine.processTimeout = setTimeout(() => runtime.process(), 1000)
+        scheduleProcess()
     }
 }
 
@@ -63,8 +80,7 @@ export async function deletedHook(name, context) {
     })
 
     if (synced) {
-        clearTimeout(runtime.engine.processTimeout)
-        runtime.engine.processTimeout = setTimeout(() => runtime.process(), 1000)
+        scheduleProcess()
     }
 }
 

package/src/manifest.js

@@ -297,6 +297,9 @@ export function createManifest(db) {
     const stmtClearFailure = db.prepare(`
         DELETE FROM mikser_failures WHERE id = ? AND destination = ?
     `)
+    const stmtClearFailuresForId = db.prepare(`
+        DELETE FROM mikser_failures WHERE id = ?
+    `)
     const stmtFailuresFor = db.prepare(`
         SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
         FROM mikser_failures WHERE id = ?
@@ -581,6 +584,24 @@ export function createManifest(db) {
             })
         },
 
+        // The entity is gone, so every failure recorded against it is
+        // irrelevant regardless of which destination it was recorded at.
+        //
+        // Deliberately NOT a foreign key with ON DELETE CASCADE, which is how
+        // mikser_refs handles the same situation: a render task's id is not
+        // guaranteed to be a row in mikser_entities — snapshots carry a
+        // `parent` precisely because paginated children render under derived
+        // ids — so an FK would make recordFailure throw from inside the
+        // handler that exists to report a render error, turning a reported
+        // failure into a crash.
+        //
+        // A rename presents as delete + create under a new id, so this covers
+        // that residue too: the old id's rows go with the delete.
+        clearFailures(id) {
+            if (!id) return
+            stmtClearFailuresForId.run(id)
+        },
+
         // A render succeeded, so whatever was recorded about it failing is
         // no longer true. Called on every success, not only after a failure —
         // it is a cheap DELETE and forgetting it would strand the marker.

package/src/plugins/api.js

@@ -4,6 +4,8 @@ import { createHash } from 'node:crypto'
 import _ from 'lodash'
 import sift from 'sift'
 import { resolveAuth, requireAuth, hasCapability, reachabilityOf } from '../auth.js'
+import { explain } from '../explain.js'
+import { buildReport, requestReport } from '../report.js'
 import { useRenderer } from '../render.js'
 import { mimeForEntity, isLoopback, ExpandError, useCollection } from '../utils.js'
 import { registerRoute } from '../routes.js'
@@ -393,6 +395,11 @@ export function api(options = {}) {
         //
         //   api.endpoints.public  { query: e => e.meta?.published, operations: ['list'] }
         //   api.endpoints.admin   { token: '...', operations: ['list','update','delete','render'] }
+        //   api.endpoints.ops     { token: '...', operations: ['diagnostics'] }
+        //
+        // `diagnostics` is in no default set: /explain, /report and /verify
+        // carry absolute paths and raw error text, so exposing them is a
+        // decision rather than a side effect of having a token.
         for (const [name, ep] of Object.entries(endpoints)) {
             const router = express.Router()
 
@@ -438,6 +445,10 @@ export function api(options = {}) {
                 ? ['list', 'update', 'delete', 'render', 'subscribe']
                 : ['list']
             const allowedOps = new Set(ep.operations ?? defaultOps)
+            // Recording the build report costs one entry per entity per
+            // cycle, so it is off unless something can read it. An endpoint
+            // exposing /report is that something.
+            if (allowedOps.has('diagnostics')) requestReport()
 
             // The endpoint's scope. A sift filter is the form to prefer —
             // queryEntities merges it into the WHERE clause, so the endpoint
@@ -922,6 +933,73 @@ export function api(options = {}) {
                 }
             })
 
+            // ── Diagnostics ────────────────────────────────────────
+            //
+            // The three questions --explain, --json and --verify answer, for
+            // a RUNNING server: CI asking "did that deploy actually rebuild
+            // anything", a dashboard, an SDK, anything not speaking MCP.
+            // `mikser && mikser --verify` becomes a request against the
+            // instance that is actually serving.
+            //
+            // Gated on their own `diagnostics` operation, which is in NEITHER
+            // default op set. That is deliberate rather than tidy: these
+            // responses carry absolute filesystem paths, layout ids and raw
+            // error messages, so folding them into `list` would leak engine
+            // internals through every endpoint that only meant to expose
+            // published content. An operator opts in per endpoint.
+            // `?reference=` rather than a path segment: an entity id contains
+            // slashes (/documents/en/page.md), which as a path would need a
+            // wildcard — and Express 5's path-to-regexp rejects the v4
+            // `:reference(*)` form outright.
+            router.get('/explain', auth, allow('diagnostics'), async (req, res) => {
+                try {
+                    const reference = req.query.reference
+                    if (!reference) {
+                        return res.status(400).json({ error: 'Missing ?reference= (entity id, meta.href, or id without its extension)' })
+                    }
+                    const report = await explain(String(reference))
+                    // 404 for an entity that is not there: `found: false` is a
+                    // real answer with a hint attached, but a REST caller
+                    // reasonably reads status before body.
+                    return res.status(report.found === false ? 404 : 200).json(report)
+                } catch (err) {
+                    logger.error('Api explain error: %s', err.message)
+                    return res.status(500).json({ error: err.message })
+                }
+            })
+
+            router.get('/report', auth, allow('diagnostics'), async (req, res) => {
+                try {
+                    return res.json(buildReport())
+                } catch (err) {
+                    logger.error('Api report error: %s', err.message)
+                    return res.status(500).json({ error: err.message })
+                }
+            })
+
+            router.get('/verify', auth, allow('diagnostics'), async (req, res) => {
+                try {
+                    if (!runtime.manifest?.verify) {
+                        return res.status(503).json({ error: 'No manifest available — nothing to verify against' })
+                    }
+                    const diff = await runtime.manifest.verify()
+                    const errors = diff.missing.length + diff.mismatched.length
+                    const warnings = diff.orphaned.length + diff.unverifiable.length
+                    // 200 either way — the check ran and this is its answer. A
+                    // CI gate reads `verdict`, which mirrors the CLI's exit
+                    // vocabulary, rather than inferring from a status code that
+                    // would conflate "drift found" with "request failed".
+                    return res.json({
+                        verdict: errors > 0 ? 'FAIL' : warnings > 0 ? 'WARN' : 'OK',
+                        snapshots: runtime.manifest.size?.() ?? null,
+                        ...diff,
+                    })
+                } catch (err) {
+                    logger.error('Api verify error: %s', err.message)
+                    return res.status(500).json({ error: err.message })
+                }
+            })
+
             router.post('/render', auth, allow('render'), async (req, res) => {
                 // Hoisted so the catch can name WHICH entity failed. A
                 // render that throws before this is assigned is itself the

package/src/report.js

@@ -11,6 +11,50 @@
 // when someone improves the wording.
 import runtime from './runtime.js'
 
+// A transport that can serve the build report declares itself here, at
+// factory time, before any cycle runs.
+//
+// Recording was gated on --json alone, which is why the report existed only
+// for a one-shot build someone piped to jq. An in-process reader is exactly
+// as much of a consumer, and a watch server is where "what did the last
+// cycle do, and why" is most worth asking.
+//
+// An opt-in call rather than report.js testing for known plugins: the list
+// of things that can read a report is not report.js's to keep, and a third
+// transport should not need an edit here to work.
+export function requestReport() {
+    runtime.options ??= {}
+    runtime.options.reportRequested = true
+}
+
+// Is anything able to read the report?
+//
+// Not recorded unconditionally: the rendered/skipped/unchanged arrays are
+// one entry per entity per cycle, which `gated` is already a bare count to
+// avoid. Recording when there IS a reader keeps the default lean without
+// making the data conditional on how you happen to have started mikser.
+function reportWanted() {
+    return !!(runtime.options?.json || runtime.options?.reportRequested)
+}
+
+// Cleared at the start of every cycle, so the report always describes the
+// LAST one rather than everything since the process started.
+//
+// It did not need this while --json meant a single build that then exited.
+// Under watch, without it, rendered/skipped grow without bound and the
+// answer to "what did the last rebuild do" becomes "here is everything,
+// find the end yourself".
+//
+// The failure store is deliberately NOT cleared here: a failure persists
+// across cycles by design — it is the retry marker's in-memory twin, and
+// the exit code depends on this cycle's count, which resetRenderErrors
+// handles at the same point.
+export function resetReport() {
+    if (!runtime.state) return
+    runtime.state.report = { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
+    runtime.state.renderErrors = []
+}
+
 function store() {
     runtime.state ??= {}
     runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
@@ -24,7 +68,7 @@ function store() {
 // almost the whole catalog on almost every build, which is noise in a
 // document meant to answer "did my change land".
 export function reportGated(count = 1) {
-    if (!runtime.options?.json) return
+    if (!reportWanted()) return
     store().gated += count
 }
 
@@ -38,7 +82,7 @@ export function reportGated(count = 1) {
 // `matched`, `dependency` each mean something specific, and a single
 // polymorphic key would push the type switch onto every consumer.
 export function reportRendered(entity, reason, decision = {}) {
-    if (!runtime.options?.json) return
+    if (!reportWanted()) return
     store().rendered.push({
         id: entity?.id,
         destination: entity?.destination ?? null,
@@ -57,12 +101,12 @@ export function reportRendered(entity, reason, decision = {}) {
 // to be. Nothing downstream is disturbed, and the count measures what
 // conservative invalidation costs.
 export function reportUnchanged(entity) {
-    if (!runtime.options?.json) return
+    if (!reportWanted()) return
     store().unchanged.push({ id: entity?.id, destination: entity?.destination ?? null })
 }
 
 export function reportSkipped(entity, reason) {
-    if (!runtime.options?.json) return
+    if (!reportWanted()) return
     store().skipped.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
 }
 
@@ -73,7 +117,7 @@ export function reportSkipped(entity, reason) {
 // `code` is the contract. Add fields freely; renaming a code is a breaking
 // change to anyone asserting on it.
 export function reportWarning(code, fields = {}) {
-    if (!runtime.options?.json) return
+    if (!reportWanted()) return
     store().warnings.push({ code, ...fields })
 }
 
@@ -141,6 +185,9 @@ export function buildReport() {
 // Emitted once, after the cycle, on stdout — which the logger has vacated
 // under --json precisely so this can be the only thing there.
 export function emitReport() {
+    // --json only, deliberately. Recording and PRINTING are different
+    // questions: a server with the mcp plugin records so a tool can read it,
+    // and must not write a document to stdout.
     if (!runtime.options?.json) return
     process.stdout.write(JSON.stringify(buildReport(), null, 2) + '\n')
 }