mikser-io 9.99.0 → 10.0.0

package/app.js

@@ -68,7 +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'),
-            renderPresets: has('--render-presets') ? (value('--render-presets') ?? true) : undefined }
+            // 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') }
 
     return {
         longRunning,

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,11 @@ 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'
+// What one plugin offers another. A plugin publishes an API under a name
+// (provideService) or adds to an extension point (contribute); consumers ask
+// core, never a sibling. Replaces reaching into runtime.options.<plugin>.
+export * from './src/services.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": "10.0.0",
   "files": [
     "app.js",
     "index.js",

package/src/cli.js

@@ -0,0 +1,173 @@
+// 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 —
+// but NOT at construction time. Declaring happens during the load phase and
+// the table is not parsed until after it, so an option read while the plugin
+// is being built is always undefined. Read it in a hook: onLoaded and later
+// all run after stage two. documents() read its folder at construction first,
+// and `--documents content` silently did nothing.
+export function cliOption(flags, description, defaultValue) {
+    // No CLI at all — a plugin constructed by a test harness, or embedded
+    // programmatically through setup({ ... }) rather than run from a terminal.
+    // There is nothing to register the option on and nothing about that is a
+    // mistake, so it returns quietly. Throwing here made every plugin that
+    // declares an option unusable in its own unit tests, which is how this was
+    // found.
+    //
+    // Declaring LATE is still an error — see below — because that one really
+    // is a mistake: the option would never be parsed and the flag would look
+    // ignored.
+    const commander = runtime.engine?.commander
+    if (!commander) return undefined
+    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)
+
+    // ONLY the options a plugin declared.
+    //
+    // Assigning the whole opts() blob put core's own options back to their
+    // parsed values — and by this point the engine has already NORMALISED
+    // several of them. `--working-folder` defaults to './' and onInitialize
+    // resolves it to an absolute path; re-assigning made it './' again, after
+    // the load phase, so every plugin that resolves a folder in onLoaded got a
+    // relative one. `path.join('./', 'schemas')` is `schemas`, which reaches
+    // import() as a BARE SPECIFIER — so schemas, presets and layout sidecars
+    // all failed with "Cannot find package 'schemas'" on a clean build that
+    // was otherwise green.
+    //
+    // Stage two exists to pick up what stage one could not know about. It has
+    // no business restating what stage one already produced and the engine has
+    // since corrected.
+    const parsed = commander.opts()
+    for (const option of commander.options) {
+        if (!declared.has(option.flags)) continue
+        const name = option.attributeName()
+        if (parsed[name] !== undefined) runtime.options[name] = parsed[name]
+    }
+}
+
+// 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'
@@ -31,7 +32,7 @@ import { queryContext } from './database/query-context.js'
 // Build a structuredClone-safe copy of runtime.options for WORKER
 // dispatch. Plugin surfaces live under `runtime.options.<plugin>` per
 // the engine's namespacing convention and routinely hold functions
-// (e.g. `runtime.options.layouts.inspect`, `runtime.options.preview.get`)
+// (e.g. the `layouts` service's inspect(), the `preview` service's get())
 // — those don't cross thread boundaries via Piscina's structured clone.
 //
 // Per-key probe: anything that survives `structuredClone(value)` passes
@@ -538,7 +539,6 @@ export async function setup(options) {
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
-            .option('--render-presets [name]', 're-render preset derivatives whose sources and revisions are unchanged; with a name, only that preset')
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')
             .option('-w --watch', 'watch entities for changes', false)
             .option('-f --force', 'rebuild everything; disable incremental dispatch', false)
@@ -599,7 +599,10 @@ Which check answers which question:
   Are the derivatives current?
       --render-presets [n]  re-derives every preset, or one by name, without
                             touching anything else. For a preset edited without
-                            bumping its revision.
+                            bumping its revision. Declared by the assets
+                            plugin, so it exists only in a project that loads
+                            one — and a config without assets() refuses it as
+                            unknown rather than accepting it and doing nothing.
 
   Start over.
       --clear               removes the output folder and reopens the cache.
@@ -632,7 +635,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 +808,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')
 
@@ -803,8 +842,18 @@ The full version, with what each code means: docs/diagnostics.md`)
         // The same three commands the instance answers over the socket —
         // one implementation, so a forwarded --audit-output cannot disagree with a
         // local one about what it checked.
-        const code = await runReportOnly()
-        if (code !== null) process.exit(code)
+        //
+        // --tools and --tool are NOT among them: they are dispatched at `import`
+        // instead, because the tool registry is not complete until every
+        // plugin's onLoaded has run and this hook runs ahead of all of them.
+        // The import dispatch existed already and was documented as
+        // load-bearing, but this call reached the same code first and exited,
+        // so it never ran — and every tool a plugin registers was missing from
+        // the CLI while the listing looked healthy, just short.
+        if (!runtime.options.tools && !runtime.options.tool) {
+            const code = await runReportOnly()
+            if (code !== null) process.exit(code)
+        }
     })
 
     onRender(async (signal) => {
@@ -1012,7 +1061,7 @@ The full version, with what each code means: docs/diagnostics.md`)
                                 mc.port2.unref()
                                 renderOptions.port = mc.port1
                                 // Strip plugin-surface functions
-                                // (runtime.options.layouts.inspect, etc.) so
+                                // (the layouts service's inspect, etc.) so
                                 // Piscina's structured clone doesn't choke on
                                 // them. Engine-side primitives pass through;
                                 // plugin surfaces are reachable via the
@@ -1459,30 +1508,17 @@ The full version, with what each code means: docs/diagnostics.md`)
         if (failed) logger.error('Mikser completed with %d render error%s', failed, failed === 1 ? '' : 's')
         else logger.notice('Mikser completed')
 
-        // Is everything the templates linked to actually there?
-        //
-        // The URL helpers build paths; they do not resolve them. So a preset
-        // that never ran, a library that was not copied, or a template naming
-        // an extension the preset stopped producing all yield a well-formed
-        // link to a file that does not exist — and the only symptom is a
-        // missing image on the deployed site, found by a person.
+        // The `render-presets-unhandled` guard is gone, and so is the state it
+        // read.
         //
-        // Checked at the end of the cycle because that is the first moment the
-        // answer is stable: derivatives are produced during the cycle, so
-        // asking any earlier would report files that were about to appear.
-        // --render-presets with nothing to consume it.
-        //
-        // The flag is implemented by the assets plugin, so without that plugin
-        // it reaches nobody: the build runs normally, nothing is re-derived,
-        // and the operator is left to notice. Checked here rather than at
-        // onLoaded because the engine's own onLoaded is registered first and
-        // runs before any plugin has set itself up.
-        if (runtime.options.renderPresets && !runtime.state?.assets?.renderPresetsHandled) {
-            useLogger().error({ code: 'render-presets-unhandled' },
-                '--render-presets was passed, but no assets plugin is loaded to act on it. '
-                + 'Nothing was re-derived. Add assets() to the plugins array, or drop the flag.')
-            process.exitCode = 1
-        }
+        // It existed because core declared `--render-presets` while the assets
+        // plugin implemented it, so the flag could be passed at a build that
+        // had no plugin to act on it — accepted, ignored, and reported after
+        // the fact. The plugin declares the option itself now, so a config
+        // without assets() does not have the flag at all and a misspelling is
+        // refused by name before anything is built. There is nothing left to
+        // warn about after the event.
+
 
         const brokenTargets = await reportBrokenReferences(useLogger())
         await reportMissingAssets(useLogger(), brokenTargets)

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.
 //
@@ -72,6 +73,11 @@ export function socketPath(workingFolder) {
 //
 //   → { type: 'build',  config, clear, renderPresets }
 //   → { type: 'report', config, tool, tools, toolArgs, explain, auditOutput, fingerprint, json }
+//
+// A PLUGIN's options are not listed here and are not hand-carried: they travel
+// on `argv` and are applied by withRequestOutput against the instance's own
+// option table. --render-presets used to be named explicitly, which is what a
+// core-declared plugin flag costs — one more thing to remember in two files.
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
 //   ← { type: 'refused', reason, detail }
@@ -416,6 +422,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 {
@@ -448,8 +465,10 @@ async function serveBuild(socket, request, logger) {
         // silent no-op, which is the failure this surface exists to remove —
         // and restoring it after keeps the watcher from forcing every later
         // 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
@@ -470,7 +489,7 @@ async function serveBuild(socket, request, logger) {
                 emitReport()
             })
         } finally {
-            runtime.options.renderPresets = priorRenderPresets
+            runtime.options.force = priorForce
         }
 
         // From the render-error count, NOT from process.exitCode.

package/src/plugins/assets.js

@@ -1,5 +1,6 @@
 import { reportEvaluated } from '../report.js'
 import { countEntities } from '../catalog.js'
+import { cliOption } from '../cli.js'
 import path from 'node:path'
 import { mkdir, writeFile, unlink, rm, readFile, symlink, } from 'fs/promises'
 import { existsSync } from 'node:fs'
@@ -86,6 +87,33 @@ export function assets(options = {}) {
         changeExtension,
         constants: { ACTION, OPERATION },
     }) => {
+    // Declared HERE, not in core.
+    //
+    // Everything this flag does happens in this plugin, and core carried it
+    // only because a plugin could not declare an option until 9.100.0. The
+    // cost of that was a flag a build could accept with nothing loaded to act
+    // on it: passed, ignored, and reported afterwards by a `render-presets-
+    // unhandled` guard in the engine. Declared here, a config without assets()
+    // simply does not have the option, so the mistake is refused by name
+    // before anything is built rather than explained after.
+    // The folders this plugin owns, on the command line.
+    //
+    // They were config-only, because a plugin could not declare an option
+    // before 9.100.0 — so overriding one for a single run meant editing the
+    // config, which is the file whose checksum decides whether the whole
+    // catalog is still valid. A flag is the difference between "try this
+    // once" and "invalidate everything".
+    //
+    // CLI beats config beats default, which is the order every other option
+    // here already follows.
+    cliOption('--assets <folder>',
+        'folder for derived assets, relative to the working folder (default: assets)')
+    cliOption('--presets <folder>',
+        'folder holding the preset modules, relative to the working folder (default: presets)')
+    cliOption('--render-presets [name]',
+        're-render preset derivatives whose sources and revisions are unchanged; '
+        + 'with a name, only that preset')
+
     const collection = 'presets'
     const type = 'preset'
     const checksumMap = new Set()
@@ -425,12 +453,16 @@ export function assets(options = {}) {
         runtime.engine ??= {}
         runtime.engine.assets = { explainMissing }
 
-        runtime.options.presets = options.presetsFolder || collection
+        // `??`, not `||`: an option commander did not see is undefined, and
+        // falling through to the config is the point. `||` would also fall
+        // through for an intentional empty string, which is a different
+        // answer than "not given".
+        runtime.options.presets = runtime.options.presets ?? options.presetsFolder ?? collection
         runtime.options.presetsFolder = path.join(runtime.options.workingFolder, runtime.options.presets)
         logger.debug('Presets folder: %s', runtime.options.presetsFolder)
         await mkdir(runtime.options.presetsFolder, { recursive: true })
 
-        runtime.options.assets = options.assetsFolder || 'assets'
+        runtime.options.assets = runtime.options.assets ?? options.assetsFolder ?? 'assets'
         runtime.options.assetsFolder = path.join(runtime.options.workingFolder, runtime.options.assets)
         logger.debug('Assets folder: %s', runtime.options.assetsFolder)
 
@@ -641,7 +673,6 @@ export function assets(options = {}) {
             // end of the cycle: a flag that reaches no plugin has to say so,
             // rather than building normally and leaving the operator to
             // notice nothing was re-derived.
-            runtime.state.assets.renderPresetsHandled = true
 
             const known = Object.keys(runtime.state.assets.presets)
             const names = wanted === true ? known : [wanted]

package/src/plugins/data.js

@@ -1,4 +1,5 @@
 import path from 'path'
+import { cliOption } from '../cli.js'
 import { mkdir, writeFile, unlink, open } from 'fs/promises'
 import _ from 'lodash'
 import sift from 'sift'
@@ -17,9 +18,23 @@ export function data(options = {}) {
         onBeforeRender,
         constants: { OPERATION },
     }) => {
+    // The folder this plugin owns, on the command line.
+    //
+    // Config-only until 9.100.0, because a plugin could not declare an option
+    // — so overriding it for one run meant editing the config, which is the
+    // file whose checksum decides whether the catalog is still valid. A flag
+    // is the difference between trying something once and invalidating
+    // everything.
+    //
+    // CLI beats config beats default. `??` rather than `||` below: an option
+    // commander did not see is undefined, and an intentional empty string is a
+    // different answer than "not given".
+    cliOption('--data <folder>',
+        'folder for emitted data files, relative to the OUTPUT folder (default: data)')
+
     onLoaded(async () => {
         const logger = useLogger()
-        runtime.options.data = options.dataFolder || 'data'
+        runtime.options.data = runtime.options.data ?? options.dataFolder ?? 'data'
         runtime.options.dataFolder = path.join(runtime.options.outputFolder, runtime.options.data)
 
         logger.debug('Data folder: %s', runtime.options.dataFolder)

package/src/plugins/documents.js

@@ -1,4 +1,5 @@
 import { useSource } from '../source.js'
+import { cliOption } from '../cli.js'
 
 // documents — the canonical content source plugin.
 //
@@ -13,6 +14,13 @@ export function documents(options = {}) {
         const collection = 'documents'
         const type = 'document'
 
+        // The folder this plugin owns, on the command line. Config-only until
+        // 9.100.0, because a plugin could not declare an option — and editing
+        // the config to try another folder once invalidates the catalog,
+        // whose checksum covers it. CLI beats config beats default.
+        cliOption('--documents <folder>',
+            'folder of source documents, relative to the working folder (default: documents)')
+
         useSource(core, {
             collection,
             type,

package/src/plugins/files.js

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { cliOption } from '../cli.js'
 import { mkdir, symlink, unlink, lstat, realpath } from 'fs/promises'
 import { globby } from 'globby'
 import pMap from 'p-map'
@@ -23,6 +24,20 @@ export function files(options = {}) {
         constants: { ACTION },
     }) => {
         const collection = 'files'
+        // The folder this plugin owns, on the command line.
+        //
+        // Config-only until 9.100.0, because a plugin could not declare an option
+        // — so overriding it for one run meant editing the config, which is the
+        // file whose checksum decides whether the catalog is still valid. A flag
+        // is the difference between trying something once and invalidating
+        // everything.
+        //
+        // CLI beats config beats default. `??` rather than `||` below: an option
+        // commander did not see is undefined, and an intentional empty string is a
+        // different answer than "not given".
+        cliOption('--files <folder>',
+            'folder of static files copied into the output by symlink, relative to the working folder (default: files)')
+
         const type = 'file'
 
         async function ensureLink(relativePath) {
@@ -156,7 +171,7 @@ export function files(options = {}) {
 
         onLoaded(async () => {
             const logger = useLogger()
-            runtime.options.files = options.filesFolder || collection
+            runtime.options.files = runtime.options.files ?? options.filesFolder ?? collection
             runtime.options.filesFolder = path.join(runtime.options.workingFolder, runtime.options.files)
 
             logger.debug('Files folder: %s', runtime.options.filesFolder)

package/src/plugins/preview.js

@@ -6,7 +6,7 @@
 //   1. An in-memory cache (Map<filename, { bytes, mime, expiresAt,
 //      size, deps }>) with LRU eviction past a configurable byte cap.
 //   2. An Express GET /preview/:filename route that serves cache entries.
-//   3. Exposes the cache surface at runtime.options.preview = { store,
+//   3. Offers the cache surface as the `preview` service = { store,
 //      get, stats, config } so other plugins (mikser-io-mcp's
 //      mikser_preview_render tool, library-mode callers) can stash bytes
 //      and retrieve them by URL without going through MCP.
@@ -29,6 +29,7 @@
 // isn't mounted.
 
 import sift from 'sift'
+import { provideService } from '../services.js'
 
 export function preview(options = {}) {
     return ({ runtime, onLoaded, onPersist, useJournal, useLogger, registerRoute, constants: { OPERATION } }) => {
@@ -98,13 +99,14 @@ export function preview(options = {}) {
         }
     }
 
-    // Expose the cache surface at runtime.options.preview so other
-    // plugins / library callers can use it without going through MCP.
-    // `config` is part of the surface too — mikser-io-mcp's
-    // mikser_preview_render reads it to derive URL paths + TTL clamps.
-    // Done at factory-eval time (before any onLoaded fires) so a
-    // later plugin's onLoad / onLoaded can already see it.
-    runtime.options.preview = { store, get, stats, config }
+    // Offer the cache surface as a service, so a plugin that wants it asks
+    // core rather than reaching into runtime.options.preview. `config` is
+    // part of the surface too — mikser-io-mcp's mikser_preview_render reads
+    // it to derive URL paths + TTL clamps.
+    //
+    // Provided at factory-eval time, before any hook runs, so a consumer's
+    // onLoad / onLoaded can already see it whatever the plugin order.
+    provideService('preview', { store, get, stats, config }, { plugin: 'mikser-io' })
 
     // Per-cycle invalidation. For every preview entry that has `deps`,
     // walk this cycle's catalog mutations and evict the entry if any
@@ -144,7 +146,7 @@ export function preview(options = {}) {
 
     // HTTP route: served regardless of whether MCP is on, so previews
     // are also reachable from library-mode callers that stored bytes
-    // via runtime.options.preview.store() directly.
+    // via the preview service's store() directly.
     onLoaded(async () => {
         const logger = useLogger()
         const app = runtime.options.app

package/src/plugins/resources.js

@@ -1,4 +1,5 @@
 import { mkdir, symlink, rename, unlink } from 'node:fs/promises'
+import { cliOption } from '../cli.js'
 import { createWriteStream } from 'node:fs'
 import lodash from 'lodash'
 import deepdash from 'deepdash'
@@ -27,6 +28,20 @@ export function resources(options = {}) {
         updateProgress,
         constants: { OPERATION },
     }) => {
+    // The folder this plugin owns, on the command line.
+    //
+    // Config-only until 9.100.0, because a plugin could not declare an option
+    // — so overriding it for one run meant editing the config, which is the
+    // file whose checksum decides whether the catalog is still valid. A flag
+    // is the difference between trying something once and invalidating
+    // everything.
+    //
+    // CLI beats config beats default. `??` rather than `||` below: an option
+    // commander did not see is undefined, and an intentional empty string is a
+    // different answer than "not given".
+    cliOption('--resources <folder>',
+        'folder of library resources linked into the output, relative to the working folder (default: resources)')
+
     const collection = 'resources'
     const type = 'resource'
 
@@ -46,7 +61,7 @@ export function resources(options = {}) {
                 : resourcesName,
         }
 
-        runtime.options.resources = options.resourcesFolder || collection
+        runtime.options.resources = runtime.options.resources ?? options.resourcesFolder ?? collection
         runtime.options.resourcesFolder = path.join(runtime.options.workingFolder, runtime.options.resources)
         logger.debug('Resources folder: %s', runtime.options.resourcesFolder)
 

package/src/plugins.js

@@ -1,5 +1,6 @@
 import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
+import { resetServices } from './services.js'
 import runtime from './runtime.js'
 
 import * as core from '../index.js'
@@ -23,6 +24,13 @@ import * as core from '../index.js'
 onLoad(() => {
     const logger = useLogger()
 
+    // The service and extension-point registries are module state, which
+    // outlives one load phase — a watcher re-reads its config in the same
+    // process. Clearing here, before any factory runs, means a reload
+    // rebuilds them from scratch instead of a provider colliding with the
+    // copy of itself it registered last time.
+    resetServices()
+
     runtime.options.plugins = (runtime.options.plugins ?? [])
         .concat(runtime.config.plugins ?? [])
         .filter(Boolean)
@@ -110,11 +118,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

package/src/services.js

@@ -0,0 +1,88 @@
+// What one plugin offers another, without either importing the other.
+//
+// Plugins reached into each other through `runtime.options`:
+//
+//       runtime.options.layouts.inspect      read by core
+//       runtime.options.schemas.lookup       read by forms, layouts, ocr
+//       runtime.options.preview.get          read by core, layouts, mcp
+//       runtime.options.roles                read by mcp
+//
+// It worked, and it was wrong in a specific way: mikser-io-mcp and
+// mikser-io-layouts were coupled through a shared mutable object neither of
+// them owns. Nothing declared the relationship, so nothing could check it —
+// a consumer's `if (!runtime.options.layouts) return` reads as a null check
+// but is really an is-that-plugin-installed check wearing a disguise.
+//
+// It also cost the two best names. Commander derives an option's property
+// from its long flag, so `--layouts <folder>` writes runtime.options.layouts
+// — on top of the inspect API, after the load phase, with the failure
+// surfacing three plugins away.
+//
+// This covers ONE direction: one plugin provides, others consume. The other
+// direction — many plugins adding to a surface one plugin serves — already
+// has a home for each surface it applies to: tools.js, routes.js, roles.js
+// and cli.js. A generic contribution registry would be a fifth way to do
+// what those four already do.
+//
+// So: core holds the registry, and neither side names the other.
+
+const services = new Map()        // name -> { api, plugin }
+
+// Publish an API under a name other plugins can ask for.
+//
+//   provideService('layouts', { inspect }, { plugin: 'mikser-io-layouts' })
+//
+// Call at factory-eval time, before any hook runs, so that a consumer's
+// onLoaded can already see it. Same rule as cliOption: declare during
+// construction, read during a hook.
+export function provideService(name, api, { plugin } = {}) {
+    if (!name || !api) return
+    const existing = services.get(name)
+    if (existing) {
+        // Two providers for one name is a configuration mistake, not a
+        // precedence question. Last-write-wins would hand consumers whichever
+        // plugin happened to be constructed later — the exact order
+        // dependence this registry exists to remove. Thrown rather than
+        // logged: this runs at factory-eval time, where plugins.js already
+        // catches, names the plugin and carries on with the rest.
+        throw new Error(
+            `Service "${name}" is already provided by ${existing.plugin ?? 'another plugin'}` +
+            `${plugin ? `; ${plugin} tried to provide it too` : ''}. Only one plugin may provide a service.`)
+    }
+    services.set(name, { api, plugin })
+}
+
+// Ask for a service. Returns undefined when nothing provides it, so a
+// consumer degrades on purpose:
+//
+//   const layouts = useService('layouts')
+//   if (!layouts) return        // layouts plugin isn't installed
+//
+// This replaces `if (!runtime.options.mcp) return`, which read as a null
+// check but was really an is-that-plugin-loaded check wearing a disguise.
+export function useService(name) {
+    return services.get(name)?.api
+}
+
+// Ask for a service the caller cannot work without. Throws naming the
+// package that provides it, because "cannot read properties of undefined"
+// does not tell anyone which npm install they are missing.
+export function requireService(name, { from } = {}) {
+    const found = services.get(name)
+    if (found) return found.api
+    throw new Error(
+        `No plugin provides the "${name}" service` +
+        (from ? `. Install ${from} and add it to the plugins array.` : '.'))
+}
+
+// Drop everything. The registries are module state, which outlives a single
+// run inside one process — tests, and the watcher's repeated config reloads.
+export function resetServices() {
+    services.clear()
+}
+
+// What is registered right now. For --explain and the MCP inventory tool:
+// "which plugin provides what" is a question people ask.
+export function serviceInventory() {
+    return [...services].map(([name, { plugin }]) => ({ name, plugin }))
+}

package/src/source.js

@@ -337,9 +337,19 @@ export function useSource(core, options) {
         // have already passed. We do folder resolution here — by which
         // point engine has set workingFolder and journal + catalog
         // have initialized.
-        absFolder = path.isAbsolute(folder)
-            ? folder
-            : path.join(runtime.options.workingFolder, folder)
+        // A `--<collection> <folder>` flag, if the plugin declared one, wins
+        // over the configured folder.
+        //
+        // Resolved HERE rather than where useSource was called, and that is
+        // the whole point: plugin factories run during the load phase, and the
+        // CLI table is not complete until after it — so an option read at
+        // construction is always undefined. documents() read it there first
+        // and `--documents content` silently did nothing, which is the shape
+        // of bug this option mechanism exists to prevent rather than create.
+        const configured = runtime.options[collection] ?? folder
+        absFolder = path.isAbsolute(configured)
+            ? configured
+            : path.join(runtime.options.workingFolder, configured)
         runtime.options[`${collection}Folder`] = absFolder
         // The authoritative set of folders whose files become entities.
         //

package/src/tools.js

@@ -7,13 +7,17 @@
 // the first. Closing that by adding a CLI flag per tool would drift the moment
 // anyone added a tool.
 //
-// One direction, today. The mcp plugin mirrors its registrations into here, so
-// every tool it registers is reachable from the CLI. The reverse is NOT true: a
-// tool registered directly against this registry does not appear in an MCP
-// session, because the substrate binds sessions from its own list and MCP wants
-// a zod shape for `inputSchema` while the engine is deliberately zod-free.
-// Registering through `runtime.options.mcp` therefore remains the way to reach
-// both surfaces, and that is what every tool does now.
+// Both directions. The mcp plugin mirrors its own registrations into here, and
+// binds every tool registered here into each session — prefixing on the way
+// out, since `mikser_` belongs to MCP's flat namespace and not to the engine.
+// So a plugin registers once, against this registry, and reaches both surfaces
+// without depending on the mcp plugin being installed, or on where it sits in
+// the plugins array.
+//
+// `inputSchema` is stored opaquely, which is what makes that possible: a
+// plugin may describe its parameters in the neutral vocabulary below or hand
+// over a zod shape, and the engine passes either through untouched rather than
+// taking a dependency on zod to hold it.
 //
 // So the REGISTRY is substrate and the transports are consumers. ADR-0006's
 // five tests, which MCP itself failed on release cadence:
@@ -50,6 +54,13 @@ export function registerTool(name, definition = {}, handler) {
         runtime.engine?.logger?.debug('Tool %s re-registered, replacing the previous handler', name)
     }
     tools.set(name, {
+        // The whole definition, not the three fields core happens to read.
+        // A transport needs more than core does — `mutates: true` is how a
+        // tool says it changes something, and MCP wraps those differently.
+        // Dropping unknown keys here meant a plugin could only reach that
+        // behaviour by registering with the mcp plugin directly, which is
+        // exactly the coupling this registry exists to remove.
+        ...definition,
         name,
         description: definition.description ?? '',
         inputSchema: definition.inputSchema ?? {},

package/testing/harness.js

@@ -7,6 +7,7 @@
 
 import _ from 'lodash'
 import realRuntime from '../src/runtime.js'
+import { resetServices } from '../src/services.js'
 import { matchEntity, normalize, changeExtension, getFormatInfo, checksum, AbortError } from '../src/utils.js'
 
 const OPERATION = {
@@ -31,6 +32,11 @@ export function createHarness({
     entities = [],
     journal = [],
 } = {}) {
+    // A fresh harness is a fresh world. The service registry is module state,
+    // so without this the previous test's provider is still registered and
+    // constructing the plugin again is (correctly) an error — every package
+    // building a plugin per test would otherwise have to remember to clear it.
+    resetServices()
     const hookNames = [
         'load', 'loaded', 'import', 'imported',
         'process', 'processed', 'persist', 'persisted',