mikser-io 10.14.0 → 11.0.2

package/package.json

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

package/src/inventory.js

@@ -30,39 +30,29 @@ function repositoryUrl(repository) {
         .replace(/\.git$/, '')
 }
 
-// Which plugins are actually RUNNING, as opposed to merely installed.
+// Every mikser package INSTALLED beside this one, described.
 //
-// The distinction is the useful half: a package in node_modules that no config
-// loads explains nothing about the site's behaviour, and an agent told
-// otherwise will look for a feature that is not switched on.
-function activeNames() {
-    const active = new Set()
-    const named = (short) => (short.startsWith('mikser-io') ? short : `mikser-io-${short}`)
-
-    // Every plugin that mounts a route already names itself there — the
-    // strongest signal available, and one that stays correct as plugins are
-    // added, because registerRoute requires it.
-    for (const route of runtime.routes ?? []) {
-        if (route?.plugin) active.add(named(route.plugin))
-    }
-    // Renderers and postprocessors are registered by name rather than by
-    // package, and the package name is that name in a fixed shape.
-    for (const name of runtime.renderers?.keys() ?? []) active.add(`mikser-io-render-${name}`)
-    for (const name of runtime.postprocessors?.keys() ?? []) active.add(`mikser-io-post-${name}`)
-    // A lifecycle plugin that mounts nothing is recognised by the surface it
-    // publishes on the runtime.
-    if (runtime.options?.layouts) active.add('mikser-io-layouts')
-    if (runtime.options?.preview) active.add('mikser-io-preview')
-    // The engine itself is always running; saying otherwise would be odd.
-    active.add('mikser-io')
-    return active
-}
-
-// Every mikser package installed beside this one, described.
+// Installed, and nothing more. This list used to carry an `active` flag,
+// derived by probing whatever surfaces a plugin happened to expose — a route
+// here, a CLI flag there. Two things were wrong with it and only the second
+// was dangerous.
+//
+// The probe went stale silently: it tested `runtime.options.layouts`, which
+// stopped being layouts' API object two majors ago and is now the `--layouts`
+// folder flag, so layouts read as inactive on every site that did not pass a
+// flag it has no reason to pass. It also tested `runtime.options.preview` for
+// a package, `mikser-io-preview`, that does not exist.
+//
+// And the flag was three-valued in code and two-valued in its contract:
+// present meant running, absent meant EITHER not running or not detectable,
+// and an agent told to read it "to know what the system can do" could only
+// read absence as off. On a real site that said no schema validation and no
+// git sync while both were running — and git sync is the only route by which
+// an agent's own edit reaches the repository.
 //
-// `active` is reported only where it can be established: a lifecycle plugin
-// that publishes nothing on the runtime cannot be detected, and saying `false`
-// for it would be a claim rather than an absence of one.
+// What is running is now answered by the runtime recording what it loads, in
+// plugins.js. This answers a different and still useful question: what is on
+// disk, what version, and where to read about it.
 export function inventory({ workingFolder = runtime.options?.workingFolder } = {}) {
     const root = path.join(workingFolder ?? '.', 'node_modules')
     let names = []
@@ -72,7 +62,6 @@ export function inventory({ workingFolder = runtime.options?.workingFolder } = {
         return []
     }
 
-    const active = activeNames()
     const plugins = []
     for (const name of names.sort()) {
         try {
@@ -82,7 +71,6 @@ export function inventory({ workingFolder = runtime.options?.workingFolder } = {
                 name,
                 version: manifest.version ?? null,
                 ...(manifest.description ? { summary: manifest.description } : {}),
-                ...(active.has(name) ? { active: true } : {}),
                 ...(manifest.homepage ? { homepage: manifest.homepage } : {}),
                 ...(repository ? { repository } : {}),
                 npm: `https://www.npmjs.com/package/${name}`,
@@ -91,3 +79,25 @@ export function inventory({ workingFolder = runtime.options?.workingFolder } = {
     }
     return plugins
 }
+
+// What this runtime LOADED — the answer to "what is running".
+//
+// Read from the record plugins.js keeps as it loads, not derived from
+// surfaces afterwards. Every loaded plugin appears, including one that named
+// nothing: `package: null` means "running, and did not say what it is", which
+// is a different statement from not running and must never be collapsed into
+// one. Nothing here is ever absent because it could not be detected — a plugin
+// that is loaded is in this list.
+export function loadedPlugins({ workingFolder = runtime.options?.workingFolder } = {}) {
+    const root = path.join(workingFolder ?? '.', 'node_modules')
+    const versionOf = (name) => {
+        if (!name) return null
+        try {
+            return JSON.parse(readFileSync(path.join(root, name, 'package.json'), 'utf8')).version ?? null
+        } catch { return null }
+    }
+    return (runtime.plugins ?? []).map(entry => ({
+        ...entry,
+        ...(entry.package ? { version: versionOf(entry.package) } : {}),
+    }))
+}

package/src/plugins/api.js

@@ -1209,5 +1209,10 @@ export function api(options = {}) {
             }
         }
     })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/commands.js

@@ -304,6 +304,6 @@ export function commands(options = {}) {
             reportUnfired()
         })
 
-        return { executeCommand }
+        return { executeCommand, module: import.meta.url }
     }
 }

package/src/plugins/data.js

@@ -216,5 +216,10 @@ export function data(options = {}) {
             }
         }
     })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/documents.js

@@ -29,6 +29,6 @@ export function documents(options = {}) {
             phase: 'import',
         })
 
-        return { collection, type }
+        return { collection, type, module: import.meta.url }
     }
 }

package/src/plugins/files.js

@@ -273,6 +273,7 @@ export function files(options = {}) {
         return {
             collection,
             type,
+            module: import.meta.url,
         }
     }
 }

package/src/plugins/front-matter.js

@@ -20,5 +20,10 @@ export function frontMatter(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/json.js

@@ -16,5 +16,10 @@ export function json(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/mapper.js

@@ -22,5 +22,10 @@ export function mapper(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/observer.js

@@ -212,6 +212,7 @@ export function observer(options = {}) {
 
         return {
             format,
+            module: import.meta.url,
         }
     }
 }

package/src/plugins/preview.js

@@ -183,6 +183,6 @@ export function preview(options = {}) {
         })
     })
 
-    return { name: 'preview' }
+    return { name: 'preview', module: import.meta.url }
     }
 }

package/src/plugins/render/file.js

@@ -164,5 +164,5 @@ export function load({ runtime, options, track, logger }) {
 }
 
 export function fileHelpers(options = {}) {
-    return { name: options.name ?? 'file', options, load }
+    return { name: options.name ?? 'file', options, load, module: import.meta.url }
 }

package/src/plugins/render/hbs.js

@@ -327,5 +327,6 @@ export function renderHbs(options = {}) {
         load,
         render,
         parseReferences,
+        module: import.meta.url,
     }
 }

package/src/plugins/render/href.js

@@ -41,5 +41,5 @@ export function load({ entity, runtime, options }) {
 }
 
 export function hrefUrlHelpers(options = {}) {
-    return { name: options.name ?? 'href', options, load }
+    return { name: options.name ?? 'href', options, load, module: import.meta.url }
 }

package/src/plugins/render/resource.js

@@ -24,5 +24,5 @@ export function load({ runtime, entity, state, options, track }) {
 }
 
 export function resourceUrlHelper(options = {}) {
-    return { name: options.name ?? 'resource', options, load }
+    return { name: options.name ?? 'resource', options, load, module: import.meta.url }
 }

package/src/plugins/resources.js

@@ -245,6 +245,7 @@ export function resources(options = {}) {
         return {
             collection,
             type,
+            module: import.meta.url,
         }
     }
 }

package/src/plugins/shares.js

@@ -38,5 +38,10 @@ export function shares(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/sources.js

@@ -31,8 +31,10 @@ export function sources(options = {}) {
         const { useLogger } = core
         if (!collections.length) {
             // No collections is a legitimate config (a flag turned them all
-            // off); nothing to register, and nothing to complain about.
-            return
+            // off); nothing to register, and nothing to complain about. Still
+            // names itself: the plugin IS loaded, and a config that turned its
+            // collections off must not make it look undetectable.
+            return { module: import.meta.url }
         }
         for (const [collection, config] of collections) {
             const {
@@ -63,6 +65,9 @@ export function sources(options = {}) {
             })
         }
         useLogger?.()?.debug('Sources registered: %s', collections.map(([c]) => c).join(', '))
+        // Names this package to the runtime's loaded-plugin record, so ping
+        // reports it as running rather than as undetectable.
+        return { module: import.meta.url }
     }
 }
 

package/src/plugins/validator.js

@@ -14,5 +14,10 @@ export function validator(options = {}) {
                 })
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/yaml.js

@@ -22,5 +22,10 @@ export function yaml(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins.js

@@ -1,6 +1,9 @@
 import { useLogger } from './engine/index.js'
 import { onLoad } from './lifecycle.js'
 import { resetServices } from './services.js'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { existsSync, readFileSync } from 'node:fs'
 import runtime from './runtime.js'
 
 import * as core from '../index.js'
@@ -40,6 +43,9 @@ onLoad(() => {
     // always sees a Map, never undefined.
     runtime.renderers      = runtime.renderers      ?? new Map()
     runtime.postprocessors = runtime.postprocessors ?? new Map()
+    // Rebuilt, not appended to: loadPlugins runs again on a config change, and
+    // a list that accumulated would report every plugin twice.
+    runtime.plugins = []
 
     const factoryEntries = []
     let registeredRenderers = 0
@@ -62,6 +68,8 @@ onLoad(() => {
                     continue
                 }
                 runtime.renderers.set(name, entry)
+                recordPlugin({ kind: 'renderer', name,
+                               package: packageOfModule(entry.module), module: entry.module ?? null })
                 registeredRenderers++
                 continue
             }
@@ -72,6 +80,8 @@ onLoad(() => {
                     continue
                 }
                 runtime.postprocessors.set(name, entry)
+                recordPlugin({ kind: 'postprocessor', name,
+                               package: packageOfModule(entry.module), module: entry.module ?? null })
                 registeredPostprocessors++
                 continue
             }
@@ -140,17 +150,83 @@ onLoad(() => {
             logger.error('Plugin factory threw on registration: %s', err.message)
             continue
         }
-        const label = descriptor?.collection ?? descriptor?.type ?? `plugin-${index + 1}`
+        // `plugin-7` names nothing a reader can act on. A plugin that
+        // declared its module has already said where it is, so the file's own
+        // stem is a better name than its position in an array.
+        const declaredName = descriptor?.module
+            ? path.basename(String(descriptor.module).split('?')[0]).replace(/\.[cm]?js$/, '')
+            : null
+        const label = descriptor?.collection ?? descriptor?.type ?? declaredName ?? `plugin-${index + 1}`
+        const registered = []
         for (const name of hookNames) {
-            for (const hook of runtime.hooks[name].slice(before.get(name))) {
+            const added = runtime.hooks[name].slice(before.get(name))
+            if (added.length) registered.push(name)
+            for (const hook of added) {
                 // 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
             }
         }
+        // Recorded whether or not it named itself. A plugin that declares
+        // nothing is still loaded, and the list must say so — that is the
+        // whole difference between this and the probe it replaces.
+        recordPlugin({
+            kind: 'lifecycle',
+            label,
+            package: packageOfModule(descriptor?.module),
+            module: descriptor?.module ?? null,
+            ...(descriptor?.collection ? { collection: descriptor.collection } : {}),
+            hooks: registered,
+        })
     }
 })
 
+
+// The package a module belongs to, read from the nearest package.json.
+//
+// Walked up from the file rather than pattern-matched on the path: a plugin
+// developed in a workspace sits at `~/Projects/mikser/mikser-io-git`, and the
+// same plugin installed sits at `<site>/node_modules/mikser-io-git`. Only the
+// manifest is true in both, and only the manifest is true for a plugin whose
+// package is not named for it.
+function packageOfModule(moduleUrl) {
+    if (typeof moduleUrl !== 'string') return null
+    let dir
+    try {
+        dir = path.dirname(moduleUrl.startsWith('file:') ? fileURLToPath(moduleUrl) : moduleUrl)
+    } catch { return null }
+    for (let depth = 0; depth < 12; depth++) {
+        const manifest = path.join(dir, 'package.json')
+        if (existsSync(manifest)) {
+            try { return JSON.parse(readFileSync(manifest, 'utf8')).name ?? null } catch { return null }
+        }
+        const parent = path.dirname(dir)
+        if (parent === dir) break
+        dir = parent
+    }
+    return null
+}
+
+// What this runtime LOADED, recorded as it loads it.
+//
+// Not derived afterwards. The previous answer was assembled by inventory.js
+// from whatever surfaces happened to be observable — a route here, a CLI flag
+// there — which made "is this plugin running" a question about how well the
+// probe was maintained rather than about the plugin. It reported layouts as
+// not running on every site that did not pass `--layouts`, because the flag it
+// probed had stopped being an API object two majors earlier and nothing failed
+// when it went stale.
+//
+// A plugin names itself by returning `module: import.meta.url` from its
+// factory, the same self-naming `registerRoute` and `provideService` already
+// require. One that names nothing is still recorded and still reported as
+// LOADED — its `package` is null, which says "this is running and did not say
+// what it is", never "this is not running".
+function recordPlugin(entry) {
+    runtime.plugins = runtime.plugins ?? []
+    runtime.plugins.push(entry)
+}
+
 function kebabToCamel(s) {
     return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
 }