Integrate wave 8 (metrics, dashboard): 28 plugins, 282 tests

compose.test.js and serve.js boot all 28; serve.js's dashboard entry
carries a hand-copied probe list mirroring its own plugins array —
which is the finding it exists to demonstrate (#463/#464: no
api.plugins registry, so the two lists can silently drift).

Findings folded into NOTES.md and REPORT.md: (1) plugin-to-plugin
isolation is zero, measured — api.fastify hooks fire for every
plugin's routes in the shared register scope, never for core's, so the
#564 line holds against core but siblings can observe and intercept
each other ungated; (2) core bug: logger:false breaks every plugin
onResponse hook (access-log hook throws on the null logger and aborts
the chain) — filed-worthy one-liner; (3) the app-registry seam
(#463/#464) gains its first live consumer; (4) api.serverInfo is now
~14 consumers. REPORT.md gains 'A measured surprise' section and the
third bug; AGENT.md gains the logger footgun and two copy-map rows.

Author: melvincarvalho

AGENT.md

@@ -11,7 +11,7 @@ Out-of-tree plugins for [JavaScript Solid
 Server](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer),
 built on its **#206 loader** (`createServer({ plugins })`, JSS ≥ 0.0.215).
 It is an *experiment*: prove the plugin api by using it, and treat every
-wall you hit as a finding, not a blocker. **26 plugins, 264 tests today.**
+wall you hit as a finding, not a blocker. **28 plugins, 282 tests today.**
 
 ### The one rule that makes the experiment valid
 
@@ -151,6 +151,8 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 | a dev/tooling subsystem | `gitscratch/` | shell a system binary via CGI |
 | a posting protocol (IndieWeb-style, client-discovered endpoint) | `micropub/` | pod bearer as the protocol token + loopback writes |
 | a data-export / archive download | `backup/` | loopback container walk streamed into a hand-rolled format |
+| an ops/observability endpoint | `metrics/` | node builtins + an `api.fastify` hook (scope: all plugins, never core) |
+| a meta/status page over siblings | `dashboard/` | anonymous loopback probes + an operator-declared list (no registry) |
 
 ## Footguns (every multi-boot suite rediscovered these)
 
@@ -165,10 +167,14 @@ Full ranking in `NOTES.md`. The ones you'll hit:
   pass an explicit `id` in `compose.test.js`/`serve.js`.
 - **Dotted prefixes** (`/.foo`) fail the WS upgrade — core reserves dotted
   paths. Use a plain prefix for anything with a socket.
+- **`logger: false` kills plugin `onResponse` hooks**: core's access-log
+  hook throws on the null logger and aborts the downstream chain. If your
+  plugin uses `onResponse`, boot tests with `logger: true, logLevel:
+  'silent'` (helpers.js defaults to `logger: false`).
 
 ## Current state
 
-26 plugins (6 ports + 20 features), 264 tests, all green (`npm test`).
+28 plugins (6 ports + 22 features), 282 tests, all green (`npm test`).
 `compose.test.js` runs every one on a single server from pure config. Two
 core PRs (#590 `api.mountApp`, #591 `/idp/refresh`) sit upstream, unmerged,
 for the maintainer's call. Everything else lives here, by design.

ISSUES.md

@@ -37,6 +37,8 @@ evidence. Legend:
 | — | `s3/` | S3-compatible object-storage gateway |
 | — | `micropub/` | IndieWeb Micropub endpoint (media upload → 🔩 raw-body stream #583) |
 | — | `backup/` | pod → `.tar.gz` export (incremental backup → 🔩 `api.events`) |
+| — | `metrics/` | `/healthz` + Prometheus exporter (core-pipeline metrics → 🔩 gated hooks) |
+| — | `dashboard/` | plugin status page (sibling discovery → 🔩 app-registry #463/#464) |
 
 Plus six **ports of bundled features** proving the migration path for #564 /
 #164: `relay/` `webrtc/` `terminal/` `tunnel/` `notifications/`, and `pay/`
@@ -71,7 +73,7 @@ Each names the seam and the consumer that proves it. Ranked in
 | #515/#516, #211 (both built, but need operator `appPaths`) | `api.reservePath()` — an API-shim owns fixed roots outside its prefix and can't self-exempt them from WAC; **two independent confirmations** |
 | #505 (recovery) | `api.auth.mintSession` / `api.identity.addAuthKey` — turn a proven channel into pod authority |
 | #495 #496 #500 #501 | `api.mcp.registerTool` — MCP has no plugin-tool seam; all four MCP issues want new tools a plugin can't add today |
-| #463 #464 | app-registry primitive — surfacing installed plugins as Solid resources |
+| #463 #464 | app-registry primitive — surfacing installed plugins as Solid resources; `dashboard/` is the live proof-of-need (it must be handed a hand-copied duplicate of the `createServer` list) |
 
 ## Core, not a plugin 🏛️ (a finding, not a gap)
 
@@ -98,11 +100,12 @@ exists.
 ## Tally
 
 Of ~40 plugin-tagged issues: **13 built as plugins here** (plus `rss/`,
-`matrix/`, `search/`, `didweb/`, `s3/`, `micropub/`, `backup/` — capability
+`matrix/`, `search/`, `didweb/`, `s3/`, `micropub/`, `backup/`, `metrics/`,
+`dashboard/` — capability
 demonstrations with no single issue), **6 ported**, **5 shipped upstream**,
 **2 more plugin-able with no blocker**, **6 clusters blocked on a named
 seam** (each with a proof-of-need consumer), the rest core-by-nature or
-product-scale. **26 plugins total, 264 tests.** The plugin api reaches most
+product-scale. **28 plugins total, 282 tests.** The plugin api reaches most
 of the backlog today; ranked by demand, the seams that would unlock the
 most next are `api.authorize` (3 blocking consumers), `api.events` (5
 consumers — matrix `/sync` needs live push, backup can only pull-on-demand),

NEXT.md

@@ -8,17 +8,18 @@ plugin), `NOTES.md` (the findings/seams — the real deliverable), and
 
 ## Where things stand
 
-- **26 plugins, 264 tests, all green** (`npm test`), all pushed to
+- **28 plugins, 282 tests, all green** (`npm test`), all pushed to
   `github.com/JavaScriptSolidServer/plugins` (branch `gh-pages`).
-- `compose.test.js` boots all 26 on **one** JSS from pure config; `serve.js`
+- `compose.test.js` boots all 28 on **one** JSS from pure config; `serve.js`
   is the runnable demo. Both must be updated when you add a plugin.
 - Built so far: 6 ports (relay, webrtc, terminal, tunnel, notifications,
-  pay) + 20 features (nip05, corsproxy, capability, webdav, sparql,
+  pay) + 22 features (nip05, corsproxy, capability, webdav, sparql,
   gitscratch, otp, carddav, mastodon, bluesky, caldav, webfinger,
-  activitypub, rss, matrix, search, didweb, s3, micropub, backup).
+  activitypub, rss, matrix, search, didweb, s3, micropub, backup,
+  metrics, dashboard).
 - Capability classes covered: realtime, WebDAV family, fediverse/social/chat
   (5 shims), IndieWeb publishing, identity, data/query/search, object
-  storage, proxy, dev, pay, data portability.
+  storage, proxy, dev, pay, data portability, ops/observability.
 - **REPORT.md exists** — the maintainer-facing summary (ranked seams, each
   fileable nearly verbatim). Keep its consumer counts current as plugins
   land.
@@ -75,8 +76,6 @@ Still genuinely plugin-shaped and distinct:
 - **oEmbed** provider for pod resources (link unfurling).
 - **feed ingest** — subscribe to external RSS/Atom, store items in the pod
   (the inverse of `rss/`; uses a corsproxy-style fetch).
-- **healthz / Prometheus `/metrics`** and a **plugin status dashboard**
-  (ops; the dashboard is a nice meta-demo listing all loaded plugins).
 - **link-shortener**, **WebSub/PubSubHubbub** (needs `api.events`),
   **SPARQL UPDATE** (extends `sparql/`), **CalDAV scheduling/free-busy**
   (extends `caldav/`), **remoteStorage** (another bundled-feature port).

NOTES.md

@@ -125,6 +125,27 @@ ports reached for it without coordinating.
    advertise it by hand). A plugin can't add headers to routes it doesn't
    own. NOT a default-on hook (bigger grant than route ownership); gate
    behind `capabilities: ['hooks']` if ever.
+9. **Plugin-to-plugin isolation is ZERO (measured — metrics/).** All
+   loader entries are activated against **one shared Fastify register
+   scope**: a hook added on `api.fastify` (`onRequest`, `preHandler`,
+   `onResponse`, `onSend`) fires for **every plugin's routes, whichever
+   order the entries load** — and **never** for core routes (`/`, LDP,
+   `/.well-known/*`), which live on the parent instance behind Fastify
+   encapsulation. So the #564 line holds against *core* (a plugin cannot
+   observe or modify core's pipeline), but plugins can already observe
+   *and intercept* each other with no capability gate. Design tension for
+   any future `capabilities: ['hooks']`: per-plugin encapsulation would be
+   the safer default, but it would break the one legitimate consumer found
+   (metrics/' cross-plugin request counters) — a scoped-vs-shared choice
+   the loader should make deliberately, not inherit from `register`.
+10. **`api.plugins` (the #463/#464 app-registry) — first live consumer:
+    dashboard/.** The one plugin whose job is describing the deployment
+    cannot enumerate its co-loaded siblings; the operator hands it a
+    hand-copied duplicate of the `createServer` plugins list, and the two
+    silently drift (an added plugin never appears; a removed one keeps
+    probing). The loader already holds exactly the needed data:
+    `api.plugins → [{ id, prefix, module }]`, read-only, plus optional
+    probe/health hints per entry.
 
 ## Test-harness footguns (host quirks, not plugin api)
 
@@ -184,6 +205,15 @@ this repo is its proof.
   candidate: when the basename is generic (`plugin`, `index`), derive from
   the parent directory (`relay/plugin.js` → `relay`). Small, backward-
   compatible, removes the most common footgun. **Filed-worthy.**
+- **`logger: false` silently kills every plugin `onResponse` hook**
+  (metrics/): core's access-log hook calls
+  `request.log.isLevelEnabled('info')`, which doesn't exist on Fastify's
+  null logger under `logger: false` — the hook throws per-request and the
+  aborted chain means downstream *plugin* `onResponse` hooks never run
+  (earlier stages are unaffected). Workaround: boot with `logger: true,
+  logLevel: 'silent'`. One-line core fix; **filed-worthy.** (helpers.js
+  defaults to `logger: false`, so any plugin using `onResponse` in tests
+  hits this.)
 - **Dotted prefixes fail the ws upgrade** — a plugin mounted at
   `/.terminal` cannot accept WebSocket connections (immediate upgrade
   error), while `/terminal` and even `/.notifications` HTTP work. Core

README.md

@@ -84,9 +84,11 @@ README and NOTES.md, ship the closest honest approximation.
 | `s3/` | — | S3-compatible object-storage gateway (SigV4) |
 | `micropub/` | — | IndieWeb Micropub endpoint — posts land in the author's pod |
 | `backup/` | — | pod container → `.tar.gz` download (data portability) |
+| `metrics/` | — | `/healthz` + Prometheus exporter; measured the plugin-hook scope |
+| `dashboard/` | — | live plugin-status page; first consumer of the #463/#464 registry seam |
 
-**264 tests, all green** (`npm test`), including `compose.test.js` — all
-twenty-six plugins on one server from pure config, pods + WAC intact
+**282 tests, all green** (`npm test`), including `compose.test.js` — all
+twenty-eight plugins on one server from pure config, pods + WAC intact
 beside them. Findings consolidated in [NOTES.md](./NOTES.md); the full
 plugin-tagged backlog triaged in [ISSUES.md](./ISSUES.md); the build guide
 is [AGENT.md](./AGENT.md); the maintainer-facing summary — what to add

REPORT.md

@@ -1,4 +1,4 @@
-# The plugin api, 26 plugins later — a report for the maintainer
+# The plugin api, 28 plugins later — a report for the maintainer
 
 This document is the actionable summary of the whole experiment: what the
 #206 plugin api can already do, what it can't, and — ranked with evidence —
@@ -14,11 +14,11 @@ want it.
 ## Executive summary
 
 - The api as shipped in 0.0.215 (`createServer({ plugins })` + `prefix` +
-  `getAgent` + `pluginDir` + `ws.route`) is **sufficient for 26 real
-  plugins across eleven capability classes** — realtime, DAV,
+  `getAgent` + `pluginDir` + `ws.route`) is **sufficient for 28 real
+  plugins across twelve capability classes** — realtime, DAV,
   fediverse/chat shims, IndieWeb publishing, identity, query/search,
-  object storage, proxy, dev tooling, pay, data portability — with zero
-  core changes.
+  object storage, proxy, dev tooling, pay, data portability,
+  ops/observability — with zero core changes.
 - Of the ~40 `plugin`-tagged backlog issues, **13 are built here**, 6
   bundled features are ported, 5 shipped upstream during this line of work,
   2 more are unblocked, and **6 clusters are blocked on exactly four
@@ -27,8 +27,13 @@ want it.
   `api.events.onResourceChange`, `api.reservePath`, and `api.serverInfo`.
   Adding the first three moves essentially every remaining plugin-shaped
   issue from "honest approximation" to "faithful implementation".
-- Two small loader bugs are worth fixing regardless (generic-basename id
-  derivation; dotted-prefix WS validation).
+- Three small loader/core bugs are worth fixing regardless
+  (generic-basename id derivation; dotted-prefix WS validation;
+  `logger: false` breaking every plugin `onResponse` hook).
+- One measured surprise: **plugins are not isolated from each other** —
+  all entries share one Fastify register scope, so any plugin can hook
+  every other plugin's routes (never core's). Worth a deliberate
+  decision, not an inherited one.
 
 ## What already works — decisions worth keeping
 
@@ -131,9 +136,9 @@ exists, moving it from operator config to plugin declaration.
 
 ### 4. `api.serverInfo` — the broadest, and the cheapest
 
-**~12 consumers** — every plugin that mints absolute URLs or loopbacks
+**~14 consumers** — every plugin that mints absolute URLs or loopbacks
 (the DAV family, the shims, rss, sparql, nip05, webfinger, notifications,
-micropub, backup…)
+micropub, backup, metrics, dashboard…)
 repeats `baseUrl`/`loopbackUrl` in config today. A wrong value fails
 *quietly* (nip05 serves an empty map). Test suites all need a
 probe-port-then-boot dance for the same reason.
@@ -149,6 +154,11 @@ probe-port-then-boot dance for the same reason.
   property to preserve, not new work.
 - **`api.mcp.registerTool`** — blocks the four MCP-tool issues
   (#495/#496/#500/#501); no consumer here because it's impossible today.
+- **`api.plugins` (the #463/#464 app-registry)** — first live consumer:
+  `dashboard/`, the plugin whose whole job is describing the deployment,
+  must be handed a hand-copied duplicate of the `createServer` plugins
+  list (drift is silent). The loader already holds the needed data:
+  `api.plugins → [{ id, prefix, module }]`, read-only.
 - **Export pure utility modules** the way `auth.js` is blessed —
   `relay/` re-vendors NIP-01 verify, `pay/` re-vendors mrc20. A
   `javascript-solid-server/nostr.js` export (or explicit vendoring
@@ -162,7 +172,7 @@ probe-port-then-boot dance for the same reason.
   Deliberately *not* asked for as a default-on hook: it's a bigger grant
   than route ownership. If ever, gate it: `capabilities: ['hooks']`.
 
-## Two loader bugs worth fixing regardless
+## Three loader/core bugs worth fixing regardless
 
 1. **Generic-basename id derivation.** Every plugin follows
    `<name>/plugin.js`, so every derived id is `plugin` and the (correct)
@@ -174,6 +184,36 @@ probe-port-then-boot dance for the same reason.
    can't accept WebSocket connections (host-reserved dotted paths), while
    `/terminal` works. Either validate/refuse dotted prefixes at load or
    document the reservation.
+3. **`logger: false` silently disables every plugin `onResponse` hook.**
+   Core's access-log hook calls `request.log.isLevelEnabled('info')`,
+   which doesn't exist on Fastify's null logger; the per-request throw
+   aborts the downstream hook chain, so plugin `onResponse` hooks never
+   fire (found by `metrics/`). One-line guard fixes it.
+
+## A measured surprise: plugins are not isolated from each other
+
+`metrics/` needed request counters, so it added an `onResponse` hook on
+`api.fastify` and measured what the hook can see (both entry orders,
+core routes probed too). Result: **the hook fires for every plugin's
+routes and never for core's.** All loader entries are activated against
+one shared `fastify.register` scope, while core routes live on the
+parent instance behind Fastify encapsulation.
+
+Two readings, both true:
+
+- The #564 line **holds against core** — a plugin cannot observe or
+  modify the pipeline of core routes, exactly as intended.
+- Plugins can already observe **and intercept** each other, ungated. A
+  hostile or buggy plugin can shadow-log or rewrite a sibling's traffic
+  today.
+
+This is worth a deliberate decision rather than an inherited one:
+per-plugin encapsulation (each entry in its own `register` scope) is the
+safer default, but note it would break the one legitimate cross-plugin
+consumer found (a metrics exporter counting all plugin traffic) — if
+hooks are ever capability-gated (`capabilities: ['hooks']` /
+`['observe']`), the shared scope could become the *granted* behavior and
+isolation the default.
 
 ## The core/plugin line (#564, answered empirically)
 

compose.test.js

@@ -46,7 +46,7 @@ describe('composition: every plugin on one server', () => {
 
   after(async () => { if (jss) await jss.close(); });
 
-  it('boots pods + idp + twenty-six plugins from config', async () => {
+  it('boots pods + idp + twenty-eight plugins from config', async () => {
     const port = await probePort();
     base = `http://127.0.0.1:${port}`;
     wsBase = `ws://127.0.0.1:${port}`;
@@ -95,6 +95,22 @@ describe('composition: every plugin on one server', () => {
         { id: 's3', module: at('s3/plugin.js'), prefix: '/s3', config: { baseUrl: base, loopbackUrl: base } },
         { id: 'micropub', module: at('micropub/plugin.js'), prefix: '/micropub', config: { baseUrl: base, loopbackUrl: base } },
         { id: 'backup', module: at('backup/plugin.js'), prefix: '/backup', config: { baseUrl: base, loopbackUrl: base } },
+        { id: 'metrics', module: at('metrics/plugin.js'), prefix: '/metrics', config: { loopbackUrl: base } },
+        {
+          id: 'dashboard',
+          module: at('dashboard/plugin.js'),
+          prefix: '/dashboard',
+          config: {
+            loopbackUrl: base,
+            // A hand-copied slice of this very list — a plugin can't see its
+            // siblings (the #463/#464 app-registry finding).
+            plugins: [
+              { id: 'nip05', probe: '/nip05/nostr.json', expect: [200] },
+              { id: 'rss', probe: '/feed/atom', expect: [400] },
+              { id: 'relay', probe: '/relay', kind: 'ws' },
+            ],
+          },
+        },
       ],
     });
     assert.ok(jss.base);
@@ -294,6 +310,27 @@ describe('composition: every plugin on one server', () => {
     assert.strictEqual(res.status, 400);
   });
 
+  it('metrics: healthz is ok and the exposition names the process gauges', async () => {
+    let res = await fetch(`${base}/metrics/healthz`);
+    assert.strictEqual(res.status, 200);
+    assert.strictEqual((await res.json()).status, 'ok');
+    res = await fetch(`${base}/metrics/metrics`);
+    assert.strictEqual(res.status, 200);
+    assert.match(await res.text(), /process_uptime_seconds/);
+  });
+
+  it('dashboard: the page names the declared plugins; status.json probes live', async () => {
+    let res = await fetch(`${base}/dashboard/`);
+    assert.strictEqual(res.status, 200);
+    const page = await res.text();
+    for (const id of ['nip05', 'rss', 'relay']) assert.ok(page.includes(id), id);
+    res = await fetch(`${base}/dashboard/status.json`);
+    assert.strictEqual(res.status, 200);
+    const status = await res.json();
+    assert.strictEqual(status.server.alive, true);
+    assert.ok(status.plugins.every((p) => p.alive), JSON.stringify(status.plugins));
+  });
+
   it('pods still work beside all of it (idp register + WAC)', async () => {
     let res = await fetch(`${base}/idp/register`, {
       method: 'POST',