@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/modules/{groups/groups.routes.ts → plugins/plugins.routes.ts}

@@ -11,35 +11,35 @@ import type { IAccessControl } from '../access/access-control.interface.js';
 import { spliceGrant } from '../access/access-splice.js';
 import { WorkflowDomainError } from '../workflow/workflow.errors.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { groupsWorkspaceId } from './groups.service.js';
-import { GroupProvisionError, type GroupProvisionService } from './group-provision.service.js';
+import { pluginsWorkspaceId } from './plugins.service.js';
+import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
 import type {
-  GroupCatalogEntry,
-  GroupSummary,
-  IGroupIndexService,
-} from './groups.contract.js';
+  PluginCatalogEntry,
+  PluginSummary,
+  IPluginIndexService,
+} from './plugins.contract.js';
 
 /**
- * Browser-facing (JWT) group routes, mounted behind `authMiddleware`:
+ * Browser-facing (JWT) plugin routes, mounted behind `authMiddleware`:
  *
- *   GET    /api/groups                            → { groups: GroupSummary[] }
- *   DELETE /api/groups/:name                      → { ok }          (owners)
- *   POST   /api/groups/:name/join-request         → { ok, number }  (opens a CR)
- *   GET    /api/groups/:name/join-requests        → { requests }    (managers)
- *   POST   /api/groups/:name/join-requests/:n/reconcile → { closed }
+ *   GET    /api/plugins                            → { plugins: PluginSummary[] }
+ *   DELETE /api/plugins/:name                      → { ok }          (owners)
+ *   POST   /api/plugins/:name/join-request         → { ok, number }  (opens a CR)
+ *   GET    /api/plugins/:name/join-requests        → { requests }    (managers)
+ *   POST   /api/plugins/:name/join-requests/:n/reconcile → { closed }
  *
- * Enumeration is three verdicts per (caller, group), all of them ordinary
+ * Enumeration is three verdicts per (caller, plugin), all of them ordinary
  * access resolution — no special cases, no side tables:
  *
- *   member       canRead on the group FOLDER
+ *   member       canRead on the plugin FOLDER
  *   manager      canWrite on the folder's access.md (admin-rescued)
  *   discoverable canRead on the access.md FILE — in the body-governed format
  *                its own `read: everyone` frontmatter grants this
  *
- * All three false ⇒ the group is absent from the response entirely.
+ * All three false ⇒ the plugin is absent from the response entirely.
  *
- * A join request is a plain change request whose branch edits the group's
+ * A join request is a plain change request whose branch edits the plugin's
  * `access.md`. Managers do NOT merge it: they read its individual proposals
  * (see `join-proposals.ts`), grant the ones they accept through the ordinary
  * access path, and the request retires itself once its rules are a subset of
@@ -52,13 +52,13 @@ import type {
  * middleware change can never silently un-gate one. Nothing here is reachable
  * with an agent connection key or a manual-auth bearer.
  */
-export function createGroupsRoutes(
-  groupIndex: IGroupIndexService,
+export function createPluginsRoutes(
+  pluginIndex: IPluginIndexService,
   accessControl: IAccessControl,
   workflow: IWorkflowService,
   workspaceService: WorkspaceService,
   joinRequests: JoinRequestsService,
-  provision: GroupProvisionService,
+  provision: PluginProvisionService,
   kbDirName: string,
   resolveUser: (req: express.Request) => Promise<AuthUser | null>,
 ): express.Router {
@@ -69,27 +69,27 @@ export function createGroupsRoutes(
   /** The FILE probe for discovery/management — the folder's access.md. */
   const accessMdOf = (folder: string) => `${folder}/access.md`;
 
-  const probesFor = (groups: GroupCatalogEntry[]): string[] => [
-    ...new Set(groups.flatMap((g) => g.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]))),
+  const probesFor = (plugins: PluginCatalogEntry[]): string[] => [
+    ...new Set(plugins.flatMap((g) => g.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]))),
   ];
 
-  /** The caller's open join CR for `group`, or null. */
-  const openJoinCr = (mine: ChangeRequest[], email: string, group: string): ChangeRequest | null =>
-    mine.find((cr) => cr.state === 'open' && cr.branch === joinBranchFor(email, group)) ?? null;
+  /** The caller's open join CR for `plugin`, or null. */
+  const openJoinCr = (mine: ChangeRequest[], email: string, plugin: string): ChangeRequest | null =>
+    mine.find((cr) => cr.state === 'open' && cr.branch === joinBranchFor(email, plugin)) ?? null;
 
-  router.get('/groups', async (req, res) => {
+  router.get('/plugins', async (req, res) => {
     const email = req.userEmail;
     if (!email) {
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
     try {
-      const catalog = await groupIndex.catalog();
+      const catalog = await pluginIndex.catalog();
       if (catalog.length === 0) {
-        res.json({ groups: [] });
+        res.json({ plugins: [] });
         return;
       }
-      const wsId = groupsWorkspaceId();
+      const wsId = pluginsWorkspaceId();
       const probes = probesFor(catalog);
       const [readable, writable, owned] = await Promise.all([
         accessControl.canReadBatch(wsId, email, probes),
@@ -97,22 +97,22 @@ export function createGroupsRoutes(
         accessControl.canOwnerBatch(wsId, email, probes),
       ]);
       // Fail closed on every verdict: a path missing from the map is denied.
-      const any = (map: Map<string, boolean>, g: GroupCatalogEntry, probe: (f: string) => string) =>
+      const any = (map: Map<string, boolean>, g: PluginCatalogEntry, probe: (f: string) => string) =>
         g.folders.some((f) => map.get(probe(f)) === true);
 
       // The caller's own open join CRs — drives `hasRequested`. A CR-listing
-      // hiccup must not take group enumeration down: degrade to "nothing
+      // hiccup must not take plugin enumeration down: degrade to "nothing
       // requested" and let the next load repair it.
       let mine: ChangeRequest[] = [];
       try {
         mine = await workflow.listChangeRequestsAuthoredBy(email);
       } catch (err) {
         console.warn(
-          `[groups] join-request lookup failed: ${err instanceof Error ? err.message : String(err)}`,
+          `[plugins] join-request lookup failed: ${err instanceof Error ? err.message : String(err)}`,
         );
       }
 
-      const groups: GroupSummary[] = [];
+      const plugins: PluginSummary[] = [];
       for (const g of catalog) {
         const member = any(readable, g, memberProbe);
         const manager = any(writable, g, accessMdOf);
@@ -123,7 +123,7 @@ export function createGroupsRoutes(
         const discoverable = member || any(readable, g, accessMdOf);
         if (!member && !manager && !discoverable) continue; // absent — fail closed
         const joinCr = member ? null : openJoinCr(mine, email, g.name);
-        groups.push({
+        plugins.push({
           name: g.name,
           folders: g.folders,
           canRead: member,
@@ -138,10 +138,10 @@ export function createGroupsRoutes(
           requestNumber: joinCr?.number ?? null,
         });
       }
-      res.json({ groups });
+      res.json({ plugins });
     } catch (err) {
-      console.error('[groups] failed to list groups:', err);
-      res.status(500).json({ error: 'Failed to list groups' });
+      console.error('[plugins] failed to list plugins:', err);
+      res.status(500).json({ error: 'Failed to list plugins' });
     }
   });
 
@@ -155,13 +155,13 @@ export function createGroupsRoutes(
    * approver who can write the touched access.md.
    */
   /**
-   * Create a group — the ONE door through which `Groups/<name>/` folders come
+   * Create a plugin — the ONE door through which `Plugins/<name>/` folders come
    * to exist. Any authenticated user may create one; that is the product
-   * model (making a group makes you the one who runs it), and the seeded
+   * model (making a plugin makes you the one who runs it), and the seeded
    * access.md immediately fences the new folder off from everyone else. See
-   * `GroupProvisionService` for why this is an endpoint and not a write path.
+   * `PluginProvisionService` for why this is an endpoint and not a write path.
    */
-  router.post('/groups', async (req, res) => {
+  router.post('/plugins', async (req, res) => {
     const user = await resolveUser(req);
     if (!user) {
       res.status(401).json({ error: 'Unauthenticated' });
@@ -175,50 +175,50 @@ export function createGroupsRoutes(
       return;
     }
     try {
-      const result = await provision.createGroup(user, name);
+      const result = await provision.createPlugin(user, name);
       res.status(201).json(result);
     } catch (err) {
-      if (err instanceof GroupProvisionError) {
+      if (err instanceof PluginProvisionError) {
         res.status(err.status).json({ error: err.message });
         return;
       }
-      console.error('[groups] create failed:', err);
-      res.status(500).json({ error: 'Failed to create the group' });
+      console.error('[plugins] create failed:', err);
+      res.status(500).json({ error: 'Failed to create the plugin' });
     }
   });
 
   /**
-   * Ensure the caller's personal folder (`Groups/personal-<id>/`) exists —
+   * Ensure the caller's personal folder (`Plugins/personal-<id>/`) exists —
    * idempotent; the UI calls it lazily right before the first personal-skill
    * write. Private by construction: its access.md names only the caller.
    */
-  router.post('/groups/personal', async (req, res) => {
+  router.post('/plugins/personal', async (req, res) => {
     const user = await resolveUser(req);
     if (!user) {
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
     try {
-      res.json(await provision.ensurePersonalGroup(user));
+      res.json(await provision.ensurePersonalPlugin(user));
     } catch (err) {
-      console.error('[groups] personal-folder ensure failed:', err);
+      console.error('[plugins] personal-folder ensure failed:', err);
       res.status(500).json({ error: 'Failed to prepare your personal folder' });
     }
   });
 
   /**
-   * Delete a group — the OWNER's verb, and only theirs. Creating a group
+   * Delete a plugin — the OWNER's verb, and only theirs. Creating a plugin
    * makes you the one who runs it; deleting it is the other end of that same
    * promise, so the gate is the `owner` verdict on the folder (owner-lists
    * only, no admin rescue) — a manager who merely writes the access.md, and
    * an admin rescued into managing it, do not get it.
    *
-   * Fail-closed like every other group surface: an unknown group and a group
+   * Fail-closed like every other plugin surface: an unknown plugin and a plugin
    * the caller does not own answer IDENTICALLY, so probing the endpoint can
    * confirm nothing about what exists. The mechanism (park, one commit,
-   * rollback on refusal) lives in `GroupProvisionService.deleteGroup`.
+   * rollback on refusal) lives in `PluginProvisionService.deletePlugin`.
    */
-  router.delete('/groups/:name', async (req, res) => {
+  router.delete('/plugins/:name', async (req, res) => {
     const email = req.userEmail;
     if (!email) {
       res.status(401).json({ error: 'Unauthenticated' });
@@ -230,32 +230,32 @@ export function createGroupsRoutes(
         res.status(401).json({ error: 'Unauthenticated' });
         return;
       }
-      // Case-sensitive, like `groupOfPath` — the group name IS the folder name.
-      const group = (await groupIndex.catalog()).find((g) => g.name === req.params.name);
-      const wsId = groupsWorkspaceId();
-      const ownerVerdicts = group
+      // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+      const plugin = (await pluginIndex.catalog()).find((g) => g.name === req.params.name);
+      const wsId = pluginsWorkspaceId();
+      const ownerVerdicts = plugin
         ? await Promise.all(
-            group.folders.map((f) => accessControl.canOwner(wsId, email, memberProbe(f))),
+            plugin.folders.map((f) => accessControl.canOwner(wsId, email, memberProbe(f))),
           )
         : [];
-      if (!group || !ownerVerdicts.some((v) => v === true)) {
-        res.status(404).json({ error: 'Unknown group', kind: 'unknown-group' });
+      if (!plugin || !ownerVerdicts.some((v) => v === true)) {
+        res.status(404).json({ error: 'Unknown plugin', kind: 'unknown-plugin' });
         return;
       }
-      await provision.deleteGroup(user, group.name);
-      groupIndex.invalidate();
+      await provision.deletePlugin(user, plugin.name);
+      pluginIndex.invalidate();
       res.json({ ok: true });
     } catch (err) {
-      if (err instanceof GroupProvisionError) {
+      if (err instanceof PluginProvisionError) {
         res.status(err.status).json({ error: err.message });
         return;
       }
-      console.error('[groups] delete failed:', err);
-      res.status(500).json({ error: 'Failed to delete the group' });
+      console.error('[plugins] delete failed:', err);
+      res.status(500).json({ error: 'Failed to delete the plugin' });
     }
   });
 
-  router.post('/groups/:name/join-request', async (req, res) => {
+  router.post('/plugins/:name/join-request', async (req, res) => {
     const email = req.userEmail;
     if (!email) {
       res.status(401).json({ error: 'Unauthenticated' });
@@ -267,39 +267,39 @@ export function createGroupsRoutes(
         res.status(401).json({ error: 'Unauthenticated' });
         return;
       }
-      const catalog = await groupIndex.catalog();
-      // Case-sensitive, like `groupOfPath` — the group name IS the folder name.
-      const group = catalog.find((g) => g.name === req.params.name);
-      const wsId = groupsWorkspaceId();
-      // Same ANY-folder shape `GET /groups` resolves with, so a group can
+      const catalog = await pluginIndex.catalog();
+      // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+      const plugin = catalog.find((g) => g.name === req.params.name);
+      const wsId = pluginsWorkspaceId();
+      // Same ANY-folder shape `GET /plugins` resolves with, so a plugin can
       // never be listed as discoverable there and rejected as unknown here.
-      const verdicts = group
+      const verdicts = plugin
         ? await accessControl.canReadBatch(
             wsId,
             email,
-            group.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]),
+            plugin.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]),
           )
         : new Map<string, boolean>();
       const any = (probe: (f: string) => string) =>
-        group?.folders.some((f) => verdicts.get(probe(f)) === true) ?? false;
-      // Discovery gate, fail-closed: an unknown group and a group the caller
+        plugin?.folders.some((f) => verdicts.get(probe(f)) === true) ?? false;
+      // Discovery gate, fail-closed: an unknown plugin and a plugin the caller
       // cannot discover answer IDENTICALLY, so probing can't confirm existence.
-      if (!group || !any(accessMdOf)) {
-        res.status(404).json({ error: 'Unknown group', kind: 'unknown-group' });
+      if (!plugin || !any(accessMdOf)) {
+        res.status(404).json({ error: 'Unknown plugin', kind: 'unknown-plugin' });
         return;
       }
       if (any(memberProbe)) {
         // Access landed between page load and click — reload, don't ask.
-        res.status(409).json({ error: 'You can already read this group', kind: 'already-readable' });
+        res.status(409).json({ error: 'You can already read this plugin', kind: 'already-readable' });
         return;
       }
-      // The grant is written to the group's primary folder — the one the
+      // The grant is written to the plugin's primary folder — the one the
       // summary's `folders[0]` names and the banner's touched-path check
       // expects.
-      const folder = group.folders[0];
+      const folder = plugin.folders[0];
 
-      const branch = joinBranchFor(email, group.name);
-      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, group.name);
+      const branch = joinBranchFor(email, plugin.name);
+      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, plugin.name);
       if (existing) {
         res.json({ ok: true, number: existing.number });
         return;
@@ -308,7 +308,7 @@ export function createGroupsRoutes(
       // A leftover branch from a rejected/withdrawn request is reused — the
       // grant commit is already on it and the splice below no-ops.
       try {
-        await workflow.createBranch(groupsWorkspaceId(), branch, DEFAULT_BRANCH);
+        await workflow.createBranch(pluginsWorkspaceId(), branch, DEFAULT_BRANCH);
       } catch {
         // exists (or raced) — proceed against it
       }
@@ -323,14 +323,14 @@ export function createGroupsRoutes(
       );
       if (spliced.changed) {
         await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-        await workflow.commitChanges(ws.id, user, `Request access to ${group.name}`);
+        await workflow.commitChanges(ws.id, user, `Request access to ${plugin.name}`);
       }
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: DEFAULT_BRANCH,
-        title: `Join request: ${group.name}`,
+        title: `Join request: ${plugin.name}`,
         description:
-          `${user.name} asked to join ${group.name}. A manager of the group accepts by ` +
+          `${user.name} asked to join ${plugin.name}. A manager of the plugin accepts by ` +
           `granting the access this branch proposes; the request closes itself once ` +
           `every proposal has landed.`,
       });
@@ -340,41 +340,41 @@ export function createGroupsRoutes(
         res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
         return;
       }
-      console.error('[groups] failed to open a join request:', err);
+      console.error('[plugins] failed to open a join request:', err);
       res.status(500).json({ error: 'Failed to request access' });
     }
   });
 
   /**
    * Resolve the caller as a MANAGER of `name` — the only role that may see or
-   * settle its join requests. Returns the group's primary folder, or null
+   * settle its join requests. Returns the plugin's primary folder, or null
    * after answering the request.
    *
    * A non-manager gets an empty list rather than a 403 (the frontend asks
-   * unconditionally, exactly as it does for every other group surface), and
-   * an unknown group is indistinguishable from an unmanaged one.
+   * unconditionally, exactly as it does for every other plugin surface), and
+   * an unknown plugin is indistinguishable from an unmanaged one.
    */
   async function requireManager(
     req: express.Request,
     res: express.Response,
     onDenied: () => void,
-  ): Promise<{ group: GroupCatalogEntry; folder: string; user: AuthUser } | null> {
+  ): Promise<{ plugin: PluginCatalogEntry; folder: string; user: AuthUser } | null> {
     const email = req.userEmail;
     if (!email) {
       res.status(401).json({ error: 'Unauthenticated' });
       return null;
     }
-    const group = (await groupIndex.catalog()).find((g) => g.name === req.params.name);
-    if (!group) {
+    const plugin = (await pluginIndex.catalog()).find((g) => g.name === req.params.name);
+    if (!plugin) {
       onDenied();
       return null;
     }
     const writable = await accessControl.canWriteBatch(
-      groupsWorkspaceId(),
+      pluginsWorkspaceId(),
       email,
-      group.folders.map(accessMdOf),
+      plugin.folders.map(accessMdOf),
     );
-    if (!group.folders.some((f) => writable.get(accessMdOf(f)) === true)) {
+    if (!plugin.folders.some((f) => writable.get(accessMdOf(f)) === true)) {
       onDenied();
       return null;
     }
@@ -383,19 +383,19 @@ export function createGroupsRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return null;
     }
-    return { group, folder: group.folders[0], user };
+    return { plugin, folder: plugin.folders[0], user };
   }
 
-  router.get('/groups/:name/join-requests', async (req, res) => {
+  router.get('/plugins/:name/join-requests', async (req, res) => {
     try {
       const ctx = await requireManager(req, res, () => res.json({ requests: [] }));
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
       res.json({
-        requests: await joinRequests.list(ctx.group.name, ctx.folder, crs, ctx.user),
+        requests: await joinRequests.list(ctx.plugin.name, ctx.folder, crs, ctx.user),
       });
     } catch (err) {
-      console.error('[groups] failed to list join requests:', err);
+      console.error('[plugins] failed to list join requests:', err);
       res.status(500).json({ error: 'Failed to list join requests' });
     }
   });
@@ -406,7 +406,7 @@ export function createGroupsRoutes(
    * round-trip; the listing does the same thing lazily, so skipping this (a
    * dropped response, a closed tab) only delays it.
    */
-  router.post('/groups/:name/join-requests/:number/reconcile', async (req, res) => {
+  router.post('/plugins/:name/join-requests/:number/reconcile', async (req, res) => {
     try {
       const ctx = await requireManager(req, res, () =>
         res.status(404).json({ error: 'Not found' }),
@@ -422,9 +422,9 @@ export function createGroupsRoutes(
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(ctx.group.name, ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(ctx.plugin.name, ctx.folder, cr, ctx.user) });
     } catch (err) {
-      console.error('[groups] failed to reconcile a join request:', err);
+      console.error('[plugins] failed to reconcile a join request:', err);
       res.status(500).json({ error: 'Failed to update the request' });
     }
   });