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

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

@@ -0,0 +1,365 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+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 { 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' }));
+    // A declared display name with padding around it — the one field of the
+    // presentation block that is also a name.
+    await write(
+      'plugins/functional/cluster-a/padded/plugin.bundle.json',
+      JSON.stringify({ name: 'padded', interface: { displayName: '  Padded Plugin  ', category: 'Ops' } }),
+    );
+    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(new NodeFs()).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
+    // FOLDER — which this foreign, read-only format keeps. It is resolved
+    // INTO the manifest the reader synthesizes, so the shared manifest-only
+    // reader says the same thing about a bundle that discovery does.
+    expect(byName.get('example-plugin')!.displayName).toBe('Example Plugin');
+    expect(byName.get('ledger')!.displayName).toBe('ledger-folder');
+    expect(pluginDisplayNameOf(byName.get('ledger')!.manifest)).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',
+      // The presentation block rides along whole, for the compiled Codex manifest.
+      interface: { displayName: 'Example Plugin', category: 'Productivity' },
+    });
+    // One answer, in both fields: the presentation block is carried whole,
+    // but the name inside it is the trimmed one the manifest and discovery
+    // report — the compile step fills that field only when it is blank, so a
+    // padded spelling left here would ship a Codex manifest calling the
+    // plugin something the catalog does not.
+    const padded = byName.get('padded')!;
+    expect(padded.displayName).toBe('Padded Plugin');
+    expect(padded.manifest).toMatchObject({
+      displayName: 'Padded Plugin',
+      interface: { displayName: 'Padded Plugin', category: 'Ops' },
+    });
+    expect(pluginDisplayNameOf(padded.manifest)).toBe('Padded 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(new NodeFs()).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);
+    // `Jira` and `Confluence` cannot be server names, so both run under their ids — and the author is told.
+    expect(warnings.filter((w) => w.includes('cannot be a server name'))).toHaveLength(2);
+    // 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(new NodeFs()).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(new NodeFs()).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(new NodeFs()).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(new NodeFs()).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(new NodeFs()).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('reads both names from the manifest and neither from the folder — the name standing in only when there is none', 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(new NodeFs()).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'],
+      // The three below name nothing usable at all — the shape the folder
+      // stands in as the IDENTITY for, out loud. What they are called follows
+      // that identity; the folder is never read for the label directly, which
+      // is why `Nested` shows as `nested`.
+      ['nested', 'nested', 'Plugins/Nested'],
+      ['numeric', 'numeric', 'Plugins/Numeric'],
+      // A name that is no identifier cannot BE the identity — the folder
+      // stands in for that too — but it is still what the manifest SAYS the
+      // plugin is called, so it is the display name.
+      ['ops', 'Not An Identifier', '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(new NodeFs()).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(new NodeFs()).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(new NodeFs()).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(new NodeFs()).discover(kb);
+    expect(plugins).toEqual([]);
+    expect(warnings).toEqual([]);
+    expect(unreadable).toEqual([]);
+  });
+});

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

@@ -0,0 +1,161 @@
+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.contract.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';
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** 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;
+    }
+  }
+
+  // A record, or nothing: a list where the block should be is not a block.
+  const ui = isRecord(bundle.interface) ? bundle.interface : {};
+  // The bundle's own rule for what it is called: `interface.displayName`,
+  // else the FOLDER — this dialect is a foreign repository's, read-only, and
+  // its folders are its presentation. The synthesized manifest carries the
+  // answer so the shared reader (`pluginDisplayNameOf`, manifest-only) tells
+  // anyone who asks the same thing this discovery reports.
+  const displayName = typeof ui.displayName === 'string' && ui.displayName.trim() ? ui.displayName.trim() : leaf;
+  // The presentation block is carried as written (below) — except for the
+  // one field that is also a name: the block gets the SAME answer the
+  // manifest does. The compile step fills `interface.displayName` only when
+  // it is blank, so a padded or blank spelling left here would ship a Codex
+  // manifest whose `interface` calls the plugin something the catalog and
+  // the API do not — the split answer this whole rule removes.
+  const carriedUi = typeof ui.displayName === 'string' ? { ...ui, displayName } : ui;
+  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;
+  manifest.displayName = displayName;
+  // What the bundle says about itself beyond the four fields above — who
+  // wrote it, what it is for, how a catalogue should present it — is carried
+  // as written, so the compiled plugin can say the same. Shapes are the
+  // vendor manifests' own (`author` an object or a string, `keywords` a list,
+  // `interface` the Codex presentation block); anything else is left where it is.
+  if (isRecord(bundle.author) || typeof bundle.author === 'string') manifest.author = bundle.author;
+  if (Array.isArray(bundle.keywords) && bundle.keywords.every((k) => typeof k === 'string')) manifest.keywords = bundle.keywords;
+  if (Object.keys(carriedUi).length > 0) manifest.interface = carriedUi;
+
+  return {
+    name,
+    displayName,
+    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,
+  };
+}