mikser-io 9.96.0 → 9.97.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.96.0",
+  "version": "9.97.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')
@@ -566,6 +601,15 @@ 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.
+
   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

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 }

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)
 }