mikser-io 9.96.0 → 9.99.0

package/app.js

@@ -58,6 +58,7 @@ function locate(argv) {
         : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json') }
         : explain                 ? { type: 'report', explain, json: has('--json') }
         : has('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json') }
+        : has('--fingerprint')    ? { type: 'report', fingerprint: true, json: has('--json') }
         : { type: 'build',
             clear: has('--clear'),
             // Not a flag that happens to be set — the client's OUTPUT

package/docs/diagnostics.md

@@ -385,9 +385,21 @@ the content: an upgraded renderer, a changed helper, a dependency that shifted
 under the build.
 
 Only entities that actually rendered can drift, so an ordinary build reports
-on what moved. Under `--force` everything re-renders with unchanged inputs,
-which makes it a full sweep — **`mikser --force` after a package upgrade is
-the regression check**.
+on what moved. Under `--force` every ENTITY re-renders with unchanged inputs,
+which makes it the check for a renderer, helper or dependency that shifted —
+**`mikser --force` after a package upgrade is the regression check for
+rendered output**.
+
+It is not a full sweep, and calling it one was wrong. Derivatives are outside
+it: an asset is re-derived when its source changes or its preset's `revision`
+moves, and `--force` is neither — so on a site with image presets, `--force`
+re-renders the documents and touches no derivative at all. A sharp upgrade,
+which is exactly the kind of dependency shift this paragraph promises to
+catch, is invisible to it.
+
+Use `--render-presets` for that half, and `--fingerprint` before and after to
+compare both halves at once — it hashes the derivatives too, which is the
+thing `find out -type f` cannot do.
 
 ### The rest, briefly
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.96.0",
+  "version": "9.99.0",
   "files": [
     "app.js",
     "index.js",

package/src/engine.js

@@ -13,6 +13,7 @@ import { OPERATION, TASKS } from './constants.js'
 import { changeExtension, formatErrorContext, projectMeta, lookupKeys, siteRootFor } from './utils.js'
 import { reportRendered, reportSkipped, reportError, renderErrorCount, emitReport, finishCycle, reportAssetUse, assetUse } from './report.js'
 import { checkReferences } from './references.js'
+import { fingerprintOutputs } from './fingerprint.js'
 import { toolSchemas, invokeTool, toolResultText, toolResultFailed } from './tools.js'
 import { registerBuiltinTools } from './builtin-tools.js'
 import { useDatabase } from './database/index.js'
@@ -294,6 +295,17 @@ async function reportMissingAssets(logger, alreadyReported = new Set()) {
 // `request` carries the CLIENT's arguments. Reading runtime.options here would
 // answer with the instance's own flags, which are whatever it happened to be
 // started with.
+// Bytes at a size a person reads. Not in the document — that carries the
+// integer, because a caller comparing two builds subtracts.
+function formatBytes(bytes) {
+    if (bytes < 1024) return `${bytes} B`
+    const units = ['kB', 'MB', 'GB']
+    let value = bytes / 1024
+    let unit = 0
+    while (value >= 1024 && unit < units.length - 1) { value /= 1024; unit++ }
+    return `${value.toFixed(1)} ${units[unit]}`
+}
+
 export async function runReportOnly(request = {}) {
     const logger = useLogger()
     const {
@@ -303,6 +315,7 @@ export async function runReportOnly(request = {}) {
         json = runtime.options.json,
         explain = runtime.options.explain,
         auditOutput = runtime.options.auditOutput,
+        fingerprint = runtime.options.fingerprint,
     } = request
 
     if (tools) {
@@ -372,6 +385,25 @@ export async function runReportOnly(request = {}) {
         return report.found ? 0 : 3
     }
 
+    if (fingerprint) {
+        const result = await fingerprintOutputs()
+        if (!result) {
+            logger.error('No output folder — nothing to fingerprint.')
+            return 2
+        }
+        if (json) {
+            process.stdout.write(JSON.stringify({ version: packageInfo.version, ...result }, null, 2) + '\n')
+        } else {
+            logger.notice('Output %s — %d file(s), %s',
+                result.output.hash, result.output.files, formatBytes(result.output.bytes))
+            for (const [name, group] of Object.entries(result.trees)) {
+                logger.info('  %s: %s — %d file(s), %s',
+                    name, group.hash, group.files, formatBytes(group.bytes))
+            }
+        }
+        return 0
+    }
+
     if (auditOutput) {
         if (!runtime.manifest) {
             logger.error('Verify: no manifest available — nothing to check against')
@@ -517,6 +549,9 @@ export async function setup(options) {
             .option('--tools', 'list the tools this build exposes, then exit', false)
             .option('--tool <name>', 'run one tool and print its result, then exit. The same tools an MCP client sees, so an agent reading CLI output and an agent speaking MCP ask the engine the same questions.')
             .option('--tool-args <json>', 'JSON arguments for --tool (e.g. \'{"destination":"/bg/index.html"}\')')
+            .option('--fingerprint', 'hash everything this build wrote — including what it wrote through a '
+                + 'symlink, which `find` does not descend into — and exit. One comparable number per output '
+                + 'tree, plus one per asset preset, for proving an upgrade moved no bytes.', 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')
@@ -544,11 +579,16 @@ Which check answers which question:
                             with themselves.
 
   Did an upgrade change what a render produces?
-      --force               re-renders everything and reports output-drift:
+      --force               re-renders every ENTITY and reports output-drift:
                             same inputs, different bytes. This is the one that
                             catches a renderer, helper or dependency moving
                             under the build. It also reconciles deletions.
 
+                            NOT derivatives. Assets are re-derived on a preset
+                            revision or a source change, and --force is
+                            neither — so a sharp upgrade is invisible to it.
+                            Use --render-presets for that half.
+
   Do the URLs in the output point at anything?
       (runs every build)    reads the emitted html and css and resolves each
                             reference the way a browser would. Reports what
@@ -566,6 +606,24 @@ Which check answers which question:
                             A boot operation: it is refused while an instance
                             is running in the same folder.
 
+  Did an upgrade move any bytes?
+      --fingerprint         hash everything the build wrote, including what it
+                            wrote THROUGH A SYMLINK — files() emits by
+                            symlinking and assets links the derivatives tree
+                            in, so \`find out -type f\` descends into neither.
+                            One number for the whole output and one per shared
+                            tree, stable across runs. Take it before and after
+                            an upgrade and compare.
+
+  Is this build one a person is waiting on?
+      (automatic)           runtime.options.requested is true for a build a
+                            client asked for — including one forwarded to a
+                            running instance — and false for a watcher's own
+                            cycle. An expensive check reads it to stand down in
+                            the dev loop without standing down forever: an
+                            instance is ALWAYS in watch mode, so watch alone
+                            answers the wrong question.
+
   What did this build do, and cost?
       --json                the whole report as one document on stdout, with
                             every warning carrying a stable code, and per-phase
@@ -1429,10 +1487,10 @@ The full version, with what each code means: docs/diagnostics.md`)
         const brokenTargets = await reportBrokenReferences(useLogger())
         await reportMissingAssets(useLogger(), brokenTargets)
 
-        // 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()
+        // The report is NOT emitted here any more. This hook is registered
+        // when the engine is imported, so it runs first among finalized hooks
+        // and every plugin's findings would land after the document was
+        // written. runtime.finalize() emits it once every hook has run.
 
         // Non-zero for a one-shot build, so `mikser && mikser --audit-output` cannot
         // pass with every page in the site stale. `exitCode` rather than

package/src/fingerprint.js

@@ -0,0 +1,144 @@
+// What this build actually wrote, as one comparable number.
+//
+// Proving an upgrade moved no bytes is the check every mikser project needs,
+// and it is the one thing a shell script cannot compute correctly from
+// outside. A real one, written twice and wrong both times, hit all of this:
+//
+//   - `find out -type f` does NOT descend into a symlink, and files() emits by
+//     symlinking while assets symlinks the whole derivatives tree in. Every
+//     "byte-identical" it printed was a statement about html, css and js only,
+//     with the derivatives silently excluded.
+//   - the derivatives live wherever `assetsFolder` says, which is config the
+//     script had to re-derive.
+//   - hashing per directory block meant the order depended on the order the
+//     blocks came back, and two runs over byte-identical trees hashed
+//     differently — a false CHANGED, which sends someone hunting a regression
+//     that never happened.
+//   - which presets are cheap to re-render (sharp, an npm dependency that an
+//     upgrade CAN change) and which are not (ffmpeg, a host binary it cannot)
+//     had to be inferred by grepping the preset sources.
+//
+// The engine knows all four without inferring anything. So it answers, and the
+// script that orchestrates the upgrade keeps only the part that is genuinely
+// its own: talking to npm.
+
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { stat, lstat } from 'node:fs/promises'
+import { globby } from 'globby'
+import runtime from './runtime.js'
+
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex')
+}
+
+// Streamed, not read into memory. A derivatives tree is the largest thing in
+// the output and the reason to fingerprint at all; loading a 40MB video to
+// hash it would make the check cost more than the build.
+function hashFile(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256')
+        createReadStream(file)
+            .on('error', reject)
+            .on('data', chunk => hash.update(chunk))
+            .on('end', () => resolve(hash.digest('hex')))
+    })
+}
+
+// One hash over a sorted list of `path\0contentHash` lines.
+//
+// The sort lives HERE and nowhere else. It used to be applied to the file list
+// as well, which made this one redundant and therefore untestable — and a
+// redundant guard is one that gets removed later by someone who checks that
+// the tests still pass. Sorting where the hash is computed also makes each
+// tree group order-independent on its own, rather than only by inheritance
+// from the walk.
+//
+// The path is part of the input: a file that moved is a change, and a hash of
+// contents alone would call a rename identical.
+// Exported because these two properties — order independence and path
+// sensitivity — are properties of the HASH, not of a build, and a scenario
+// cannot force globby to return files in a hostile order to check them.
+export function combineEntries(entries) {
+    const lines = entries
+        .map(({ file, hash }) => `${file}\0${hash}`)
+        .sort()
+        .join('\n')
+    return sha256(lines)
+}
+
+
+// Everything the build wrote, including what it wrote through a symlink.
+//
+// `followSymbolicLinks: true` is the whole point — see above. `onlyFiles`
+// keeps directory symlinks from being listed as entries in their own right
+// while still descending through them.
+export async function fingerprintOutputs() {
+    const outputFolder = runtime.options?.outputFolder
+    if (!outputFolder) return null
+
+    const files = await globby('**/*', {
+        cwd: outputFolder,
+        followSymbolicLinks: true,
+        onlyFiles: true,
+        suppressErrors: true,
+        dot: true,
+    })
+
+    const entries = []
+    let bytes = 0
+    for (const file of files) {
+        const absolute = path.join(outputFolder, file)
+        try {
+            const info = await stat(absolute)
+            bytes += info.size
+            entries.push({ file, hash: await hashFile(absolute), size: info.size })
+        } catch { /* vanished mid-walk — a concurrent build, not our business */ }
+    }
+
+    // Broken out per shared tree, because the parts of an output answer
+    // different questions about an upgrade. A preset rendering through an npm
+    // dependency (sharp) can move when that dependency does; one shelling out
+    // to a host binary (ffmpeg) cannot, and re-rendering it to find that out
+    // costs minutes. A caller comparing releases can hash the whole output, or
+    // just the groups whose renderer an upgrade could have touched.
+    //
+    // The trees are found by asking the OUTPUT, not the plugin that made them.
+    // A report-only command runs in an onLoaded registered when the engine is
+    // imported, which is before every plugin's — so runtime.options.assets is
+    // not set yet and reading it grouped nothing at all. The filesystem knows
+    // the same fact and knows it in every phase: a top-level entry that is a
+    // symlink to a directory is a tree emitted from elsewhere, which is what
+    // both assets and resources produce and what `find` refuses to descend
+    // into.
+    const groups = {}
+    for (const name of new Set(entries.map(e => e.file.split('/')[0]))) {
+        const top = path.join(outputFolder, name)
+        let linked = false
+        try { linked = (await lstat(top)).isSymbolicLink() } catch { continue }
+        if (!linked) continue
+        const prefix = `${name}/`
+        for (const entry of entries) {
+            if (!entry.file.startsWith(prefix)) continue
+            // `<tree>/<group>/…` — the preset, for an assets tree. A tree
+            // holding files directly is reported under its own name.
+            const rest = entry.file.slice(prefix.length).split('/')
+            const label = rest.length > 1 ? `${name}/${rest[0]}` : name
+            const group = (groups[label] ??= { files: [], bytes: 0 })
+            group.files.push(entry)
+            group.bytes += entry.size
+        }
+    }
+    const trees = groups
+
+    return {
+        output: { hash: combineEntries(entries), files: entries.length, bytes },
+        trees: Object.fromEntries(
+            Object.entries(trees)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([name, group]) => [name, {
+                    hash: combineEntries(group.files), files: group.files.length, bytes: group.bytes,
+                }])),
+    }
+}

package/src/instance.js

@@ -71,7 +71,7 @@ export function socketPath(workingFolder) {
 // ship together, so there is nothing to negotiate and no version to carry.
 //
 //   → { type: 'build',  config, clear, renderPresets }
-//   → { type: 'report', config, tool, tools, toolArgs, explain, auditOutput, json }
+//   → { type: 'report', config, tool, tools, toolArgs, explain, auditOutput, fingerprint, json }
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
 //   ← { type: 'refused', reason, detail }
@@ -399,7 +399,20 @@ function refuseStale(socket, movedFile) {
 // not put the instance into json mode for everyone.
 async function withRequestOutput(request, run) {
     const prior = {}
-    for (const key of ['json', 'tool', 'tools']) {
+    // `requested` is not a flag the client sent — it is the fact that a client
+    // sent anything at all.
+    //
+    // An instance is always in watch or server mode, so a plugin asking "am I
+    // in the dev loop" gets `yes` for a build a PERSON just typed and is
+    // waiting on. An expensive check that stands down in the dev loop then
+    // stands down forever on a project whose documented model is a watcher
+    // always up — it never runs, and says nothing, which is the failure this
+    // whole surface exists to remove.
+    //
+    // Set for the duration of the request and restored with the rest, so a
+    // watcher's own cycle before or after is unaffected.
+    request = { ...request, requested: true }
+    for (const key of ['json', 'tool', 'tools', 'requested']) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
     }

package/src/report.js

@@ -133,6 +133,10 @@ export function resetReport() {
 // an import here would close the cycle.
 runtime.resetReport = resetReport
 
+// And so it can emit the report AFTER every finalized hook, for the same
+// reason and by the same route. See runtime.finalize().
+runtime.emitReport = emitReport
+
 // End of a cycle: stamp it, file it, and wake anyone waiting on it.
 export function finishCycle() {
     if (!runtime.state?.cycle || runtime.state.cycle.finishedAt) return

package/src/runtime.js

@@ -213,6 +213,23 @@ const runtime = {
     async finalize(signal) {
         await this.callHooks(this.hooks.finalize, signal, 'finalize')
         await this.callHooks(this.hooks.finalized, signal, 'finalized')
+
+        // The report is the LAST thing that happens, after every hook that
+        // could still add to it.
+        //
+        // It used to be emitted from the engine's own onFinalized — which is
+        // registered when the engine module is imported, so it ran FIRST among
+        // finalized hooks and every plugin's findings landed after the
+        // document was already written. A plugin could print a warning to the
+        // console and have it absent from --json, with nothing to suggest the
+        // two disagreed.
+        //
+        // That is not a lint bug or a schemas bug; it is one ordering bug that
+        // every plugin inherits, which is why it is fixed here rather than in
+        // each of them. A finding raised through logger.warn reaches the
+        // report because the report is a VIEW of that stream — and a view has
+        // to be taken after the writing stops.
+        await this.emitReport?.()
     },
 
     async sync(operation) {

package/src/tools.js

@@ -129,5 +129,6 @@ export function toolResultFailed(result) {
 // settle and Node drained the loop and left.
 export function isReportOnlyRun() {
     const options = runtime.options ?? {}
-    return Boolean(options.explain || options.auditOutput || options.tool || options.tools)
+    return Boolean(options.explain || options.auditOutput || options.tool || options.tools
+        || options.fingerprint)
 }