Integrate wave 11 (admin): 33 plugins, 374 tests — the capstone

compose.test.js boots all 33; serve.js's front door is now /admin/,
fed by ONE shared INVENTORY array beside the real plugins list — the
hand-copied-registry workaround living in the demo itself (#463/#464).
ADMIN_AGENTS env gates the operator home; without it the plugin warns
loudly that the surface is open.

Docs folded: NOTES gains seams 11 (api.isOperator — terminal, metrics
and admin hold three incompatible answers to 'who is the operator?')
and 12 (the admin-surface gaps: runtime lifecycle, install, settings
panels, log tailing, storage introspection); api.plugins is now a
two-consumer seam. REPORT.md gains 'The wp-admin test' — the capstone
gap table: the read side of a WordPress-style admin works today but
only by the operator re-telling the plugin what the host already
knows three ways; the write side's absences each name their seam.

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. **32 plugins, 363 tests today.**
+wall you hit as a finding, not a blocker. **33 plugins, 374 tests today.**
 
 ### The one rule that makes the experiment valid
 
@@ -157,6 +157,7 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 | a stateless request/response protocol (mail, sync, …) | `jmap/` | loopback CRUD + in-protocol refusal of push/delta |
 | a storage protocol with conditional writes | `remotestorage/` | If-Match/If-None-Match pass through loopback intact |
 | a redirect / metadata micro-service | `shortlink/` | pluginDir JSON table + wildcard slug routes |
+| an operator/admin surface | `admin/` | compose probes + podsRoot scan behind an agent allowlist |
 
 ## Footguns (every multi-boot suite rediscovered these)
 
@@ -178,7 +179,7 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 
 ## Current state
 
-32 plugins (7 ports + 25 features), 363 tests, all green (`npm test`).
+33 plugins (7 ports + 26 features), 374 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

@@ -43,6 +43,7 @@ evidence. Legend:
 | — | `jmap/` | JMAP mail over the pod (push/delta → 🔩 `api.events`; blobs → 🔩 #583) |
 | #163 | `remotestorage/` | remoteStorage server — 7th port; witnessed the webfinger collision |
 | — | `shortlink/` | link shortener for pod URLs (pluginDir persistence, 11th witness) |
+| #463/#464-adj | `admin/` | operator home — the wp-admin gap analysis; every missing pillar names a seam |
 
 Plus seven **ports of bundled features** proving the migration path for
 #564 / #164: `relay/` `webrtc/` `terminal/` `tunnel/` `notifications/`
@@ -106,11 +107,11 @@ exists.
 
 Of ~40 plugin-tagged issues: **14 built as plugins here** (plus `rss/`,
 `matrix/`, `search/`, `didweb/`, `s3/`, `micropub/`, `backup/`, `metrics/`,
-`dashboard/`, `oembed/`, `jmap/`, `shortlink/` — capability
+`dashboard/`, `oembed/`, `jmap/`, `shortlink/`, `admin/` — capability
 demonstrations with no single issue), **7 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. **32 plugins total, 363 tests.** The plugin api reaches most
+product-scale. **33 plugins total, 374 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` (7
 consumers — matrix `/sync` needs live push, jmap can't do push or delta

NEXT.md

@@ -8,16 +8,18 @@ plugin), `NOTES.md` (the findings/seams — the real deliverable), and
 
 ## Where things stand
 
-- **32 plugins, 363 tests, all green** (`npm test`), all pushed to
+- **33 plugins, 374 tests, all green** (`npm test`), all pushed to
   `github.com/JavaScriptSolidServer/plugins` (branch `gh-pages`).
-- `compose.test.js` boots all 32 on **one** JSS from pure config; `serve.js`
-  is the runnable demo. Both must be updated when you add a plugin.
+- `compose.test.js` boots all 33 on **one** JSS from pure config; `serve.js`
+  is the runnable demo — its front door is now `admin/` (`/admin/`), the
+  capstone wp-admin-style operator home fed by a shared `INVENTORY` array.
+  All three must be updated when you add a plugin.
 - Built so far: 7 ports (relay, webrtc, terminal, tunnel, notifications,
-  remotestorage, pay) + 25 features (nip05, corsproxy, capability, webdav,
+  remotestorage, pay) + 26 features (nip05, corsproxy, capability, webdav,
   sparql — now with UPDATE, gitscratch, otp, carddav, mastodon, bluesky,
   caldav — now with free-busy, webfinger,
   activitypub, rss, matrix, search, didweb, s3, micropub, backup,
-  metrics, dashboard, oembed, jmap, shortlink).
+  metrics, dashboard, oembed, jmap, shortlink, admin).
 - Capability classes covered: realtime, WebDAV family, fediverse/social/chat
   (5 shims), IndieWeb publishing, identity, data/query/search, object
   storage, proxy, dev, pay, data portability, ops/observability, mail,

NOTES.md

@@ -179,14 +179,33 @@ ports reached for it without coordinating.
    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:
+10. **`api.plugins` (the #463/#464 app-registry) — two consumers:
+    dashboard/ and admin/.** The plugins whose job is describing the
+    deployment cannot enumerate their co-loaded siblings; the operator
+    hands each a
+    hand-copied duplicate of the `createServer` plugins list, and the
+    copies silently drift (an added plugin never appears; a removed one
+    keeps probing). serve.js now maintains ONE shared `INVENTORY` array
+    beside the real plugins array — the workaround that proves the
+    seam. The loader already holds exactly the needed data:
     `api.plugins → [{ id, prefix, module }]`, read-only, plus optional
     probe/health hints per entry.
+11. **No operator concept — `api.isOperator` (admin/).** Three plugins
+    now hold three incompatible answers to "who is the operator?":
+    terminal/ (shared token), metrics/ (optional bearer token), admin/
+    (`adminAgents` WebID allowlist). The host itself knows nothing of
+    operators, so every ops-facing plugin invents its own gate. A tiny
+    seam (`api.isOperator(agentId)` or an `operators: []` server option)
+    would unify them.
+12. **The admin-surface gaps, named (admin/).** The wp-admin pillars the
+    api cannot express, each measured by building the operator home:
+    runtime **enable/disable** (`deactivate()` exists but nothing calls
+    it after boot), **install** (#200 marketplace + post-boot loading),
+    **settings panels** (no contribute-a-panel affordance — the
+    `adminPage` link convention is the workaround), **log viewing**
+    (`api.log` is write-only), and **storage introspection** (pods/disk
+    stats need an operator-repeated `podsRoot` path — a filesystem
+    cousin of `api.serverInfo`). Full gap table in admin/README.md.
 
 ## Test-harness footguns (host quirks, not plugin api)
 

README.md

@@ -90,9 +90,10 @@ README and NOTES.md, ship the closest honest approximation.
 | `oembed/` | — | oEmbed provider for pod resources (link unfurling; XSS-refusing) |
 | `jmap/` | — | JMAP mail over pod messages — the stateless/push line, sharpened |
 | `shortlink/` | — | link shortener for pod URLs (deliberately not an open redirector) |
+| `admin/` | — | **the capstone**: wp-admin-style operator home; each missing pillar names its seam |
 
-**363 tests, all green** (`npm test`), including `compose.test.js` — all
-thirty-two plugins on one server from pure config, pods + WAC intact
+**374 tests, all green** (`npm test`), including `compose.test.js` — all
+thirty-three 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, 32 plugins later — a report for the maintainer
+# The plugin api, 33 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,7 +14,7 @@ drafted so it could be filed nearly verbatim if wanted.
 ## Executive summary
 
 - The api as shipped in 0.0.215 (`createServer({ plugins })` + `prefix` +
-  `getAgent` + `pluginDir` + `ws.route`) is **sufficient for 32 real
+  `getAgent` + `pluginDir` + `ws.route`) is **sufficient for 33 real
   plugins across fifteen capability classes** — realtime, DAV,
   fediverse/chat shims, IndieWeb publishing, identity, query/search,
   object storage, proxy, dev tooling, pay, data portability,
@@ -187,11 +187,17 @@ 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` (the #463/#464 app-registry)** — two consumers:
+  `dashboard/` and `admin/`, the plugins whose whole job is describing
+  the deployment, must each be handed a hand-copied duplicate of the
+  `createServer` plugins list (drift is silent; `serve.js` now maintains
+  a shared `INVENTORY` array beside the real list — the workaround that
+  proves the seam). The loader already holds the needed data:
   `api.plugins → [{ id, prefix, module }]`, read-only.
+- **`api.isOperator` (an operator concept)** — terminal/, metrics/ and
+  admin/ hold three incompatible answers to "who is the operator?"
+  (shared token, optional bearer, WebID allowlist). A tiny seam — an
+  `operators: []` server option surfaced to plugins — would unify them.
 - **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
@@ -268,6 +274,30 @@ hooks are ever capability-gated (`capabilities: ['hooks']` /
 `['observe']`), the shared scope could become the *granted* behavior and
 isolation the default.
 
+## The wp-admin test (the capstone)
+
+`admin/` asks the question every plugin platform eventually answers: can
+the ecosystem build its own WordPress-style admin? The read side — server
+health, live plugin inventory with probes, pod/user and storage stats,
+an agent-allowlist gate — works today, **but only because the operator
+re-tells the plugin what the host already knows, three different ways**
+(origin, plugins list, data root). The write side is where the api's
+edges are exact:
+
+| wp-admin pillar | Today | The seam |
+|---|---|---|
+| Plugin inventory | hand-copied config, silent drift | `api.plugins` (#463/#464) |
+| Install from a store | impossible (boot-time config) | #200 + post-boot loading |
+| Enable / disable | impossible — `deactivate()` exists, nothing calls it at runtime | runtime lifecycle on the loader |
+| Per-plugin settings panels | `adminPage` link convention | a contribute-a-panel affordance |
+| Health | ✅ live probes | registry health hints would refine it |
+| Users / storage | ✅ via operator-repeated `podsRoot` | storage introspection (cousin of `serverInfo`) |
+| Logs | impossible — `api.log` is write-only | a log-tailing seam |
+| Who is admin? | every plugin invents a gate | `api.isOperator` / `operators: []` |
+
+None of these are asks to build an admin panel into core — the plugin
+proves the *shell* can live out-of-tree; the seams are the data feeds.
+
 ## The core/plugin line (#564, answered empirically)
 
 **A feature is plugin-able iff it OWNS its routes; it stays core iff it

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 + thirty-two plugins from config', async () => {
+  it('boots pods + idp + thirty-three plugins from config', async () => {
     const port = await probePort();
     base = `http://127.0.0.1:${port}`;
     wsBase = `ws://127.0.0.1:${port}`;
@@ -108,6 +108,22 @@ describe('composition: every plugin on one server', () => {
           config: { baseUrl: base, loopbackUrl: base, claimWellKnown: false },
         },
         { id: 'metrics', module: at('metrics/plugin.js'), prefix: '/metrics', config: { loopbackUrl: base } },
+        {
+          id: 'admin',
+          module: at('admin/plugin.js'),
+          prefix: '/admin',
+          // No adminAgents in the composition → open mode (the plugin warns
+          // loudly at activate; the finding: no operator concept in the api).
+          config: {
+            loopbackUrl: base,
+            baseUrl: base,
+            podsRoot: root,
+            plugins: [
+              { id: 'nip05', prefix: '/nip05', probe: '/nip05/nostr.json', expect: [200] },
+              { id: 'metrics', prefix: '/metrics', probe: '/metrics/healthz', expect: [200] },
+            ],
+          },
+        },
         {
           id: 'dashboard',
           module: at('dashboard/plugin.js'),
@@ -349,6 +365,19 @@ describe('composition: every plugin on one server', () => {
     assert.strictEqual(res.status, 400); // missing ?resource — endpoint alive
   });
 
+  it('admin: the operator home renders with plugin inventory and pods stats', async () => {
+    let res = await fetch(`${base}/admin/`);
+    assert.strictEqual(res.status, 200);
+    const page = await res.text();
+    assert.ok(page.includes('nip05'));
+    assert.ok(page.includes('metrics'));
+    res = await fetch(`${base}/admin/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.state === 'up'), JSON.stringify(status.plugins));
+  });
+
   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);