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

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

@@ -0,0 +1,150 @@
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+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 { PluginLinkIndex } from '../plugin-links.js';
+import type { PluginSource } from '../discovery/plugin-source.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
+import { compileMarketplace, type VirtualTree } from './compile-marketplace.js';
+
+const execFileAsync = promisify(execFile);
+
+/** Whose view of the knowledge base to compile. */
+export type CompileAudience = { userEmail: string } | { everyone: true };
+
+/**
+ * The compiler wired to the live deployment: the default-branch checkout,
+ * the released catalog, the link index, and the access resolver as the read
+ * verdict. Every sink — the per-user git endpoint, a public mirror, a local
+ * export — asks this for a tree and writes it somewhere.
+ *
+ * Two audiences: a PERSON (their `canRead` per skill, exactly the catalog's
+ * filter) or EVERYONE (only what `read: everyone` reaches cleanly — the
+ * public subset a shared mirror may carry). Nothing in between: an audience
+ * that is "these three people" would need a union of verdicts nobody has
+ * asked for yet.
+ */
+export class MarketplaceCompilerService {
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly accessControl: IAccessControl,
+    private readonly skillService: ISkillService,
+    private readonly links: PluginLinkIndex,
+    private readonly kbDirName: string,
+    private readonly marketplace: {
+      name: string;
+      owner: string;
+      description?: string;
+      /** The hosted MCP endpoint to ship in the skills plugin (URL only). */
+      knowledgeBaseMcp?: { name: string; url: string };
+    },
+    private readonly source: PluginSource = new KbPluginSource(),
+  ) {}
+
+  /**
+   * 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
+   * placeholder would make every later compile look unnecessary — source
+   * changes and access revocations would never reach that caller again.
+   */
+  async sourceCommit(): Promise<string> {
+    const { kbRoot } = await this.checkout();
+    const { stdout } = await execFileAsync('git', ['-C', kbRoot, 'rev-parse', 'HEAD']);
+    const sha = stdout.trim();
+    // SHA-1 or SHA-256 object format: any hex object id is a commit.
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha)) {
+      throw new Error(`could not read the default branch's commit (${sha || 'empty'})`);
+    }
+    return sha;
+  }
+
+  async compileFor(
+    audience: CompileAudience,
+    /** The commit to stamp the tree with, when the caller already read it (the freshness check does). */
+    knownCommit?: string,
+  ): Promise<VirtualTree & { sourceCommit: string }> {
+    const { wsId, kbRoot } = await this.checkout();
+    // Strictness about the commit belongs to the FRESHNESS check (the repo
+    // service calls `sourceCommit()` itself and refuses to serve without
+    // one). A compile of a checkout git cannot describe still yields a
+    // correct tree; only its README and bundle version lose the sha.
+    const sourceCommit = knownCommit ?? (await this.sourceCommit().catch(() => 'unknown'));
+    // The tree is stamped with the checkout's commit, so every input must be
+    // read from that checkout NOW — not from a catalog scanned before the
+    // commit landed. The skill catalog, the link index and the access memo
+    // are TTL caches that nothing drops on an ordinary write (an MCP
+    // `write_files` moves HEAD and invalidates none of them), and the repo
+    // service keys freshness on the stamped commit: a tree compiled from a
+    // stale catalog under a fresh sha would be "current" until the NEXT
+    // commit, with the caller's marketplace frozen on content the knowledge
+    // base no longer has. Compiles run once per moved commit per caller, so
+    // the rescan is cheap where it matters.
+    this.skillService.invalidate();
+    this.links.invalidate();
+    this.accessControl.invalidate(wsId);
+    const skills = await this.skillService.listSkills(undefined);
+    const membership = await this.links.membership();
+    const { plugins, warnings: discoveryWarnings } = await this.source.discover(kbRoot);
+    const readable = await this.readPredicate(wsId, audience, skills.map((s) => `${s.path}/SKILL.md`));
+    const tree = await compileMarketplace({
+      kbRoot,
+      skills,
+      plugins,
+      membership,
+      readable,
+      options: { ...this.marketplace, sourceCommit },
+    });
+    // Discovery's warnings ride with the compile's: a plugin left out for a
+    // malformed manifest or an unresolved MCP profile is otherwise an
+    // omission nobody can diagnose from the tree alone.
+    return { ...tree, warnings: [...discoveryWarnings, ...tree.warnings], sourceCommit };
+  }
+
+  // --- internal --------------------------------------------------------------
+
+  private async checkout(): Promise<{ wsId: string; kbRoot: string }> {
+    const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+    return { wsId, kbRoot: path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName) };
+  }
+
+  /**
+   * One batch verdict per compile, then a lookup. Fail closed both ways: a
+   * path the batch skipped is unreadable, and for the everyone audience a
+   * skill is public only when the resolver says `read: everyone` applies
+   * cleanly (`restricted: false`).
+   */
+  private async readPredicate(
+    wsId: string,
+    audience: CompileAudience,
+    docPaths: string[],
+  ): Promise<(repoPath: string) => Promise<boolean>> {
+    if ('userEmail' in audience) {
+      const verdicts = docPaths.length
+        ? await this.accessControl.canReadBatch(wsId, audience.userEmail, docPaths)
+        : new Map<string, boolean>();
+      return async (p) => verdicts.get(p) === true;
+    }
+    const cache = new Map<string, boolean>();
+    return async (p) => {
+      const hit = cache.get(p);
+      if (hit !== undefined) return hit;
+      let verdict = false;
+      try {
+        verdict = !(await this.accessControl.eligibleReaders(wsId, p)).restricted;
+      } catch {
+        verdict = false;
+      }
+      cache.set(p, verdict);
+      return verdict;
+    };
+  }
+}
+
+/** 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

@@ -0,0 +1,329 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { KbPluginSource } from '../kb-plugin-source.js';
+
+/**
+ * The customer's tree, in their own root names (lowercase `plugins/` and
+ * `skills/`), with the four ownership scopes they use and a registry with an
+ * `extends` chain. The dialect must read it as plugins that link skills.
+ */
+
+const REGISTRY = {
+  servers: [
+    { id: 'jira', name: 'Jira', config: { command: 'npx', args: ['-y', 'jira-mcp'], env: { JIRA_URL: 'https://j' } } },
+    { id: 'confluence', name: 'Confluence', config: { type: 'http', url: 'https://mcp.confluence.example' } },
+    { id: 'flat-http', type: 'http', url: 'https://flat.example' },
+  ],
+  profiles: [
+    { id: 'base', servers: ['jira'] },
+    { id: 'global', servers: ['confluence', 'ghost'], extends: 'base' },
+    { id: 'loop-a', servers: ['flat-http'], extends: 'loop-b' },
+    { id: 'loop-b', servers: [], extends: 'loop-a' },
+    { id: 'empty', servers: [] },
+  ],
+};
+
+describe('KbPluginSource — bundles', () => {
+  let kb: string;
+  const write = async (rel: string, text: string) => {
+    const abs = path.join(kb, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+
+  beforeEach(async () => {
+    kb = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-bundle-'));
+    configureKbLayout({ 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',
+      JSON.stringify({
+        name: 'example-plugin',
+        version: '1.3.1',
+        description: 'What this plugin is for',
+        mcpProfile: 'global',
+        interface: { displayName: 'Example Plugin', category: 'Productivity' },
+        sourceSkillRoots: ['skills/departments/engineering/shared/cluster-a', 'skills/functional/cluster-a/one-skill'],
+      }),
+    );
+    await write(
+      'plugins/departments/business/finance/close/plugin.bundle.json',
+      JSON.stringify({ name: 'close', version: '0.1.0', mcpProfile: 'empty', sourceSkillRoots: ['skills/departments/business/finance'] }),
+    );
+    await write('plugins/departments/engineering/shared/unnamed/plugin.bundle.json', JSON.stringify({ sourceSkillRoots: ['../escape', 'skills/x'] }));
+    // A bundle whose name is not its folder's, with no display name of its own.
+    await write('plugins/departments/business/finance/ledger-folder/plugin.bundle.json', JSON.stringify({ name: 'ledger' }));
+    await write('plugins/broken/plugin.bundle.json', '{ not json');
+  });
+  afterEach(async () => {
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
+    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().discover(kb);
+    const byName = new Map(plugins.map((p) => [p.name, p]));
+    expect([...byName.keys()].sort()).toEqual(['close', 'example-plugin', 'ledger', 'unnamed']);
+    // The shared contract: a declared display name, else the FOLDER — never the identity.
+    expect(byName.get('example-plugin')!.displayName).toBe('Example Plugin');
+    expect(byName.get('ledger')!.displayName).toBe('ledger-folder');
+
+    const example = byName.get('example-plugin')!;
+    expect(example.folder).toBe('plugins/functional/cluster-a/example-plugin');
+    expect(example.relFolder).toBe('functional/cluster-a/example-plugin');
+    expect(example.exists).toBe(true);
+    expect(example.linksAreManaged).toBe(false);
+    expect(example.linkedRoots).toEqual([
+      'skills/departments/engineering/shared/cluster-a',
+      'skills/functional/cluster-a/one-skill',
+    ]);
+    expect(example.manifest).toEqual({
+      name: 'example-plugin',
+      version: '1.3.1',
+      description: 'What this plugin is for',
+      displayName: 'Example Plugin',
+    });
+    // An unnamed bundle takes its folder's name; a bad root is dropped with a warning.
+    expect(byName.get('unnamed')!.linkedRoots).toEqual(['skills/x']);
+    expect(warnings.some((w) => w.includes('../escape'))).toBe(true);
+    expect(warnings.some((w) => w.includes('plugins/broken'))).toBe(true);
+  });
+
+  it('expands mcpProfile through the registry, following extends and reporting unknowns', async () => {
+    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const example = plugins.find((p) => p.name === 'example-plugin')!;
+    expect(example.mcpServers).toEqual({
+      confluence: { type: 'streamable-http', url: 'https://mcp.confluence.example' },
+      jira: { type: 'stdio', command: 'npx', args: ['-y', 'jira-mcp'], env: { JIRA_URL: 'https://j' } },
+    });
+    expect(JSON.parse(example.mcpJsonText!)).toEqual({ mcpServers: example.mcpServers });
+    expect(warnings.some((w) => w.includes('unknown server "ghost"'))).toBe(true);
+    // An empty profile is valid and selects nothing.
+    expect(plugins.find((p) => p.name === 'close')!.mcpServers).toBeNull();
+  });
+
+  it('skips a registry server that could not work, and the second of two declarations with one id', async () => {
+    await write(
+      'configs/mcp/registry.json',
+      JSON.stringify({
+        servers: [
+          { id: 'jira', config: { command: 'npx', args: ['-y', 'jira-mcp'] } },
+          { id: 'jira', config: { command: 'something-else' } },
+          { id: 'no-url', config: { type: 'http' } },
+          { id: 'blank-url', config: { url: '  ' } },
+          { id: 'odd', config: { type: 'grpc', url: 'https://x' } },
+          // A stray blank url beside a real command is still a stdio server.
+          { id: 'launch', config: { type: 'stdio', command: 'run-it', url: '' } },
+          { id: 'untyped-launch', config: { command: 'run-it', url: '' } },
+          // The client speaks no sse; shipping it would install a server nothing can use.
+          { id: 'events', config: { type: 'sse', url: 'https://events.example' } },
+          // A name that cannot be a server name (the secret namespace, the route slug).
+          { id: 'Bad Id', config: { command: 'x' } },
+        ],
+        profiles: [
+          { id: 'global', servers: ['jira', 'no-url', 'blank-url', 'odd', 'launch', 'untyped-launch', 'events', 'Bad Id'] },
+        ],
+      }),
+    );
+    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const example = plugins.find((p) => p.name === 'example-plugin')!;
+    expect(example.mcpServers).toEqual({
+      jira: { type: 'stdio', command: 'npx', args: ['-y', 'jira-mcp'] },
+      launch: { type: 'stdio', command: 'run-it', args: [] },
+      'untyped-launch': { type: 'stdio', command: 'run-it', args: [] },
+    });
+    expect(warnings.some((w) => w.includes('"jira" is declared twice'))).toBe(true);
+    // The reasons are the shared judgement's — the same words an mcp.json entry gets.
+    expect(warnings.some((w) => w.includes('"no-url" no url'))).toBe(true);
+    expect(warnings.some((w) => w.includes('"blank-url" has neither a url nor a command'))).toBe(true);
+    expect(warnings.some((w) => w.includes('"odd" unknown type "grpc"'))).toBe(true);
+    expect(warnings.some((w) => w.includes('"events" the MCP client has no `sse` transport'))).toBe(true);
+    expect(warnings.some((w) => w.includes('"Bad Id" the name is the secret namespace'))).toBe(true);
+  });
+
+  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().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);
+  });
+
+  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().discover(kb);
+    expect(plugins.find((p) => p.name === 'example-plugin')!.mcpServers).toBeNull();
+    expect(warnings.some((w) => w.includes('no registry'))).toBe(true);
+  });
+});
+
+describe('KbPluginSource — one walk, both shapes', () => {
+  let kb: string;
+  const write = async (rel: string, text: string) => {
+    const abs = path.join(kb, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+
+  beforeEach(async () => {
+    kb = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-mixed-'));
+  });
+  afterEach(async () => {
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
+    await fs.rm(kb, { recursive: true, force: true });
+  });
+
+  it('reads native manifests and bundles side by side, at any depth, and stops at a plugin folder', async () => {
+    // A native plugin directly under the root, with a skill inside — the
+    // skill folder must not be mistaken for a nested plugin.
+    await write('Plugins/GTM/plugin.json', JSON.stringify({ name: 'gtm', extensions: { 'software.bevel.hexis': { skills: ['Skills/Eng'] } } }));
+    await write('Plugins/GTM/access.md', '---\n---\nread:\n  - everyone\n');
+    await write('Plugins/GTM/skills/outreach/SKILL.md', '---\ndescription: x\n---\n');
+    await write('Plugins/GTM/skills/outreach/plugin.json', '{"name":"not-a-plugin"}');
+    // A pre-manifest folder (access.md only) directly under the root: NOT a
+    // plugin to discovery — the boot step gives it a manifest first.
+    await write('Plugins/Legacy/access.md', '---\n---\nread:\n  - everyone\n');
+    // A bundle three folders down, and a native manifest two folders down.
+    await write('Plugins/functional/cluster/example/plugin.bundle.json', JSON.stringify({ name: 'example', sourceSkillRoots: ['Skills/x'] }));
+    await write('Plugins/teams/deep/plugin.json', JSON.stringify({ name: 'deep' }));
+    // A folder with BOTH files: the manifest wins.
+    await write('Plugins/Both/plugin.json', JSON.stringify({ name: 'both' }));
+    await write('Plugins/Both/plugin.bundle.json', JSON.stringify({ name: 'both-bundle', sourceSkillRoots: ['Skills/y'] }));
+    // A deeper folder that is only a container: walked through, never a plugin.
+    await write('Plugins/teams/empty-container/README.md', 'nothing here');
+    // A level-one scope that carries an access.md of its own AND plugins
+    // beneath: a container, not a plugin.
+    await write('Plugins/functional/access.md', '---\n---\nread:\n  - everyone\n');
+
+    const { plugins, warnings } = await new KbPluginSource().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([
+      ['both', 'Plugins/Both', true, false],
+      ['example', 'Plugins/functional/cluster/example', false, true],
+      ['gtm', 'Plugins/GTM', true, true],
+      ['deep', 'Plugins/teams/deep', true, false],
+    ]);
+    expect(plugins.find((p) => p.name === 'gtm')?.linkedRoots).toEqual(['Skills/Eng']);
+    expect(plugins.find((p) => p.name === 'both')?.linkedRoots).toEqual([]);
+    expect(warnings).toEqual([]);
+  });
+
+  it('keeps the first of two plugins whose names fold to one slug, and says which was skipped', async () => {
+    await write('Plugins/a/GTM/plugin.json', '{}');
+    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().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',
+      'Plugins/c/gtm: plugin name "gtm" is already used by Plugins/a/GTM — plugin skipped',
+    ]);
+  });
+
+  it('the manifest name is the identity and the folder only the label — unless the name is no identifier', async () => {
+    await write('Plugins/GTM/plugin.json', JSON.stringify({ name: 'go-to-market', displayName: 'Go To Market' }));
+    await write('Plugins/Numeric/plugin.json', '{"name":42}');
+    // A name nested deeper than any stack would serialise: the warning must
+    // describe it, never try to print it.
+    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().discover(kb);
+    expect(plugins.map((p) => [p.name, p.displayName, p.folder])).toEqual([
+      ['go-to-market', 'Go To Market', 'Plugins/GTM'],
+      ['nested', 'Nested', 'Plugins/Nested'],
+      ['numeric', 'Numeric', 'Plugins/Numeric'],
+      ['ops', 'Ops', 'Plugins/Ops'],
+      ['plain', 'Plain', 'Plugins/Plain'],
+    ]);
+    // Every PRESENT name that is no identifier is said out loud — whatever its type.
+    expect(warnings).toEqual([
+      'Plugins/Nested/plugin.json names a value of type array, which is not a plugin identifier (lowercase kebab-case) — the folder stands in as "nested"',
+      'Plugins/Numeric/plugin.json names a value of type number, which is not a plugin identifier (lowercase kebab-case) — the folder stands in as "numeric"',
+      'Plugins/Ops/plugin.json names "Not An Identifier", which is not a plugin identifier (lowercase kebab-case) — the folder stands in as "ops"',
+    ]);
+  });
+
+  it('counts what exists but could not be read — a folder, a manifest — so a writer can tell a hole from an absence', async () => {
+    await write('Plugins/GTM/plugin.json', '{"name":"gtm"}');
+    // An optional file that cannot be read carries no identity: a warning, never a hole.
+    await write('Plugins/GTM/mcp.json', '{"mcpServers":{}}');
+    await write('Plugins/Hidden/plugin.json', '{"name":"hidden-identity"}');
+    await write('Plugins/teams/Deep/plugin.json', '{"name":"deep"}');
+    const realReaddir = fs.readdir;
+    const realReadFile = fs.readFile;
+    const eacces = () => Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }));
+    const spies = [
+      vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) =>
+        String(dir).endsWith('teams') ? eacces() : (realReaddir as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts)) as never),
+      vi.spyOn(fs, 'readFile').mockImplementation(((file: string, opts: unknown) =>
+        (String(file).includes('Hidden') && String(file).endsWith('plugin.json')) || String(file).endsWith('mcp.json')
+          ? eacces()
+          : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never),
+    ];
+    try {
+      const { plugins, warnings, unreadable } = await new KbPluginSource().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.
+      expect(unreadable).toEqual(['Plugins/Hidden/plugin.json', 'Plugins/teams']);
+      expect(plugins.map((p) => p.name)).toEqual(['gtm']);
+      expect(warnings.some((w) => w.startsWith('Plugins/Hidden/plugin.json could not be read'))).toBe(true);
+      expect(warnings.some((w) => w.startsWith('Plugins/teams: could not be read'))).toBe(true);
+      // The unreadable mcp.json is said, and GTM stands without it.
+      expect(warnings.some((w) => w.startsWith('Plugins/GTM/mcp.json could not be read'))).toBe(true);
+      expect(plugins[0]!.mcpServers).toBeNull();
+    } finally {
+      for (const s of spies) s.mockRestore();
+    }
+  });
+
+  it('a folder whose identity file could not be read is a hole that CLAIMS its subtree: nothing beneath surfaces as a plugin', async () => {
+    await write('Plugins/GTM/plugin.json', '{"name":"gtm"}');
+    await write('Plugins/Hidden/plugin.json', '{"name":"hidden"}');
+    // Beneath the hole: the walk still visits it (other listeners may need
+    // it), but to discovery it is inside a plugin folder — not a plugin.
+    await write('Plugins/Hidden/Sub/plugin.json', '{"name":"sub"}');
+    const realReadFile = fs.readFile;
+    const spy = vi.spyOn(fs, 'readFile').mockImplementation(((file: string, opts: unknown) =>
+      String(file).endsWith(path.join('Hidden', 'plugin.json'))
+        ? 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().discover(kb);
+      expect(unreadable).toEqual(['Plugins/Hidden/plugin.json']);
+      expect(plugins.map((p) => p.name)).toEqual(['gtm']);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('a manifest that vanishes between the probe and the read is no plugin — never one under a guessed name', async () => {
+    await write('Plugins/GTM/plugin.json', '{"name":"gtm"}');
+    await write('Plugins/Gone/plugin.json', '{"name":"gone"}');
+    const realReadFile = fs.readFile;
+    const spy = vi.spyOn(fs, 'readFile').mockImplementation(((file: string, opts: unknown) =>
+      String(file).endsWith(path.join('Gone', 'plugin.json'))
+        ? 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().discover(kb);
+      expect(plugins.map((p) => p.name)).toEqual(['gtm']);
+      expect(unreadable).toEqual([]);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('a knowledge base without a plugins root has no plugins and no complaint', async () => {
+    const { plugins, warnings, unreadable } = await new KbPluginSource().discover(kb);
+    expect(plugins).toEqual([]);
+    expect(warnings).toEqual([]);
+    expect(unreadable).toEqual([]);
+  });
+});

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

@@ -0,0 +1,140 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isPersonalPluginDir, normalizeSkillRoot, pluginManifestName } from '@bevel-software/platform-shared';
+import { isAbsence } from '../../../../shared/fs-errors.js';
+import type { DiscoveredPlugin } from '../plugin-source.js';
+import { expandProfile, parseRegistry, type McpRegistry } from './registry.js';
+
+/**
+ * THE DETACHABLE PART — a customer's plugin file format, read as-is:
+ *
+ *   <pluginsRoot>/<scope…>/<plugin>/plugin.bundle.json
+ *     {
+ *       "name": "example-plugin", "version": "1.3.1", "description": "…",
+ *       "mcpProfile": "global",
+ *       "interface": { "displayName": "Example Plugin", "category": "…" },
+ *       "sourceSkillRoots": [ "skills/departments/engineering/shared/<cluster>" ]
+ *     }
+ *
+ * A bundle is a LIST OF SKILL PATHS plus a pointer into an MCP registry —
+ * which is exactly the native model's "a plugin links skills" with different
+ * field names. So the reader maps:
+ *
+ *   sourceSkillRoots   → linkedRoots          (a root is a skill or a folder of skills)
+ *   mcpProfile         → mcpServers           (expanded through the registry)
+ *   name/version/desc  → a synthesised manifest
+ *   interface.displayName → the plugin's display name
+ *
+ * The walker (`kb-plugin-source.ts`) calls this for every folder holding a
+ * bundle file; this reads the file and decides nothing else. READ-ONLY by
+ * construction: nothing in this directory writes. A bundle's links are plain
+ * references (`linksAreManaged: false`): no principal grant is written or
+ * checked, the skills' own scopes decide readability.
+ *
+ * Deleting the dialect later = this directory, the one `else if` in the
+ * walker that calls it, and the walker's registry load.
+ */
+export const BUNDLE_FILE = 'plugin.bundle.json';
+export const DEFAULT_REGISTRY_PATH = 'configs/mcp/registry.json';
+
+/** The registry, when the repository has one; a missing file is null, a broken one warns. */
+export async function loadRegistry(kbRoot: string, warnings: string[]): Promise<McpRegistry | null> {
+  let text: string;
+  try {
+    text = await fs.readFile(path.join(kbRoot, DEFAULT_REGISTRY_PATH), 'utf-8');
+  } catch (err) {
+    // No registry is a valid state: bundles without a profile are still
+    // plugins. A registry that exists but cannot be read is not.
+    if (!isAbsence(err)) {
+      const code = (err as { code?: unknown } | null)?.code;
+      warnings.push(`${DEFAULT_REGISTRY_PATH} could not be read (${String(code ?? err)}) — every mcpProfile is unresolved`);
+    }
+    return null;
+  }
+  const registry = parseRegistry(text);
+  warnings.push(...registry.warnings);
+  return registry;
+}
+
+export async function readBundlePlugin(
+  dir: string,
+  folder: string,
+  relFolder: string,
+  registry: McpRegistry | null,
+  warnings: string[],
+  unreadable: string[],
+): 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
+  // refuse); a file that is not a bundle is a plugin that is not there.
+  let text: string;
+  try {
+    text = await fs.readFile(path.join(dir, BUNDLE_FILE), 'utf-8');
+  } catch (err) {
+    if (!isAbsence(err)) {
+      warnings.push(`${folder}/${BUNDLE_FILE} could not be read — ${err instanceof Error ? err.message : String(err)}`);
+      unreadable.push(`${folder}/${BUNDLE_FILE}`);
+    }
+    return null;
+  }
+  let bundle: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('not an object');
+    bundle = parsed as Record<string, unknown>;
+  } catch {
+    warnings.push(`${folder}/${BUNDLE_FILE} is not a JSON object — plugin skipped`);
+    return null;
+  }
+  const leaf = path.posix.basename(relFolder);
+  const name = typeof bundle.name === 'string' && bundle.name.trim() ? bundle.name.trim() : leaf;
+
+  const linkedRoots: string[] = [];
+  for (const raw of Array.isArray(bundle.sourceSkillRoots) ? bundle.sourceSkillRoots : []) {
+    const normalised = normalizeSkillRoot(typeof raw === 'string' ? raw : '');
+    if (normalised === null) {
+      warnings.push(`${folder}: sourceSkillRoots entry ${JSON.stringify(raw)} is not a folder path — ignored`);
+    } else if (!linkedRoots.includes(normalised)) {
+      linkedRoots.push(normalised);
+    }
+  }
+
+  let mcpServers: Record<string, unknown> | null = null;
+  if (typeof bundle.mcpProfile === 'string' && bundle.mcpProfile.trim()) {
+    if (!registry) {
+      warnings.push(`${folder}: mcpProfile "${bundle.mcpProfile}" named but no registry could be read`);
+    } else {
+      const expanded = expandProfile(registry, bundle.mcpProfile.trim());
+      warnings.push(...expanded.warnings.map((w) => `${folder}: ${w}`));
+      if (Object.keys(expanded.mcpServers).length > 0) mcpServers = expanded.mcpServers;
+    }
+  }
+
+  const ui =
+    typeof bundle.interface === 'object' && bundle.interface !== null
+      ? (bundle.interface as Record<string, unknown>)
+      : {};
+  const manifest: Record<string, unknown> = { name: pluginManifestName(name) };
+  if (typeof bundle.version === 'string') manifest.version = bundle.version;
+  if (typeof bundle.description === 'string') manifest.description = bundle.description;
+  if (typeof ui.displayName === 'string') manifest.displayName = ui.displayName;
+
+  return {
+    name,
+    // The shared contract (`DiscoveredPlugin.displayName`): the declared
+    // display name, else the FOLDER — never the identity.
+    displayName: typeof ui.displayName === 'string' && ui.displayName.trim() ? ui.displayName.trim() : leaf,
+    folder,
+    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),
+    exists: true,
+    manifest,
+    manifestText: null,
+    linkedRoots,
+    mcpServers,
+    mcpJsonText: mcpServers ? JSON.stringify({ mcpServers }) : null,
+    linksAreManaged: false,
+  };
+}