@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/plugins/__tests__/plugins.routes.test.ts

@@ -5,6 +5,8 @@ import path from 'node:path';
 import os from 'node:os';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 
 import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
 import type { ChangeRequest, IWorkflowService } from '@bevel-software/platform-shared';
@@ -14,8 +16,11 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ISkillService, SkillSummary } from '../../skills/skills.contract.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import { PluginIndexService } from '../plugins.service.js';
-import { createPluginsRoutes } from '../plugins.routes.js';
+import { createPluginCreationRoutes, createPluginsRoutes } from '../plugins.routes.js';
 import type { JoinRequestsService } from '../join-requests.service.js';
+import { PluginJoinRequestJobs } from '../join-request-jobs.service.js';
+import { pluginFolderBelowRoot } from '../plugins.service.js';
+import { FakeJoinRequestStore } from './fake-join-request-store.js';
 import type { PluginSummary, IPluginIndexService } from '../plugins.contract.js';
 
 /**
@@ -79,14 +84,24 @@ async function makeHarness(opts: HarnessOpts = {}) {
   const kbRoot = path.join(workspaceDir, KB);
   // Both carry the manifest that makes a folder a plugin to discovery, and
   // the access.md that makes it exist to the index.
-  const fixtures: [string, string][] = [
-    ['GTM', 'gtm'],
-    ['Finance', 'finance'],
-    ...Object.entries(opts.extraPlugins ?? {}),
+  // Folder, identity, display name. GTM's three spellings are deliberately
+  // all different: nothing here may read the folder for either name, and a
+  // fixture whose displayName echoed its folder could not tell the two apart.
+  const fixtures: [string, string, string][] = [
+    ['GTM', 'gtm', 'Google Tag Manager'],
+    ['Finance', 'finance', 'Finance'],
+    ...Object.entries(opts.extraPlugins ?? {}).map(
+      ([folder, name]): [string, string, string] => [folder, name, folder],
+    ),
   ];
-  for (const [folder, name] of fixtures) {
+  for (const [folder, name, displayName] of fixtures) {
     await fs.mkdir(path.join(kbRoot, 'Plugins', folder), { recursive: true });
-    await fs.writeFile(path.join(kbRoot, 'Plugins', folder, 'plugin.json'), `{"name":"${name}"}`);
+    // Both names in the file, as every manifest carries them: the identity
+    // and the spelling people see. Nothing reads the folder for either.
+    await fs.writeFile(
+      path.join(kbRoot, 'Plugins', folder, 'plugin.json'),
+      `{"name":"${name}","displayName":"${displayName}"}`,
+    );
     await fs.writeFile(
       path.join(kbRoot, 'Plugins', folder, 'access.md'),
       '---\nread:\n  - everyone\n---\nread: []\n',
@@ -128,6 +143,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
       async (n: number) => (opts.authoredCrs ?? []).find((c) => c.number === n) ?? null,
     ),
     createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
+    listBranches: vi.fn(async () => []),
     commitChanges: vi.fn(async () => null),
     openChangeRequest: vi.fn(async () => ({ number: 42 })),
   } as unknown as IWorkflowService;
@@ -139,7 +155,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
 
   const index =
     opts.index ??
-    new PluginIndexService(workspaceService, accessControl, skillService, toolService, KB);
+    new PluginIndexService(workspaceService, accessControl, skillService, toolService, KB, new KbPluginSource(new NodeFs()));
 
   const email = opts.email === undefined ? ALI : opts.email;
   const app = express();
@@ -156,23 +172,54 @@ async function makeHarness(opts: HarnessOpts = {}) {
     reconcile: vi.fn(async () => false),
   } as unknown as JoinRequestsService;
 
+  // The records half is REAL over an in-memory table, because the route's
+  // whole contract now is "write a row, answer, then do the git" — a stub
+  // would assert the route called something, not that the row and the change
+  // request are one-to-one. The git it eventually does is the workflow stub
+  // above, as it always was.
+  const joinRequestStore = new FakeJoinRequestStore();
+  // The change requests the store can see are the ones the listing is told
+  // about, state and all — so a test that lists a closed request is also
+  // telling the record it names that the request is over.
+  for (const c of opts.authoredCrs ?? []) joinRequestStore.changeRequests.set(c.number, c.state);
+  const joinRequestJobs = new PluginJoinRequestJobs(joinRequestStore, {
+    workflow,
+    workspaceService,
+    kbDirName: KB,
+    target: async (pluginKey) => {
+      const entry = (await index.catalog()).find(
+        (g) => pluginFolderBelowRoot(g.folders[0]) === pluginKey,
+      );
+      return entry ? { folder: entry.folders[0], displayName: entry.displayName } : null;
+    },
+    requester: async (mail) => ({ ...ALI_USER, email: mail }),
+  });
+
   // Provisioning MECHANISM is exercised by its own service tests; the routes
   // here only need to prove what they hand it and when they refuse to.
   const provision = {
     createPlugin: vi.fn(async () => ({ folder: 'GTM', created: true })),
+    ensurePersonalPlugin: vi.fn(async () => ({ folder: 'personal-u-1', created: false })),
     deletePlugin: vi.fn(async () => undefined),
   };
 
+  // The creation doors are their own router in the server (behind the
+  // key-or-session gate); here they share the fake identity middleware.
+  app.use(
+    '/api',
+    createPluginCreationRoutes(provision as never, async (req) =>
+      req.userEmail ? { ...ALI_USER, email: req.userEmail } : null,
+    ),
+  );
   app.use(
     '/api',
     createPluginsRoutes(
       index,
       accessControl,
       workflow,
-      workspaceService,
       joinRequests,
+      joinRequestJobs,
       provision as never,
-      KB,
       async (req) => (req.userEmail ? { ...ALI_USER, email: req.userEmail } : null),
     ),
   );
@@ -188,6 +235,8 @@ async function makeHarness(opts: HarnessOpts = {}) {
     workflow,
     workspaceService,
     joinRequests,
+    joinRequestJobs,
+    joinRequestStore,
     provision,
   };
 }
@@ -227,6 +276,51 @@ describe('/api/plugins routes', () => {
     }
   });
 
+  it('POST /plugins hands the service the name and, when given, the grouping folder to make it in', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    const post = (body: unknown) =>
+      fetch(`${h.baseUrl}/api/plugins`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    expect((await post({ name: 'Sales' })).status).toBe(201);
+    expect(h.provision.createPlugin).toHaveBeenLastCalledWith(expect.objectContaining({ email: ALI }), 'Sales', undefined);
+    expect((await post({ name: 'Sales', parent: 'Teams/EU' })).status).toBe(201);
+    expect(h.provision.createPlugin).toHaveBeenLastCalledWith(expect.anything(), 'Sales', 'Teams/EU');
+    // A parent that is not a string is a bad request, not a service error.
+    expect((await post({ name: 'Sales', parent: 7 })).status).toBe(400);
+    expect(h.provision.createPlugin).toHaveBeenCalledTimes(2);
+  });
+
+  it('POST /plugins/personal ensures the caller’s own space and returns it; no caller, no space', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    const res = await fetch(`${h.baseUrl}/api/plugins/personal`, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ folder: 'personal-u-1', created: false });
+    expect(h.provision.ensurePersonalPlugin).toHaveBeenCalledWith(expect.objectContaining({ email: ALI }));
+
+    const anon = await makeHarness({ email: null });
+    try {
+      expect((await fetch(`${anon.baseUrl}/api/plugins/personal`, { method: 'POST' })).status).toBe(401);
+      expect(anon.provision.ensurePersonalPlugin).not.toHaveBeenCalled();
+    } finally {
+      await close(anon.server);
+    }
+  });
+
+  it("POST /plugins/personal keeps the service's own status — a 503 for incomplete discovery is retryable, not a 500", async () => {
+    const h = await makeHarness();
+    server = h.server;
+    const { PluginProvisionError } = await import('../plugin-provision.service.js');
+    h.provision.ensurePersonalPlugin.mockRejectedValueOnce(new PluginProvisionError('Plugin discovery is incomplete', 503));
+    const res = await fetch(`${h.baseUrl}/api/plugins/personal`, { method: 'POST' });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: 'Plugin discovery is incomplete' });
+  });
+
   it('lists member plugins sorted, counting by pluginOfPath', async () => {
     const h = await makeHarness({
       readable: MEMBER_OF_BOTH,
@@ -239,10 +333,16 @@ describe('/api/plugins routes', () => {
     server = h.server;
     const { status, plugins } = await listPlugins(h.baseUrl);
     expect(status).toBe(200);
-    // Named by identity (the manifest), labelled by folder.
-    expect(plugins.map((g) => [g.name, g.displayName])).toEqual([['finance', 'Finance'], ['gtm', 'GTM']]);
-    expect(plugins[0]).toMatchObject({ canRead: true, skillCount: 0, toolCount: 1 });
-    expect(plugins[1]).toMatchObject({ canRead: true, skillCount: 1, toolCount: 0 });
+    // Named by identity and labelled by display name — both the manifest's.
+    expect(plugins.map((g) => [g.name, g.displayName])).toEqual([
+      ['finance', 'Finance'],
+      ['gtm', 'Google Tag Manager'],
+    ]);
+    // `linkedRoots` is part of the summary's contract — the plugin page reads
+    // it to name where a linked card lives. Neither fixture links anything,
+    // and an empty list is what says so; a dropped mapping would be `undefined`.
+    expect(plugins[0]).toMatchObject({ canRead: true, skillCount: 0, toolCount: 1, linkedRoots: [] });
+    expect(plugins[1]).toMatchObject({ canRead: true, skillCount: 1, toolCount: 0, linkedRoots: [] });
   });
 
   it("carries the index's broken-link count into the summary — the server's, not the caller's slice", async () => {
@@ -250,6 +350,7 @@ describe('/api/plugins routes', () => {
       name: 'gtm',
       displayName: 'GTM',
       folders: ['Plugins/GTM'],
+      linkedRoots: ['Skills/Testing'],
       linksAreManaged: true,
       skillCount: 2,
       toolCount: 0,
@@ -257,6 +358,8 @@ describe('/api/plugins routes', () => {
       owners: { roles: [], users: [] },
       writers: { roles: [], users: [] },
       readers: { restricted: true, roles: [], users: [] },
+      isPrivate: false,
+      warnings: ['mcpProfile "global" named but no registry could be read'],
     };
     const h = await makeHarness({
       readable: MEMBER_OF_BOTH,
@@ -265,7 +368,15 @@ describe('/api/plugins routes', () => {
     server = h.server;
     const { plugins } = await listPlugins(h.baseUrl);
     expect(plugins).toHaveLength(1);
-    expect(plugins[0]).toMatchObject({ name: 'gtm', brokenLinks: 2 });
+    expect(plugins[0]).toMatchObject({
+      name: 'gtm',
+      brokenLinks: 2,
+      // The roots the index scanned reach the page, which needs them to say
+      // where a linked card lives.
+      linkedRoots: ['Skills/Testing'],
+      // What discovery left out reaches the summary as the index said it.
+      warnings: ['mcpProfile "global" named but no registry could be read'],
+    });
   });
 
   it('a DISCOVERABLE plugin (access.md readable, folder not) lists locked with hasRequested from the join CR', async () => {
@@ -392,12 +503,47 @@ describe('/api/plugins routes', () => {
     expect((await res.json()).kind).toBe('already-readable');
   });
 
-  it('join-request: branch + splice + commit + CR, on the deterministic join branch', async () => {
+  it('join-request: records the ask and answers BEFORE any git has run', async () => {
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    // The one thing the endpoint may not do any more is wait for a clone. A
+    // workflow that never settles stands in for one: the answer must arrive
+    // anyway, and say the request is recorded and not yet carried.
+    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockReturnValue(new Promise(() => {}));
+
+    const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, state: 'pending', number: null });
+    expect(h.joinRequestStore.all()).toMatchObject([
+      { requesterEmail: ALI, pluginKey: 'Finance', status: 'pending', changeRequestNumber: null },
+    ]);
+    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('join-request: the recorded request is REPORTED as requested before its CR exists', async () => {
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockReturnValue(new Promise(() => {}));
+    await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
+
+    // A reload one second after the click. No change request exists — the
+    // record is the only thing that can answer, and it does.
+    const { plugins } = await listPlugins(h.baseUrl);
+    expect(plugins[0]).toMatchObject({
+      name: 'finance',
+      hasRequested: true,
+      requestNumber: null,
+      requestFailure: null,
+    });
+  });
+
+  it('join-request: branch + splice + commit + CR, on the deterministic join branch — after the answer', async () => {
     const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
     server = h.server;
     const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
     expect(res.status).toBe(200);
-    expect(await res.json()).toEqual({ ok: true, number: 42 });
+    expect(await res.json()).toEqual({ ok: true, state: 'pending', number: null });
+    await h.joinRequestJobs.drain();
 
     // The branch is cut from the FOLDER name, as every join branch before the
     // manifest became the identity was — so none of them is orphaned.
@@ -421,6 +567,8 @@ describe('/api/plugins routes', () => {
         title: 'Join request: Finance',
       }),
     );
+    // And the record now names the change request that carries it.
+    expect(h.joinRequestStore.all()).toMatchObject([{ status: 'opened', changeRequestNumber: 42 }]);
   });
 
   it('keys a join request by the folder PATH below the root — two folders sharing a basename never share a branch', async () => {
@@ -431,12 +579,13 @@ describe('/api/plugins routes', () => {
     server = h.server;
     const res = await fetch(`${h.baseUrl}/api/plugins/team-gtm/join-request`, { method: 'POST' });
     expect(res.status).toBe(200);
+    await h.joinRequestJobs.drain();
     const branch = joinBranchFor(ALI, 'teams/GTM');
     expect(branch).not.toBe(joinBranchFor(ALI, 'GTM'));
     expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, branch, DEFAULT_BRANCH);
   });
 
-  it('join-request is idempotent: an existing open join CR is returned, nothing new is created', async () => {
+  it('join-request adopts an existing open join CR instead of opening a second one', async () => {
     const h = await makeHarness({
       readable: { [ALI]: ['Plugins/Finance/access.md'] },
       authoredCrs: [cr({ branch: joinBranchFor(ALI, 'Finance'), number: 9 })],
@@ -444,9 +593,211 @@ describe('/api/plugins routes', () => {
     server = h.server;
     const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
     expect(res.status).toBe(200);
-    expect(await res.json()).toEqual({ ok: true, number: 9 });
+    await h.joinRequestJobs.drain();
     expect(h.workflow.createBranch).not.toHaveBeenCalled();
     expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+    // The record ends up pointing at the request that was already there.
+    expect(h.joinRequestStore.all()).toMatchObject([{ status: 'opened', changeRequestNumber: 9 }]);
+  });
+
+  it('join-request: two clicks leave ONE record and open ONE change request', async () => {
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    // Two tabs, at the same moment. Neither has seen the other's answer.
+    const [first, second] = await Promise.all([
+      fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' }),
+      fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' }),
+    ]);
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    // BOTH bodies, not just the statuses: the contract the concurrent path
+    // advertises is that each tab is told the ask is recorded. Pinning only
+    // the status would let this answer regress to a different shape — a
+    // dropped `state`, a stale `number` — with the test still green.
+    //
+    // Either state is correct for a tab here, and which one is a race: the
+    // git work is instant against these stubs, so the second answer can be
+    // written after the first click's job has already opened the request. What
+    // must hold for both is that the ask is recorded and the shape is the
+    // shape — never a refusal, never a second request's number.
+    for (const answer of [await first.json(), await second.json()]) {
+      expect(answer).toEqual(
+        answer.state === 'opened'
+          ? { ok: true, state: 'opened', number: 42 }
+          : { ok: true, state: 'pending', number: null },
+      );
+    }
+    await h.joinRequestJobs.drain();
+
+    expect(h.joinRequestStore.all()).toHaveLength(1);
+    expect(h.workflow.openChangeRequest).toHaveBeenCalledTimes(1);
+  });
+
+  it('join-request: a failure is recorded, and the listing hands the plugin back with the reason', async () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    (h.workflow.openChangeRequest as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('the remote refused the push'),
+    );
+    server = h.server;
+    const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
+    // The answer was still instant and still said the ask was recorded — the
+    // failure is a fact about what happened next.
+    expect(await res.json()).toEqual({ ok: true, state: 'pending', number: null });
+    await h.joinRequestJobs.drain();
+
+    expect(h.joinRequestStore.all()).toMatchObject([
+      { status: 'failed', failureReason: 'the remote refused the push' },
+    ]);
+    const { plugins } = await listPlugins(h.baseUrl);
+    expect(plugins[0]).toMatchObject({
+      name: 'finance',
+      hasRequested: false,
+      requestFailure: 'the remote refused the push',
+    });
+    error.mockRestore();
+  });
+
+  it('join-request: a click after a failure RETRIES the recorded request rather than recording a second', async () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    (h.workflow.openChangeRequest as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('the remote refused the push'),
+    );
+    server = h.server;
+    await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
+    await h.joinRequestJobs.drain();
+    const [failed] = h.joinRequestStore.all();
+
+    await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
+    await h.joinRequestJobs.drain();
+
+    const rows = h.joinRequestStore.all();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe(failed.id);
+    expect(rows[0]).toMatchObject({ status: 'opened', changeRequestNumber: 42, failureReason: null });
+    expect(h.workflow.openChangeRequest).toHaveBeenCalledTimes(2);
+    error.mockRestore();
+  });
+
+  it('a request recorded before a restart is picked up by the sweep', async () => {
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    // The row a dead process left behind: recorded, never carried.
+    h.joinRequestStore.seed({
+      requesterEmail: ALI,
+      requesterName: 'Ali Baba',
+      pluginKey: 'Finance',
+      status: 'pending',
+      failureReason: null,
+      changeRequestNumber: null,
+      claimedAt: null,
+    });
+
+    await h.joinRequestJobs.sweep();
+    await h.joinRequestJobs.drain();
+
+    expect(h.workflow.openChangeRequest).toHaveBeenCalledTimes(1);
+    expect(h.joinRequestStore.all()).toMatchObject([{ status: 'opened', changeRequestNumber: 42 }]);
+  });
+
+  it('degrades to the change requests alone when the recorded requests cannot be read', async () => {
+    const h = await makeHarness({
+      readable: { [ALI]: ['Plugins/Finance/access.md'] },
+      authoredCrs: [cr({ branch: joinBranchFor(ALI, 'Finance'), number: 9 })],
+    });
+    vi.spyOn(h.joinRequestStore, 'forRequester').mockRejectedValueOnce(new Error('db down'));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    server = h.server;
+    const { status, plugins } = await listPlugins(h.baseUrl);
+    expect(status).toBe(200);
+    expect(plugins[0]).toMatchObject({ hasRequested: true, requestNumber: 9 });
+    warn.mockRestore();
+  });
+
+  it('a declined request is over: the listing hands the button back, and the next click asks again on the same record', async () => {
+    // Before the record existed, "requested" came from the open change request
+    // alone, so a decline handed the button back. The record must not change
+    // that: an `opened` row whose request is closed is an answered ask. And
+    // the answer has to come from the request's ROW — the authored listing
+    // is open-only, so it never lists a closed request; a fixture that put
+    // the closed request in the listing would pass a check that reads the
+    // wrong source. The listing here is empty, as it is in production.
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    h.joinRequestStore.changeRequests.set(9, 'closed');
+    const answered = h.joinRequestStore.seed({
+      requesterEmail: ALI,
+      requesterName: 'Ali Baba',
+      pluginKey: 'Finance',
+      status: 'opened',
+      failureReason: null,
+      changeRequestNumber: 9,
+      claimedAt: null,
+    });
+
+    const { plugins } = await listPlugins(h.baseUrl);
+    expect(plugins[0]).toMatchObject({
+      name: 'finance',
+      hasRequested: false,
+      requestNumber: null,
+      requestFailure: null,
+    });
+
+    const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
+    expect(await res.json()).toEqual({ ok: true, state: 'pending', number: null });
+    await h.joinRequestJobs.drain();
+
+    const rows = h.joinRequestStore.all();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe(answered.id);
+    expect(rows[0]).toMatchObject({ status: 'opened', changeRequestNumber: 42 });
+    expect(h.workflow.openChangeRequest).toHaveBeenCalledTimes(1);
+  });
+
+  it('an opened record whose request is still open counts, before the open listing knows it', async () => {
+    // Marked seconds ago, the open listing cached without it: the request's
+    // row says it is open, and that is what decides — not the listing, which
+    // would otherwise flicker the card to a button right after a request
+    // landed.
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    h.joinRequestStore.changeRequests.set(9, 'open');
+    h.joinRequestStore.seed({
+      requesterEmail: ALI,
+      requesterName: 'Ali Baba',
+      pluginKey: 'Finance',
+      status: 'opened',
+      failureReason: null,
+      changeRequestNumber: 9,
+      claimedAt: null,
+    });
+    const { plugins } = await listPlugins(h.baseUrl);
+    expect(plugins[0]).toMatchObject({ name: 'finance', hasRequested: true, requestNumber: 9 });
+  });
+
+  it('keeps an opened record standing when its request\'s state cannot be read', async () => {
+    // The third read the index makes, and the one whose failure must lean
+    // the other way: a request that may well still be open must not be
+    // handed back as a button, so an unreadable state is the benefit of the
+    // doubt — the person sees the card, not an invitation to ask twice.
+    const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
+    server = h.server;
+    h.joinRequestStore.seed({
+      requesterEmail: ALI,
+      requesterName: 'Ali Baba',
+      pluginKey: 'Finance',
+      status: 'opened',
+      failureReason: null,
+      changeRequestNumber: 9,
+      claimedAt: null,
+    });
+    vi.spyOn(h.joinRequestStore, 'changeRequestStates').mockRejectedValueOnce(new Error('db down'));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { status, plugins } = await listPlugins(h.baseUrl);
+    expect(status).toBe(200);
+    expect(plugins[0]).toMatchObject({ name: 'finance', hasRequested: true, requestNumber: 9 });
+    warn.mockRestore();
   });
 
   it('degrades hasRequested to false when the CR lookup throws', async () => {

package/src/modules/plugins/__tests__/plugins.tools.test.ts

@@ -0,0 +1,131 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import { keyOrSessionAuth } from '../../tool-auth/key-or-session.middleware.js';
+import { createAuthMiddleware } from '../../auth/auth.middleware.js';
+import { registerPluginsTools, CREATE_PLUGIN, MY_PLUGIN } from '../plugins.tools.js';
+import { createPluginCreationRoutes } from '../plugins.routes.js';
+import { PluginProvisionError } from '../plugin-provision.service.js';
+
+/**
+ * The plugin tools are DESCRIPTIONS of the app's own creation endpoints.
+ * Two things to hold: the definitions point at those endpoints and are in
+ * every surface's catalog; and the endpoints admit an agent's connection
+ * key through the key-or-session gate exactly as they admit a session —
+ * one implementation, whoever knocks.
+ */
+
+const ALICE = { id: 'user-alice', email: 'alice@x.com', name: 'Alice' };
+
+describe('the tool definitions', () => {
+  it('describe the creation endpoints, and reach every surface', async () => {
+    expect((CREATE_PLUGIN.tool_call_template as { url: string }).url).toBe('${API_URL}/api/plugins');
+    expect((MY_PLUGIN.tool_call_template as { url: string }).url).toBe('${API_URL}/api/plugins/personal');
+    const registry = new ToolRegistry();
+    registerPluginsTools(registry);
+    for (const tools of [await registry.listExternal({ userEmail: ALICE.email }), await registry.listInternal({ userEmail: ALICE.email })]) {
+      expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(['my_plugin', 'create_plugin']));
+    }
+  });
+});
+
+describe('the creation endpoints behind the key-or-session gate', () => {
+  const ensurePersonalPlugin = vi.fn(async (user: { id: string }) => ({
+    folder: `personal-${user.id}`,
+    path: `Plugins/personal-${user.id}`,
+    skillsDir: `Plugins/personal-${user.id}/skills`,
+    name: `personal-${user.id}`,
+    created: true,
+  }));
+  const createPlugin = vi.fn(async (_user: unknown, name: string, parent?: string) => {
+    const folder = parent ? `${parent}/${name}` : name;
+    return { folder, path: `Plugins/${folder}`, skillsDir: `Plugins/${folder}/skills`, name: name.toLowerCase(), created: true };
+  });
+
+  let httpServer: HttpServer | undefined;
+
+  const externalApiKeyService = {
+    looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+    verifyAndLoadToken: async (t: string) => (t === 'bevel_alice' ? { user: ALICE, tokenId: 'tok-a' } : null),
+  } as never;
+  const authService = {
+    getUserById: async (id: string) => (id === ALICE.id ? ALICE : null),
+    verifyToken: (t: string) => {
+      if (t !== 'session-alice') throw new Error('bad token');
+      return { userId: ALICE.id, email: ALICE.email };
+    },
+  } as never;
+
+  async function start(): Promise<string> {
+    const internalToken = new InternalTokenService({ secret: 'test-secret' });
+    const app = express();
+    app.use(express.json());
+    app.use(
+      '/api',
+      keyOrSessionAuth({
+        sessionAuth: createAuthMiddleware(authService),
+        toolAuth: createToolAuthMiddleware(externalApiKeyService, internalToken),
+        isToolCredential: (t) => internalToken.looksLikeInternalToken(t) || externalApiKeyService.looksLikeExternalApiKey(t),
+      }),
+      createPluginCreationRoutes({ ensurePersonalPlugin, createPlugin } as never, async (req) =>
+        req.userId ? ((await (authService as { getUserById(id: string): Promise<unknown> }).getUserById(req.userId)) as never) : null,
+      ),
+    );
+    httpServer = await new Promise<HttpServer>((r) => {
+      const s = app.listen(0, () => r(s));
+    });
+    return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+  }
+
+  afterEach(async () => {
+    if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+    httpServer = undefined;
+    vi.clearAllMocks();
+  });
+
+  const post = (base: string, path: string, body: unknown, bearer: string) =>
+    fetch(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${bearer}` },
+      body: JSON.stringify(body),
+    });
+
+  it("a connection key reaches the same endpoint a session does, as the same person", async () => {
+    const base = await start();
+    const byKey = await post(base, '/api/plugins', { name: 'GTM', parent: 'Teams' }, 'bevel_alice');
+    expect(byKey.status).toBe(201);
+    expect(await byKey.json()).toEqual({
+      folder: 'Teams/GTM',
+      path: 'Plugins/Teams/GTM',
+      skillsDir: 'Plugins/Teams/GTM/skills',
+      name: 'gtm',
+      created: true,
+    });
+    expect(createPlugin).toHaveBeenLastCalledWith(expect.objectContaining({ id: ALICE.id }), 'GTM', 'Teams');
+
+    const bySession = await post(base, '/api/plugins', { name: 'Ops' }, 'session-alice');
+    expect(bySession.status).toBe(201);
+    expect(createPlugin).toHaveBeenLastCalledWith(expect.objectContaining({ id: ALICE.id }), 'Ops', undefined);
+  });
+
+  it("my_plugin's endpoint ensures the caller's own space for a key holder", async () => {
+    const base = await start();
+    const res = await post(base, '/api/plugins/personal', {}, 'bevel_alice');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ path: 'Plugins/personal-user-alice', skillsDir: 'Plugins/personal-user-alice/skills' });
+    expect(ensurePersonalPlugin).toHaveBeenCalledWith(expect.objectContaining({ id: ALICE.id }));
+  });
+
+  it("refuses a bad key and a bad session alike, and passes the service's refusal through with its status", async () => {
+    const base = await start();
+    expect((await post(base, '/api/plugins', { name: 'X' }, 'bevel_nobody')).status).toBe(401);
+    expect((await post(base, '/api/plugins', { name: 'X' }, 'session-nobody')).status).toBe(401);
+    createPlugin.mockRejectedValueOnce(new PluginProvisionError('There is no folder "Nope" under Plugins/.', 404));
+    const refused = await post(base, '/api/plugins', { name: 'X', parent: 'Nope' }, 'bevel_alice');
+    expect(refused.status).toBe(404);
+    expect(await refused.json()).toEqual({ error: 'There is no folder "Nope" under Plugins/.' });
+  });
+});