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

package/src/modules/plugins/__tests__/plugin-links.service.test.ts

@@ -4,7 +4,7 @@ import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { DEFAULT_BRANCH, type AuthUser } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, withLinkedSkillRoots, type AuthUser } from '@bevel-software/platform-shared';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
@@ -13,6 +13,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { PluginLinkIndex } from '../plugin-links.js';
 import { PluginLinksService, PluginLinkError } from '../plugin-links.service.js';
 import type { ProvisionCommitDriver } from '../plugin-provision.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * Linking end to end over a real tree: the real resolver decides who may
@@ -36,6 +37,10 @@ describe('PluginLinksService', () => {
   let root: string;
   let repo: string;
   let commits: string[];
+  /** The commit SUBJECT each of those landed with — `undefined` = the default. */
+  let subjects: (string | undefined)[];
+  /** Set to make the commit driver refuse every path containing it. */
+  let failCommitsUnder: string | null;
   let access: AccessControlService;
   let skills: SkillService;
   let index: PluginLinkIndex;
@@ -52,6 +57,8 @@ describe('PluginLinksService', () => {
     root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-links-'));
     repo = path.join(root, wsId, KB_DIR);
     commits = [];
+    subjects = [];
+    failCommitsUnder = null;
     const workspaceService = {
       getOrCreateForBranch: async () => ({ id: wsId }),
       getWorkspacePath: async (id: string) => path.join(root, id),
@@ -64,8 +71,12 @@ describe('PluginLinksService', () => {
       ensureRemotesFetched: async () => undefined,
     } as unknown as WorkspaceService;
     const driver: ProvisionCommitDriver = {
-      runPendingCommit: async (_ws, _branch, target) => {
+      runPendingCommit: async (_ws, _branch, target, _user, opts) => {
+        if (failCommitsUnder !== null && target.includes(failCommitsUnder)) {
+          throw new Error('the push gate said no');
+        }
         commits.push(target);
+        subjects.push(opts?.summary);
       },
     };
 
@@ -84,9 +95,10 @@ describe('PluginLinksService', () => {
 
     const disk = new NodeFs();
     access = new AccessControlService(workspaceService, KB_DIR, disk);
-    skills = new SkillService(workspaceService, access, KB_DIR, disk);
-    index = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, new KbPluginSource(disk));
-    svc = new PluginLinksService(workspaceService, driver, access, skills, index, KB_DIR);
+    const kb = testKbContext({ kbDirName: KB_DIR });
+    skills = new SkillService(workspaceService, access, kb, disk);
+    index = new PluginLinkIndex(workspaceService, skills, access, kb, new KbPluginSource(disk, kb));
+    svc = new PluginLinksService(workspaceService, driver, access, skills, index, kb);
   });
   afterEach(() => fs.rm(root, { recursive: true, force: true }));
 
@@ -281,4 +293,207 @@ describe('PluginLinksService', () => {
     index.invalidate();
     expect(await index.pluginsOf('Plugins/GTM/skills/outreach')).toEqual([{ name: 'gtm', linked: false, granted: true }]);
   });
+
+  /**
+   * A link written into the manifest WITHOUT its grants — the hand edit this
+   * whole surface exists for. `link()` writes both lines; every test below is
+   * about what the index and the repair say when they are absent.
+   */
+  const linkByHand = async (...roots: string[]) => {
+    await write(
+      'Plugins/GTM/plugin.json',
+      `${JSON.stringify(withLinkedSkillRoots({ name: 'gtm', version: '1.0.0' }, roots), null, 2)}\n`,
+    );
+    access.invalidate(wsId);
+    skills.invalidate();
+    index.invalidate();
+  };
+
+  /** Whether the index calls the link to one skill healthy. */
+  const grantedOf = async (skillPath: string) =>
+    (await index.pluginsOf(skillPath)).find((m) => m.name === 'gtm')?.granted;
+
+  describe('granted — the two lines at the root, and nothing else', () => {
+    it('a PUBLIC root is not granted: the grant is the link, not the readability', async () => {
+      // The demo-core shape: the repository root says `read: everyone`, so
+      // GTM's members can read the skill and the link still names nothing.
+      await write('access.md', '---\n---\nread:\n  - everyone\nwrite:\n  - Admin\n');
+      await linkByHand('Skills/Eng/deploy');
+
+      expect(await access.canRead(wsId, member.email, 'Skills/Eng/deploy/SKILL.md')).toBe(true);
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(false);
+    });
+
+    it('a plugin grant INHERITED from a folder above the root does not count', async () => {
+      await write(
+        'Skills/Eng/access.md',
+        '---\n---\nread:\n  - plugin/gtm/read\nwrite:\n  - Eve <eve@x.io>\n  - plugin/gtm/write\n',
+      );
+      await linkByHand('Skills/Eng/deploy');
+
+      // The members CAN read it — and the root the manifest names still says
+      // nothing about GTM, so the link is one edit of Skills/Eng away from
+      // silently sharing nothing.
+      expect(await access.canRead(wsId, member.email, 'Skills/Eng/deploy/SKILL.md')).toBe(true);
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(false);
+    });
+
+    it('both lines at the root are granted; a deny BELOW the root is not', async () => {
+      await write(
+        'Skills/Eng/access.md',
+        '---\n---\nread:\n  - plugin/gtm/read\nwrite:\n  - Eve <eve@x.io>\n  - plugin/gtm/write\n',
+      );
+      await write('Skills/Eng/rollback/access.md', '---\n---\nread:\n  - deny plugin/gtm/read\n');
+      await linkByHand('Skills/Eng');
+
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(true);
+      expect(await grantedOf('Skills/Eng/rollback')).toBe(false);
+    });
+
+    it('a deny AT the root beside the lines is not granted — the deny is the operator\'s', async () => {
+      // What a repair leaves behind when someone has denied the plugin: the
+      // grant is spliced in, the deny stays, and the link stays broken.
+      await write(
+        'Skills/Eng/deploy/access.md',
+        '---\n---\nread:\n  - plugin/gtm/read\n  - deny plugin/gtm/read\nwrite:\n  - plugin/gtm/write\n',
+      );
+      await linkByHand('Skills/Eng/deploy');
+
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(false);
+    });
+  });
+
+  describe('repairAll — what opening the plugin page runs', () => {
+    it('does not call a link denied at its root repaired: nothing to write, and the banner keeps it', async () => {
+      // The lines are there; a `deny` beside them is what breaks the link.
+      // The repair has nothing to write, and a root it did not write is not
+      // one it fixed — reporting it repaired would hide it from the one
+      // person who could act, and reload the page for nothing.
+      await write(
+        'Skills/Eng/deploy/access.md',
+        '---\n---\nread:\n  - plugin/gtm/read\n  - deny plugin/gtm/read\nwrite:\n  - Mia <mia@x.io>\n  - plugin/gtm/write\n',
+      );
+      await linkByHand('Skills/Eng/deploy');
+      commits.length = 0;
+
+      const report = await svc.repairAll(manager, 'gtm');
+      expect(report.repaired).toEqual([]);
+      expect(report.skipped).toMatchObject([
+        { root: 'Skills/Eng/deploy', reason: 'denied', skills: [{ path: 'Skills/Eng/deploy', name: 'deploy' }] },
+      ]);
+      // Eve edits Skills/Eng (the fixture's own rule) and Mia the root itself:
+      // both can remove the deny, so both are named.
+      expect(report.skipped[0].editors.users.map((u) => u.email).sort()).toEqual(['eve@x.io', 'mia@x.io']);
+      expect(commits).toEqual([]);
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(false);
+    });
+
+    it('repairs every link the writer may write, silently, and says nothing about them', async () => {
+      await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n  - Mia <mia@x.io>\n');
+      await linkByHand('Skills/Eng/deploy', 'Skills/Eng/rollback');
+      commits.length = 0;
+      subjects.length = 0;
+
+      expect(await svc.repairAll(manager, 'gtm')).toEqual({
+        repaired: ['Skills/Eng/deploy', 'Skills/Eng/rollback'],
+        skipped: [],
+      });
+      expect(commits).toEqual([
+        `${KB_DIR}/Skills/Eng/deploy/access.md`,
+        `${KB_DIR}/Skills/Eng/rollback/access.md`,
+      ]);
+      // The commit is the only trace a silent repair leaves, so it has to
+      // explain itself.
+      expect(subjects).toEqual([
+        'Repair link: gtm → Skills/Eng/deploy (automatic, on opening the plugin page)',
+        'Repair link: gtm → Skills/Eng/rollback (automatic, on opening the plugin page)',
+      ]);
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(true);
+      expect(await grantedOf('Skills/Eng/rollback')).toBe(true);
+    });
+
+    it('writes exactly what the manual repair writes', async () => {
+      await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+      await linkByHand('Skills/Eng/deploy', 'Skills/Eng/rollback');
+
+      await svc.repair(manager, 'gtm', 'Skills/Eng/deploy');
+      await svc.repairAll(manager, 'gtm');
+      expect(await read('Skills/Eng/rollback/access.md')).toEqual(
+        await read('Skills/Eng/deploy/access.md'),
+      );
+    });
+
+    it('leaves a link the writer may not repair alone, and names who can', async () => {
+      // Skills/Eng is Eve's. Mia manages GTM and nothing else.
+      await linkByHand('Skills/Eng/deploy');
+      commits.length = 0;
+
+      const report = await svc.repairAll(manager, 'gtm');
+      expect(report.repaired).toEqual([]);
+      expect(report.skipped).toEqual([
+        {
+          root: 'Skills/Eng/deploy',
+          reason: 'needs-skill-write',
+          skills: [{ path: 'Skills/Eng/deploy', name: 'deploy' }],
+          // Admin holds the write floor on any access.md, so an admin can
+          // always repair a link; the eligible lists carry no display names,
+          // so Eve is named by the address a reader can write to.
+          editors: { roles: ['Admin'], users: [{ name: 'eve@x.io', email: 'eve@x.io' }] },
+        },
+      ]);
+      expect(commits).toEqual([]);
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(false);
+    });
+
+    it('is refused for someone who may not write the plugin — the same 404 as an unknown one', async () => {
+      await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Sam <sam@x.io>\n');
+      await linkByHand('Skills/Eng/deploy');
+
+      await expect(svc.repairAll(member, 'gtm')).rejects.toMatchObject({ status: 404 });
+      await expect(svc.repairAll(manager, 'Ghost')).rejects.toMatchObject({ status: 404 });
+      // Sam may write the skill; being unable to write GTM is what stopped it.
+      expect(commits).toEqual([]);
+      expect(await grantedOf('Skills/Eng/deploy')).toBe(false);
+    });
+
+    it('writes nothing the second time: a root that already carries both lines is left alone', async () => {
+      await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+      await linkByHand('Skills/Eng/deploy');
+      await svc.repairAll(manager, 'gtm');
+      commits.length = 0;
+
+      expect(await svc.repairAll(manager, 'gtm')).toEqual({ repaired: [], skipped: [] });
+      expect(commits).toEqual([]);
+      const rules = await read('Skills/Eng/deploy/access.md');
+      expect(rules.match(/plugin\/gtm\/read/g)).toHaveLength(1);
+      expect(rules.match(/plugin\/gtm\/write/g)).toHaveLength(1);
+    });
+
+    it('a repair that fails leaves the others repaired, and stays in the report', async () => {
+      await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n  - Mia <mia@x.io>\n');
+      await linkByHand('Skills/Eng/deploy', 'Skills/Eng/rollback');
+      failCommitsUnder = 'Skills/Eng/rollback';
+      commits.length = 0;
+
+      const report = await svc.repairAll(manager, 'gtm');
+      expect(report.repaired).toEqual(['Skills/Eng/deploy']);
+      expect(report.skipped).toMatchObject([{ root: 'Skills/Eng/rollback', reason: 'failed' }]);
+      // Eve and Mia both edit the scope, so both are named as able to repair it.
+      expect(report.skipped[0].editors.users.map((u) => u.email).sort()).toEqual([
+        'eve@x.io',
+        'mia@x.io',
+      ]);
+      expect(commits).toEqual([`${KB_DIR}/Skills/Eng/deploy/access.md`]);
+      expect(await read('Skills/Eng/deploy/access.md')).toContain('plugin/gtm/read');
+    });
+
+    it('has nothing to do for a plugin whose links are all healthy', async () => {
+      await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+      await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
+      commits.length = 0;
+
+      expect(await svc.repairAll(manager, 'gtm')).toEqual({ repaired: [], skipped: [] });
+      expect(commits).toEqual([]);
+    });
+  });
 });

package/src/modules/plugins/__tests__/plugin-provision.service.test.ts

@@ -15,6 +15,7 @@ import {
   pluginAccessMd,
   personalAccessMd,
 } from '../plugin-provision.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
 const USER: AuthUser = { id: 'u1-abcd', email: 'ali@example.com', name: 'Ali Vega' } as AuthUser;
@@ -50,7 +51,8 @@ async function makeHarness() {
   const commits = { runPendingCommit: vi.fn(async () => undefined) };
   const accessControl = { invalidate: vi.fn() } as unknown as IAccessControl;
   const events = { emit: vi.fn() };
-  const svc = new PluginProvisionService(workspaceService, commits, accessControl, KB, events, new KbPluginSource(new NodeFs()), new NodeFs());
+  const kb = testKbContext({ kbDirName: KB });
+  const svc = new PluginProvisionService(workspaceService, commits, accessControl, kb, events, new KbPluginSource(new NodeFs(), kb), new NodeFs());
   return { svc, dir, commits, accessControl, events, writeFile };
 }
 

package/src/modules/plugins/__tests__/plugin-rename.service.test.ts

@@ -12,6 +12,7 @@ import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js'
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 import { PluginRenameError, PluginRenameService, renamePluginPrincipalInText } from '../plugin-rename.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 // The one walk of the checkout, with a switch that makes it report a hole —
 // the way a folder it cannot list would — to every listener on it. The
@@ -115,7 +116,7 @@ describe('PluginRenameService', () => {
 
     access = new AccessControlService(workspaceService, KB_DIR, new NodeFs());
     const disk = new HoledFs();
-    svc = new PluginRenameService(workspaceService, driver, access, new KbPluginSource(disk), disk, KB_DIR, undefined, () => {
+    svc = new PluginRenameService(workspaceService, driver, access, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })), disk, testKbContext({ kbDirName: KB_DIR }), undefined, () => {
       invalidated += 1;
     });
   });
@@ -124,7 +125,7 @@ describe('PluginRenameService', () => {
   it('refuses to claim a name against a listing with a hole in it — an unreadable folder may hold that very plugin', async () => {
     // Discovery as the walker reports it when a folder exists but could not
     // be read: the plugins it did see, plus the hole.
-    const real = new KbPluginSource(new NodeFs());
+    const real = new KbPluginSource(new NodeFs(), testKbContext({ kbDirName: KB_DIR }));
     const holed = {
       dialect: 'kb',
       discover: async (root: string) => ({ ...(await real.discover(root)), unreadable: ['Plugins/Hidden'] }),
@@ -135,7 +136,7 @@ describe('PluginRenameService', () => {
       access,
       holed,
       new NodeFs(),
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
     );
     await expect(svcOverHole.rename(manager, 'gtm', { name: 'go-to-market' })).rejects.toMatchObject({
       status: 503,
@@ -155,7 +156,7 @@ describe('PluginRenameService', () => {
   });
 
   it('tells a NON-manager nothing about the tree — a holed discovery is still just "unknown plugin" to them', async () => {
-    const real = new KbPluginSource(new NodeFs());
+    const real = new KbPluginSource(new NodeFs(), testKbContext({ kbDirName: KB_DIR }));
     const holed = {
       dialect: 'kb',
       discover: async (root: string) => ({ ...(await real.discover(root)), unreadable: ['Plugins/Hidden'] }),
@@ -166,7 +167,7 @@ describe('PluginRenameService', () => {
       access,
       holed,
       new NodeFs(),
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
     );
     const refusal = await svcOverHole.rename(member, 'gtm', { name: 'go-to-market' }).catch((e: unknown) => e);
     expect(refusal).toMatchObject({ status: 404, payload: { kind: 'unknown-plugin' } });
@@ -269,7 +270,7 @@ describe('PluginRenameService', () => {
       expect(await read('Skills/Eng/deploy/access.md')).toBe(DEPLOY_RULES);
       // The three answers that must never diverge: the rename's, the
       // discovery source's, and the shared reader's over the file itself.
-      const { plugins } = await new KbPluginSource(new NodeFs()).discover(repo);
+      const { plugins } = await new KbPluginSource(new NodeFs(), testKbContext({ kbDirName: KB_DIR })).discover(repo);
       const found = plugins.find((p) => p.folder === 'Plugins/GTM')!;
       expect([found.name, found.displayName]).toEqual([result.name, result.displayName]);
       expect(pluginDisplayNameOf(JSON.parse(await read('Plugins/GTM/plugin.json')))).toBe(result.displayName);

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

@@ -22,6 +22,7 @@ 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';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP-level contract for the plugin routes: the auth gate, the three-tier
@@ -155,7 +156,14 @@ async function makeHarness(opts: HarnessOpts = {}) {
 
   const index =
     opts.index ??
-    new PluginIndexService(workspaceService, accessControl, skillService, toolService, KB, new KbPluginSource(new NodeFs()));
+    new PluginIndexService(
+      workspaceService,
+      accessControl,
+      skillService,
+      toolService,
+      testKbContext({ kbDirName: KB }),
+      new KbPluginSource(new NodeFs(), testKbContext({ kbDirName: KB })),
+    );
 
   const email = opts.email === undefined ? ALI : opts.email;
   const app = express();
@@ -185,7 +193,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
   const joinRequestJobs = new PluginJoinRequestJobs(joinRequestStore, {
     workflow,
     workspaceService,
-    kbDirName: KB,
+    kb: testKbContext({ kbDirName: KB }),
     target: async (pluginKey) => {
       const entry = (await index.catalog()).find(
         (g) => pluginFolderBelowRoot(g.folders[0]) === pluginKey,
@@ -221,6 +229,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
       joinRequestJobs,
       provision as never,
       async (req) => (req.userEmail ? { ...ALI_USER, email: req.userEmail } : null),
+      testKbContext({ kbDirName: KB }),
     ),
   );
 

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

@@ -8,6 +8,7 @@ import type { ISkillService, SkillSummary } from '../../skills/skills.contract.j
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { IPluginIndexService, PluginCatalogEntry } from '../plugins.contract.js';
 import { createTeamsRoutes } from '../teams.routes.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * `GET /api/teams` — what each group can use, by id, sliced to what the
@@ -92,7 +93,7 @@ async function harness(opts: HarnessOpts = {}) {
     if (email) req.userEmail = email;
     next();
   });
-  app.use('/api', createTeamsRoutes(accessControl, index, skills, tools));
+  app.use('/api', createTeamsRoutes(accessControl, index, skills, tools, testKbContext()));
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });

package/src/modules/plugins/compile/marketplace-compiler.service.ts

@@ -1,9 +1,8 @@
 import path from 'node:path';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ISkillService } from '../../skills/skills.contract.js';
-import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import type { KbContext } from '../../../shared/kb-context.js';
 import type { PluginLinkIndex } from '../plugin-links.js';
 import type { PluginSource } from '../discovery/plugin-source.js';
 import type { ITreeWalker } from '../../../shared/fs.contract.js';
@@ -31,7 +30,7 @@ export class MarketplaceCompilerService {
     private readonly accessControl: IAccessControl,
     private readonly skillService: ISkillService,
     private readonly links: PluginLinkIndex,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly marketplace: {
       name: string;
       owner: string;
@@ -45,6 +44,10 @@ export class MarketplaceCompilerService {
     private readonly gitRunner: IGitRunner,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   /**
    * The default-branch commit the next compile would read. Throws when git
    * cannot say: the repo service keys freshness on this value, and a stable
@@ -108,7 +111,7 @@ export class MarketplaceCompilerService {
   // --- internal --------------------------------------------------------------
 
   private async checkout(): Promise<{ wsId: string; kbRoot: string }> {
-    const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+    const wsId = (await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch)).id;
     return { wsId, kbRoot: path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName) };
   }
 
@@ -144,8 +147,3 @@ export class MarketplaceCompilerService {
     };
   }
 }
-
-/** The default-branch workspace id compiles run against. */
-export function compileWorkspaceId(): string {
-  return workspaceIdForBranch(DEFAULT_BRANCH);
-}

package/src/modules/plugins/discovery/__tests__/kb-plugin-source.test.ts

@@ -3,8 +3,12 @@ import { NodeFs } from '../../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { DEFAULT_KB_LAYOUT, configureKbLayout, pluginDisplayNameOf } from '@bevel-software/platform-shared';
+import { pluginDisplayNameOf } from '@bevel-software/platform-shared';
 import { KbPluginSource } from '../kb-plugin-source.js';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+
+/** The layout the source under test reads; a suite swaps it for the customer's names. */
+let kbContext = testKbContext();
 
 /**
  * The customer's tree, in their own root names (lowercase `plugins/` and
@@ -37,7 +41,7 @@ describe('KbPluginSource — bundles', () => {
 
   beforeEach(async () => {
     kb = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-bundle-'));
-    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    kbContext = testKbContext({ layout: { knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' } });
     await write('configs/mcp/registry.json', JSON.stringify(REGISTRY));
     await write(
       'plugins/functional/cluster-a/example-plugin/plugin.bundle.json',
@@ -66,12 +70,12 @@ describe('KbPluginSource — bundles', () => {
     await write('plugins/broken/plugin.bundle.json', '{ not json');
   });
   afterEach(async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
+    kbContext = testKbContext();
     await fs.rm(kb, { recursive: true, force: true });
   });
 
   it('finds bundles at any depth and reads them as plugins that link skill roots', async () => {
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     const byName = new Map(plugins.map((p) => [p.name, p]));
     expect([...byName.keys()].sort()).toEqual(['close', 'example-plugin', 'ledger', 'padded', 'unnamed']);
     // The bundle dialect's own rule — a declared display name, else the
@@ -119,7 +123,7 @@ describe('KbPluginSource — bundles', () => {
   });
 
   it('expands mcpProfile through the registry, following extends and reporting unknowns', async () => {
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     const example = plugins.find((p) => p.name === 'example-plugin')!;
     expect(example.mcpServers).toEqual({
       confluence: { type: 'streamable-http', url: 'https://mcp.confluence.example' },
@@ -156,7 +160,7 @@ describe('KbPluginSource — bundles', () => {
         ],
       }),
     );
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     const example = plugins.find((p) => p.name === 'example-plugin')!;
     expect(example.mcpServers).toEqual({
       jira: { type: 'stdio', command: 'npx', args: ['-y', 'jira-mcp'] },
@@ -174,7 +178,7 @@ describe('KbPluginSource — bundles', () => {
 
   it('cuts an extends cycle instead of hanging, and keeps what it collected', async () => {
     await write('plugins/loop/plugin.bundle.json', JSON.stringify({ name: 'loop', mcpProfile: 'loop-a' }));
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     const loop = plugins.find((p) => p.name === 'loop')!;
     expect(loop.mcpServers).toEqual({ 'flat-http': { type: 'streamable-http', url: 'https://flat.example' } });
     expect(warnings.some((w) => w.includes('cycle'))).toBe(true);
@@ -182,7 +186,7 @@ describe('KbPluginSource — bundles', () => {
 
   it('a missing registry leaves the plugins standing, servers-less, with a warning per profile', async () => {
     await fs.rm(path.join(kb, 'configs'), { recursive: true });
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     expect(plugins.find((p) => p.name === 'example-plugin')!.mcpServers).toBeNull();
     expect(warnings.some((w) => w.includes('no registry'))).toBe(true);
   });
@@ -200,7 +204,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     kb = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-mixed-'));
   });
   afterEach(async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
+    kbContext = testKbContext();
     await fs.rm(kb, { recursive: true, force: true });
   });
 
@@ -226,7 +230,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     // beneath: a container, not a plugin.
     await write('Plugins/functional/access.md', '---\n---\nread:\n  - everyone\n');
 
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     // Folders are visited in locale order (case-insensitive), depth first.
     // Position means nothing: only the two files make a plugin.
     expect(plugins.map((p) => [p.name, p.folder, p.linksAreManaged, p.exists])).toEqual([
@@ -245,7 +249,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     await write('Plugins/b/GTM/plugin.json', '{}');
     // Different spelling, same manifest slug: still one plugin.
     await write('Plugins/c/gtm/plugin.json', '{}');
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     expect(plugins.map((p) => p.folder)).toEqual(['Plugins/a/GTM']);
     expect(warnings).toEqual([
       'Plugins/b/GTM: plugin name "gtm" is already used by Plugins/a/GTM — plugin skipped',
@@ -261,7 +265,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     await write('Plugins/Nested/plugin.json', `{"name":${'['.repeat(20000)}${']'.repeat(20000)}}`);
     await write('Plugins/Ops/plugin.json', JSON.stringify({ name: 'Not An Identifier' }));
     await write('Plugins/Plain/plugin.json', '{}');
-    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     expect(plugins.map((p) => [p.name, p.displayName, p.folder])).toEqual([
       // Both fields present: both are read, and `Plugins/GTM` says nothing.
       ['go-to-market', 'Go To Market', 'Plugins/GTM'],
@@ -303,7 +307,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
           : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never),
     ];
     try {
-      const { plugins, warnings, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
+      const { plugins, warnings, unreadable } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
       // The container could not be listed: nothing beneath it was seen. The
       // manifest could not be read: an identity nobody could see, so the
       // plugin is not listed under a guessed one. Both are holes, not absence.
@@ -331,7 +335,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
         ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
         : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never);
     try {
-      const { plugins, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
+      const { plugins, unreadable } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
       expect(unreadable).toEqual(['Plugins/Hidden/plugin.json']);
       expect(plugins.map((p) => p.name)).toEqual(['gtm']);
     } finally {
@@ -348,7 +352,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
         ? Promise.reject(Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' }))
         : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never);
     try {
-      const { plugins, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
+      const { plugins, unreadable } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
       expect(plugins.map((p) => p.name)).toEqual(['gtm']);
       expect(unreadable).toEqual([]);
     } finally {
@@ -357,7 +361,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
   });
 
   it('a knowledge base without a plugins root has no plugins and no complaint', async () => {
-    const { plugins, warnings, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
+    const { plugins, warnings, unreadable } = await new KbPluginSource(new NodeFs(), kbContext).discover(kb);
     expect(plugins).toEqual([]);
     expect(warnings).toEqual([]);
     expect(unreadable).toEqual([]);

package/src/modules/plugins/discovery/bundle-dialect/bundle.source.ts

@@ -1,6 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { isPersonalPluginDir, normalizeSkillRoot, pluginManifestName } from '@bevel-software/platform-shared';
+import {
+  isPersonalPluginDir,
+  normalizeSkillRoot,
+  pluginManifestName,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
 import { isAbsence } from '../../../../shared/fs.contract.js';
 import type { DiscoveredPlugin } from '../plugin-source.js';
 import { expandProfile, parseRegistry, type McpRegistry } from './registry.js';
@@ -67,6 +72,8 @@ export async function readBundlePlugin(
   registry: McpRegistry | null,
   warnings: string[],
   unreadable: string[],
+  /** Names the plugins root a personal folder sits directly under. */
+  layout: KbLayout,
 ): Promise<DiscoveredPlugin | null> {
   // Reading and parsing are two failures with two meanings: a file that
   // cannot be read is a plugin nobody could see (counted, so a writer can
@@ -149,7 +156,7 @@ export async function readBundlePlugin(
     relFolder,
     // The same rule as the native reader: a reserved personal folder directly
     // under the root is a place, not a plugin, whatever file it carries.
-    personal: isPersonalPluginDir(folder),
+    personal: isPersonalPluginDir(folder, layout),
     exists: true,
     manifest,
     manifestText: null,