the hono app is built, not assembled once

first piece of the plugin system: the platform can now be rebuilt with a
different set of plugins mounted, at runtime, without restarting.

hono cannot do this the obvious way. its default SmartRouter throws "Can not add
a route since the matcher is already built" the moment a route is added after
serving begins, RegExpRouter does the same, and hono has no api to REMOVE a
route at all — so uninstall was impossible even with TrieRouter, which does
allow adding. tested all four.

so nothing is added to a live app. buildHonoApp(plugins) constructs a fresh one
and honoServer is reassigned, which keeps the default fast router and makes
uninstall expressible. server.tsx now serves it through a closure rather than
the bound honoServer.fetch — that one line is the whole mechanism, since the
bound method would capture whichever app existed at serve() and every rebuild
would silently do nothing.

buildHonoApp is pure: everything it needs arrives as an argument, so an app for
a hypothetical plugin set can be built without a database, a filesystem or a
running server.

alongside it, discovery. plugins live at platform/plugins/<app-name>/ — inside
the repo, because bun links the workspace packages into the root node_modules
and that is what lets a plugin author write `import { useClient } from
'hooks/useClient'` with no publishing and no version negotiation. verified with
Bun.resolveSync from a directory there.

discovery is by convention and presence is the declaration: api/router.ts,
db/schema.ts, sidecar/index.ts, web/Router.tsx. the app name comes from the
directory, so it cannot disagree with where the code sits, and the sidecar
runtime comes from the extension — .mjs is node, .ts is bun — which is already
the rule here and cannot contradict the file it describes.

a broken plugin is collected, never thrown: one unreadable manifest must not
stop the boot or hide the nine beside it that are fine.

verified by booting the refactored server on a spare port — /api answers 200,
protected routes still 401. full suite: 719 pass, and the same 10 failures as
before this change (8 in capabilities, plus cliamp and pty), stash-verified
earlier as pre-existing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/servers/plugins/discover.test.ts

@@ -0,0 +1,87 @@
+import { afterAll, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { discoverPlugins } from './discover';
+
+// Discovery against a real tree, because every assertion here is about the FILESYSTEM being the
+// declaration. Mocking `existsSync` would test the mock.
+
+const root = mkdtempSync(join(tmpdir(), 'officer-plugins-'));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+const MANIFEST = (over = '') => `export const manifest = {
+  publisher: 'officerdev', version: '1.0.0', platform: '>=1.0.0',
+  label: 'X', summary: 'x', icon: 'Network', color: '#fff',
+  permissions: [], ${over}
+};`;
+
+function plant(appName: string, files: Record<string, string>) {
+  const dir = join(root, appName);
+  for (const [rel, body] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, body);
+  }
+  return dir;
+}
+
+plant('full', {
+  'manifest.ts': MANIFEST(),
+  'api/router.ts': 'export const router = {};',
+  'db/schema.ts': 'export const t = {};',
+  'sidecar/index.ts': 'export {};',
+  'web/Router.tsx': 'export default () => null;',
+  'web/panels.ts': 'export const appRegistryMetas = [];',
+});
+plant('bare', { 'manifest.ts': MANIFEST() });
+plant('nodeish', { 'manifest.ts': MANIFEST(), 'sidecar/index.mjs': 'export {};' });
+plant('broken', { 'manifest.ts': 'export const manifest = { publisher: 1 };' });
+plant('nomanifest', { 'api/router.ts': 'export const router = {};' });
+plant('_scratch', { 'manifest.ts': MANIFEST() });
+
+describe('discoverPlugins', () => {
+  it('reads what the tree declares, and nothing more', async () => {
+    const { plugins } = await discoverPlugins(root);
+    const full = plugins.find((p) => p.appName === 'full')!;
+    expect(full.api).toContain('api/router.ts');
+    expect(full.schema).toContain('db/schema.ts');
+    expect(full.sidecar).toEqual({ script: join(root, 'full/sidecar/index.ts'), runtime: 'bun' });
+    expect(full.web?.panels).toContain('web/panels.ts');
+  });
+
+  it('a manifest alone is a valid plugin — every other part is optional', async () => {
+    const { plugins } = await discoverPlugins(root);
+    const bare = plugins.find((p) => p.appName === 'bare')!;
+    expect([bare.api, bare.schema, bare.sidecar, bare.web]).toEqual([null, null, null, null]);
+  });
+
+  // The runtime is the extension, not a field, so it cannot contradict the file it describes.
+  it('reads the runtime off the extension', async () => {
+    const { plugins } = await discoverPlugins(root);
+    expect(plugins.find((p) => p.appName === 'nodeish')!.sidecar?.runtime).toBe('node');
+  });
+
+  it('takes the app name from the directory, so it cannot disagree with where the code sits', async () => {
+    const { plugins } = await discoverPlugins(root);
+    expect(plugins.map((p) => p.appName)).toContain('full');
+  });
+
+  // The property that matters most: one bad plugin must not take the platform down, or hide the good
+  // ones beside it. "Broken, and here is why" is renderable; a failed boot is only greppable.
+  it('collects broken plugins instead of throwing', async () => {
+    const { plugins, broken } = await discoverPlugins(root);
+    expect(broken.map((b) => b.appName).sort()).toEqual(['broken', 'nomanifest']);
+    expect(broken.find((b) => b.appName === 'nomanifest')!.error).toContain('no manifest.ts');
+    expect(plugins.length).toBeGreaterThan(0);
+  });
+
+  it('skips underscore and dot directories, which are scratch space', async () => {
+    const { plugins, broken } = await discoverPlugins(root);
+    expect([...plugins, ...broken].map((p) => p.appName)).not.toContain('_scratch');
+  });
+
+  it('is empty, not an error, when there is no plugins directory at all', async () => {
+    expect(await discoverPlugins(join(root, 'does-not-exist'))).toEqual({ plugins: [], broken: [] });
+  });
+});

src/servers/plugins/discover.ts

@@ -0,0 +1,125 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { PLATFORM_DIR } from '../data-path';
+import { manifestProblems, type DiscoveredPlugin, type PluginManifest } from './manifest';
+
+// Finding plugins on disk.
+//
+// They live at `<platform>/plugins/<app-name>/` — INSIDE the repository, not beside it, and that is what
+// makes the whole developer story work. Bun links the workspace packages into the root `node_modules`, so
+// anything under the repo can `import { useClient } from 'hooks/useClient'` with no publishing, no package
+// registry and no version negotiation. A plugin author clones the platform, drops their plugin in, and
+// runs it in dev — the WordPress model — and the same tree is what the server builds from.
+//
+// Verified: `Bun.resolveSync('hooks/useClient', '<platform>/plugins/anything')` resolves.
+//
+// Discovery is by CONVENTION. Presence is the declaration:
+//
+//   manifest.ts        required — everything a directory listing cannot say
+//   api/router.ts      a backend router
+//   db/schema.ts       tables
+//   sidecar/index.ts   a process (`.mjs` instead means node — see below)
+//   web/Router.tsx     a frontend
+//   web/panels.ts      panel apps
+//
+// Nothing here reads the database. This answers "what is on disk", which is a different question from
+// "what is installed" — the install table answers that, and the two disagreeing is a state the app store
+// has to render rather than a bug to prevent.
+
+/** Where plugins live. Inside the repo, so the workspace packages resolve. */
+export const PLUGINS_DIR = join(PLATFORM_DIR, 'plugins');
+
+/**
+ * The runtime is the file extension, not a manifest field.
+ *
+ * `sidecar/index.mjs` runs under node, `sidecar/index.ts` under bun. Implicit, but it is the rule this
+ * repository already follows — `officer-pty` is `pty/index.mjs` under node because node-pty is a native
+ * module built against Node's ABI, and everything else is bun. Better than a field that can contradict
+ * the file it describes.
+ */
+function findSidecar(dir: string): DiscoveredPlugin['sidecar'] {
+  const ts = join(dir, 'sidecar', 'index.ts');
+  if (existsSync(ts)) return { script: ts, runtime: 'bun' };
+  const mjs = join(dir, 'sidecar', 'index.mjs');
+  if (existsSync(mjs)) return { script: mjs, runtime: 'node' };
+  return null;
+}
+
+function findWeb(dir: string): DiscoveredPlugin['web'] {
+  const router = join(dir, 'web', 'Router.tsx');
+  if (!existsSync(router)) return null;
+  const panels = join(dir, 'web', 'panels.ts');
+  return { router, panels: existsSync(panels) ? panels : null };
+}
+
+const fileOrNull = (path: string): string | null => (existsSync(path) ? path : null);
+
+/**
+ * Read one plugin directory.
+ *
+ * Throws with every problem at once rather than the first, because a manifest fixed one field per attempt
+ * is a manifest nobody finishes.
+ */
+export async function loadPlugin(dir: string, appName: string): Promise<DiscoveredPlugin> {
+  const manifestPath = join(dir, 'manifest.ts');
+  if (!existsSync(manifestPath)) throw new Error(`${appName}: no manifest.ts`);
+
+  let manifest: PluginManifest | null = null;
+  try {
+    const module = (await import(manifestPath)) as { manifest?: PluginManifest };
+    manifest = module.manifest ?? null;
+  } catch (err) {
+    throw new Error(`${appName}: manifest.ts failed to load — ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const problems = manifestProblems(appName, manifest);
+  if (problems.length) throw new Error(`${appName}: ${problems.join('; ')}`);
+
+  return {
+    appName,
+    dir,
+    manifest: manifest as PluginManifest,
+    api: fileOrNull(join(dir, 'api', 'router.ts')),
+    schema: fileOrNull(join(dir, 'db', 'schema.ts')),
+    sidecar: findSidecar(dir),
+    web: findWeb(dir),
+  };
+}
+
+export type DiscoveryResult = {
+  plugins: DiscoveredPlugin[];
+  /** Directories that look like plugins but could not be read. Reported, never thrown — see below. */
+  broken: { appName: string; error: string }[];
+};
+
+/**
+ * Every plugin directory under `PLUGINS_DIR`.
+ *
+ * A broken plugin is COLLECTED, not thrown. One unreadable manifest must not stop the platform from
+ * booting or hide the nine plugins beside it that are fine — and "this one is broken, here is why" is
+ * something the app store can render, where a failed boot is something only a log can.
+ */
+export async function discoverPlugins(root: string = PLUGINS_DIR): Promise<DiscoveryResult> {
+  if (!existsSync(root)) return { plugins: [], broken: [] };
+
+  const plugins: DiscoveredPlugin[] = [];
+  const broken: { appName: string; error: string }[] = [];
+
+  for (const entry of readdirSync(root)) {
+    // `_`-prefixed directories are scratch space, and dotfiles are not plugins.
+    if (entry.startsWith('.') || entry.startsWith('_')) continue;
+    const dir = join(root, entry);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    try {
+      plugins.push(await loadPlugin(dir, entry));
+    } catch (err) {
+      broken.push({ appName: entry, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  return { plugins: plugins.sort((a, b) => a.appName.localeCompare(b.appName)), broken };
+}

src/servers/plugins/manifest.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'bun:test';
+import { manifestProblems, mountPrefix, type PluginManifest } from './manifest';
+
+const valid = (over: Partial<PluginManifest> = {}): PluginManifest => ({
+  publisher: 'officerdev',
+  version: '1.0.0',
+  platform: '>=1.0.0 <2.0.0',
+  label: 'Offscale',
+  summary: 'Your tailnet',
+  icon: 'Network',
+  color: '#818cf8',
+  permissions: [{ key: 'offscale', label: 'Offscale', description: 'The tailnet', ownerOnly: true }],
+  ...over,
+});
+
+describe('mountPrefix', () => {
+  it('puts first-party plugins at the root', () => {
+    expect(mountPrefix({ appName: 'offscale', manifest: { publisher: 'officerdev' } })).toBe('/offscale');
+  });
+
+  it('puts everyone else under /p/<publisher>/', () => {
+    expect(mountPrefix({ appName: 'notes', manifest: { publisher: 'alice' } })).toBe('/p/alice/notes');
+  });
+
+  // The property the segment exists for: a third party cannot reach a core route's namespace, whatever
+  // they call their plugin. Without it, publishing `notes` at /api/notes would mean the platform could
+  // never add /api/notes itself.
+  it('cannot shadow a core route, whatever the plugin is called', () => {
+    for (const core of ['chat', 'users', 'terminal', 'auth', 'files']) {
+      expect(mountPrefix({ appName: core, manifest: { publisher: 'alice' } })).toBe(`/p/alice/${core}`);
+    }
+  });
+});
+
+describe('manifestProblems', () => {
+  it('accepts a good manifest', () => {
+    expect(manifestProblems('offscale', valid())).toEqual([]);
+  });
+
+  it('rejects a missing manifest with a reason rather than a crash', () => {
+    expect(manifestProblems('offscale', null)).toHaveLength(1);
+  });
+
+  it('reports every problem at once, not the first', () => {
+    // An install fixed one field per attempt is an install nobody finishes.
+    const problems = manifestProblems('offscale', { publisher: 'officerdev' } as Partial<PluginManifest>);
+    expect(problems.length).toBeGreaterThan(3);
+  });
+
+  // The app name is a URL segment, a SQL identifier prefix and a directory name simultaneously. Anything
+  // that is not safe in all three has to be refused at the door.
+  it.each([
+    ['Offscale', 'uppercase'],
+    ['1offscale', 'leading digit'],
+    ['off scale', 'space'],
+    ['off_scale', 'underscore'],
+    ['off/scale', 'slash'],
+    ['../escape', 'traversal'],
+    ['', 'empty'],
+  ])('refuses the directory name %p (%s)', (appName) => {
+    expect(manifestProblems(appName, valid()).length).toBeGreaterThan(0);
+  });
+
+  it('refuses a publisher that is not a safe path segment', () => {
+    expect(manifestProblems('notes', valid({ publisher: '../evil' })).length).toBeGreaterThan(0);
+  });
+
+  it('requires permissions to be an array, so [] is how a plugin says it gates nothing', () => {
+    expect(manifestProblems('notes', valid({ permissions: [] }))).toEqual([]);
+    expect(manifestProblems('notes', valid({ permissions: undefined })).length).toBeGreaterThan(0);
+  });
+
+  it('names the permission that is malformed, by index', () => {
+    const problems = manifestProblems('notes', valid({ permissions: [{ label: 'x' }] as never }));
+    expect(problems.some((p) => p.includes('permissions[0].key'))).toBe(true);
+  });
+});

src/servers/plugins/manifest.ts

@@ -0,0 +1,151 @@
+// What a plugin declares about itself, and what the tree declares for it.
+//
+// ── The manifest holds only what a directory listing cannot say ──
+//
+// Everything structural is convention, and presence is the declaration: `sidecar/index.ts` means there is
+// a sidecar, `api/router.ts` means there are routes, `db/schema.ts` means there are tables, `web/` means
+// there is a frontend. The manifest carries the residue — an identity fact, or something a human chose.
+//
+// That is why there is no `sidecar`, `schema` or `frontend` field here, and no dock or title field either:
+// the tile is `{ label, icon, color, to: mountPrefix() }` and the title is `label`, all of which are
+// already below. Writing them twice could only ever drift.
+//
+// See docs/offscale-plugin.md for the reasoning behind each decision recorded here.
+
+/**
+ * A permission the plugin adds to the platform's permission system.
+ *
+ * Called `permissions` and NOT `capabilities`: that word already means three different things in this
+ * codebase — the permission registry, the file-based item store under `$OFFICER_ROOT/capabilities`, and
+ * the routing keys a sidecar registers with. A fourth would be one too many.
+ */
+export type PluginPermission = {
+  /** Stable identifier, stored as the grant's subject. Renaming one is a data change. */
+  key: string;
+  label: string;
+  description: string;
+  /**
+   * Owner-only, or grantable to members. The whole distinction a plugin needs.
+   *
+   * The platform's own `CapabilityKind` has five values because the PLATFORM has five sorts of surface.
+   * A plugin has two states, so this is a boolean — which also removes the escalation question rather
+   * than answering it: a plugin cannot claim `core` if `core` is not a word it can say.
+   */
+  ownerOnly?: boolean;
+  /**
+   * Requests that look like writes and are not — `POST /ssh-test` probes, `POST /policy/assist` proposes
+   * a document and never saves one. Without declaring them, a read-level account meets what reads as a
+   * broken feature where a withheld permission should be.
+   */
+  readOnlyWrites?: string[];
+};
+
+export type PluginManifest = {
+  /**
+   * Who published it. The ONLY input to `mountPrefix`, so first-party and third-party can never become two
+   * code paths. Constant today; the seam third parties hang off later.
+   */
+  publisher: string;
+  /** The plugin's own semver. Updates compare against this. */
+  version: string;
+  /** Which platform versions this build is good for. Refused at install when it does not match. */
+  platform: string;
+
+  label: string;
+  summary: string;
+  /** A lucide icon name, resolved at render. */
+  icon: string;
+  /** Tile colour. */
+  color: string;
+
+  permissions: PluginPermission[];
+};
+
+/** What the platform knows about a plugin on disk: its manifest, plus everything the tree said. */
+export type DiscoveredPlugin = {
+  /**
+   * THE id — route segment, table prefix, sidecar suffix, install key.
+   *
+   * Taken from the DIRECTORY NAME rather than declared, so the id cannot disagree with where the code
+   * sits. The cost is that renaming a directory re-identifies the plugin; the benefit is that the two can
+   * never drift, and a wrong table prefix is a much quieter failure than a missing directory.
+   */
+  appName: string;
+  /** Absolute path to the plugin's directory. */
+  dir: string;
+  manifest: PluginManifest;
+
+  /** `api/router.ts` — a backend router, mounted at `mountPrefix`. */
+  api: string | null;
+  /** `db/schema.ts` — tables, pushed on install. Every name must be prefixed `<appName>_`. */
+  schema: string | null;
+  /** `sidecar/index.{ts,mjs}` — a process for PM2. */
+  sidecar: { script: string; runtime: 'bun' | 'node' } | null;
+  /** `web/Router.tsx` — a frontend, mounted at `<mountPrefix>/*` by the generated Plugins.tsx. */
+  web: { router: string; panels: string | null } | null;
+};
+
+/**
+ * Where a plugin's routes live, on both the API and the frontend.
+ *
+ * `publisher` is the only input, deliberately. First-party plugins sit at the root because Officer Dev
+ * owns that namespace anyway and provenance is then legible at a glance in a log; third-party plugins sit
+ * under `/p/<publisher>/`, which is what makes it impossible for any plugin to shadow a core route — and
+ * therefore what lets the platform keep adding core routes forever without breaking an install.
+ *
+ * NOTHING else in the codebase may branch on provenance. If that difference leaks past this one function
+ * — a special case in the router, a bypassed check, a different install branch — first-party and
+ * third-party become two systems, and only one of them gets tested.
+ */
+export const FIRST_PARTY_PUBLISHER = 'officerdev';
+
+export function mountPrefix(plugin: { appName: string; manifest: { publisher: string } }): string {
+  const { appName } = plugin;
+  return plugin.manifest.publisher === FIRST_PARTY_PUBLISHER
+    ? `/${appName}`
+    : `/p/${plugin.manifest.publisher}/${appName}`;
+}
+
+/** An app name has to be a URL segment, a SQL identifier prefix and a directory name at once. */
+const APP_NAME_RE = /^[a-z][a-z0-9-]{0,38}$/;
+
+/** A publisher shares the app name's constraints — it is a path segment too. */
+const PUBLISHER_RE = /^[a-z][a-z0-9-]{0,38}$/;
+
+/**
+ * Validate a manifest read off disk. Returns the reasons it is unusable, empty when it is fine.
+ *
+ * Returns every problem rather than the first, because an install that fails one field at a time is an
+ * install someone retries four times.
+ */
+export function manifestProblems(appName: string, manifest: Partial<PluginManifest> | null): string[] {
+  const problems: string[] = [];
+  if (!manifest) return ['no manifest, or it did not export `manifest`'];
+
+  if (!APP_NAME_RE.test(appName)) {
+    problems.push(`directory name "${appName}" must be lowercase letters, digits and dashes, starting with a letter`);
+  }
+  if (typeof manifest.publisher !== 'string' || !PUBLISHER_RE.test(manifest.publisher)) {
+    problems.push('publisher must be lowercase letters, digits and dashes');
+  }
+  for (const field of ['version', 'platform', 'label', 'summary', 'icon', 'color'] as const) {
+    if (typeof manifest[field] !== 'string' || !manifest[field]) problems.push(`${field} is required`);
+  }
+  if (!Array.isArray(manifest.permissions)) {
+    problems.push('permissions must be an array (use [] when the plugin gates nothing)');
+  } else {
+    for (const [i, permission] of manifest.permissions.entries()) {
+      if (!permission || typeof permission.key !== 'string' || !permission.key) {
+        problems.push(`permissions[${i}].key is required`);
+        continue;
+      }
+      // The permission key shares the capability registry's namespace, so a plugin colliding with a core
+      // capability would silently widen or narrow it. Prefixing is not enforced here — the installer
+      // checks against the live registry, which is the only thing that knows what is taken.
+      if (typeof permission.label !== 'string' || !permission.label) {
+        problems.push(`permissions[${i}].label is required`);
+      }
+    }
+  }
+  return problems;
+}