mikser-io 9.99.0 → 9.101.0

package/app.js

@@ -68,6 +68,13 @@ function locate(argv) {
             // was started without the flag. So the contract has to travel
             // with the request or it is not honoured at all.
             json: has('--json'),
+            // Travels for the same reason clear and renderPresets do: it
+            // changes what the CYCLE does, and the instance was started
+            // without it. A forwarded --force silently did not force — it
+            // rebuilt whatever the gates let through, which on a settled tree
+            // is nothing, and a caller asking for a full re-render got a no-op
+            // reported as success.
+            force: has('--force', '-f'),
             renderPresets: has('--render-presets') ? (value('--render-presets') ?? true) : undefined }
 
     return {

package/docs/diagnostics.md

@@ -171,6 +171,17 @@ cycle being reported.
 }
 ```
 
+`plugins` breaks a phase down by who spent it:
+
+```
+"plugins": [ { "phase": "finalized", "plugin": "lighthouse", "ms": 6381.1, "calls": 1 } ]
+```
+
+Inside the phases, not beside them — a plugin's time is part of its phase's, so
+the phase totals still add up to `total`. Without it, `finalized` is one number
+covering the reference check, schemas, lint and any audit, and attributing a
+regression to one of them takes a separate measurement each.
+
 Ordered slowest first, so a diff between two versions leads with what moved.
 This exists because the report said what was *done* and never what it *took*: a
 preset fan-out that scanned the whole catalog every cycle shipped and ran for

package/index.js

@@ -5,6 +5,7 @@ export * from './src/auth.js'
 export * from './src/roles.js'
 export * from './src/inventory.js'
 export * from './src/report.js'
+export * from './src/cli.js'
 // The diagnostics behind --explain. Exported so a transport — the MCP tool
 // surface, the api plugin's routes — can serve the same structured report the
 // CLI formats, rather than each one reimplementing the question.

package/package.json

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

package/src/cli.js

@@ -0,0 +1,139 @@
+// CLI options a plugin adds.
+//
+// An option is a contract between a person and a build, and a plugin is where
+// half the build lives — so a plugin that cannot add one has to be reached
+// some other way: an environment variable, a config key that means "do the
+// expensive thing", a wrapper script. All three were tried downstream and all
+// three are worse in the same way: they are invisible to `--help`, they cannot
+// be refused when misspelled, and they do not appear beside the checks they
+// belong next to.
+//
+// The reason it was not possible is an ordering fact rather than a decision.
+// The engine parses argv in onInitialize, and the CONFIG — which is where the
+// plugins are named — is not read until onLoad. At the moment the first parse
+// runs, the engine genuinely does not know what options exist.
+//
+// So the parse happens in two stages, and the second one is the real one:
+//
+//   1. onInitialize — core's own options, tolerating unknowns, because the
+//      table is knowingly incomplete. Enough to find the config and the
+//      folders.
+//   2. after the load phase — every plugin has been constructed and has had
+//      its chance to declare, so the table is complete. argv is parsed again
+//      against it, and NOW an unknown option is an error.
+//
+// The refusal that has to survive this is the one from 9.81.0: a misspelled
+// flag must never be silently ignored. It is not weakened, only moved to the
+// point where "unknown" can actually be decided.
+
+import runtime from './runtime.js'
+
+// What plugins declared, for the message when something is not recognised and
+// for anyone asking what a build's option table actually contains.
+const declared = new Map()
+
+// Declare a CLI option from inside a plugin.
+//
+// Call it while the plugin is being constructed — that is during the load
+// phase, before the second parse. Declaring later is not an error but the
+// option will not be parsed, so it says so rather than doing nothing.
+//
+//   cliOption('--lighthouse', 'audit the built pages with Lighthouse, and exit 0')
+//
+// Reads back from `runtime.options` under commander's usual camel-cased name.
+export function cliOption(flags, description, defaultValue) {
+    const commander = runtime.engine?.commander
+    if (!commander) {
+        throw new Error('cliOption: no commander yet — call it while the plugin is being constructed')
+    }
+    if (runtime.engine.cliSealed) {
+        throw new Error(
+            `cliOption(${JSON.stringify(flags)}): the option table was already parsed. `
+            + 'Declare options while the plugin is constructed (the load phase), not afterwards — '
+            + 'a later one would never be read and the flag would look ignored.')
+    }
+    if (declared.has(flags)) return declared.get(flags)
+    const option = defaultValue === undefined
+        ? commander.option(flags, description)
+        : commander.option(flags, description, defaultValue)
+    declared.set(flags, option)
+    return option
+}
+
+// Every option a plugin added, in declaration order.
+export function pluginCliOptions() {
+    return [...declared.keys()]
+}
+
+// Stage two: the table is complete, so parse for real.
+//
+// Called once, after the load phase. Merges what the complete table yields
+// over what stage one produced — a plugin's option lands here for the first
+// time, and core's own options parse identically both times.
+export function completeCliParse() {
+    const commander = runtime.engine?.commander
+    if (!commander || runtime.engine.cliSealed) return
+    runtime.engine.cliSealed = true
+
+    // Always, even when no plugin declared anything.
+    //
+    // Stage one tolerates an unknown option AND the excess argument it then
+    // looks like, so it cannot be the stage that judges argv — left to it,
+    // `mikser --bogus-flag` came back "too many arguments. Expected 0
+    // arguments but got 1", which is commander describing its own internal
+    // reading rather than the mistake a person made. Skipping stage two when
+    // no plugin declared would leave exactly that message on most builds.
+    //
+    // Strict here: every option any part of this build understands is
+    // registered, so anything left over is a misspelling, and saying which one
+    // is the whole point of the refusal.
+    commander.allowUnknownOption(false).allowExcessArguments(false)
+
+    // Help, now that the table is complete — including every option the
+    // project's own plugins declared, which is the whole reason it waited.
+    if (runtime.engine.helpRequested) {
+        commander.outputHelp()
+        process.exit(0)
+    }
+
+    commander.parse(process.argv)
+    Object.assign(runtime.options, commander.opts())
+}
+
+// The plugin-declared options carried by a client's argv.
+//
+// A forwarded build is answered by an INSTANCE, which parsed its own argv
+// (`--watch`) and never saw the client's. Core's own request options — json,
+// clear, renderPresets — each travel explicitly for exactly this reason. A
+// plugin option has to as well, or `mikser --lighthouse` works with nothing
+// listening and silently does nothing with a watcher up, which is the failure
+// this whole surface exists to remove.
+//
+// Read from the argv the client sent, against the table the INSTANCE has:
+// both processes load the same config, so the instance knows every option the
+// client could legitimately have passed.
+export function pluginOptionsFrom(argv) {
+    const commander = runtime.engine?.commander
+    if (!commander || !declared.size || !Array.isArray(argv)) return {}
+    // A throwaway parse: `parseOptions` reads without applying, so the
+    // instance's own options are untouched by asking what a client sent.
+    let parsed
+    try {
+        const probe = commander.createCommand()
+        for (const flags of declared.keys()) probe.option(flags, '')
+        probe.allowUnknownOption(true).allowExcessArguments(true)
+        probe.parse(argv, { from: 'user' })
+        parsed = probe.opts()
+    } catch {
+        return {}
+    }
+    // Only what a plugin declared. Core's options travel on the request
+    // itself, and re-applying them from argv here would give two sources for
+    // one answer.
+    const names = new Set(Object.keys(parsed))
+    const values = {}
+    for (const name of names) {
+        if (parsed[name] !== undefined) values[name] = parsed[name]
+    }
+    return values
+}

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 { completeCliParse } from './cli.js'
 import { fingerprintOutputs } from './fingerprint.js'
 import { toolSchemas, invokeTool, toolResultText, toolResultFailed } from './tools.js'
 import { registerBuiltinTools } from './builtin-tools.js'
@@ -624,6 +625,11 @@ Which check answers which question:
                             instance is ALWAYS in watch mode, so watch alone
                             answers the wrong question.
 
+  Is the page fast, and can it be read?
+      --lighthouse          from mikser-io-lighthouse, if installed. A plugin
+                            declares its own options now, and they appear here
+                            beside core's — see cliOption().
+
   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
@@ -632,7 +638,34 @@ Which check answers which question:
 
 The full version, with what each code means: docs/diagnostics.md`)
 
-        Object.assign(runtime.options, options || runtime.engine.commander.parse(process.argv).opts())
+        // Stage one of two. The config names the plugins and is not read
+        // until onLoad, so at this moment the engine does not yet know every
+        // option this build understands — a plugin's is not registered. Left
+        // strict, `mikser --lighthouse` would be rejected before the plugin
+        // that defines it had been constructed.
+        //
+        // Tolerated here and decided in stage two, where the table is complete
+        // — see completeCliParse(). The 9.81.0 refusal is not weakened, it is
+        // moved to the point where "unknown" can be answered.
+        runtime.engine.commander.allowUnknownOption(true).allowExcessArguments(true)
+
+        // --help is answered in stage two, for the same reason the parse is.
+        //
+        // Commander prints help and exits the moment it sees the flag, which
+        // in stage one is before any plugin has been constructed — so the help
+        // would list core's options and silently omit every option the
+        // project's own plugins add. A help text that is missing the flag you
+        // are looking for is worse than a slower one.
+        //
+        // Held out of this parse and answered after the table is complete. It
+        // does mean `--help` now loads the config, which is the honest cost of
+        // describing THIS project's mikser rather than a generic one.
+        const helpFlags = ['--help', '-h']
+        runtime.engine.helpRequested = process.argv.some(arg => helpFlags.includes(arg))
+        const argv = runtime.engine.helpRequested
+            ? process.argv.filter(arg => !helpFlags.includes(arg))
+            : process.argv
+        Object.assign(runtime.options, options || runtime.engine.commander.parse(argv).opts())
         // runtime.options.info gates the progress bar — gauge stays
         // silent in --debug/--trace modes because logs are voluminous
         // there and a bar on top would just be noise.
@@ -778,6 +811,15 @@ The full version, with what each code means: docs/diagnostics.md`)
     })
 
     onLoaded(async () => {
+        // Stage two of the parse, before anything reads an option.
+        //
+        // Every plugin has been constructed by now and has had its chance to
+        // declare, so the table is complete and argv is parsed against all of
+        // it. This engine hook is registered when the module is imported, so
+        // it runs ahead of every plugin's own onLoaded — which is what makes
+        // it safe for a plugin to read its own option there.
+        completeCliParse()
+
         const logger = useLogger()
         logger.debug(runtime.options, 'Mikser options')
 

package/src/instance.js

@@ -38,6 +38,7 @@ import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
 import { runReportOnly } from './engine.js'
 import { emitReport } from './report.js'
+import { pluginOptionsFrom } from './cli.js'
 
 // Where the endpoint lives.
 //
@@ -416,6 +417,17 @@ async function withRequestOutput(request, run) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
     }
+
+    // Whatever the client's argv said about a PLUGIN's options.
+    //
+    // The instance parsed its own argv and never saw the client's, so a flag a
+    // plugin declared worked with nothing listening and did nothing with a
+    // watcher up. Applied and restored with the rest of the request's
+    // contract, so a watcher's own cycle before or after is unaffected.
+    for (const [name, value] of Object.entries(pluginOptionsFrom(request.argv))) {
+        if (!(name in prior)) prior[name] = runtime.options[name]
+        runtime.options[name] = value
+    }
     try {
         return await run()
     } finally {
@@ -450,6 +462,10 @@ async function serveBuild(socket, request, logger) {
         // rebuild.
         const priorRenderPresets = runtime.options.renderPresets
         if (request.renderPresets !== undefined) runtime.options.renderPresets = request.renderPresets
+        // Applied for THIS cycle only, like renderPresets. An instance left in
+        // force mode would re-render the whole site on every later save.
+        const priorForce = runtime.options.force
+        if (request.force) runtime.options.force = true
         try {
             // The report is emitted by the cycle itself, from inside
             // rebuild() — the same call a one-shot makes. Nothing here
@@ -471,6 +487,7 @@ async function serveBuild(socket, request, logger) {
             })
         } finally {
             runtime.options.renderPresets = priorRenderPresets
+            runtime.options.force = priorForce
         }
 
         // From the render-error count, NOT from process.exitCode.

package/src/plugins.js

@@ -110,11 +110,35 @@ onLoad(() => {
     if (registeredPostprocessors) parts.push(`${registeredPostprocessors} postprocessor${registeredPostprocessors === 1 ? '' : 's'}`)
     logger.info('Loading plugins: %s', parts.join(', '))
 
-    for (const factoryReturn of factoryEntries) {
+    // Which plugin registered which hook, so a phase can be broken down.
+    //
+    // `timings` said `finalized: 19400ms` and stopped there — and finalized is
+    // where the reference check, schemas, lint and lighthouse all live, so the
+    // one number said nothing about which of them cost it. Downstream that
+    // took three separate measurements to attribute a 465ms lint pass.
+    //
+    // Labelled retroactively, because a plugin's identity is not knowable
+    // until its factory RETURNS: the entry in the plugins array is already the
+    // factory's result, so there is no name to read going in, and the
+    // descriptor with `collection` on it only exists coming out. So the hooks
+    // are diffed across the call and tagged with what the call produced.
+    const hookNames = Object.keys(runtime.hooks)
+    for (const [index, factoryReturn] of factoryEntries.entries()) {
+        const before = new Map(hookNames.map(name => [name, runtime.hooks[name].length]))
+        let descriptor
         try {
-            factoryReturn(core)
+            descriptor = factoryReturn(core)
         } catch (err) {
             logger.error('Plugin factory threw on registration: %s', err.message)
+            continue
+        }
+        const label = descriptor?.collection ?? descriptor?.type ?? `plugin-${index + 1}`
+        for (const name of hookNames) {
+            for (const hook of runtime.hooks[name].slice(before.get(name))) {
+                // A plugin registering the same function twice keeps its first
+                // label rather than being renamed by a later registration.
+                if (typeof hook === 'function' && !hook.mikserPlugin) hook.mikserPlugin = label
+            }
         }
     }
 })

package/src/report.js

@@ -126,6 +126,8 @@ export function resetReport() {
     // asking. The boot phases therefore appear in the first cycle's report and
     // not in later ones, which is what actually happened.
     runtime.state.timings = {}
+    runtime.state.pluginTimings = {}
+    runtime.state.activity = { rendered: 0, changed: 0 }
 }
 
 // Published on the runtime so runtime.js can start a fresh cycle for a
@@ -194,6 +196,7 @@ export function reportWipe(cause, detail = {}) {
 // One source whose bytes moved. The complement of reportGated: between them
 // every file the engine looked at is accounted for.
 export function reportChanged(id) {
+    if (id) activity().changed++
     if (!reportWanted() || !id) return
     const store = changedStore()
     store.count++
@@ -277,6 +280,7 @@ export function reportGated(count = 1) {
 // `matched`, `dependency` each mean something specific, and a single
 // polymorphic key would push the type switch onto every consumer.
 export function reportRendered(entity, reason, decision = {}) {
+    activity().rendered++
     if (!reportWanted()) return
     store().rendered.push({
         id: entity?.id,
@@ -425,6 +429,45 @@ export function renderErrorCount() {
     return errorStore().length
 }
 
+// A bare count of what the cycle did, kept whether or not anyone is reading
+// the report.
+//
+// The rendered/skipped/unchanged ARRAYS are only recorded when something can
+// read them — one entry per entity per cycle is not free, which is why `gated`
+// was already a bare count. So a check asking "did this cycle do anything"
+// cannot read those arrays: without --json they are empty, and a cold build
+// that rendered the whole site looks identical to a no-op. That is exactly the
+// mistake the first version of cycleMovedNothing() made, and it reported
+// "nothing moved" on a build that had just rendered.
+//
+// Two integers cost nothing and are always true.
+function activity() {
+    runtime.state ??= {}
+    runtime.state.activity ??= { rendered: 0, changed: 0 }
+    return runtime.state.activity
+}
+
+// Did this cycle move anything?
+//
+// For a check that reads the OUTPUT — a linter, an audit — a cycle that
+// rendered nothing and changed nothing produced the same bytes the last one
+// did, so running again spends time to reprint what was already said.
+// Downstream that was measured: a lint pass costing 465ms of every no-op
+// rebuild, and a Lighthouse audit costing 19 SECONDS of one.
+//
+// Both halves matter. `rendered` alone is not enough: files() emits by
+// symlinking rather than rendering, so a new static file changes the output
+// with nothing rendered. `changed` covers that — it counts the sources whose
+// bytes moved this cycle.
+//
+// A plugin skipping on this must SAY so. "Nothing to report" and "did not run"
+// are indistinguishable otherwise, which is the property this codebase keeps
+// having to remove.
+export function cycleMovedNothing() {
+    const { rendered, changed } = activity()
+    return rendered === 0 && changed === 0
+}
+
 // The cause, and enough detail to act on it.
 //
 // A wipe outranks changed sources: when the cache went, everything is a
@@ -451,6 +494,12 @@ function phaseTimings() {
     const entries = Object.entries(timings)
         .map(([phase, { ms, calls }]) => ({ phase, ms: Math.round(ms * 10) / 10, calls }))
         .sort((a, b) => b.ms - a.ms)
+    // Inside the phases, not beside them: a plugin's time is part of its
+    // phase's, so this is a breakdown rather than an addition.
+    const byPlugin = Object.values(runtime.state?.pluginTimings ?? {})
+        .map(({ phase, plugin, ms, calls }) => ({ phase, plugin, ms: Math.round(ms * 10) / 10, calls }))
+        .sort((a, b) => b.ms - a.ms)
+
     return {
         // This cycle, summed. The phases below add up to it.
         total: Math.round(entries.reduce((sum, e) => sum + e.ms, 0) * 10) / 10,
@@ -467,6 +516,7 @@ function phaseTimings() {
         // misled by a name like "elapsed".
         processUptime: Math.round(process.uptime() * 1000 * 10) / 10,
         phases: entries,
+        ...(byPlugin.length ? { plugins: byPlugin } : {}),
     }
 }
 

package/src/runtime.js

@@ -82,6 +82,19 @@ const runtime = {
     //
     // Accumulated per phase rather than assigned, because a phase runs more
     // than once in a watch process and a cycle can re-enter one.
+    // Per plugin within a phase. Kept apart from `phases` so the phase totals
+    // still add up to `total` — a plugin's time is INSIDE its phase, not
+    // beside it, and adding both would double-count the run.
+    recordPluginPhase(phaseName, plugin, ms) {
+        if (!phaseName || !plugin) return
+        this.state ??= {}
+        const byPlugin = (this.state.pluginTimings ??= {})
+        const key = `${phaseName}:${plugin}`
+        const entry = (byPlugin[key] ??= { phase: phaseName, plugin, ms: 0, calls: 0 })
+        entry.ms += ms
+        entry.calls++
+    },
+
     recordPhase(phaseName, ms) {
         if (!phaseName) return
         this.state ??= {}
@@ -101,7 +114,14 @@ const runtime = {
         try {
             for (let hook of hooks) {
                 if (signal?.aborted) throw new AbortError()
+                // Timed per hook when it belongs to a plugin, so a phase can
+                // be broken down by who spent it. `finalized` alone is where
+                // the reference check, schemas, lint and an audit all live.
+                const hookStarted = hook.mikserPlugin ? performance.now() : 0
                 await hook(signal)
+                if (hook.mikserPlugin) {
+                    this.recordPluginPhase(phaseName, hook.mikserPlugin, performance.now() - hookStarted)
+                }
             }
         } finally {
             // In `finally`, so a phase that threw still reports what it spent