mikser-io 9.66.0 → 9.67.0

package/CLAUDE.md

@@ -242,7 +242,11 @@ brevity.
   EINVAL`. chmod 0600, so the filesystem permission is the access
   decision. A forwarded build RESCANS (`runtime.rebuild()`), never
   drains: a client can beat the inotify event for the file it just
-  wrote. Exit code comes from `renderErrorCount()`, not
+  wrote. Report-only commands (`--tool`, `--tools`, `--verify`,
+  `--explain`) forward too — they read, so a local run damaged nothing,
+  but a catalogue another process is mid-write in is not one anyone can
+  answer from. `runReportOnly()` in engine.js is the one implementation
+  both paths call. Exit code comes from `renderErrorCount()`, not
   `process.exitCode` — the engine suppresses that in watch mode by
   design. Config mismatch is refused by resolved PATH; config drift
   under a running instance is detected by stat over `configCoverage`.

package/app.js

@@ -24,27 +24,37 @@ function locate(argv) {
         }
         return null
     }
-    const has = (...names) => names.some(n => argv.includes(n))
+    const has = (...names) => names.some(n => argv.includes(n) || argv.some(a => names.some(x => a.startsWith(`${x}=`))))
+
+    // What to ask the instance for. Report-only commands go over the same
+    // socket as a build: they read, so running them locally never damaged
+    // anything, but a catalogue being written by another process is not a
+    // catalogue anyone can answer from — a --verify against a half-finished
+    // cycle reports drift that is not there.
+    const tool = value('--tool')
+    const explain = value('--explain')
+    const request = has('--tools') ? { type: 'report', tools: true, json: has('--json') }
+        : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json') }
+        : explain                 ? { type: 'report', explain, json: has('--json') }
+        : has('--verify')         ? { type: 'report', verify: true, json: has('--json') }
+        : { type: 'build', clear: has('--clear') }
+
     return {
         workingFolder: value('--working-folder', '-i') ?? '.',
         config: value('--config', '-c') ?? 'mikser.config.js',
-        clear: has('--clear'),
         // Commander's negated form: `attach` is true unless --no-attach said so.
         attach: has('--no-attach') ? false : true,
-        // Report-only runs read; they do not write the catalogue or the output
-        // tree, and their handlers exit the process themselves. Left local —
-        // the guard in setup() still says an instance is there.
-        reportOnly: has('--tool', '--tools', '--verify', '--explain'),
+        request,
     }
 }
 
 async function main() {
     const where = locate(process.argv.slice(2))
-    if (where.attach !== false && !where.reportOnly) {
+    if (where.attach !== false) {
         const code = await forward({
             workingFolder: path.resolve(where.workingFolder),
             config: path.resolve(where.workingFolder, where.config),
-            clear: where.clear,
+            request: where.request,
         })
         // null means nobody was listening — carry on exactly as before.
         if (code !== null) process.exit(code)

package/docs/diagnostics.md

@@ -759,6 +759,14 @@ Three things it refuses or reports rather than guessing:
 - **A folder held by someone else.** `--no-attach` runs a private engine
   anyway — for checking that a cold start works — and says the folder is held.
 
+`--tool`, `--tools`, `--verify` and `--explain` forward as well, and for a
+different reason than builds do. They only read, so running one locally never
+damaged anything — it just could not be trusted: on a large site a local
+`--verify` reads a catalogue the instance is halfway through writing and
+reports drift that is a cycle in progress. The instance has the settled state
+and the config that produced it. Exit codes cross the socket unchanged, so
+`--explain` still answers 3 for an entity that is not there.
+
 A forwarded build **rescans**; it does not drain what the watcher happened to
 queue. A client that writes a file and immediately asks can beat the file
 event, and draining would then build without the change that prompted the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.66.0",
+  "version": "9.67.0",
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/engine.js

@@ -89,6 +89,127 @@ function workerSafeOptions(opts) {
     return result
 }
 
+// The report-only commands, as functions that RETURN their exit code.
+//
+// They used to be inline here and call process.exit, which is fine for a
+// process whose only job is to answer one question and stop. It is not fine
+// for the instance that has to answer the same question on behalf of a client
+// and stay alive — and answering it there is the point, because a local run
+// reads a catalogue another process is in the middle of writing.
+//
+// `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.
+export async function runReportOnly(request = {}) {
+    const logger = useLogger()
+    const {
+        tools = runtime.options.tools,
+        tool = runtime.options.tool,
+        toolArgs = runtime.options.toolArgs,
+        json = runtime.options.json,
+        explain = runtime.options.explain,
+        verify = runtime.options.verify,
+    } = request
+
+    if (tools) {
+        const schemas = toolSchemas()
+        if (json) {
+            process.stdout.write(JSON.stringify(schemas, null, 2) + '\n')
+        } else if (!schemas.length) {
+            logger.warn('No tools registered. The mcp plugin registers the standard set; '
+                + 'this flag only lists and invokes what is registered.')
+        } else {
+            for (const schema of schemas) {
+                process.stdout.write(`${schema.name}\n    ${String(schema.description).split('\n')[0]}\n`)
+            }
+        }
+        return 0
+    }
+
+    if (tool) {
+        // An empty catalog answers every question with a confident nothing —
+        // `null`, `total: 0`, "no render claims this destination" — all of
+        // which read as "the thing you asked about does not exist" when the
+        // truth is "nothing has been built here yet". Said once, before the
+        // answer, so it cannot be missed.
+        const entityCount = (() => {
+            try {
+                return useDatabase().handle
+                    .prepare('SELECT count(*) AS n FROM mikser_entities').get()?.n ?? 0
+            } catch { return null }
+        })()
+        if (entityCount === 0 && !runtime.manifest?.size?.()) {
+            logger.warn('The catalog and manifest are empty — no build has run in this working '
+                + 'folder. Tools answer from what the last build recorded, so this one will '
+                + 'report nothing found. Run a build first.')
+        }
+
+        let args = {}
+        if (toolArgs) {
+            try {
+                args = JSON.parse(toolArgs)
+            } catch (err) {
+                logger.error('--tool-args is not valid JSON: %s', err.message)
+                return 3
+            }
+        }
+        let result
+        try {
+            result = await invokeTool(tool, args)
+        } catch (err) {
+            logger.error('%s', err.message)
+            return 3
+        }
+        process.stdout.write(toolResultText(result) + '\n')
+        // A tool that reports failure must not exit 0 — an agent reading CLI
+        // output has only the exit code to branch on.
+        return toolResultFailed(result) ? 1 : 0
+    }
+
+    if (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)
+        const { explain: explainEntity, formatExplain } = await import('./explain.js')
+        const report = await explainEntity(explain)
+        process.stdout.write((json ? JSON.stringify(report, null, 2) : formatExplain(report)) + '\n')
+        return report.found ? 0 : 3
+    }
+
+    if (verify) {
+        if (!runtime.manifest) {
+            logger.error('Verify: no manifest available — nothing to check against')
+            return 2
+        }
+        const { verdict, missing, mismatched, unverifiable, orphaned, collisions } =
+            await runtime.manifest.verify()
+        const total = runtime.manifest.size()
+
+        for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
+        for (const e of mismatched)   logger.error('Mismatched: %s (entity %s)%s', e.destination, e.id,
+            e.writtenBy ? ` — the bytes on disk are ${e.writtenBy}'s` : '')
+        for (const e of unverifiable) logger.warn('No hash:    %s (entity %s)', e.destination, e.id)
+        for (const e of orphaned)     logger.warn('Orphan:     %s', e.path)
+        // Named per destination: "two entities write here" is only actionable
+        // if you know which two.
+        for (const c of collisions)   logger.warn('Collision:  %s ← %s', c.destination, c.entities.join(', '))
+
+        // Level picked from the verdict, because the level IS the marker in
+        // pino-pretty's messageFormat: notice renders 🟢, warn 🟡, error 🔴. A
+        // fixed `notice` prints a green tick next to the word FAIL, which
+        // reads as success at a glance even though the exit code is right.
+        const report = verdict === 'FAIL' ? logger.error : verdict === 'WARN' ? logger.warn : logger.notice
+        report.call(logger,
+            'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned, %d collisions',
+            verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length, collisions.length)
+        return verdict === 'FAIL' ? 2 : verdict === 'WARN' ? 1 : 0
+    }
+
+    return null   // not a report-only request
+}
+
 export async function setup(options) {
     runtime.options.threads = options?.threads !== undefined ? options.threads : 4
     runtime.engine = {
@@ -291,57 +412,8 @@ export async function setup(options) {
         // registry is complete. Nothing is imported, because this exits first,
         // the same way --explain and --verify do.
         if (runtime.options.tools || runtime.options.tool) {
-            if (runtime.options.tools) {
-                const schemas = toolSchemas()
-                if (runtime.options.json) {
-                    process.stdout.write(JSON.stringify(schemas, null, 2) + '\n')
-                } else if (!schemas.length) {
-                    logger.warn('No tools registered. The mcp plugin registers the standard set; '
-                        + 'this flag only lists and invokes what is registered.')
-                } else {
-                    for (const schema of schemas) {
-                        process.stdout.write(`${schema.name}\n    ${String(schema.description).split('\n')[0]}\n`)
-                    }
-                }
-                process.exit(0)
-            }
-            // An empty catalog answers every question with a confident
-            // nothing — `null`, `total: 0`, "no render claims this
-            // destination" — all of which read as "the thing you asked about
-            // does not exist" when the truth is "nothing has been built here
-            // yet". Said once, before the answer, so it cannot be missed.
-            const entityCount = (() => {
-                try {
-                    return useDatabase().handle
-                        .prepare('SELECT count(*) AS n FROM mikser_entities').get()?.n ?? 0
-                } catch { return null }
-            })()
-            if (entityCount === 0 && !runtime.manifest?.size?.()) {
-                logger.warn('The catalog and manifest are empty — no build has run in this working '
-                    + 'folder. Tools answer from what the last build recorded, so this one will '
-                    + 'report nothing found. Run a build first.')
-            }
-
-            let args = {}
-            if (runtime.options.toolArgs) {
-                try {
-                    args = JSON.parse(runtime.options.toolArgs)
-                } catch (err) {
-                    logger.error('--tool-args is not valid JSON: %s', err.message)
-                    process.exit(3)
-                }
-            }
-            let result
-            try {
-                result = await invokeTool(runtime.options.tool, args)
-            } catch (err) {
-                logger.error('%s', err.message)
-                process.exit(3)
-            }
-            process.stdout.write(toolResultText(result) + '\n')
-            // A tool that reports failure must not exit 0 — an agent reading
-            // CLI output has only the exit code to branch on.
-            process.exit(toolResultFailed(result) ? 1 : 0)
+            const code = await runReportOnly()
+            if (code !== null) process.exit(code)
         }
     })
 
@@ -368,58 +440,11 @@ export async function setup(options) {
         //   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.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')
-                process.exit(2)
-            }
-            const { verdict, missing, mismatched, unverifiable, orphaned, collisions } =
-                await runtime.manifest.verify()
-            const total = runtime.manifest.size()
-
-            for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
-            for (const e of mismatched)   logger.error('Mismatched: %s (entity %s)%s', e.destination, e.id,
-                e.writtenBy ? ` — the bytes on disk are ${e.writtenBy}'s` : '')
-            for (const e of unverifiable) logger.warn('No hash:    %s (entity %s)', e.destination, e.id)
-            for (const e of orphaned)     logger.warn('Orphan:     %s', e.path)
-            // Named per destination: "two entities write here" is only
-            // actionable if you know which two.
-            for (const c of collisions)   logger.warn('Collision:  %s ← %s', c.destination, c.entities.join(', '))
-
-            // Level picked from the verdict, because the level IS the marker
-            // in pino-pretty's messageFormat: notice renders 🟢, warn 🟡,
-            // error 🔴. A fixed `notice` prints a green tick next to the word
-            // FAIL, which reads as success at a glance even though the exit
-            // code is right.
-            const report = verdict === 'FAIL' ? logger.error : verdict === 'WARN' ? logger.warn : logger.notice
-            report.call(logger,
-                'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned, %d collisions',
-                verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length, collisions.length)
-            process.exit(verdict === 'FAIL' ? 2 : verdict === 'WARN' ? 1 : 0)
-        }
+        // The same three commands the instance answers over the socket —
+        // one implementation, so a forwarded --verify cannot disagree with a
+        // local one about what it checked.
+        const code = await runReportOnly()
+        if (code !== null) process.exit(code)
     })
 
     onRender(async (signal) => {

package/src/instance.js

@@ -34,6 +34,7 @@ import { chmod } from 'node:fs/promises'
 import runtime from './runtime.js'
 import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
+import { runReportOnly } from './engine.js'
 
 // Where the endpoint lives.
 //
@@ -66,7 +67,8 @@ export function socketPath(workingFolder) {
 // Newline-delimited JSON, one object per line. Deliberately boring: both ends
 // ship together, so there is nothing to negotiate and no version to carry.
 //
-//   → { type: 'build', config, clear }
+//   → { type: 'build',  config, clear }
+//   → { type: 'report', config, tool, tools, toolArgs, explain, verify, json }
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
 //   ← { type: 'refused', reason, detail }
@@ -97,7 +99,7 @@ function readFrames(socket, onFrame) {
 // which case the caller proceeds exactly as it always did. Called before
 // setup(), so a forwarded command never pays for importing the config or the
 // plugin graph, which is most of what a one-shot spends its time on.
-export function forward({ workingFolder, config, clear }) {
+export function forward({ workingFolder, config, request }) {
     const endpoint = socketPath(workingFolder)
 
     return new Promise((resolve) => {
@@ -116,7 +118,7 @@ export function forward({ workingFolder, config, clear }) {
             resolve(null)
         })
 
-        socket.on('connect', () => frame(socket, { type: 'build', config, clear }))
+        socket.on('connect', () => frame(socket, { ...request, config }))
 
         readFrames(socket, (message) => {
             if (message.type === 'log') {
@@ -219,29 +221,50 @@ async function configStale() {
     return null
 }
 
-async function serveBuild(socket, request, logger) {
-    const wrongConfig = configMismatch(request.config)
-    if (wrongConfig) {
-        frame(socket, {
-            type: 'refused',
-            reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
-            detail: 'Forwarding would build with the wrong config — the accident this refusal exists to prevent. '
-                + 'Stop that instance, or pass --no-attach to run your own.',
-        })
-        return
+// Report-only commands, answered from the live catalogue.
+//
+// These read; they do not write, so running them locally was safe for the
+// FILES. It was not safe for the ANSWER. A local --verify at ten thousand
+// pages reads a catalogue the instance is in the middle of writing and reports
+// drift that is a half-finished cycle, and a local --tool answers from
+// whatever the last build left rather than from what is true now.
+//
+// The instance has the settled state and the config that produced it, so it is
+// the only process that can answer correctly. Same guards as a build: wrong
+// config refuses, drifted config refuses.
+async function serveReport(socket, request, logger) {
+    const restore = captureOutput((chunk) => frame(socket, { type: 'log', chunk }))
+    let code = 0
+    try {
+        code = await runReportOnly(request) ?? 0
+    } catch (err) {
+        logger?.error('instance: forwarded report failed — %s', err.message)
+        code = 3
+    } finally {
+        restore()
     }
+    frame(socket, { type: 'done', code })
+}
 
-    const movedFile = await configStale()
-    if (movedFile) {
-        frame(socket, {
-            type: 'refused',
-            reason: `this instance's config changed on disk since it started (${movedFile}).`,
-            detail: 'It is still building with the old one. Restart it, and this command will reach an '
-                + 'instance that matches what you edited.',
-        })
-        return
-    }
+function refuseConfig(socket, request, wrongConfig) {
+    frame(socket, {
+        type: 'refused',
+        reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
+        detail: 'Answering would use the wrong config — the accident this refusal exists to prevent. '
+            + 'Stop that instance, or pass --no-attach to run your own.',
+    })
+}
 
+function refuseStale(socket, movedFile) {
+    frame(socket, {
+        type: 'refused',
+        reason: `this instance's config changed on disk since it started (${movedFile}).`,
+        detail: 'It is still running the old one. Restart it, and this command will reach an instance that '
+            + 'matches what you edited.',
+    })
+}
+
+async function serveBuild(socket, request, logger) {
     const restore = captureOutput((chunk) => frame(socket, { type: 'log', chunk }))
     let code = 0
     try {
@@ -304,8 +327,20 @@ export function serveInstance() {
         server = net.createServer((socket) => {
             socket.on('error', () => { /* client vanished mid-request */ })
             readFrames(socket, (request) => {
-                if (request.type !== 'build') return
-                chain = chain.then(() => serveBuild(socket, request, logger)).catch(() => {})
+                if (request.type !== 'build' && request.type !== 'report') return
+                chain = chain.then(async () => {
+                    // Both kinds answer for the client's config, not the
+                    // instance's — a report against the wrong config is the
+                    // original incident, and it is wrong whether or not it
+                    // writes anything.
+                    const wrongConfig = configMismatch(request.config)
+                    if (wrongConfig) return refuseConfig(socket, request, wrongConfig)
+                    const movedFile = await configStale()
+                    if (movedFile) return refuseStale(socket, movedFile)
+                    return request.type === 'build'
+                        ? serveBuild(socket, request, logger)
+                        : serveReport(socket, request, logger)
+                }).catch(() => {})
             })
         })
         server.on('error', (err) => {