step 1/4: the permission engine is called permissions, not capabilities

The word meant four different things in this repo, not the three the offscale
doc records:

  1. the permission registry              → RENAMED here
  2. $OFFICER_ROOT/capabilities/ items    → kept; this is what capabilities are
  3. sidecar routing keys                 → step 3, becoming `handles`
  4. Lightning wallet features            → kept; a domain term, and on the wire
                                            to the mobile apps

The fourth was not in the doc and a global find-and-replace would have broken
the mobile wallet, which reads `{ kind, capabilities: Capability[] }` from the
wallet sidecar. So this renamed against an explicit file allowlist rather than
by sweeping the tree, and `CapabilityPage.tsx` — the UI for the item store, and
correctly named already — was left alone.

Moved: servers/capabilities/ → servers/permissions/, capability-gate.ts →
permission-gate.ts, users/capabilities-routes.ts → permissions-routes.ts,
hooks/useCapabilities.ts → usePermissions.ts. Identifiers follow.

Three breaks the typechecker could not see, all found by exercising it live.

The route paths moved with the prose sweep, so the server served
/user/permissions while the frontend still called /user/capabilities. A 404 on
every page load, and tsgo clean throughout.

The response FIELD moved too. `client.get<SelfPermissions>()` is an unchecked
cast, so `data.capabilities` became `undefined` at runtime with no compile
error — `can()` would have answered "no" to everything and the dock would have
emptied itself.

And the grants list was passed straight out of the database, so it arrived as
`{ role, capability, level }` while the screen read `grant.permission`. Every
role would have rendered as holding nothing. It is now mapped in the route:
the wire says `permission`, the column still says `capability`, and step 2
therefore changes nothing any client can see.

The stale react-query keys were the quiet one: two files still invalidated
['self-capabilities'] after the hook moved to ['self-permissions'], so
installing a plugin would have silently stopped refreshing the dock.

The database is untouched — `role_capabilities` and its `capability` column are
step 2, and the two call sites that cross that boundary say so in a comment.
Round-tripped the 9 live grants through the admin endpoint to prove the PUT
contract survived: 9 before, 9 after, Member's three intact.

Also reverted prettier churn on five landing-page files that a broad --write
picked up. Second time today; the lesson is not sticking.

tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures — two of which
now read "path → permission" rather than "path → capability".
This commit is contained in:
2026-08-15 16:03:22 +00:00
parent b0fcd8b81b
commit 2e8ec845c8
59 changed files with 454 additions and 442 deletions
+1 -1
View File
@@ -18,7 +18,7 @@
*
* Called `permissions`, and that word is used throughout the plugin system deliberately. The other one
* already means three different things here — the permission registry, the file-based item store under
* `$OFFICER_ROOT/capabilities`, and the routing keys a sidecar registers with — and a fourth meaning
* `$OFFICER_ROOT/permissions`, and the routing keys a sidecar registers with — and a fourth meaning
* would be one too many. Nothing in this system uses it.
*/
export type PluginPermission = {
+5 -5
View File
@@ -1,7 +1,7 @@
import { listPluginInstalls, type PluginInstall } from 'officerdb';
import type { MountedPlugin } from '../hono';
import { rebuildHonoApp } from '../hono';
import { setPluginPermissions, type Capability } from '../capabilities/registry';
import { setPluginPermissions, type Permission } from '../permissions/registry';
import { discoverPlugins } from './discover';
import { mountPrefix, type DiscoveredPlugin } from './manifest';
import { generatePluginsModule, rebuildFrontend } from './generate';
@@ -99,7 +99,7 @@ export async function mountablePlugins(snapshot: PluginsSnapshot): Promise<Mount
* claim no path — a plugin wanting genuinely separate surfaces needs sub-path claims in the manifest, and
* that can be added when something needs it rather than guessed at now.
*/
function pluginPermissions(state: PluginState): Capability[] {
function pluginPermissions(state: PluginState): Permission[] {
const { plugin } = state;
const prefix = mountPrefix(plugin);
@@ -170,7 +170,7 @@ export async function refreshPluginMounts(options: { skipFrontend?: boolean } =
* (`dockItemsFromPlugins`).
*
* Presentation comes from the manifest and the route from `mountPrefix`, so there is one source for both
* and nothing to keep in step. `capability` is the plugin's first permission when it has one, which is
* and nothing to keep in step. `permission` is the plugin's first permission when it has one, which is
* what lets the self endpoint filter the tile out for an account that cannot reach the screen —
* a member must not be handed the manifest of a feature they may not use, even to hide it.
*
@@ -180,7 +180,7 @@ export async function refreshPluginMounts(options: { skipFrontend?: boolean } =
export async function pluginDockManifests(): Promise<
Array<{
sidecarId: string;
capability: string | null;
permission: string | null;
name: string;
icon?: string;
image?: string;
@@ -197,7 +197,7 @@ export async function pluginDockManifests(): Promise<
const prefix = mountPrefix(plugin);
return {
sidecarId: plugin.appName,
capability: plugin.manifest.permissions[0]?.key ?? null,
permission: plugin.manifest.permissions[0]?.key ?? null,
name: plugin.manifest.label,
// A shipped `assets/icon.png` wins; the lucide NAME is the fallback for a plugin with no
// artwork of its own. The dock renders `image` as an <img> and `icon` through `resolveIcon`,