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

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,

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

@@ -1,7 +1,8 @@
 import path from 'node:path';
-import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, pluginManifestName } from '@bevel-software/platform-shared';
+import { PLUGIN_MANIFEST_FILE, pluginManifestName, type KbLayout } from '@bevel-software/platform-shared';
 import type { DiscoveredPlugin, Discovery, PluginSource, PluginSourceWalk } from './plugin-source.js';
 import type { IFsProbe, ITreeWalker, WalkListener } from '../../../shared/fs.contract.js';
+import type { KbContext } from '../../../shared/kb-context.js';
 import { readNativePlugin } from './native.source.js';
 import { BUNDLE_FILE, loadRegistry, readBundlePlugin } from './bundle-dialect/bundle.source.js';
 import type { McpRegistry } from './bundle-dialect/registry.js';
@@ -38,7 +39,11 @@ import type { McpRegistry } from './bundle-dialect/registry.js';
 export class KbPluginSource implements PluginSource {
   readonly dialect = 'kb';
 
-  constructor(private readonly disk: ITreeWalker & IFsProbe) {}
+  constructor(
+    private readonly disk: ITreeWalker & IFsProbe,
+    /** Read per walk, never captured: the plugins root is renameable from the setup screen. */
+    private readonly kb: Pick<KbContext, 'layout'>,
+  ) {}
 
   async discover(kbRoot: string): Promise<Discovery> {
     return (await this.walkWith(kbRoot, [])).discovery;
@@ -47,7 +52,7 @@ export class KbPluginSource implements PluginSource {
   async walkWith(kbRoot: string, listeners: readonly WalkListener[]): Promise<PluginSourceWalk> {
     const warnings: string[] = [];
     const registry = await loadRegistry(kbRoot, warnings);
-    const listener = pluginListener(this.disk, kbRoot, registry, warnings);
+    const listener = pluginListener(this.disk, kbRoot, this.kb.layout, registry, warnings);
     const { holes } = await this.disk.walkKb(kbRoot, [listener.listener, ...listeners]);
     return { discovery: listener.result(), holes };
   }
@@ -57,16 +62,18 @@ export class KbPluginSource implements PluginSource {
 function pluginListener(
   disk: IFsProbe,
   kbRoot: string,
+  layout: KbLayout,
   registry: McpRegistry | null,
   warnings: string[],
 ): { listener: WalkListener; result(): Discovery } {
+  const { pluginsDir } = layout;
   const unreadable: string[] = [];
   const plugins: DiscoveredPlugin[] = [];
   const seen = new Map<string, string>();
   /** Folders claimed as plugins (or as holes standing where a plugin may be): nothing beneath is looked at. */
   const claimed: string[] = [];
 
-  const underRoot = (rel: string) => rel === PLUGINS_DIR || rel.startsWith(`${PLUGINS_DIR}/`);
+  const underRoot = (rel: string) => rel === pluginsDir || rel.startsWith(`${pluginsDir}/`);
   const beneathClaimed = (rel: string) => claimed.some((c) => rel === c || rel.startsWith(`${c}/`));
 
   // Uniqueness is judged on the MANIFEST SLUG, not the raw name: `Sales Team`
@@ -87,18 +94,18 @@ function pluginListener(
   return {
     listener: {
       async onDir(rel, entries) {
-        if (!underRoot(rel) || rel === PLUGINS_DIR || beneathClaimed(rel)) return;
+        if (!underRoot(rel) || rel === pluginsDir || beneathClaimed(rel)) return;
         const has = (name: string) => entries.some((e) => e.isFile() && e.name === name);
         const dir = path.join(kbRoot, rel);
-        const relFolder = rel.slice(PLUGINS_DIR.length + 1);
+        const relFolder = rel.slice(pluginsDir.length + 1);
         if (has(PLUGIN_MANIFEST_FILE)) {
           claimed.push(rel);
           // A manifest that could not be read: a hole, and still claimed.
-          const native = await readNativePlugin(disk, dir, rel, relFolder, warnings, unreadable);
+          const native = await readNativePlugin(disk, dir, rel, relFolder, warnings, unreadable, layout);
           if (native) claim(native);
         } else if (has(BUNDLE_FILE)) {
           claimed.push(rel);
-          const bundle = await readBundlePlugin(dir, rel, relFolder, registry, warnings, unreadable);
+          const bundle = await readBundlePlugin(dir, rel, relFolder, registry, warnings, unreadable, layout);
           if (bundle) claim(bundle);
         }
       },

package/src/modules/plugins/discovery/native.source.ts

@@ -8,6 +8,7 @@ import {
   linkedSkillRoots,
   pluginDisplayNameOf,
   pluginIdentityOf,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
 import { isAbsence, type IFsProbe } from '../../../shared/fs.contract.js';
 import type { DiscoveredPlugin } from './plugin-source.js';
@@ -31,6 +32,8 @@ export async function readNativePlugin(
   relFolder: string,
   warnings: string[],
   unreadable: string[],
+  /** Names the plugins root a personal folder sits directly under. */
+  layout: KbLayout,
 ): Promise<DiscoveredPlugin | null> {
   const folderName = path.posix.basename(relFolder);
   const manifestRead = await readText(path.join(dir, PLUGIN_MANIFEST_FILE), folder, warnings);
@@ -97,7 +100,7 @@ export async function readNativePlugin(
     folder,
     relFolder,
     // The one structural rule: a direct child of the root with the prefix.
-    personal: isPersonalPluginDir(folder),
+    personal: isPersonalPluginDir(folder, layout),
     exists,
     manifest,
     manifestText,

package/src/modules/plugins/index.ts

@@ -1,4 +1,4 @@
-export { PluginIndexService, pluginsWorkspaceId, pluginFolderBelowRoot } from './plugins.service.js';
+export { PluginIndexService, pluginFolderBelowRoot } from './plugins.service.js';
 export {
   PluginProvisionService,
   PluginProvisionError,

package/src/modules/plugins/join-request-jobs.service.ts

@@ -1,5 +1,4 @@
 import {
-  DEFAULT_BRANCH,
   joinBranchFor,
   type AuthUser,
   type ChangeRequestState,
@@ -9,8 +8,8 @@ import { spliceGrant } from '../access-model/access-splice.js';
 import { sanitizeError } from '../workflow/sanitize-error.js';
 import { logger } from '../../shared/logging.js';
 import { printable } from '../../shared/printable.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { pluginsWorkspaceId } from './plugins.service.js';
 import type {
   ClaimedJoinRequest,
   JoinRequestRecord,
@@ -148,7 +147,8 @@ export interface JoinRequestJobsDeps {
     | 'listChangeRequestsAuthoredBy'
   >;
   workspaceService: Pick<WorkspaceService, 'getOrCreateForBranch' | 'readFile' | 'writeFile'>;
-  kbDirName: string;
+  /** The checkout folder, and which branch the request is cut from and aimed at. */
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId'>;
   /**
    * The plugin a recorded key still names, or null when nothing does — it was
    * deleted, or its folder moved out from under the record.
@@ -508,7 +508,8 @@ export class PluginJoinRequestJobs {
     claim: ClaimedJoinRequest,
     stillOurs: () => Promise<void>,
   ): Promise<void> {
-    const { workflow, workspaceService, kbDirName } = this.deps;
+    const { workflow, workspaceService, kb } = this.deps;
+    const { kbDirName } = kb;
     const target = await this.deps.target(record.pluginKey);
     if (!target) throw new Error('the plugin is no longer available');
     const user = await this.deps.requester(record.requesterEmail);
@@ -607,7 +608,7 @@ export class PluginJoinRequestJobs {
     }
     const detail = await workflow.openChangeRequest(ws.id, user, {
       sourceBranch: branch,
-      targetBranch: DEFAULT_BRANCH,
+      targetBranch: kb.defaultBranch,
       // People read these: the display name, not the identifier.
       title: `Join request: ${target.displayName}`,
       description:
@@ -637,9 +638,9 @@ export class PluginJoinRequestJobs {
    * leaves the next click free to retry the same row.
    */
   private async ensureBranch(branch: string): Promise<void> {
-    const wsId = pluginsWorkspaceId();
+    const wsId = this.deps.kb.defaultWorkspaceId();
     try {
-      await this.deps.workflow.createBranch(wsId, branch, DEFAULT_BRANCH);
+      await this.deps.workflow.createBranch(wsId, branch, this.deps.kb.defaultBranch);
       return;
     } catch (err) {
       const branches = await this.deps.workflow.listBranches(wsId, {

package/src/modules/plugins/join-requests.service.ts

@@ -1,5 +1,4 @@
 import {
-  DEFAULT_BRANCH,
   isJoinBranchFor,
   type AuthUser,
   type ChangeRequest,
@@ -9,7 +8,7 @@ import { type WorkspaceService } from '../workspace/workspace.service.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { pendingProposals, type JoinProposal } from './join-proposals.js';
 
 /** One open join change request, with what it still proposes. */
@@ -46,6 +45,7 @@ export class JoinRequestsService {
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly workflow: IWorkflowService,
+    private readonly kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>,
   ) {}
 
   /**
@@ -64,7 +64,7 @@ export class JoinRequestsService {
   ): Promise<JoinRequest[]> {
     await this.refresh();
     const accessPath = `${folder}/access.md`;
-    const baseText = await this.readAt(DEFAULT_BRANCH, accessPath);
+    const baseText = await this.readAt(this.kb.defaultBranch, accessPath);
     const out: JoinRequest[] = [];
     for (const cr of crs) {
       if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin)) continue;
@@ -104,7 +104,7 @@ export class JoinRequestsService {
     const accessPath = `${folder}/access.md`;
     const proposals = pendingProposals(
       await this.readAt(cr.branch, accessPath),
-      await this.readAt(DEFAULT_BRANCH, accessPath),
+      await this.readAt(this.kb.defaultBranch, accessPath),
       accessPath,
     );
     if (proposals.length > 0) return false;
@@ -125,7 +125,7 @@ export class JoinRequestsService {
    * next pass tries again.
    */
   private async settle(cr: ChangeRequest, actor: AuthUser): Promise<void> {
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
     try {
       await this.workflow.rejectChangeRequest(
         cr.number,
@@ -167,7 +167,7 @@ export class JoinRequestsService {
   private async readAt(branch: string, repoRelPath: string): Promise<string | null> {
     try {
       return await this.workspaceService.readFileAtRef(
-        workspaceIdForBranch(DEFAULT_BRANCH),
+        this.kb.defaultWorkspaceId(),
         `origin/${branch}`,
         repoRelPath,
       );
@@ -183,7 +183,7 @@ export class JoinRequestsService {
    */
   private async refresh(): Promise<void> {
     await this.workspaceService
-      .ensureRemotesFetched(workspaceIdForBranch(DEFAULT_BRANCH))
+      .ensureRemotesFetched(this.kb.defaultWorkspaceId())
       .catch(() => undefined);
   }
 }