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

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

@@ -0,0 +1,248 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ISkillService, SkillSummary } from '../../skills/skills.contract.js';
+import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import type { IPluginIndexService, PluginCatalogEntry } from '../plugins.contract.js';
+import { createTeamsRoutes } from '../teams.routes.js';
+
+/**
+ * `GET /api/teams` — what each group can use, by id, sliced to what the
+ * caller already sees. The resolver is stubbed with two tables: what the
+ * CALLER reads and what each GROUP reads; the route's job is the join.
+ */
+
+const ALI = 'ali@bevel.software';
+
+const principals = (over: Partial<PluginCatalogEntry>): PluginCatalogEntry => ({
+  name: 'gtm',
+  displayName: 'GTM',
+  folders: ['Plugins/GTM'],
+  linkedRoots: [],
+  linksAreManaged: true,
+  skillCount: 0,
+  toolCount: 0,
+  brokenLinks: 0,
+  owners: { roles: [], users: [] },
+  writers: { roles: [], users: [] },
+  readers: { restricted: true, roles: [], users: [] },
+  isPrivate: false,
+  warnings: [],
+  ...over,
+});
+
+const CATALOG: PluginCatalogEntry[] = [
+  principals({}),
+  principals({ name: 'finance', displayName: 'Finance', folders: ['Plugins/Finance'] }),
+  principals({ name: 'personal-ali', displayName: "Ali's plugin", folders: ['Plugins/personal-ali'] }),
+];
+
+const SKILLS: SkillSummary[] = [
+  { name: 'outreach', description: '', path: 'Skills/Sales/outreach' },
+  { name: 'ledger', description: '', path: 'Skills/Finance/ledger' },
+  { name: 'weekly', description: '', path: 'Plugins/personal-ali/skills/weekly' },
+];
+
+const TOOLS: ToolManualSummary[] = [
+  { slug: 'hubspot', name: 'HubSpot', path: 'Plugins/GTM/mcp.json', type: 'mcp' } as ToolManualSummary,
+  { slug: 'books', name: 'Books', path: 'Plugins/Finance/books.tool', type: 'inline' } as ToolManualSummary,
+  { slug: 'gmail', name: 'Gmail', path: 'Plugins/personal-ali/mcp.json', type: 'mcp' } as ToolManualSummary,
+];
+
+interface HarnessOpts {
+  groups?: string[];
+  /** What the caller reads. */
+  caller?: string[];
+  /** What each group reads; a group absent here is "not a group" (null). */
+  team?: Record<string, string[]>;
+  /** What the org-wide `everyone` principal reads. */
+  everyone?: string[];
+  email?: string | null;
+}
+
+/** The org-wide entry every answer opens with — empty unless `everyone` says otherwise. */
+const NOTHING_ORG_WIDE = { name: 'Everyone', plugins: [], skills: [], tools: [] };
+
+const servers: Server[] = [];
+afterEach(async () => {
+  await Promise.all(servers.splice(0).map((s) => new Promise<void>((r) => s.close(() => r()))));
+});
+
+async function harness(opts: HarnessOpts = {}) {
+  const tableVerdict = (allowed: string[] | undefined, paths: string[]) =>
+    new Map(paths.map((p) => [p, (allowed ?? []).includes(p)]));
+  const accessControl = {
+    kbPrincipals: vi.fn(async () => ({ roles: [], groups: opts.groups ?? ['Sales Team'], plugins: [], people: [] })),
+    canReadBatch: vi.fn(async (_w: string, _email: string, paths: string[]) => tableVerdict(opts.caller, paths)),
+    canReadAsGroupBatch: vi.fn(async (_w: string, group: string, paths: string[]) =>
+      opts.team && group in opts.team ? tableVerdict(opts.team[group], paths) : null,
+    ),
+    canReadAsEveryoneBatch: vi.fn(async (_w: string, paths: string[]) => tableVerdict(opts.everyone, paths)),
+  } as unknown as IAccessControl;
+  const index = { catalog: async () => CATALOG, invalidate: () => undefined } as IPluginIndexService;
+  const skills = { listSkills: async () => SKILLS } as unknown as ISkillService;
+  const tools = { listAllSummaries: async () => TOOLS } as unknown as IToolManualService;
+
+  const email = opts.email === undefined ? ALI : opts.email;
+  const app = express();
+  app.use('/api', (req, _res, next) => {
+    if (email) req.userEmail = email;
+    next();
+  });
+  app.use('/api', createTeamsRoutes(accessControl, index, skills, tools));
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  servers.push(server);
+  const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  return { get: () => fetch(`${base}/api/teams`), accessControl };
+}
+
+describe('GET /api/teams', () => {
+  const EVERYTHING = [
+    'Plugins/GTM',
+    'Plugins/GTM/access.md',
+    'Plugins/Finance',
+    'Plugins/Finance/access.md',
+    'Skills/Sales/outreach/SKILL.md',
+    'Skills/Finance/ledger/SKILL.md',
+    'Plugins/personal-ali/skills/weekly/SKILL.md',
+    'Plugins/GTM/mcp.json',
+    'Plugins/Finance/books.tool',
+    'Plugins/personal-ali/mcp.json',
+  ];
+
+  it('names what the team reads, by id, and only what the caller sees too', async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: {
+        'Sales Team': ['Plugins/GTM', 'Skills/Sales/outreach/SKILL.md', 'Plugins/GTM/mcp.json'],
+        'Finance Team': ['Plugins/Finance', 'Skills/Finance/ledger/SKILL.md', 'Plugins/Finance/books.tool'],
+      },
+    });
+    const res = await h.get();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      teams: [
+        NOTHING_ORG_WIDE,
+        { name: 'Sales Team', plugins: ['gtm'], skills: ['outreach'], tools: ['hubspot'] },
+        { name: 'Finance Team', plugins: ['finance'], skills: ['ledger'], tools: ['books'] },
+      ],
+    });
+  });
+
+  it('opens with Everyone — what the org-wide principal reads, cut to what the caller sees, ahead of every group', async () => {
+    const h = await harness({
+      groups: ['Sales Team'],
+      caller: ['Plugins/GTM', 'Plugins/Finance/access.md', 'Skills/Sales/outreach/SKILL.md', 'Plugins/GTM/mcp.json'],
+      everyone: [
+        'Plugins/GTM',
+        'Plugins/Finance',
+        'Skills/Sales/outreach/SKILL.md',
+        'Skills/Finance/ledger/SKILL.md', // the caller cannot read it — withheld
+        'Plugins/GTM/mcp.json',
+      ],
+      team: { 'Sales Team': ['Plugins/GTM'] },
+    });
+    expect(await (await h.get()).json()).toEqual({
+      teams: [
+        // Finance is org-wide readable and the caller can discover it: listed, like any team's.
+        { name: 'Everyone', plugins: ['gtm', 'finance'], skills: ['outreach'], tools: ['hubspot'] },
+        { name: 'Sales Team', plugins: ['gtm'], skills: [], tools: [] },
+      ],
+    });
+  });
+
+  it('lists Everyone even when nothing is org-wide, and when there are no groups at all', async () => {
+    const h = await harness({ groups: [], caller: EVERYTHING });
+    expect(await (await h.get()).json()).toEqual({ teams: [NOTHING_ORG_WIDE] });
+  });
+
+  it('withholds what the caller cannot read, whatever the team can', async () => {
+    const h = await harness({
+      caller: ['Plugins/GTM', 'Skills/Sales/outreach/SKILL.md'],
+      team: {
+        'Sales Team': [
+          'Plugins/GTM',
+          'Plugins/Finance',
+          'Skills/Sales/outreach/SKILL.md',
+          'Skills/Finance/ledger/SKILL.md',
+          'Plugins/GTM/mcp.json',
+        ],
+      },
+    });
+    expect(await (await h.get()).json()).toEqual({
+      teams: [NOTHING_ORG_WIDE, { name: 'Sales Team', plugins: ['gtm'], skills: ['outreach'], tools: [] }],
+    });
+  });
+
+  it("lists a plugin the caller can only DISCOVER — it is on their index, locked", async () => {
+    const h = await harness({
+      caller: ['Plugins/Finance/access.md'],
+      team: { 'Sales Team': ['Plugins/Finance'] },
+    });
+    expect(await (await h.get()).json()).toEqual({
+      teams: [NOTHING_ORG_WIDE, { name: 'Sales Team', plugins: ['finance'], skills: [], tools: [] }],
+    });
+  });
+
+  it("never offers a personal plugin, or what lives in it, as a team's — whatever the resolver says", async () => {
+    // The stub grants EVERYTHING to the team, the personal skill and tool
+    // included (a hand-written grant inside a personal folder could): the
+    // route withholds them by where they live, not by the verdict. The same
+    // holds for the org-wide entry.
+    const h = await harness({
+      caller: EVERYTHING,
+      everyone: EVERYTHING,
+      team: { 'Sales Team': EVERYTHING },
+    });
+    const all = { plugins: ['gtm', 'finance'], skills: ['outreach', 'ledger'], tools: ['hubspot', 'books'] };
+    expect(await (await h.get()).json()).toEqual({
+      teams: [
+        { name: 'Everyone', ...all },
+        { name: 'Sales Team', ...all },
+      ],
+    });
+  });
+
+  it('skips a group the resolver no longer knows', async () => {
+    const h = await harness({ groups: ['Sales Team', 'Gone'], caller: EVERYTHING, team: { 'Sales Team': [] } });
+    expect(await (await h.get()).json()).toEqual({
+      teams: [NOTHING_ORG_WIDE, { name: 'Sales Team', plugins: [], skills: [], tools: [] }],
+    });
+  });
+
+  it('asks the resolver once for the caller, once for everyone and once per group, over one probe set', async () => {
+    const h = await harness({ groups: ['A', 'B'], caller: EVERYTHING, team: { A: [], B: [] } });
+    await h.get();
+    expect(h.accessControl.canReadBatch).toHaveBeenCalledTimes(1);
+    expect(h.accessControl.canReadAsEveryoneBatch).toHaveBeenCalledTimes(1);
+    expect(h.accessControl.canReadAsGroupBatch).toHaveBeenCalledTimes(2);
+    const [, , probes] = vi.mocked(h.accessControl.canReadBatch).mock.calls[0]!;
+    expect(vi.mocked(h.accessControl.canReadAsEveryoneBatch).mock.calls[0]![1]).toBe(probes);
+    // Personal folders are not probed at all — not as plugins, not for what
+    // they hold; everything else is, once: every plugin folder and its
+    // access.md, every skill's SKILL.md, every tool's file.
+    expect([...probes].sort()).toEqual(
+      [
+        'Plugins/GTM',
+        'Plugins/GTM/access.md',
+        'Plugins/GTM/mcp.json',
+        'Plugins/Finance',
+        'Plugins/Finance/access.md',
+        'Plugins/Finance/books.tool',
+        'Skills/Sales/outreach/SKILL.md',
+        'Skills/Finance/ledger/SKILL.md',
+      ].sort(),
+    );
+  });
+
+  it('is 401 without a caller', async () => {
+    const h = await harness({ email: null });
+    expect((await h.get()).status).toBe(401);
+  });
+});

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

@@ -1,13 +1,15 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
+  HEXIS_EXTENSION_NS,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
   PLUGIN_MANIFEST_SCHEMA,
   PLUGIN_MCP_SCHEMA,
   pluginManifestName,
 } from '@bevel-software/platform-shared';
-import { walkFiles } from '../../../shared/fs-walk.js';
+import { BUNDLE_FILE as BUNDLE_MANIFEST_FILE } from '../discovery/bundle-dialect/bundle.source.js';
+import type { ITreeWalker } from '../../../shared/fs.contract.js';
 import { containsVariableReference } from '../../../shared/variable-refs.js';
 import { judgeMcpServerEntry } from '../../tool-manuals/mcp-json-discovery.js';
 import type { SkillSummary } from '../../skills/skills.contract.js';
@@ -28,9 +30,11 @@ import type { DiscoveredPlugin } from '../discovery/plugin-source.js';
  *
  * What comes out, for one caller:
  *
- *   .claude-plugin/marketplace.json      Claude Code's catalogue
+ *   .claude-plugin/marketplace.json      Claude Code's catalogue (and Cowork's,
+ *                                        claude.ai's): every plugin below
  *   .agents/plugins/marketplace.json     Codex's catalogue, every entry
- *                                        INSTALLED_BY_DEFAULT
+ *                                        INSTALLED_BY_DEFAULT — without the
+ *                                        bundle, which would install it all twice
  *   plugins/<slug>/…                     one per plugin the caller may read
  *                                        anything of: inline + linked skills,
  *                                        the portable half of mcp.json
@@ -39,10 +43,12 @@ import type { DiscoveredPlugin } from '../discovery/plugin-source.js';
  *                                        only in plugins the caller cannot see,
  *                                        is still one install away — plus the
  *                                        knowledge base's own MCP endpoint
- *   plugins/hexis-all/…                  a bundle whose only content is a
- *                                        dependency on every plugin above —
- *                                        Claude Code installs them all from
- *                                        one `claude plugin install`
+ *   plugins/hexis-all/…                  the one-install bundle: a plugin of
+ *                                        its own holding every readable skill
+ *                                        once and the knowledge base's MCP
+ *                                        endpoint — content, not a dependency
+ *                                        list, because only Claude Code
+ *                                        resolves one
  *   skills/<name>/…                      every readable skill once, flat, for
  *                                        `npx skills add <url> --all`
  *   README.md                            names the source commit
@@ -85,6 +91,8 @@ export interface MarketplaceOptions {
 }
 
 export interface CompileInput {
+  /** The walk that lists a skill folder's files. */
+  disk: ITreeWalker;
   /** Absolute path of the KB checkout (the folder holding `Plugins/`, `Skills/`, …). */
   kbRoot: string;
   /** The released catalog, UNFILTERED — `readable` does the filtering. */
@@ -114,18 +122,16 @@ const RESERVED_SLUGS = new Set([BUNDLE_NAME, SKILLS_PLUGIN_NAME]);
 const NEVER_SHIPPED = new Set(['access.md', '.bevelignore']);
 
 export async function compileMarketplace(input: CompileInput): Promise<VirtualTree> {
-  const { kbRoot, skills, plugins, membership, readable, options } = input;
+  const { disk, kbRoot, skills, plugins, membership, readable, options } = input;
   const files = new Map<string, Buffer>();
   const warnings: string[] = [];
   const put = (rel: string, content: string | Buffer) =>
     files.set(rel, typeof content === 'string' ? Buffer.from(content, 'utf-8') : content);
 
-  // One verdict per skill, resolved once: every plugin below reads from it. A
-  // RETIRED skill (its governance lifecycle) stays in the catalog for its
-  // owners but never ships — retiring is how a skill leaves every agent.
+  // One verdict per skill, resolved once: every plugin below reads from it.
+  // Readability is the only gate — every skill the caller may read ships.
   const readableSkills = new Map<string, SkillSummary>();
   for (const s of skills) {
-    if (s.lifecycle === 'retired') continue;
     if (await readable(`${s.path}/SKILL.md`)) readableSkills.set(s.path, s);
   }
 
@@ -134,6 +140,11 @@ export async function compileMarketplace(input: CompileInput): Promise<VirtualTr
     displayName: string;
     description?: string;
     version?: string;
+    /** Who wrote it, as the source manifest says — an object or a string. */
+    author?: unknown;
+    keywords?: string[];
+    /** The presentation block a catalogue shows (Codex's `interface`), as the source manifest says. */
+    ui?: Record<string, unknown>;
     skills: SkillSummary[];
     /** Source folder (real plugins only). */
     folder?: string;
@@ -177,11 +188,18 @@ export async function compileMarketplace(input: CompileInput): Promise<VirtualTr
       warnings.push(`${plugin.folder}: manifest name "${slug}" is already taken in this marketplace — plugin skipped`);
       continue;
     }
+    const ui = isRecord(manifest?.interface) ? manifest.interface : undefined;
     out.push({
       slug,
       displayName: plugin.displayName,
       description: typeof manifest?.description === 'string' ? manifest.description : undefined,
       version: typeof manifest?.version === 'string' ? manifest.version : undefined,
+      author: isRecord(manifest?.author) || typeof manifest?.author === 'string' ? manifest.author : undefined,
+      keywords:
+        Array.isArray(manifest?.keywords) && manifest.keywords.every((k) => typeof k === 'string')
+          ? (manifest.keywords as string[])
+          : undefined,
+      ui,
       skills: dedup,
       folder: plugin.folder,
       mcp: mcp ?? undefined,
@@ -224,63 +242,95 @@ export async function compileMarketplace(input: CompileInput): Promise<VirtualTr
     }
   }
 
-  // 3. Materialise every plugin: the three manifests + copied skill folders.
+  // 3. Materialise every plugin: the plugin folder's own files, the copied
+  //    skill folders, then the three manifests — in that order, so what the
+  //    platform writes wins over a checked-in file of the same name.
   for (const p of out) {
     const base = `plugins/${p.slug}`;
+    // The folder's own files — a CONVENTIONS.md the skills refer to, a
+    // README, reference material — ship beside the skills. What does not:
+    // the platform's own files (rules, the source manifests, `mcp.json`, all
+    // rewritten below), the inline skills (copied by name below), and the
+    // hexis-only `.tool` manuals under their extension folder.
+    if (p.folder) await copyPluginFiles(disk, kbRoot, p.folder, base, put);
+    for (const s of p.skills) {
+      await copySkill(disk, kbRoot, s,`${base}/skills/${s.name}`, put);
+    }
     const spec: Record<string, unknown> = { $schema: PLUGIN_MANIFEST_SCHEMA, name: p.slug };
     if (p.version) spec.version = p.version;
     if (p.description) spec.description = p.description;
+    if (p.author !== undefined) spec.author = p.author;
+    if (p.keywords) spec.keywords = p.keywords;
     put(`${base}/${PLUGIN_MANIFEST_FILE}`, `${JSON.stringify(spec, null, 2)}\n`);
     const vendor: Record<string, unknown> = { name: p.slug };
     if (p.version) vendor.version = p.version;
     vendor.description = p.description ?? p.displayName;
+    if (p.author !== undefined) vendor.author = p.author;
+    if (p.keywords) vendor.keywords = p.keywords;
     put(`${base}/.claude-plugin/plugin.json`, `${JSON.stringify(vendor, null, 2)}\n`);
-    put(`${base}/.codex-plugin/plugin.json`, `${JSON.stringify(vendor, null, 2)}\n`);
+    // Codex's manifest carries the presentation block: the source's own,
+    // completed with the one thing every plugin can say about itself when
+    // the block does not say it — a partial block is a block, not a reason
+    // to lose the name.
+    const ui: Record<string, unknown> = { ...(p.ui ?? {}) };
+    if (typeof ui.displayName !== 'string' || !ui.displayName.trim()) ui.displayName = p.displayName;
+    const codex: Record<string, unknown> = { ...vendor, interface: ui };
+    put(`${base}/.codex-plugin/plugin.json`, `${JSON.stringify(codex, null, 2)}\n`);
     if (p.mcp) {
       put(`${base}/${PLUGIN_MCP_FILE}`, `${JSON.stringify({ $schema: PLUGIN_MCP_SCHEMA, mcpServers: p.mcp }, null, 2)}\n`);
       put(`${base}/.mcp.json`, `${JSON.stringify({ mcpServers: p.mcp }, null, 2)}\n`);
     }
-    for (const s of p.skills) {
-      await copySkill(kbRoot, s, `${base}/skills/${s.name}`, put);
-    }
   }
 
-  // 4. The one-install bundle: a Claude manifest with nothing but dependencies.
+  // 4. Every readable skill once, by name — ONE set, carried twice: the flat
+  //    root skills/ folder, and the one-install bundle below.
+  const flat = dedupeByName(
+    [...readableSkills.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    (s, other) =>
+      warnings.push(`"${s.name}" at ${s.path} shares its name with ${other.path} — left out of skills/ and the bundle`),
+  );
+  for (const s of flat) await copySkill(disk, kbRoot, s,`skills/${s.name}`, put);
+
+  // 5. The one-install bundle: a plugin of its own that IS everything the
+  //    caller may read — every skill once, plus the knowledge base's MCP
+  //    endpoint — not a manifest naming the plugins above as dependencies.
+  //    Only Claude Code resolves a dependency list; Cowork and claude.ai
+  //    install a plugin's content and nothing more, so for one install to
+  //    mean the same thing on every surface, the content has to be there.
+  //    Its version is the source commit, so an auto-update sees every change.
   const bundle = pluginManifestName(options.bundleName ?? BUNDLE_NAME);
-  const slugs = out.map((p) => p.slug);
-  if (slugs.includes(bundle)) {
+  const bundleTaken = out.some((p) => p.slug === bundle);
+  if (bundleTaken) {
     // Only reachable with a non-default bundle name that folds to a real
     // plugin's slug: the default is reserved above. Skipping the bundle
-    // beats overwriting that plugin's manifests with a dependency list.
+    // beats overwriting that plugin's tree with everything.
     warnings.push(`the bundle name "${bundle}" collides with a plugin's manifest name — no bundle plugin emitted`);
   }
-  if (slugs.length > 0 && !slugs.includes(bundle)) {
+  const bundleEmitted = !bundleTaken && (flat.length > 0 || kbMcp !== undefined);
+  if (bundleEmitted) {
+    const base = `plugins/${bundle}`;
     const shortSha = options.sourceCommit.slice(0, 12) || '0';
-    const description = `Everything in ${options.owner}'s marketplace you may read — one install.`;
+    const description = `Everything in ${options.owner}'s marketplace you may read, in one install.`;
     put(
-      `plugins/${bundle}/.claude-plugin/plugin.json`,
-      `${JSON.stringify({ name: bundle, version: `0.0.0-${shortSha}`, description, dependencies: slugs }, null, 2)}\n`,
+      `${base}/.claude-plugin/plugin.json`,
+      `${JSON.stringify({ name: bundle, version: `0.0.0-${shortSha}`, description }, null, 2)}\n`,
     );
     put(
-      `plugins/${bundle}/${PLUGIN_MANIFEST_FILE}`,
+      `${base}/${PLUGIN_MANIFEST_FILE}`,
       `${JSON.stringify({ $schema: PLUGIN_MANIFEST_SCHEMA, name: bundle, description }, null, 2)}\n`,
     );
-    put(
-      `plugins/${bundle}/.codex-plugin/plugin.json`,
-      `${JSON.stringify({ name: bundle, description }, null, 2)}\n`,
-    );
+    if (kbMcp) {
+      put(`${base}/${PLUGIN_MCP_FILE}`, `${JSON.stringify({ $schema: PLUGIN_MCP_SCHEMA, mcpServers: kbMcp }, null, 2)}\n`);
+      put(`${base}/.mcp.json`, `${JSON.stringify({ mcpServers: kbMcp }, null, 2)}\n`);
+    }
+    for (const s of flat) await copySkill(disk, kbRoot, s,`${base}/skills/${s.name}`, put);
   }
 
-  // 5. The flat root skills/ folder, every readable skill once.
-  const flat = dedupeByName(
-    [...readableSkills.values()].sort((a, b) => a.path.localeCompare(b.path)),
-    (s, other) => warnings.push(`skills/: "${s.name}" at ${s.path} shares its name with ${other.path} — left out`),
-  );
-  for (const s of flat) await copySkill(kbRoot, s, `skills/${s.name}`, put);
-
-  // 6. The two catalogues + a README naming the source.
-  const bundleEmitted = slugs.length > 0 && !slugs.includes(bundle);
-  const entries = [...out.map((p) => ({ slug: p.slug, description: p.description ?? p.displayName })), ...(bundleEmitted ? [{ slug: bundle, description: 'Everything you may read, one install' }] : [])];
+  // 6. The two catalogues + a README naming the source. The bundle is listed
+  //    for Claude's surfaces only: Codex installs every catalogue entry on
+  //    add, and the bundle repeats what the other entries already carry.
+  const entries = out.map((p) => ({ slug: p.slug, description: p.description ?? p.displayName }));
+  const claudeEntries = [...entries, ...(bundleEmitted ? [{ slug: bundle, description: 'Everything you may read, one install' }] : [])];
   put(
     '.claude-plugin/marketplace.json',
     `${JSON.stringify(
@@ -288,7 +338,7 @@ export async function compileMarketplace(input: CompileInput): Promise<VirtualTr
         name: options.name,
         owner: { name: options.owner },
         ...(options.description ? { description: options.description } : {}),
-        plugins: entries.map((e) => ({ name: e.slug, source: `./plugins/${e.slug}`, description: e.description })),
+        plugins: claudeEntries.map((e) => ({ name: e.slug, source: `./plugins/${e.slug}`, description: e.description })),
       },
       null,
       2,
@@ -318,25 +368,56 @@ export async function compileMarketplace(input: CompileInput): Promise<VirtualTr
       `Compiled from ${options.owner}'s knowledge base at commit \`${options.sourceCommit}\`.`,
       'This tree is generated: edit the knowledge base, not these files.',
       '',
-      `Plugins: ${entries.map((e) => e.slug).join(', ') || 'none'}.`,
+      `Plugins: ${claudeEntries.map((e) => e.slug).join(', ') || 'none'}.`,
       '',
     ].join('\n'),
   );
 
-  return { files, warnings, plugins: entries.map((e) => e.slug) };
+  return { files, warnings, plugins: claudeEntries.map((e) => e.slug) };
 }
 
 // --- helpers ------------------------------------------------------------------
 
+/** The files of a plugin's own folder that are the platform's or another step's to write, never copied as they are. */
+const REWRITTEN_AT_ROOT = new Set([PLUGIN_MANIFEST_FILE, BUNDLE_MANIFEST_FILE, PLUGIN_MCP_FILE]);
+
+/**
+ * Copy a plugin folder's own files under `dest`: everything except the
+ * platform's files (rules, the manifests and `mcp.json` at the root — all
+ * rewritten by the compiler), the inline skills under `skills/` (copied by
+ * name, so a clash resolves the same way everywhere), the hexis extension
+ * folder (`.tool` manuals no other client runs) and `.tool` files anywhere.
+ */
+async function copyPluginFiles(
+  disk: ITreeWalker,
+  kbRoot: string,
+  folder: string,
+  dest: string,
+  put: (rel: string, content: Buffer) => void,
+): Promise<void> {
+  const abs = path.join(kbRoot, folder);
+  for (const rel of await disk.walkFiles(abs, (name) => !NEVER_SHIPPED.has(name) && !name.endsWith('.tool'))) {
+    const top = rel.split('/')[0];
+    if (top === 'skills' || top === HEXIS_EXTENSION_NS) continue;
+    if (!rel.includes('/') && REWRITTEN_AT_ROOT.has(rel)) continue;
+    put(`${dest}/${rel}`, await fs.readFile(path.join(abs, rel)));
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
 /** Copy a skill folder (minus what never ships) under `dest`. */
 async function copySkill(
+  disk: ITreeWalker,
   kbRoot: string,
   skill: SkillSummary,
   dest: string,
   put: (rel: string, content: Buffer) => void,
 ): Promise<void> {
   const abs = path.join(kbRoot, skill.path);
-  for (const rel of await walkFiles(abs, (name) => !NEVER_SHIPPED.has(name))) {
+  for (const rel of await disk.walkFiles(abs, (name) => !NEVER_SHIPPED.has(name))) {
     put(`${dest}/${rel}`, await fs.readFile(path.join(abs, rel)));
   }
 }
@@ -381,8 +462,21 @@ function portableMcp(
       leftOut(name, verdict.reason);
       continue;
     }
+    // Fields the judgement does not read (`startup_timeout_sec`, say) ride
+    // along as declared — a client that knows one uses it, one that does
+    // not ignores it — unless they hold a vault reference, which no client
+    // can expand.
+    // Built without a prototype, so a field spelled `__proto__` is a field
+    // that survives to the serialised entry, not a prototype assignment.
+    const extras: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    if (isRecord(raw)) {
+      for (const [key, value] of Object.entries(raw)) {
+        if (JUDGED_KEYS.has(key) || containsVariableReference(JSON.stringify(value))) continue;
+        extras[key] = value;
+      }
+    }
     if (verdict.transport === 'stdio') {
-      out[name] = { ...verdict.entry };
+      out[name] = { ...verdict.entry, ...extras };
       continue;
     }
     const entry: Record<string, unknown> = { type: verdict.entry.type, url: verdict.entry.url };
@@ -397,7 +491,10 @@ function portableMcp(
       }
       if (Object.keys(headers).length > 0) entry.headers = headers;
     }
-    out[name] = entry;
+    out[name] = { ...entry, ...extras };
   }
   return Object.keys(out).length > 0 ? out : null;
 }
+
+/** The server fields the judgement reads and normalises; every other field passes through. */
+const JUDGED_KEYS = new Set(['type', 'url', 'command', 'args', 'env', 'cwd', 'headers']);

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

@@ -1,6 +1,4 @@
 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';
@@ -8,11 +6,10 @@ 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 type { ITreeWalker } from '../../../shared/fs.contract.js';
+import type { IGitRunner } from '../../../shared/git.contract.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 };
 
@@ -42,7 +39,10 @@ export class MarketplaceCompilerService {
       /** The hosted MCP endpoint to ship in the skills plugin (URL only). */
       knowledgeBaseMcp?: { name: string; url: string };
     },
-    private readonly source: PluginSource = new KbPluginSource(),
+    private readonly source: PluginSource,
+    private readonly disk: ITreeWalker,
+    /** How git is run — see `shared/git.contract.ts`. */
+    private readonly gitRunner: IGitRunner,
   ) {}
 
   /**
@@ -53,7 +53,7 @@ export class MarketplaceCompilerService {
    */
   async sourceCommit(): Promise<string> {
     const { kbRoot } = await this.checkout();
-    const { stdout } = await execFileAsync('git', ['-C', kbRoot, 'rev-parse', 'HEAD']);
+    const { stdout } = await this.gitRunner.run(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)) {
@@ -91,6 +91,7 @@ export class MarketplaceCompilerService {
     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({
+      disk: this.disk,
       kbRoot,
       skills,
       plugins,