mikser-io 9.7.0 → 9.14.0

package/docs/configuration.md

@@ -59,6 +59,7 @@ These options are part of `runtime.options` and apply to the engine itself.
 | `threads` | — | number | `4` | Worker thread count for the Piscina pools (`renderWorkers`, `postprocessWorkers`). Both pools are lazy (`minThreads: 0` + `idleTimeout: 30_000`) so INLINE-only workloads spin up zero workers. |
 | `server` | `-s, --server [port]` | number\|boolean | — | When set, the engine creates a shared Express app on `runtime.options.app` and listens on the given port (default `3001`) after all plugins have mounted their routes. Plugins like `api` attach to it instead of starting their own server. The `outputFolder` is also served as a static catch-all route at `/` (plugin routes match first; anything that doesn't match falls through to the rendered output). Requires `express` to be installed. |
 | `junk` | — | array\|false | built-in list | OS and file-manager litter, filtered out of both the scan and the watcher. The dot-prefixed files (`.DS_Store`, `._*`) were already invisible — globby defaults to `dot: false` and the watcher ignores leading dots — but the Windows ones are **not** dotfiles: `Thumbs.db` and `desktop.ini` were measurably scanned *and* watched, and became entities. The list is deliberately conservative (OS/file-manager artifacts and application lock files only, no `*.tmp`, `*.bak` or editor backups), because a filter that silently drops content is worse than the litter it prevents. `false` disables it; an array replaces it. See `isJunkPath` / `JUNK_IGNORE` in `src/utils.js`. Plugins that write metadata next to content add their own patterns with `registerJunk({ ignore, match })` — the engine provides the mechanism and the plugin the knowledge of what its files are called (`mikser-io-webdav` registers `*.nephelemeta`). Plugin registrations survive an array override, since narrowing the OS list is not a request to start importing a library's sidecars. |
+| — (plugin) | — | object | — | `sources({ styles: { folder: 'styles', extensions: ['css'] } })` registers build inputs as catalog entities, one collection per key. A sidecar can then read them with `findEntities()`, whose queries land in the render's `refClosure` — so editing, adding or removing a part re-renders the bundle and nothing else. Reading the same files with `fs` instead works for one build and silently breaks watch, because the engine has no dependency on a file it never saw. Nothing is linked into `outputFolder`: these are inputs, not output. Named `sources` rather than `inputs` because `entity.inputs` already means something adjacent — bytes an output depends on without being entities at all. |
 | `cors` / `no-cors` | `--cors` / `--no-cors` | boolean | — | Toggle CORS on the engine's shared Express app. See `src/server.js` for the extensible header arrays plugins push onto. |
 | `server.requestTimeout` | — | number | node default (`300000`) | Milliseconds a single request may take, set on the underlying `http.Server`. Node's 5-minute default is effectively an **upload size limit expressed in seconds** — a large file over a slow link is indistinguishable from a stalled request, so it is cut off and the caller sees a truncated write rather than a readable error. Only reachable from the `http.Server`, which the engine owns, so a plugin that mounts an upload surface (`mikser-io-webdav`, `forms` with large attachments) cannot raise it for itself. `0` disables the cap: reasonable on a trusted-network build server, bad facing the internet, where it removes the only bound on how long a client can hold a connection open doing nothing. `headersTimeout` is clamped to stay at or below it. The server is also exposed as `runtime.options.httpServer`. |
 | `url` | `-u, --url <url>` | string | — | Public URL where this mikser is reachable (e.g. `https://blog.me.com`). Validated, trailing slash stripped, stamped on `runtime.options.url`. Read by webhook-capable plugins for push-vs-poll gating (`url.startsWith('https://')`); used by anything that surfaces absolute URLs externally — MCP preview URLs returned to agents, forms share links, email tracking pixels. Plugins that just need internal URLs keep using `runtime.options.port`. |

package/index.js

@@ -2,6 +2,7 @@ export { default as runtime } from './src/runtime.js'
 export * as constants from './src/constants.js'
 export * from './src/utils.js'
 export * from './src/auth.js'
+export * from './src/report.js'
 export * from './src/lifecycle.js'
 export * from './src/database/index.js'
 export * from './src/journal.js'
@@ -24,6 +25,7 @@ export * from './src/routes.js'
 // for the v9 plugin shape.
 export { api }           from './src/plugins/api.js'
 export { assets }        from './src/plugins/assets.js'
+export { sources }       from './src/plugins/sources.js'
 export { commands }      from './src/plugins/commands.js'
 export { data }          from './src/plugins/data.js'
 export { documents }     from './src/plugins/documents.js'

package/package.json

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

package/src/config.js

@@ -1,12 +1,34 @@
 import runtime from './runtime.js'
 import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
+import { checksum } from './utils.js'
 import path from 'node:path'
 
 onLoad(async () => {
     const logger = useLogger()
     const configFile = path.resolve(runtime.options.config)
     logger.info('Config: %s', configFile)
+
+    // Stamp the config so a change to it can invalidate the derived cache.
+    //
+    // Without this, editing mikser.config.js invalidated NOTHING: flipping
+    // an option that changes every page's destination reported "36 unchanged"
+    // and left the previous output in place. The config was genuinely read —
+    // --force applied it immediately — it simply took part in no
+    // invalidation, so the only symptom was output that did not match the
+    // config, with nothing saying so.
+    //
+    // The file's bytes only. A config that imports other modules will not
+    // notice a change in those, which is a real limit worth knowing rather
+    // than a reason to hash the whole module graph.
+    try {
+        runtime.options.configChecksum = await checksum(configFile)
+    } catch {
+        // No config file is a legitimate state (defaults all the way down);
+        // absent stamp means "nothing to compare", not "changed".
+        runtime.options.configChecksum = null
+    }
+
     try {
         const config = await import(configFile)
         if (typeof config.default == 'function') {

package/src/database/index.js

@@ -247,10 +247,38 @@ export function createSqliteDatabase({
         handle = new Database(dbPath)
         setupConnection()
 
-        const recorded = handle.prepare('SELECT value FROM mikser_meta WHERE key = ?')
-            .get('schema_version')?.value
+        const stmtMeta = handle.prepare('SELECT value FROM mikser_meta WHERE key = ?')
+        const recorded = stmtMeta.get('schema_version')?.value
+
+        // A config change invalidates the cache for the same reason a version
+        // change does: the derived state was computed under different rules.
+        //
+        // Before this, editing mikser.config.js invalidated nothing — flipping
+        // an option that changes every page's destination reported "36
+        // unchanged" and left the previous output in place. The config was
+        // read; it simply took part in no invalidation, so the only symptom
+        // was output that did not match the config and nothing saying so.
+        //
+        // Treated exactly like a version mismatch rather than something
+        // narrower: a config edit can change how sources are PARSED (a mapper
+        // transform, documents() options) as well as how they are rendered,
+        // so invalidating only the render manifest would still leave stale
+        // entities. Per ADR-0002 the files are the source of truth, so
+        // rebuilding is always safe — just slower.
+        const recordedConfig = stmtMeta.get('config_checksum')?.value
+        const currentConfig = runtime.options.configChecksum ?? null
+        const configChanged = Boolean(recordedConfig && currentConfig && recordedConfig !== currentConfig)
+
         let upgradedFromVersion = null
-        if (recorded && recorded !== version) {
+        if (configChanged && !(recorded && recorded !== version)) {
+            logger?.warn(
+                'Config changed since the last run. Wiping the cache and rebuilding from sources ' +
+                '(files are the source of truth — no source data is affected). Note this tracks the ' +
+                'bytes of %s only: a change in a module it imports is not seen.',
+                runtime.options.config,
+            )
+        }
+        if ((recorded && recorded !== version) || configChanged) {
             // Schema mismatch on upgrade or downgrade. Per ADR-0002 the
             // files on disk are the source of truth and this database
             // is a derived cache, so the right behavior is to wipe the
@@ -261,10 +289,12 @@ export function createSqliteDatabase({
             // expect a cold-start rebuild on this run. No data loss
             // beyond the cache itself; everything in mikser.sqlite is
             // recoverable from the working folder.
-            logger?.warn(
-                'Database schema mismatch: stored=%s, current=%s. Wiping the cache and rebuilding from sources (files are the source of truth — no source data is affected).',
-                recorded, version,
-            )
+            if (recorded && recorded !== version) {
+                logger?.warn(
+                    'Database schema mismatch: stored=%s, current=%s. Wiping the cache and rebuilding from sources (files are the source of truth — no source data is affected).',
+                    recorded, version,
+                )
+            }
             handle.close()
             handle = null
 
@@ -277,12 +307,16 @@ export function createSqliteDatabase({
                 }
             }
 
-            upgradedFromVersion = recorded
+            // Non-null marks the provisioning context as firstRun/upgraded,
+            // which is the right shape for a config change too: what the
+            // provisioners see is an empty-state database either way.
+            upgradedFromVersion = recorded ?? 'config'
             handle = new Database(dbPath)
             setupConnection()
         }
-        handle.prepare('INSERT OR REPLACE INTO mikser_meta (key, value) VALUES (?, ?)')
-            .run('schema_version', version)
+        const stmtStamp = handle.prepare('INSERT OR REPLACE INTO mikser_meta (key, value) VALUES (?, ?)')
+        stmtStamp.run('schema_version', version)
+        if (currentConfig) stmtStamp.run('config_checksum', currentConfig)
 
         // Build provisioning context. firstRun is true when the file
         // didn't exist before this open OR when the schema mismatch

package/src/engine.js

@@ -10,6 +10,7 @@ import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
 import { changeExtension, formatErrorContext, projectMeta, lookupKeys } from './utils.js'
+import { reportRendered, reportSkipped, emitReport } from './report.js'
 import render from './render.js'
 import postprocess, { loadPlugin as loadPostPlugin } from './postprocess.js'
 import map from 'p-map'
@@ -115,6 +116,8 @@ export async function setup(options) {
             .option('-f --force', 'rebuild everything; disable incremental dispatch', false)
             .option('-R --resume', 'continue from journal entries left by a previous interrupted run; skip the initial filesystem scan', false)
             .option('--verify', 'verify output folder against manifest; report drift instead of building', false)
+            .option('--explain <entity>', 'explain one entity — layout, destination, hashes, refClosure, and whether a build would re-render it. Accepts an id, a meta.href, or an id without its extension. Reports instead of building.')
+            .option('--json', 'machine-readable output (with --explain, and for a build\'s render/skip/warning report)', false)
             .option('-d --debug', 'display debug statements')
             .option('-t --trace', 'display trace statements')
             .option('-e --runtime-folder <folder>', 'set mikser runtime folder relative to working folder', 'runtime')
@@ -226,6 +229,25 @@ export async function setup(options) {
         //                 corruption, but state is messy)
         //   2 — errors   (missing or mismatched files — output is
         //                 actually wrong on disk)
+        // --explain: report on one entity and exit, like --verify. Placed
+        // before it because a caller reaching for both means the explain.
+        //
+        // Exit codes:
+        //   0 — the entity was found and described
+        //   3 — not in the catalog (distinct from --verify's 1/2, which are
+        //       about output drift; "no such entity" is neither clean nor
+        //       corrupt, it is a question that could not be answered)
+        if (runtime.options.explain) {
+            const { explain, formatExplain } = await import('./explain.js')
+            const report = await explain(runtime.options.explain)
+            if (runtime.options.json) {
+                process.stdout.write(JSON.stringify(report, null, 2) + '\n')
+            } else {
+                process.stdout.write(formatExplain(report) + '\n')
+            }
+            process.exit(report.found ? 0 : 3)
+        }
+
         if (runtime.options.verify) {
             if (!runtime.manifest) {
                 logger.error('Verify: no manifest available — nothing to check against')
@@ -331,13 +353,21 @@ export async function setup(options) {
                 // next run. A postprocess-aware manifest that also
                 // skips when the postprocess output is current would
                 // close the gap — not yet implemented.
-                if (!options.postprocessor && runtime.manifest?.shouldSkip(entity, mutatedRefs, currentHashes, mutatedEntities)) {
+                const decision = options.postprocessor
+                    // A postprocessor consumes the intermediate rendered
+                    // file, so skipping would leave its input missing.
+                    ? { skip: false, reason: 'postprocessor' }
+                    : runtime.manifest?.skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities)
+                        ?? { skip: false, reason: 'no-manifest' }
+                if (decision.skip) {
                     skipped++
                     entry.output = { success: true, skipped: 'manifest' }
                     await updateEntry({ id, output: entry.output })
+                    reportSkipped(entity, decision.reason)
                     logger.debug('Manifest skip: %s → %s', entity.name || entity.id, entity.destination)
                     return
                 }
+                reportRendered(entity, decision.reason)
                 // Project reference-marker keys (`$author`, `$hero`, …)
                 // into their normalized form (`author`, `hero`) before
                 // the entity crosses into the renderer — applies whether
@@ -716,6 +746,10 @@ export async function setup(options) {
             }
         }
         logger.notice('Mikser completed')
+        // After the cycle, and only under --json. stdout has been kept clear
+        // for exactly this (the logger writes to stderr under --json), so the
+        // document is the only thing on it and can be piped to jq.
+        emitReport()
     })
 
     onCancelled(async () => {
@@ -723,7 +757,18 @@ export async function setup(options) {
         logger.notice('Mikser restarted')
     })
 
-    console.info('\x1b[1mmikser\x1b[22;5;38;2;255;63;0m.\x1b[0m %s\n', packageInfo.version)
+    // Banner to stderr under --json, for the same reason the logger goes
+    // there: stdout must contain only the document.
+    //
+    // argv directly, not runtime.options: commander parses in a lifecycle
+    // hook, which runs after setup() returns, so options.json is still
+    // undefined here. The logger has no such problem — it writes during the
+    // run, by which time options exist.
+    if (runtime.options?.json || process.argv.includes('--json')) {
+        process.stderr.write(`mikser. ${packageInfo.version}\n`)
+    } else {
+        console.info('\x1b[1mmikser\x1b[22;5;38;2;255;63;0m.\x1b[0m %s\n', packageInfo.version)
+    }
     return runtime
 }
 

package/src/explain.js

@@ -0,0 +1,194 @@
+// `--explain <entity-id>` — what happened to one entity, and why.
+//
+// Assembly, not new machinery: every line comes from state the engine already
+// keeps (catalog, manifest snapshots, inputHashOf, the layouts matcher's
+// output). It exists because the question asked most often about a build is
+// "why did this NOT change?", and until now the only way to answer it was to
+// read plugin source and hand-query runtime/mikser.sqlite — which works, and
+// needs knowledge a user of the tool should not need.
+//
+// Follows --verify's shape: report and exit, no build phases run.
+import { inputHashOf, lookupKeys, checksum as fileChecksum } from './utils.js'
+import { findEntity } from './catalog.js'
+import runtime from './runtime.js'
+
+const shortHash = (h) => (h ? String(h).slice(0, 8) : null)
+const when = (ms) => (ms ? new Date(ms).toISOString().replace('T', ' ').slice(0, 19) : null)
+
+// Resolve loosely: an id, a meta.href, or an id without its extension. The
+// same extension-tolerant resolution refs and the catalog already use — so a
+// caller can paste whatever form they have in front of them.
+async function resolve(reference) {
+    const direct = await findEntity({ id: reference })
+    if (direct) return direct
+    const byHref = await findEntity({ 'meta.href': reference })
+    if (byHref) return byHref
+    // id-minus-extension: /documents/bg/index → /documents/bg/index.md
+    const like = await findEntity({ id: { $regex: `^${reference.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.[^./]+$` } })
+    return like ?? null
+}
+
+export async function explain(reference) {
+    const entity = await resolve(reference)
+    if (!entity) {
+        return {
+            found: false,
+            reference,
+            // The likeliest reasons, in the order they actually happen.
+            hint: 'Not in the catalog. Either nothing imported it (check the source plugin\'s folder and extensions), '
+                + 'it was filtered as junk (see the `junk` config), or the id is spelled differently — '
+                + 'try the meta.href or the id without its extension.',
+        }
+    }
+
+    const snapshots = runtime.manifest?.snapshotsFor(entity.id) ?? []
+    const currentHash = inputHashOf(entity)
+
+    // The catalog is as of the LAST BUILD. If the file has been edited since,
+    // nothing here knows it yet — the hashes would all agree and the verdict
+    // would say "skipped", which is true of the catalog and misleading about
+    // the next build. So check the file too, and say which is being reported.
+    //
+    // A caveat rather than a bug: some plugins compose a checksum from more
+    // than one file (layouts folds in its .js sidecar), so a difference does
+    // not always mean the entity's own source moved. Both values are reported
+    // and the wording avoids claiming more than is known.
+    let source = null
+    if (entity.uri) {
+        try {
+            const onDisk = await fileChecksum(entity.uri)
+            source = {
+                uri: entity.uri,
+                catalogChecksum: entity.checksum ?? null,
+                fileChecksum: onDisk,
+                differs: entity.checksum != null && entity.checksum !== onDisk,
+            }
+        } catch (err) {
+            source = { uri: entity.uri, error: err.code === 'ENOENT' ? 'file is gone' : err.message }
+        }
+    }
+
+    return {
+        found: true,
+        id: entity.id,
+        collection: entity.collection,
+        type: entity.type,
+        name: entity.name,
+        // The layouts matcher records both the layout and the pattern that
+        // claimed the entity; with several layouts, all of them.
+        layouts: (entity.layouts ?? (entity.layout ? [entity.layout] : [])).map(l => ({
+            name: l?.name ?? null,
+            matchedBy: l?.matchedBy ?? entity.meta?.layoutMatch ?? null,
+            format: l?.format ?? null,
+            postprocessors: l?.postprocessors ?? (l?.postprocessor ? [l.postprocessor] : []),
+            // The layout's OWN declared inputs — its .js sidecar, and the
+            // digest covering everything the sidecar imports. Surfaced on the
+            // page's report rather than only the layout's, because "does
+            // editing this helper module invalidate my page" is asked about
+            // the page. Not seeing it is what makes people build a workaround
+            // for something already handled.
+            inputs: l?.inputs ?? null,
+        })),
+        destination: entity.destination ?? null,
+        lang: entity.meta?.lang ?? null,
+        href: entity.meta?.href ?? null,
+        // Why a render would or would not happen. `inputHash` is the entity's
+        // current hash; each snapshot carries the hash it was rendered at, so
+        // the two disagreeing IS the answer to "why did this change".
+        inputHash: currentHash,
+        inputHashOf: entity.checksum && entity.meta == null && entity.content == null
+            ? 'checksum'
+            : 'meta+content+inputs',
+        inputs: entity.inputs ?? null,
+        checksum: entity.checksum ?? null,
+        source,
+        renders: snapshots.map(snap => ({
+            destination: snap.destination,
+            renderedAt: when(snap.renderedAt),
+            inputHash: snap.inputHash,
+            // The single most useful field: does this entity's current hash
+            // match what it was last rendered at?
+            stale: snap.inputHash !== currentHash,
+            outputHash: snap.outputHash ?? null,
+            parent: snap.parent ?? null,
+            refClosure: (snap.refClosure ?? []).map(entry =>
+                entry.kind === 'query'
+                    ? { kind: 'query', filter: entry.filter }
+                    : { kind: entry.kind, target: entry.target, hash: shortHash(entry.hash) }),
+        })),
+        // What a plain build would do next, stated plainly.
+        verdict: source?.error === 'file is gone'
+            ? 'source file is gone — a build would DELETE this entity and unlink its output'
+            : source?.differs
+                ? 'source differs from the catalog — a build would re-import it first, then re-render. '
+                  + '(Some plugins compose a checksum from several files, so verify before concluding.)'
+                : snapshots.length === 0
+            ? 'never rendered — no manifest snapshot. Either it has no layout, or its layout produced no destination.'
+            : snapshots.some(s => s.inputHash !== currentHash)
+                ? 'would re-render — the entity\'s input hash differs from what it was last rendered at'
+                : 'would be SKIPPED — input hash unchanged. A dependency in refClosure changing is the only other thing that would re-render it.',
+        lookupKeys: lookupKeys(entity),
+    }
+}
+
+// Human-readable rendering. Deliberately aligned columns rather than prose:
+// the point is to be scanned, and to be diffable between two runs.
+export function formatExplain(report) {
+    const out = []
+    const row = (label, value) => out.push(`${label.padEnd(12)}${value}`)
+
+    if (!report.found) {
+        out.push(`not found   ${report.reference}`)
+        out.push('')
+        out.push(report.hint)
+        return out.join('\n')
+    }
+
+    row('entity', `${report.id}   (${report.collection}/${report.type})`)
+    if (report.href) row('href', report.href)
+    if (report.lang) row('lang', report.lang)
+    if (report.layouts.length) {
+        for (const l of report.layouts) {
+            row('layout', `${l.name ?? '(unnamed)'}${l.matchedBy ? `   (matched ${JSON.stringify(l.matchedBy)})` : ''}`
+                + (l.postprocessors?.length ? `   → ${l.postprocessors.join(' → ')}` : ''))
+            const li = l.inputs && Object.entries(l.inputs).filter(([, v]) => v != null)
+            if (li?.length) {
+                out.push(`  inputs     ${li.map(([k, v]) => `${k} ${shortHash(v)}`).join(', ')}`)
+            }
+        }
+    } else {
+        row('layout', 'none matched — this entity is not rendered')
+    }
+    row('destination', report.destination ?? '(none — never assigned)')
+    row('inputHash', `${shortHash(report.inputHash)}  = ${report.inputHashOf}`)
+    if (report.source) {
+        row('source', report.source.error
+            ? `${report.source.uri}   [${report.source.error}]`
+            : `${report.source.uri}${report.source.differs ? '   [DIFFERS from the catalog — not yet re-imported]' : ''}`)
+    }
+    if (report.inputs) {
+        const parts = Object.entries(report.inputs)
+            .filter(([, v]) => v != null)
+            .map(([k, v]) => `${k} ${shortHash(v)}`)
+        if (parts.length) row('inputs', parts.join(', '))
+    }
+
+    if (!report.renders.length) {
+        row('rendered', 'never')
+    }
+    for (const r of report.renders) {
+        row('rendered', `${r.renderedAt ?? 'unknown'}   → ${r.destination}`
+            + (r.stale ? '   [STALE: input hash moved since]' : '   [current]'))
+        const closure = r.refClosure
+        row('refClosure', `${closure.length} edge${closure.length === 1 ? '' : 's'}`)
+        for (const e of closure) {
+            out.push(e.kind === 'query'
+                ? `  query      ${JSON.stringify(e.filter)}`
+                : `  ${e.kind.padEnd(10)} ${e.target}${e.hash ? `  ${e.hash}` : ''}`)
+        }
+    }
+
+    out.push('')
+    out.push(report.verdict)
+    return out.join('\n')
+}

package/src/logger.js

@@ -122,7 +122,13 @@ function createTerminalStream() {
     return new Writable({
         write(chunk, enc, cb) {
             if (gauge) gauge.disable()
-            process.stdout.write(chunk, enc)
+            // --json puts a machine-readable document on stdout, so every
+            // log line has to go somewhere else or the document cannot be
+            // parsed. stderr rather than silence: the operator still sees
+            // the build, and `mikser --explain x --json | jq` still works —
+            // which is the entire point of the flag.
+            const out = runtime.options?.json ? process.stderr : process.stdout
+            out.write(chunk, enc)
             if (gauge) gauge.enable()
             cb()
         },

package/src/manifest.js

@@ -180,6 +180,10 @@ async function hashOutputFile(destination) {
 export function createManifest(db) {
     if (!db) throw new Error('createManifest: db is required')
 
+    const stmtLookupById = db.prepare(`
+        SELECT id, destination, inputHash, outputHash, refClosure, renderedAt, parent
+        FROM mikser_snapshots WHERE id = ? ORDER BY destination
+    `)
     const stmtLookup = db.prepare(`
         SELECT id, destination, inputHash, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots WHERE id = ? AND destination = ?
@@ -251,23 +255,51 @@ export function createManifest(db) {
             return rowToSnap(stmtLookup.get(query.id, query.destination))
         },
 
+        // EVERY snapshot for an entity, not just the one at a known
+        // destination. An entity can have several — one per matched layout,
+        // one per paginated page — and a caller asking "what happened to
+        // this?" does not know the destinations in advance. That is exactly
+        // the position an operator (or an agent) is in when a page did not
+        // change and they want to know why.
+        snapshotsFor(id) {
+            if (!id) return []
+            return stmtLookupById.all(id).map(rowToSnap)
+        },
+
         // Should this render be skipped? See the original docstring in
         // the prior NDJSON-backed implementation — logic is unchanged,
         // backing storage is the only thing that changed.
+        // Boolean wrapper, kept because that is what the render loop asked
+        // for first. skipDecision carries the same logic plus WHY, which is
+        // what a machine-readable build report needs — "Rendered: 16" is a
+        // number nobody can assert on.
         shouldSkip(entity, mutatedRefs, currentHashes, mutatedEntities) {
-            if (entity?.meta?.cache === false) return false
+            return this.skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities).skip
+        },
+
+        // { skip, reason } — reason is set either way, and the vocabulary is
+        // stable so it can be asserted against:
+        //
+        //   unchanged        nothing this render depends on moved
+        //   never-rendered   no snapshot: first build, or it never rendered
+        //   inputs-changed   the entity's own hash moved
+        //   ref-changed      a $-ref or partial it depends on moved
+        //   query-matched    an entity matching a recorded query mutated
+        //   cache-disabled   meta.cache === false
+        skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities) {
+            if (entity?.meta?.cache === false) return { skip: false, reason: 'cache-disabled' }
             const snapshot = this.lookup(entity)
-            if (!snapshot?.inputHash) return false
-            if (inputHashOf(entity) !== snapshot.inputHash) return false
-            if (!snapshot.refClosure?.length) return true
+            if (!snapshot?.inputHash) return { skip: false, reason: 'never-rendered' }
+            if (inputHashOf(entity) !== snapshot.inputHash) return { skip: false, reason: 'inputs-changed' }
+            if (!snapshot.refClosure?.length) return { skip: true, reason: 'unchanged' }
             const sourceLang = entity?.meta?.lang ?? null
             for (const entry of snapshot.refClosure) {
                 if (entry.kind === 'query') {
-                    if (!entry.filter) return false
+                    if (!entry.filter) return { skip: false, reason: 'query-matched' }
                     if (!mutatedEntities?.size) continue
                     const matcher = sift(entry.filter)
                     for (const mutated of mutatedEntities.values()) {
-                        if (matcher(mutated)) return false
+                        if (matcher(mutated)) return { skip: false, reason: 'query-matched' }
                     }
                     continue
                 }
@@ -286,13 +318,13 @@ export function createManifest(db) {
                         continue
                     }
                 }
-                if (!entry.hash) return false
+                if (!entry.hash) return { skip: false, reason: 'ref-changed' }
                 const currentHash = currentHashes?.get(entry.target)
                 if (currentHash === undefined) continue
-                if (currentHash === null) return false
-                if (currentHash !== entry.hash) return false
+                if (currentHash === null) return { skip: false, reason: 'ref-changed' }
+                if (currentHash !== entry.hash) return { skip: false, reason: 'ref-changed' }
             }
-            return true
+            return { skip: true, reason: 'unchanged' }
         },
 
         // Record a successful render. Single INSERT OR REPLACE.

package/src/plugins/assets.js

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module'
 import { globby } from 'globby'
 import _ from 'lodash'
 import map from 'p-map'
+import { reportWarning } from '../report.js'
 
 // Normalize a `options.presets[name]` value to a consistent
 // { matches, options } shape so callers don't have to inspect which form
@@ -86,19 +87,54 @@ export function assets(options = {}) {
     const type = 'preset'
     const checksumMap = new Set()
 
+    // A preset that matches nothing builds green and says nothing, which is
+    // how a mistyped pattern ships. `files({ outputFolder })` prefixes `name`
+    // and `meta.url` but NOT `id`, and `match` runs against `id` — so
+    // '/files/media/devices/**' looks right and matches zero. Tallied here,
+    // reported once per process at onFinalize.
+    const matchTally = { evaluated: 0, matched: new Set(), reported: false }
+
     async function getEntityPresets(entity) {
         const entityPresets = []
+        matchTally.evaluated++
         for (let preset in (options.presets || {})) {
             const { matches } = normalizePresetConfig(options.presets[preset])
             for (let match of matches) {
                 if (matchEntity(entity, match)) {
                     entityPresets.push(preset)
+                    matchTally.matched.add(preset)
                 }
             }
         }
         return entityPresets
     }
 
+    // Report presets that matched none of the entities this run evaluated.
+    //
+    // Deliberately phrased as what was OBSERVED rather than "this preset is
+    // broken": an incremental cycle only re-evaluates changed entities, so a
+    // preset can legitimately match nothing in a run of three. The count and
+    // the --force hint let the reader tell the two apart, which a bare
+    // "matched nothing" would not. Once per process, so watch mode is quiet.
+    function reportUnmatchedPresets(logger) {
+        if (matchTally.reported) return
+        const configured = Object.keys(options.presets || {})
+        if (!configured.length || !matchTally.evaluated) return
+        matchTally.reported = true
+
+        for (const preset of configured) {
+            if (matchTally.matched.has(preset)) continue
+            const { matches } = normalizePresetConfig(options.presets[preset])
+            reportWarning('preset-no-match', { preset, evaluated: matchTally.evaluated, patterns: matches })
+            logger.warn(
+                'Assets preset %j matched none of the %d entities evaluated (patterns: %s). ' +
+                'Patterns run against entity.id, which files({ outputFolder }) does NOT prefix — ' +
+                'the prefix appears on name and meta.url only. On an incremental run unchanged ' +
+                'entities are not re-evaluated; use --force to check the whole catalog.',
+                preset, matchTally.evaluated, matches.join(', '))
+        }
+    }
+
     // Resolve a preset name to an importable module location. Local
     // files in presetsFolder win; names with no local file fall back to
     // an npm package named `mikser-io-preset-<name>`, resolved from the
@@ -437,6 +473,8 @@ export function assets(options = {}) {
         const logger = useLogger()
         const { presets } = runtime.state.assets
 
+        reportUnmatchedPresets(logger)
+
         let revisions = await globby('**/*.md5', { cwd: runtime.options.assetsFolder })
         for (let revision of revisions) {
             const [preset] = revision.split(path.sep)

package/src/plugins/commands.js

@@ -31,16 +31,16 @@ export function commands(options = {}) {
             if (_.endsWith(command, '&')) {
                 command = command.slice(0, -1)
                 if (!running[command]) {
-                    logger.info('Command: %s', command, runtime.options.wokrkingFolder)
-                    const subprocess = execaCommand(command, { cwd: runtime.options.wokrkingFolder, all: true })
+                    logger.info('Command: %s', command, runtime.options.workingFolder)
+                    const subprocess = execaCommand(command, { cwd: runtime.options.workingFolder, all: true })
                     eachLine(subprocess.all, line => logger.info(line))
                     running[command] = subprocess
                         .then(() => delete running[command])
                         .catch(err => logger.error(err, 'Command error'))
                 }
             } else {
-                logger.info('Command: %s', command, runtime.options.wokrkingFolder)
-                const subprocess = execaCommand(command, { cwd: runtime.options.wokrkingFolder, all: true })
+                logger.info('Command: %s', command, runtime.options.workingFolder)
+                const subprocess = execaCommand(command, { cwd: runtime.options.workingFolder, all: true })
                 await eachLine(subprocess.all, line => logger.debug(line))
                 await subprocess
             }

package/src/plugins/render/preset.js

@@ -1,7 +1,25 @@
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 
+// A renderer's `load` runs for EVERY entity in the cycle, not only the ones
+// this renderer will render — that is deliberate and is how renderAsset
+// installs runtime.asset() for all templates. So this has to tolerate an
+// entity that has no preset, rather than assume it is looking at one.
+//
+// Without the guard, adding renderPreset() to a project's plugin list made
+// every page render throw on `entity.preset.uri` — and a crash reads as
+// "you have found something real", which is a much more expensive wrong
+// signal than a no-op. The names invite exactly that mistake:
+//
+//   renderAsset()   provides runtime.asset() to templates  (a URL helper)
+//   assets()        runs presets and produces derivatives   (the work)
+//   renderPreset()  renders a preset-authored layout        (this file)
+//
+// All three are named after the object they concern rather than the job they
+// do, so reasoning "the one that RUNS presets must be renderPreset" is wrong
+// but not unreasonable.
 export async function load({ entity, runtime }) {
+    if (!entity?.preset?.uri) return
     const preset = await import(`${entity.preset.uri}?stamp=${Date.now()}`)
     runtime.preset = preset.default
 }

package/src/plugins/sources.js

@@ -0,0 +1,69 @@
+// Register build inputs — styles/, js/ — as catalog entities.
+//
+// The gap this fills: a site that bundles assets needs a layout sidecar to
+// read those files. Reading them with `fs` works for a one-shot build and
+// SILENTLY breaks watch — the engine has no dependency on a file it never
+// saw, so editing styles/sections/hero.css rebuilds nothing and the page is
+// stale with nothing saying so. The first build is correct, which is what
+// makes it expensive: the mistake only surfaces later as "why didn't my edit
+// take effect", and the obvious workaround is the broken one.
+//
+// Registered as entities instead, a sidecar reads them with findEntities(),
+// whose queries are recorded into the render's refClosure — so touching one
+// part re-renders the bundle and nothing else, by the same mechanism that
+// re-renders a page when a document it references changes.
+//
+// Deliberately NOT the `files` plugin: these are inputs, not output. Nothing
+// is linked into out/, no meta.url is stamped, and they take no part in
+// ADR-0011 served-path resolution. A stylesheet part is not a thing the site
+// serves; it is a thing the site is built from.
+//
+// Named `sources` rather than `inputs` because `entity.inputs` already means
+// something adjacent but different — bytes an entity's output depends on
+// without them being entities at all (see inputHashOf). Two spellings of
+// "input" meaning two things would be worse than a slightly generic name.
+import path from 'node:path'
+import { useSource } from '../source.js'
+
+export function sources(options = {}) {
+    const collections = Object.entries(options)
+    return (core) => {
+        const { useLogger } = core
+        if (!collections.length) {
+            // No collections is a legitimate config (a flag turned them all
+            // off); nothing to register, and nothing to complain about.
+            return
+        }
+        for (const [collection, config] of collections) {
+            const {
+                folder = collection,
+                extensions = ['*'],
+                ignore = [],
+                // Content is the point — a sidecar bundling CSS needs the
+                // bytes, not just the path. Overridable for a collection
+                // that only needs to be *known* (an image manifest, say).
+                content = true,
+                load,
+                // Code-shaped, so the extension stays in `id` (two parts of
+                // the same name in different languages must not collide) and
+                // `name` keeps the folder-relative path without it.
+                stripExtensionFromId = false,
+            } = config ?? {}
+
+            useSource(core, {
+                collection,
+                type: 'source',
+                folder,
+                extensions,
+                ignore,
+                content,
+                stripExtensionFromId,
+                load: load ?? (async () => ({})),
+                progress: `${collection.replace(/^./, c => c.toUpperCase())} import`,
+            })
+        }
+        useLogger?.()?.debug('Sources registered: %s', collections.map(([c]) => c).join(', '))
+    }
+}
+
+export default sources

package/src/report.js

@@ -0,0 +1,76 @@
+// The machine-readable build report behind `--json`.
+//
+// `Rendered: 16` is a number nobody can assert on. Verifying "did my change
+// land" without this means diffing the output folder against a snapshot taken
+// beforehand — a lot of ceremony for one question.
+//
+// The valuable field is `reason`, not the counts. And a stable `code` on a
+// warning matters more than its prose: it lets a caller assert "this build
+// produced no preset-no-match" instead of grepping a sentence that may be
+// reworded — which is exactly the kind of assertion that should not break
+// when someone improves the wording.
+import runtime from './runtime.js'
+
+function store() {
+    runtime.state ??= {}
+    runtime.state.report ??= { rendered: [], skipped: [], warnings: [], gated: 0 }
+    return runtime.state.report
+}
+
+// An entity whose SOURCE did not change is gated at import and never becomes
+// a render task at all — so it appears in neither `rendered` nor `skipped`,
+// and the two lists would not reconcile with the corpus size without saying
+// so. Counted rather than listed: on a 14k-entity site the list would be
+// 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
+    store().gated += count
+}
+
+export function reportRendered(entity, reason) {
+    if (!runtime.options?.json) return
+    store().rendered.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
+}
+
+export function reportSkipped(entity, reason) {
+    if (!runtime.options?.json) return
+    store().skipped.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
+}
+
+// Called ALONGSIDE logger.warn, not instead of it: a human reading the
+// terminal still needs the sentence, and the sentence is where the
+// explanation lives. This carries the assertable part.
+//
+// `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
+    store().warnings.push({ code, ...fields })
+}
+
+export function buildReport() {
+    const report = store()
+    return {
+        rendered: report.rendered,
+        skipped: report.skipped,
+        warnings: report.warnings,
+        summary: {
+            rendered: report.rendered.length,
+            // Renders that were CONSIDERED and skipped by the manifest.
+            skipped: report.skipped.length,
+            // Entities gated at import because their source was unchanged, so
+            // no render was ever scheduled. Different question, different
+            // number — see reportGated.
+            gated: report.gated,
+            warnings: report.warnings.length,
+        },
+    }
+}
+
+// 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() {
+    if (!runtime.options?.json) return
+    process.stdout.write(JSON.stringify(buildReport(), null, 2) + '\n')
+}

package/src/source.js

@@ -43,7 +43,8 @@ import { globby } from 'globby'
 import pMap from 'p-map'
 import runtime from './runtime.js'
 import { ACTION } from './constants.js'
-import { checksum as fileChecksum, junkIgnore } from './utils.js'
+import { checksum as fileChecksum, checksumOf, junkIgnore } from './utils.js'
+import { reportGated } from './report.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { useDatabase } from './database/index.js'
 
@@ -74,7 +75,14 @@ const SCAN_CONCURRENCY = 16
 // no SQL) instead of per-file findById. The single-file chokidar
 // event handler (no scan context) doesn't pass it and falls back to
 // findById, which is fine for low-frequency one-off mutations.
-export async function gateChecksum(file, id, { reload = false, priorChecksums } = {}) {
+// `bytes`, when given, is content the caller has ALREADY read: the checksum
+// is derived from those exact bytes rather than from a second, independent
+// read. That is the whole point — two reads of a file being written can
+// disagree, and the losing combination (empty content + a checksum correct
+// for the finished file) is permanent, because every later sync then
+// short-circuits on "unchanged".
+export async function gateChecksum(file, id, { reload = false, priorChecksums, bytes } = {}) {
+    const compute = () => (bytes !== undefined ? checksumOf(bytes) : fileChecksum(file))
     const canGate = !reload
         && !runtime.options.force
         && !runtime.catalog?.cacheInvalidated
@@ -83,12 +91,12 @@ export async function gateChecksum(file, id, { reload = false, priorChecksums }
             ? priorChecksums.get(id)
             : findById(id)?.checksum
         if (priorChecksum) {
-            const current = await fileChecksum(file)
+            const current = await compute()
             if (priorChecksum === current) return null
             return current
         }
     }
-    return await fileChecksum(file)
+    return await compute()
 }
 
 // Delete sweep. After a scan, find every catalog entity in `collection`
@@ -263,9 +271,17 @@ export function useSource(core, options) {
     const prefix = idPrefix ?? `/${collection}`
     const cap = collection.replace(/^./, c => c.toUpperCase())
     const progressLabel = progress ?? `${cap} import`
+    // A SINGLE extension must not go through brace syntax: `**/*.{css}`
+    // matches NOTHING in minimatch/globby — a one-element brace is not
+    // expanded — so a source declaring one extension silently imported zero
+    // files and reported "Styles loaded: 0" as though the folder were empty.
+    // Same shape as the other silent-declaration failures: green build,
+    // nothing there.
     const pattern = extensions.includes('*')
         ? '**/*'
-        : `**/*.{${extensions.join(',')}}`
+        : extensions.length === 1
+            ? `**/*.${extensions[0]}`
+            : `**/*.{${extensions.join(',')}}`
 
     // Hot-reload — chokidar dispatches into onSync(collection) when
     // a file inside the folder changes.
@@ -413,9 +429,31 @@ export function useSource(core, options) {
             : `${prefix}/${relativePath.replace(/\\/g, '/')}`
         scanned?.add(id)
 
-        const chksum = await gateChecksum(file, id, { reload, priorChecksums })
+        // When this source stores content, read the file ONCE and let both
+        // the checksum and the stored body come from the same bytes. The
+        // previous shape hashed the file in gateChecksum and then read it
+        // again below — two reads, and a torn write between them persisted
+        // an empty body next to a valid checksum, permanently.
+        //
+        // No extra cost: the gate already read the whole file to hash it.
+        // Only for `content` sources; large media goes through files.js,
+        // which stores no body and must not be slurped into memory.
+        let bytes
+        if (content) {
+            try {
+                bytes = await readFile(file)
+            } catch (err) {
+                logger.warn('%s read failed for %s: %s', collection, name, err.message)
+                return
+            }
+        }
+
+        const chksum = await gateChecksum(file, id, { reload, priorChecksums, bytes })
         if (chksum === null) {
             if (stats) stats.skipped++
+            // Never becomes a render task, so it would otherwise be invisible
+            // in the --json report. Counted, not listed.
+            reportGated()
             return
         }
 
@@ -430,12 +468,9 @@ export function useSource(core, options) {
             checksum: chksum,
         }
         if (content) {
-            try {
-                base.content = await readFile(file, 'utf8')
-            } catch (err) {
-                logger.warn('%s read failed for %s: %s', collection, name, err.message)
-                return
-            }
+            // Decoded from the bytes the checksum was taken over — not
+            // re-read. See the gate above.
+            base.content = bytes.toString('utf8')
         }
         try {
             const extra = await load({ file, name, relativePath, entity: base })

package/src/utils.js

@@ -1,9 +1,8 @@
 import crypto from 'node:crypto'
-import { hashFile, hash } from 'hasha'
-import { stat, readFile, writeFile, mkdir, unlink } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { hashFile } from 'hasha'
+import { stat, readFile, writeFile, mkdir, unlink, open } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import TruncateStream from 'truncate-stream'
-import { createReadStream } from 'node:fs'
 import _ from 'lodash'
 import { minimatch } from 'minimatch'
 import path from 'path'
@@ -27,6 +26,18 @@ export function inputHashOf(entity) {
     return crypto.createHash('sha1').update(JSON.stringify({
         meta: entity.meta ?? null,
         content: entity.content ?? null,
+        // `inputs` is how a plugin declares bytes that are NOT part of the
+        // entity's own content but that its output depends on. Whatever is
+        // put here participates in the hash, so a change to it invalidates
+        // every consumer through the normal refClosure path.
+        //
+        // The case that needed it: a layout's `.js` sidecar. It is the
+        // entity's data layer, it is not its content, and it was in no hash
+        // at all — so editing it re-rendered nothing, silently, in a fresh
+        // build. Moving the layout's gate `checksum` was not enough, because
+        // an entity that HAS content is hashed on {meta, content} and its
+        // checksum is ignored. This is the seam that was missing.
+        inputs: entity.inputs ?? null,
     })).digest('hex')
 }
 
@@ -301,17 +312,68 @@ export class AbortError extends Error {
     }
 }
 
+const CHECKSUM_MAX_BYTES = 300 * 1024
+
+// Checksum from bytes the CALLER ALREADY HAS — no I/O, and therefore no
+// second read to disagree with the first.
+//
+// The hazard this exists to remove: a plugin that stores content does
+//
+//     meta: { body: await readFile(source, 'utf8') },
+//     checksum: await checksum(source),
+//
+// which is two independent reads of the same file. A watcher firing on the
+// truncate half of a write gets '' from readFile while checksum(), a moment
+// later, sees the finished file. The entity is stored with an empty body and
+// a checksum that is CORRECT FOR THE FINAL CONTENT — so every later sync
+// short-circuits on "unchanged" and the empty body is permanent. Only
+// --clear recovers it, and nothing anywhere reports a problem.
+//
+// Byte-compatible with checksum(uri) below, deliberately: the two must be
+// interchangeable or swapping a caller over would invalidate its catalog.
+export function checksumOf(content) {
+    const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8')
+    if (buf.length < CHECKSUM_MAX_BYTES) {
+        return createHash('md5').update(buf).digest('hex')
+    }
+    const head = createHash('md5').update(buf.subarray(0, CHECKSUM_MAX_BYTES)).digest('hex')
+    const tail = createHash('md5').update(buf.subarray(buf.length - CHECKSUM_MAX_BYTES)).digest('hex')
+    return `${buf.length}:${head}:${tail}`
+}
+
+// Checksum a file by path.
+//
+// Files under 300 KB are hashed whole. Larger ones are hashed at both ends
+// plus their length, which reads 600 KB instead of gigabytes — the point of
+// the truncation is that a 1.4 GB video must not be streamed on every cycle.
+//
+// The TAIL is new. The previous form was `size + md5(first 300KB)`, which
+// silently misses any change beyond byte 307200 that preserves the file's
+// length: the checksum matches, the sync reports "unchanged", and the edit
+// is dropped exactly as permanently as the torn-read case above. Hashing
+// both ends does not make this collision-proof — nothing short of a full
+// hash does — but it turns "any late edit of the same length" into
+// "a late edit that also collides on 128 bits".
 export async function checksum(uri) {
-    const maxBytes = 300 * 1024
     const { size } = await stat(uri)
-    if (size < maxBytes) {
+    if (size < CHECKSUM_MAX_BYTES) {
         return await hashFile(uri, { algorithm: 'md5' })
-    } else {
-        const truncate = new TruncateStream({ maxBytes })
-        const fileStream = createReadStream(uri)
-        fileStream.pipe(truncate)
-        const checksum = size.toString() + ':' + await hash(truncate, { algorithm: 'md5' })
-        return checksum
+    }
+    const head = await hashRange(uri, 0, CHECKSUM_MAX_BYTES)
+    const tail = await hashRange(uri, size - CHECKSUM_MAX_BYTES, CHECKSUM_MAX_BYTES)
+    return `${size}:${head}:${tail}`
+}
+
+// md5 of `length` bytes starting at `start`. A positional read, so the
+// bytes in between are never touched.
+async function hashRange(uri, start, length) {
+    const handle = await open(uri, 'r')
+    try {
+        const buf = Buffer.allocUnsafe(length)
+        const { bytesRead } = await handle.read(buf, 0, length, start)
+        return createHash('md5').update(buf.subarray(0, bytesRead)).digest('hex')
+    } finally {
+        await handle.close()
     }
 }