mikser-io 9.50.2 → 9.54.0

package/docs/api-reference.md

@@ -844,6 +844,36 @@ AsyncLocalStorage than the engine's, queries record no edges, and index pages,
 sitemaps and feeds silently stop rebuilding. Production consumers resolve both
 from their own tree, so the problem is local to the dev workspace.
 
+## Inventory
+
+What this mikser is made of.
+
+### `inventory({ workingFolder } = {})`
+
+Every installed mikser package with its version, purpose and links, and
+`active: true` on the ones actually running.
+
+```js
+[
+  { name: 'mikser-io-drive', version: '0.14.0', active: true,
+    summary: 'WebDAV for mikser-io. Exposes working-folder directories as …',
+    homepage: '…', repository: 'https://github.com/…', npm: 'https://www.npmjs.com/package/…' },
+]
+```
+
+**Derived, never declared.** Every plugin already carries a description, a
+homepage and a repository in its own `package.json`, kept current because npm
+publishes from it. A second summary held elsewhere would be one more thing to
+drift — and the first time it drifted it would be describing a plugin that had
+changed underneath it.
+
+**Installed and active are different facts.** A package in `node_modules` that
+no config loads explains nothing about a site's behaviour, and an agent told
+otherwise looks for a feature that is not switched on. `active` is reported
+only where it can be established — a plugin that mounts a route names itself
+there, a renderer registers under a known name — and is absent rather than
+`false` where it cannot, because `false` would be a claim.
+
 ## Roles
 
 Enforcement needs only the flat capability list. Explaining a refusal needs the
@@ -855,7 +885,37 @@ indistinguishable from inside a session.
 | `describeAuthority({ capabilities, roles, catalogue, summaries })` | everything a session can say about its own authority |
 | `reachOf(capabilities)` | `{ writable, readOnly }` as collection names |
 | `actingRole(held, catalogue)` | which role is in force |
-| `otherRoles(held, catalogue, summaries)` | who to ask, and what they add |
+| `rolesIn(catalogue, { acting, summaries })` | every role and its reach, the acting one marked |
+| `registerCapability(capability, meaning)` | declare what a capability protects |
+| `capabilityMeaning(capability)` | what is known about one |
+
+### Capabilities describe themselves
+
+Core does not know what `drive:layouts` protects, where that folder is, or what
+it is for — the plugin enforcing it does. So the plugin declares it, the same
+way it declares a route or a schema:
+
+```js
+registerCapability('drive:documents', {
+    plugin: 'drive',
+    grants: 'read',                       // 'read' | 'write' | 'operate'
+    resource: {
+        kind: 'collection',
+        name: 'documents',
+        folder: 'documents',              // where it is on disk
+        summary: 'the words on the pages' // what it is FOR
+    },
+})
+```
+
+`reachOf` then describes a credential in terms of the SITE rather than of
+verbs — a collection, its folder and its purpose — which is what an agent needs
+to reason about where it is working, not merely whether a call will be refused.
+A capability nothing has declared lands in `also` rather than being dropped: a
+role described only by the part of it that maps to folders is not described.
+
+The `drive:<name>[:write]` convention is still recognised for deployments whose
+plugins predate the registry, so they keep their answer.
 | `explainRefusal({ capability, role, target, catalogue, summaries })` | the sentence an agent repeats |
 
 `readOnly` is the field that makes a refusal explainable, and it is more useful
@@ -867,6 +927,11 @@ capabilities cover the others — roles are normally written as widening tiers
 and `null` when none dominates, because the acting authority genuinely is the
 union and naming half of it would be a lie.
 
+`roles` lists every role, not only the ones the session lacks. One field has to
+serve two readers: someone deciding who to ask, and someone holding the widest
+role trying to see what exists at all — and a "roles you do not have" field
+tells the second one nothing, since for an admin it is always empty.
+
 > **Informational, permanently.** Naming the role that could do something is
 > what makes a handoff possible. There is no way to request one and none should
 > be added: a role is a decision about a person, taken by whoever configures the

package/index.js

@@ -3,6 +3,7 @@ export * as constants from './src/constants.js'
 export * from './src/utils.js'
 export * from './src/auth.js'
 export * from './src/roles.js'
+export * from './src/inventory.js'
 export * from './src/report.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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mikser-io",
-  "version": "9.50.2",
-  "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
+  "version": "9.54.0",
+  "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {
     ".": "./index.js",

package/src/inventory.js

@@ -0,0 +1,93 @@
+// What this mikser is made of.
+//
+// An agent arriving at a site can see what it may write and what it may not,
+// and nothing at all about the machine doing the writing: which plugins are
+// installed, what each one is for, or where to read about them. So it reasons
+// about a system it cannot name — and a capability like `drive:layouts` means
+// nothing until you know a plugin called mikser-io-drive exists and what it
+// does.
+//
+// DERIVED, not declared. Every plugin already carries a description, a
+// homepage and a repository in its own package.json, kept current because npm
+// publishes from it. A second hand-written summary somewhere else would be one
+// more thing to drift, and the first time it drifted it would be describing a
+// plugin that had changed underneath it.
+
+import path from 'node:path'
+import { readdirSync, readFileSync } from 'node:fs'
+import runtime from './runtime.js'
+
+// A repository field is a string or an object, and either may be a shorthand
+// or a git URL. Normalised to something a reader can open.
+function repositoryUrl(repository) {
+    const raw = typeof repository === 'string' ? repository : repository?.url
+    if (!raw) return null
+    const shorthand = /^(?:github:)?([\w.-]+\/[\w.-]+)$/.exec(raw)
+    if (shorthand) return `https://github.com/${shorthand[1]}`
+    return raw
+        .replace(/^git\+/, '')
+        .replace(/^git:\/\//, 'https://')
+        .replace(/\.git$/, '')
+}
+
+// Which plugins are actually RUNNING, as opposed to merely installed.
+//
+// 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.
+//
+// `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.
+export function inventory({ workingFolder = runtime.options?.workingFolder } = {}) {
+    const root = path.join(workingFolder ?? '.', 'node_modules')
+    let names = []
+    try {
+        names = readdirSync(root).filter(n => n === 'mikser-io' || n.startsWith('mikser-io-'))
+    } catch {
+        return []
+    }
+
+    const active = activeNames()
+    const plugins = []
+    for (const name of names.sort()) {
+        try {
+            const manifest = JSON.parse(readFileSync(path.join(root, name, 'package.json'), 'utf8'))
+            const repository = repositoryUrl(manifest.repository)
+            plugins.push({
+                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}`,
+            })
+        } catch { /* unreadable manifest — say nothing rather than something wrong */ }
+    }
+    return plugins
+}

package/src/plugins/api.js

@@ -4,6 +4,7 @@ import { createHash } from 'node:crypto'
 import _ from 'lodash'
 import sift from 'sift'
 import { resolveAuth, requireAuth, hasCapability, reachabilityOf } from '../auth.js'
+import { registerCapability } from '../roles.js'
 import { explain } from '../explain.js'
 import { buildReport, requestReport } from '../report.js'
 import { useRenderer } from '../render.js'
@@ -316,6 +317,17 @@ function sseSend(res, eventName, payload) {
     } catch { /* connection dropped — cleanup runs via 'close' */ }
 }
 
+// What each operation is, in words. Read by the capability registry so a
+// session can be told what `api:render` means without knowing this plugin.
+const API_OPERATIONS = {
+    list:        'read entities from the catalogue over HTTP',
+    update:      'create or change entities over HTTP',
+    delete:      'remove entities over HTTP',
+    render:      'trigger a render',
+    subscribe:   'hold an open connection for live changes',
+    diagnostics: 'read the build report and engine diagnostics',
+}
+
 export function api(options = {}) {
     return ({
         runtime,
@@ -445,6 +457,23 @@ export function api(options = {}) {
                 ? ['list', 'update', 'delete', 'render', 'subscribe']
                 : ['list']
             const allowedOps = new Set(ep.operations ?? defaultOps)
+
+            // What each api capability lets a caller DO, in the vocabulary of
+            // the catalogue rather than of HTTP. Declared here because this is
+            // where they are enforced — core should not have to know one
+            // plugin's operation names to explain a credential that holds
+            // them.
+            for (const op of allowedOps) {
+                registerCapability(`api:${op}`, {
+                    plugin: 'api',
+                    grants: 'operate',
+                    resource: {
+                        kind: 'operation',
+                        name: `api:${op}`,
+                        summary: API_OPERATIONS[op] ?? `the api's ${op} operation`,
+                    },
+                })
+            }
             // Recording the build report costs one entry per entity per
             // cycle, so it is off unless something can read it. An endpoint
             // exposing /report is that something.

package/src/plugins/render/hbs.js

@@ -45,7 +45,7 @@ function* walkPartials(node) {
 // helper args) can surface them under additional keys.
 export function parseReferences(source) {
     if (typeof source !== 'string' || !source) {
-        return { variables: [], partials: [], iterations: [], assigns: [], helpers: [] }
+        return { variables: [], partials: [], iterations: [], assigns: [], optional: [], helpers: [] }
     }
     let ast
     try {
@@ -53,7 +53,7 @@ export function parseReferences(source) {
     } catch (err) {
         // Author-side parse failure shouldn't kill inspect(). Surface
         // the message and an empty result.
-        return { variables: [], partials: [], iterations: [], assigns: [], helpers: [], parseError: err.message }
+        return { variables: [], partials: [], iterations: [], assigns: [], optional: [], helpers: [], parseError: err.message }
     }
 
     const variables  = new Set()
@@ -62,6 +62,12 @@ export function parseReferences(source) {
     const partials   = new Map()
     const iterations = []
     const helpers    = new Set()
+    // Keys the template reads only behind a guard, so their absence is
+    // tolerated rather than a gap. The same distinction liquid draws: a
+    // contract that reports every key as required makes an optional section
+    // look like a missing one, and an editor chases a field the page never
+    // needed.
+    const optional   = new Set()
 
     // Handlebars has no file-scoped assignment; aliases come from block
     // params (`as |x|`), which are scoped to their block. That scope is known
@@ -73,9 +79,12 @@ export function parseReferences(source) {
         const base = scope[head]
         return base ? [base, ...rest].join('.') : path
     }
-    const record = (path, scope) => {
+    const record = (path, scope, guarded = false) => {
         const resolved = deref(path, scope)
-        if (resolved) variables.add(resolved)
+        if (resolved) {
+            variables.add(resolved)
+            if (guarded) optional.add(resolved)
+        }
         return resolved
     }
     // A partial argument's path, or null when it is a literal — a quoted
@@ -86,16 +95,16 @@ export function parseReferences(source) {
     // pollute the helpers set. `each` shows up as an iteration instead.
     const BUILTIN_BLOCKS = new Set(['if', 'unless', 'each', 'with', 'lookup'])
 
-    function visit(node, scope = {}) {
+    function visit(node, scope = {}, guarded = false) {
         if (!node || typeof node !== 'object') return
         switch (node.type) {
             case 'Program':
-                for (const child of node.body ?? []) visit(child, scope)
+                for (const child of node.body ?? []) visit(child, scope, guarded)
                 break
             case 'MustacheStatement':
                 // {{path.to.var}} — record the path.
                 if (node.path?.type === 'PathExpression' && !BUILTIN_BLOCKS.has(node.path.original)) {
-                    record(node.path.original, scope)
+                    record(node.path.original, scope, guarded)
                 }
                 // {{helper arg1 arg2}} with args → it's a helper call.
                 if (node.params?.length && node.path?.original && !BUILTIN_BLOCKS.has(node.path.original)) {
@@ -103,8 +112,8 @@ export function parseReferences(source) {
                 }
                 // Walk param paths too — they're variable refs.
                 for (const param of node.params ?? []) {
-                    if (param?.type === 'PathExpression') record(param.original, scope)
-                    if (param?.type === 'SubExpression') visit(param, scope)
+                    if (param?.type === 'PathExpression') record(param.original, scope, guarded)
+                    if (param?.type === 'SubExpression') visit(param, scope, guarded)
                 }
                 break
             case 'SubExpression':
@@ -155,8 +164,16 @@ export function parseReferences(source) {
                         if (param?.type === 'SubExpression') visit(param, scope)
                     }
                 }
-                if (node.program) visit(node.program, inner)
-                if (node.inverse) visit(node.inverse, scope)
+                // `if` and `unless` are what make the content inside them
+                // optional; `each` and `with` are not — they narrow scope, and
+                // a key read inside one is read whenever the block runs at all.
+                //
+                // The CONDITION itself stays required: `{{#if hero}}` reads
+                // `hero` unconditionally to decide, exactly as liquid's `case`
+                // subject does.
+                const guards = node.path?.original === 'if' || node.path?.original === 'unless'
+                if (node.program) visit(node.program, inner, guarded || guards)
+                if (node.inverse) visit(node.inverse, scope, guarded || guards)
                 break
             }
             case 'PartialStatement':
@@ -200,6 +217,8 @@ export function parseReferences(source) {
         // params, already resolved above. Present and empty so every engine
         // returns the same shape and no caller has to branch on the engine.
         assigns:    [],
+        // Read only behind `{{#if}}` / `{{#unless}}`, so absence is tolerated.
+        optional:   Array.from(optional).sort(),
         helpers:    Array.from(helpers).sort(),
     }
 }

package/src/roles.js

@@ -22,27 +22,81 @@
 // whoever configures the site, and an agent's part in it is to say what it
 // cannot do and stop.
 
-// Capabilities follow `drive:<name>` to read and `drive:<name>:write` to
-// write. That convention is the whole mapping — it needs no list of endpoints
-// to stay correct as collections are added.
-const DRIVE = /^drive:([^:]+)(?::write)?$/
+// What each capability MEANS, declared by whoever owns it.
+//
+// Core used to carry a regex for `drive:<name>[:write]` — one plugin's naming
+// convention, hardcoded in the engine. It answered for drive and nothing else:
+// `api:list` and `mcp:use` came back as bare strings, a plugin adding its own
+// capability got no explanation at all, and the FOLDER behind a collection —
+// the thing an agent actually needs to reason about the site — was knowledge
+// core never had.
+//
+// A registry instead, the same shape as routes and schemas: the plugin that
+// enforces a capability is the one that can say what it protects, where it
+// lives and what it is for.
+const capabilityMeanings = new Map()
+
+// Declare one capability. Called by the plugin that enforces it.
+//
+//   registerCapability('drive:documents', {
+//       plugin: 'drive',
+//       grants: 'read',                       // 'read' | 'write' | 'operate'
+//       resource: {
+//           kind: 'collection',
+//           name: 'documents',
+//           folder: 'documents',              // where it is on disk
+//           summary: 'the words on the pages' // what it is FOR
+//       },
+//   })
+export function registerCapability(capability, meaning = {}) {
+    if (!capability) return
+    capabilityMeanings.set(capability, { capability, ...meaning })
+}
+
+export function capabilityMeaning(capability) {
+    const known = capabilityMeanings.get(capability)
+    if (known) return known
+    // Nothing declared it. The drive convention is still recognised, so a
+    // deployment whose plugins predate the registry keeps its answer rather
+    // than reporting every collection as an unexplained string.
+    const m = /^drive:([^:]+?)(:write)?$/.exec(capability)
+    if (!m) return null
+    return {
+        capability,
+        plugin: 'drive',
+        grants: m[2] ? 'write' : 'read',
+        resource: { kind: 'collection', name: m[1] },
+    }
+}
 
 // Split a capability list into what it can change and what it can only look
-// at. `readOnly` is the field that makes a refusal explainable, and it is more
-// useful than the capabilities it is derived from because it is already in the
-// vocabulary the person asking uses: collection names, not verbs.
+// at, described rather than merely named.
+//
+// `readOnly` is the field that makes a refusal explainable, and it is more
+// useful than the capabilities it comes from because it is already in the
+// vocabulary the person asking uses — a collection, the folder it lives in and
+// what that folder is for, not a verb.
 export function reachOf(capabilities = []) {
-    const readable = new Set()
+    const readable = new Map()
     const writable = new Set()
+    const also = []
     for (const capability of capabilities ?? []) {
-        const m = DRIVE.exec(capability)
-        if (!m) continue
-        readable.add(m[1])
-        if (capability.endsWith(':write')) writable.add(m[1])
+        const meaning = capabilityMeaning(capability)
+        const resource = meaning?.resource
+        if (!resource?.name) { also.push(capability); continue }
+        readable.set(resource.name, {
+            name: resource.name,
+            ...(resource.folder ? { folder: resource.folder } : {}),
+            ...(resource.summary ? { summary: resource.summary } : {}),
+            ...(resource.kind && resource.kind !== 'collection' ? { kind: resource.kind } : {}),
+        })
+        if (meaning.grants === 'write') writable.add(resource.name)
     }
+    const byName = (a, b) => a.name.localeCompare(b.name)
     return {
-        writable: [...writable].sort(),
-        readOnly: [...readable].filter(name => !writable.has(name)).sort(),
+        writable: [...readable.values()].filter(r => writable.has(r.name)).sort(byName),
+        readOnly: [...readable.values()].filter(r => !writable.has(r.name)).sort(byName),
+        also: also.sort(),
     }
 }
 
@@ -64,32 +118,28 @@ export function actingRole(held = [], catalogue = {}) {
     return names.find(candidate => names.every(other => covers(candidate, other))) ?? null
 }
 
-// The roles this principal does NOT hold, and what each would add.
+// Every role and what it may do, with the acting one marked.
 //
-// Named so an agent can say WHO to ask. Roles are not credentials — listing
-// them reveals that a `developers` role exists, which is exactly what makes a
-// handoff possible, and nothing about how to obtain it.
-export function otherRoles(held = [], catalogue = {}, summaries = {}) {
-    const mine = new Set(held ?? [])
-    const have = new Set((held ?? []).flatMap(name => catalogue[name] ?? []))
-    return Object.entries(catalogue)
-        .filter(([name]) => !mine.has(name))
-        .map(([name, capabilities]) => {
-            const adds = (capabilities ?? []).filter(capability => !have.has(capability))
-            // A role that adds nothing this principal already has is noise in
-            // a handoff — there is nobody to ask, because it can do no more.
-            if (!adds.length) return null
-            const reach = reachOf(adds)
-            return {
-                name,
-                // Expressed as collections where the capabilities allow it,
-                // because "layouts, styles, scripts" is what a person asking
-                // for help can act on and `drive:layouts:write` is not.
-                adds: reach.writable.length ? reach.writable : adds,
-                ...(summaries[name] ? { summary: summaries[name] } : {}),
-            }
-        })
-        .filter(Boolean)
+// One list rather than two. A "roles you do not have" field cannot describe
+// the site to whoever holds the widest one — an admin sees an empty array and
+// concludes no other roles exist — and a reader comparing their own reach
+// against someone else's needs both sides in the same shape anyway.
+//
+// Roles are not credentials. Naming them, and saying what each can reach, is
+// what makes a handoff possible: it tells an agent who to ask. It reveals
+// nothing about how to become one, and there is no way to ask for one.
+export function rolesIn(catalogue = {}, { acting = null, summaries = {} } = {}) {
+    return Object.entries(catalogue).map(([name, capabilities]) => {
+        const { writable, readOnly, also } = reachOf(capabilities)
+        return {
+            name,
+            ...(name === acting ? { acting: true } : {}),
+            ...(summaries[name] ? { summary: summaries[name] } : {}),
+            writable,
+            readOnly,
+            ...(also.length ? { also } : {}),
+        }
+    })
 }
 
 // Everything a session should be able to say about its own authority.
@@ -105,18 +155,20 @@ export function describeAuthority({ capabilities, roles = [], catalogue = {}, su
             capabilities: null,
             writable: null,
             readOnly: null,
-            otherRoles: [],
+            roles: [],
         }
     }
     const role = actingRole(roles, catalogue)
     const { writable, readOnly } = reachOf(capabilities)
     return {
         role,
-        ...(roles?.length && !role ? { roles } : {}),
+        // Only when no single role covers the others: the acting authority is
+        // then the union, and naming one of them would be a lie.
+        ...(roles?.length && !role ? { heldRoles: roles } : {}),
         ...(summaries[role] ? { roleSummary: summaries[role] } : {}),
         writable,
         readOnly,
-        otherRoles: otherRoles(roles, catalogue, summaries),
+        roles: rolesIn(catalogue, { acting: role, summaries }),
     }
 }