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

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

@@ -53,6 +53,8 @@ interface HarnessOpts {
   email?: string | null;
   skills?: SkillSummary[];
   tools?: ToolManualSummary[];
+  /** More plugins: folder path below `Plugins/` → manifest name. */
+  extraPlugins?: Record<string, string>;
 }
 
 function cr(over: Partial<ChangeRequest>): ChangeRequest {
@@ -75,17 +77,21 @@ async function makeHarness(opts: HarnessOpts = {}) {
   const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-plugins-routes-'));
   tmpDirs.push(workspaceDir);
   const kbRoot = path.join(workspaceDir, KB);
-  // Both carry the access.md that makes a folder a plugin at all.
-  await fs.mkdir(path.join(kbRoot, 'Plugins', 'GTM'), { recursive: true });
-  await fs.writeFile(
-    path.join(kbRoot, 'Plugins', 'GTM', 'access.md'),
-    '---\nread:\n  - everyone\n---\nread: []\n',
-  );
-  await fs.mkdir(path.join(kbRoot, 'Plugins', 'Finance'), { recursive: true });
-  await fs.writeFile(
-    path.join(kbRoot, 'Plugins', 'Finance', 'access.md'),
-    '---\nread:\n  - everyone\n---\nread: []\n',
-  );
+  // Both carry the manifest that makes a folder a plugin to discovery, and
+  // the access.md that makes it exist to the index.
+  const fixtures: [string, string][] = [
+    ['GTM', 'gtm'],
+    ['Finance', 'finance'],
+    ...Object.entries(opts.extraPlugins ?? {}),
+  ];
+  for (const [folder, name] of fixtures) {
+    await fs.mkdir(path.join(kbRoot, 'Plugins', folder), { recursive: true });
+    await fs.writeFile(path.join(kbRoot, 'Plugins', folder, 'plugin.json'), `{"name":"${name}"}`);
+    await fs.writeFile(
+      path.join(kbRoot, 'Plugins', folder, 'access.md'),
+      '---\nread:\n  - everyone\n---\nread: []\n',
+    );
+  }
 
   const workspaceService = {
     getOrCreateForBranch: async (branch: string) => ({ id: workspaceIdForBranch(branch) }),
@@ -233,11 +239,35 @@ describe('/api/plugins routes', () => {
     server = h.server;
     const { status, plugins } = await listPlugins(h.baseUrl);
     expect(status).toBe(200);
-    expect(plugins.map((g) => g.name)).toEqual(['Finance', 'GTM']);
+    // Named by identity (the manifest), labelled by folder.
+    expect(plugins.map((g) => [g.name, g.displayName])).toEqual([['finance', 'Finance'], ['gtm', 'GTM']]);
     expect(plugins[0]).toMatchObject({ canRead: true, skillCount: 0, toolCount: 1 });
     expect(plugins[1]).toMatchObject({ canRead: true, skillCount: 1, toolCount: 0 });
   });
 
+  it("carries the index's broken-link count into the summary — the server's, not the caller's slice", async () => {
+    const entry = {
+      name: 'gtm',
+      displayName: 'GTM',
+      folders: ['Plugins/GTM'],
+      linksAreManaged: true,
+      skillCount: 2,
+      toolCount: 0,
+      brokenLinks: 2,
+      owners: { roles: [], users: [] },
+      writers: { roles: [], users: [] },
+      readers: { restricted: true, roles: [], users: [] },
+    };
+    const h = await makeHarness({
+      readable: MEMBER_OF_BOTH,
+      index: { catalog: async () => [entry], invalidate: () => {} } as unknown as IPluginIndexService,
+    });
+    server = h.server;
+    const { plugins } = await listPlugins(h.baseUrl);
+    expect(plugins).toHaveLength(1);
+    expect(plugins[0]).toMatchObject({ name: 'gtm', brokenLinks: 2 });
+  });
+
   it('a DISCOVERABLE plugin (access.md readable, folder not) lists locked with hasRequested from the join CR', async () => {
     const h = await makeHarness({
       readable: { [ALI]: ['Plugins/Finance/access.md'] },
@@ -245,7 +275,7 @@ describe('/api/plugins routes', () => {
     });
     server = h.server;
     const { plugins } = await listPlugins(h.baseUrl);
-    expect(plugins.map((g) => g.name)).toEqual(['Finance']);
+    expect(plugins.map((g) => g.name)).toEqual(['finance']);
     expect(plugins[0]).toMatchObject({
       canRead: false,
       canWrite: false,
@@ -258,8 +288,9 @@ describe('/api/plugins routes', () => {
     const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
     server = h.server;
     const { plugins, raw } = await listPlugins(h.baseUrl);
-    expect(plugins.map((g) => g.name)).toEqual(['Finance']);
-    expect(raw).not.toContain('"name":"GTM"');
+    expect(plugins.map((g) => g.name)).toEqual(['finance']);
+    expect(raw).not.toContain('"name":"gtm"');
+    expect(raw).not.toContain('"GTM"');
     expect(raw).not.toContain('Plugins/GTM');
   });
 
@@ -267,7 +298,7 @@ describe('/api/plugins routes', () => {
     const h = await makeHarness({ writable: { [ALI]: ['Plugins/GTM/access.md'] } });
     server = h.server;
     const { plugins } = await listPlugins(h.baseUrl);
-    expect(plugins.map((g) => g.name)).toEqual(['GTM']);
+    expect(plugins.map((g) => g.name)).toEqual(['gtm']);
     expect(plugins[0]).toMatchObject({ canRead: false, canWrite: true });
   });
 
@@ -278,7 +309,7 @@ describe('/api/plugins routes', () => {
     });
     server = h.server;
     const { plugins } = await listPlugins(h.baseUrl);
-    expect(plugins[0]).toMatchObject({ name: 'GTM', canRead: true, hasRequested: false });
+    expect(plugins[0]).toMatchObject({ name: 'gtm', canRead: true, hasRequested: false });
   });
 
   it('lists the owner verdict per caller — the folder verdict, not the manager one', async () => {
@@ -288,8 +319,8 @@ describe('/api/plugins routes', () => {
     });
     server = h.server;
     const { plugins } = await listPlugins(h.baseUrl);
-    expect(plugins.find((g) => g.name === 'GTM')).toMatchObject({ isOwner: true });
-    expect(plugins.find((g) => g.name === 'Finance')).toMatchObject({ isOwner: false });
+    expect(plugins.find((g) => g.name === 'gtm')).toMatchObject({ isOwner: true });
+    expect(plugins.find((g) => g.name === 'finance')).toMatchObject({ isOwner: false });
   });
 
   it('delete: 404 for unknown AND for a non-owner — a manager included (identical, fail-closed)', async () => {
@@ -301,7 +332,7 @@ describe('/api/plugins routes', () => {
       writable: { [ALI]: ['Plugins/GTM/access.md'] },
     });
     server = h.server;
-    for (const name of ['Nope', 'GTM']) {
+    for (const name of ['Nope', 'gtm']) {
       const res = await fetch(`${h.baseUrl}/api/plugins/${name}`, { method: 'DELETE' });
       expect(res.status, name).toBe(404);
       expect(await res.json()).toEqual({ error: 'Unknown plugin', kind: 'unknown-plugin' });
@@ -309,12 +340,13 @@ describe('/api/plugins routes', () => {
     expect(h.provision.deletePlugin).not.toHaveBeenCalled();
   });
 
-  it('delete: an OWNER deletes through the provision door, by the catalog name', async () => {
+  it('delete: an OWNER deletes through the provision door — found by identity, deleted by folder', async () => {
     const h = await makeHarness({ owner: { [ALI]: ['Plugins/GTM'] } });
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/GTM`, { method: 'DELETE' });
+    const res = await fetch(`${h.baseUrl}/api/plugins/gtm`, { method: 'DELETE' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true });
+    // Provisioning owns folders, so it is handed the folder, not the name.
     expect(h.provision.deletePlugin).toHaveBeenCalledWith(
       expect.objectContaining({ email: ALI }),
       'GTM',
@@ -326,7 +358,7 @@ describe('/api/plugins routes', () => {
     const { PluginProvisionError } = await import('../plugin-provision.service.js');
     h.provision.deletePlugin.mockRejectedValueOnce(new PluginProvisionError('Unknown plugin', 404));
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/GTM`, { method: 'DELETE' });
+    const res = await fetch(`${h.baseUrl}/api/plugins/gtm`, { method: 'DELETE' });
     expect(res.status).toBe(404);
     expect(await res.json()).toEqual({ error: 'Unknown plugin' });
   });
@@ -336,7 +368,7 @@ describe('/api/plugins routes', () => {
     const h = await makeHarness({ owner: { [ALI]: ['Plugins/GTM'] } });
     h.provision.deletePlugin.mockRejectedValueOnce(new Error('push refused'));
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/GTM`, { method: 'DELETE' });
+    const res = await fetch(`${h.baseUrl}/api/plugins/gtm`, { method: 'DELETE' });
     expect(res.status).toBe(500);
     expect(await res.json()).toEqual({ error: 'Failed to delete the plugin' });
     error.mockRestore();
@@ -345,7 +377,7 @@ describe('/api/plugins routes', () => {
   it('join-request: 404 for unknown AND for undiscoverable (identical, fail-closed)', async () => {
     const h = await makeHarness({});
     server = h.server;
-    for (const name of ['Nope', 'GTM']) {
+    for (const name of ['Nope', 'gtm']) {
       const res = await fetch(`${h.baseUrl}/api/plugins/${name}/join-request`, { method: 'POST' });
       expect(res.status, name).toBe(404);
       expect(await res.json()).toEqual({ error: 'Unknown plugin', kind: 'unknown-plugin' });
@@ -355,7 +387,7 @@ describe('/api/plugins routes', () => {
   it('join-request: 409 when the caller can already read the folder', async () => {
     const h = await makeHarness({ readable: MEMBER_OF_BOTH });
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/Finance/join-request`, { method: 'POST' });
+    const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
     expect(res.status).toBe(409);
     expect((await res.json()).kind).toBe('already-readable');
   });
@@ -363,10 +395,12 @@ describe('/api/plugins routes', () => {
   it('join-request: branch + splice + commit + CR, on the deterministic join branch', async () => {
     const h = await makeHarness({ readable: { [ALI]: ['Plugins/Finance/access.md'] } });
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/Finance/join-request`, { method: 'POST' });
+    const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true, number: 42 });
 
+    // The branch is cut from the FOLDER name, as every join branch before the
+    // manifest became the identity was — so none of them is orphaned.
     const branch = joinBranchFor(ALI, 'Finance');
     expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, branch, DEFAULT_BRANCH);
     // The write went to the plugin's access.md and added the caller to the
@@ -389,13 +423,26 @@ describe('/api/plugins routes', () => {
     );
   });
 
+  it('keys a join request by the folder PATH below the root — two folders sharing a basename never share a branch', async () => {
+    const h = await makeHarness({
+      extraPlugins: { 'teams/GTM': 'team-gtm' },
+      readable: { [ALI]: ['Plugins/teams/GTM/access.md'] },
+    });
+    server = h.server;
+    const res = await fetch(`${h.baseUrl}/api/plugins/team-gtm/join-request`, { method: 'POST' });
+    expect(res.status).toBe(200);
+    const branch = joinBranchFor(ALI, 'teams/GTM');
+    expect(branch).not.toBe(joinBranchFor(ALI, 'GTM'));
+    expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, branch, DEFAULT_BRANCH);
+  });
+
   it('join-request is idempotent: an existing open join CR is returned, nothing new is created', async () => {
     const h = await makeHarness({
       readable: { [ALI]: ['Plugins/Finance/access.md'] },
       authoredCrs: [cr({ branch: joinBranchFor(ALI, 'Finance'), number: 9 })],
     });
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/Finance/join-request`, { method: 'POST' });
+    const res = await fetch(`${h.baseUrl}/api/plugins/finance/join-request`, { method: 'POST' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true, number: 9 });
     expect(h.workflow.createBranch).not.toHaveBeenCalled();
@@ -418,7 +465,7 @@ describe('/api/plugins routes', () => {
   it('join-requests: a MANAGER gets the service\'s list for the plugin', async () => {
     const h = await makeHarness({ writable: { [ALI]: ['Plugins/GTM/access.md'] } });
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/GTM/join-requests`);
+    const res = await fetch(`${h.baseUrl}/api/plugins/gtm/join-requests`);
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ requests: [] });
     expect(h.joinRequests.list).toHaveBeenCalledWith(
@@ -434,7 +481,7 @@ describe('/api/plugins routes', () => {
     // question only the server answers.
     const h = await makeHarness({ readable: MEMBER_OF_BOTH });
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/GTM/join-requests`);
+    const res = await fetch(`${h.baseUrl}/api/plugins/gtm/join-requests`);
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ requests: [] });
     expect(h.joinRequests.list).not.toHaveBeenCalled();
@@ -443,7 +490,7 @@ describe('/api/plugins routes', () => {
   it('reconcile: 404 for a non-manager — indistinguishable from a missing request', async () => {
     const h = await makeHarness({ readable: MEMBER_OF_BOTH, authoredCrs: [cr({ number: 7 })] });
     server = h.server;
-    const denied = await fetch(`${h.baseUrl}/api/plugins/GTM/join-requests/7/reconcile`, {
+    const denied = await fetch(`${h.baseUrl}/api/plugins/gtm/join-requests/7/reconcile`, {
       method: 'POST',
     });
     expect(denied.status).toBe(404);
@@ -453,7 +500,7 @@ describe('/api/plugins routes', () => {
   it('reconcile: 404 for a manager when the change request does not exist', async () => {
     const h = await makeHarness({ writable: { [ALI]: ['Plugins/GTM/access.md'] } });
     server = h.server;
-    const missing = await fetch(`${h.baseUrl}/api/plugins/GTM/join-requests/999/reconcile`, {
+    const missing = await fetch(`${h.baseUrl}/api/plugins/gtm/join-requests/999/reconcile`, {
       method: 'POST',
     });
     expect(missing.status).toBe(404);
@@ -467,7 +514,7 @@ describe('/api/plugins routes', () => {
     });
     (h.joinRequests.reconcile as ReturnType<typeof vi.fn>).mockResolvedValue(true);
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/plugins/GTM/join-requests/7/reconcile`, {
+    const res = await fetch(`${h.baseUrl}/api/plugins/gtm/join-requests/7/reconcile`, {
       method: 'POST',
     });
     expect(res.status).toBe(200);

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

@@ -0,0 +1,403 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  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 { containsVariableReference } from '../../../shared/variable-refs.js';
+import { judgeMcpServerEntry } from '../../tool-manuals/mcp-json-discovery.js';
+import type { SkillSummary } from '../../skills/skills.contract.js';
+import type { LinkMembership } from '../plugin-links.js';
+import type { DiscoveredPlugin } from '../discovery/plugin-source.js';
+
+/**
+ * The compiler: SOURCE layout in, DISTRIBUTION layout out.
+ *
+ * Source is what lives in the knowledge base — shared skills under
+ * `Skills/`, plugin folders under `Plugins/` whose manifests LINK to them.
+ * Distribution is what an agent installs: a marketplace of self-contained
+ * plugins, each physically holding its skills (Claude Code refuses paths
+ * that escape a plugin's directory, and symlinks are out), in the vendor
+ * layouts the clients read today — `.claude-plugin/plugin.json`,
+ * `.codex-plugin/plugin.json`, `.mcp.json` — beside the Agent Plugins
+ * `plugin.json` and `mcp.json`.
+ *
+ * What comes out, for one caller:
+ *
+ *   .claude-plugin/marketplace.json      Claude Code's catalogue
+ *   .agents/plugins/marketplace.json     Codex's catalogue, every entry
+ *                                        INSTALLED_BY_DEFAULT
+ *   plugins/<slug>/…                     one per plugin the caller may read
+ *                                        anything of: inline + linked skills,
+ *                                        the portable half of mcp.json
+ *   plugins/skills-and-knowledge/…       every readable skill no plugin above
+ *                                        ships — how a standalone skill, or one
+ *                                        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`
+ *   skills/<name>/…                      every readable skill once, flat, for
+ *                                        `npx skills add <url> --all`
+ *   README.md                            names the source commit
+ *
+ * FAIL CLOSED, per file: a skill is copied only when `readable` says yes for
+ * its SKILL.md — the same per-path verdict the catalog filters on — so the
+ * compiled tree for a caller holds exactly what that caller may read, and
+ * nothing about a skill they may not. Plugins with nothing readable are
+ * left out entirely. `access.md` and `.bevelignore` never ship; neither do
+ * the hexis-only `.tool` manuals (no other client can run them), nor an
+ * `mcp.json` header carrying a `${VAR}` vault reference (the extension block
+ * that resolves it is ours, and a header a client would send verbatim must
+ * not name a secret it cannot expand).
+ *
+ * A pure function of its inputs — it reads the KB tree it is pointed at and
+ * returns a virtual tree; writing it somewhere (a git namespace, a folder, a
+ * remote) is the sink's business.
+ */
+
+export interface MarketplaceOptions {
+  /** The marketplace's name — a slug the clients key it on. */
+  name: string;
+  /** Shown as the marketplace owner. */
+  owner: string;
+  description?: string;
+  /** The default-branch commit the tree was compiled from; also the bundle's version. */
+  sourceCommit: string;
+  /** The name of the one-install bundle plugin. */
+  bundleName?: string;
+  /** The name of the leftovers plugin holding skills no other plugin ships. */
+  skillsPluginName?: string;
+  /**
+   * This deployment's hosted MCP endpoint — the knowledge base as a tool.
+   * Shipped in the leftovers plugin's `mcp.json` so an agent that installs
+   * from the marketplace can read the knowledge its skills refer to. URL only,
+   * never a credential: the endpoint challenges with OAuth metadata, and the
+   * client signs the person in on first use.
+   */
+  knowledgeBaseMcp?: { name: string; url: string };
+}
+
+export interface CompileInput {
+  /** Absolute path of the KB checkout (the folder holding `Plugins/`, `Skills/`, …). */
+  kbRoot: string;
+  /** The released catalog, UNFILTERED — `readable` does the filtering. */
+  skills: SkillSummary[];
+  /** The plugins as the configured source discovered them (manifests and servers already parsed). */
+  plugins: DiscoveredPlugin[];
+  /** Which plugins hold which skills, from the link index. */
+  membership: LinkMembership;
+  /** The caller's read verdict on a repo-relative path (`<skillFolder>/SKILL.md`). */
+  readable: (repoPath: string) => Promise<boolean>;
+  options: MarketplaceOptions;
+}
+
+export interface VirtualTree {
+  /** repo-relative POSIX path → file bytes. */
+  files: Map<string, Buffer>;
+  /** What was left out and why — name clashes, unparsable manifests. */
+  warnings: string[];
+  /** The plugin slugs the tree carries, in marketplace order. */
+  plugins: string[];
+}
+
+const BUNDLE_NAME = 'hexis-all';
+const SKILLS_PLUGIN_NAME = 'skills-and-knowledge';
+/** Slugs the compiler emits itself; a real plugin may not take them. */
+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 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.
+  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);
+  }
+
+  interface PluginOut {
+    slug: string;
+    displayName: string;
+    description?: string;
+    version?: string;
+    skills: SkillSummary[];
+    /** Source folder (real plugins only). */
+    folder?: string;
+    /** The portable `mcpServers` map to ship, when the plugin has servers. */
+    mcp?: Record<string, Record<string, unknown>>;
+  }
+  const out: PluginOut[] = [];
+
+  // 1. Real plugins: inline skills (in the folder) + linked skills (from the
+  //    manifest), each only if readable. Personal folders are places, not
+  //    plugins; a plugin the index does not count as existing is not shipped.
+  const byName = new Map(plugins.map((p) => [p.name, p]));
+  for (const [name, links] of [...membership.byPlugin.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const plugin = byName.get(name);
+    if (!plugin || plugin.personal || !plugin.exists) continue;
+    const manifest = plugin.manifest;
+    const inline = [...readableSkills.values()].filter((s) => s.path.startsWith(`${plugin.folder}/`));
+    const linked = links.linkedSkills
+      .map((p) => readableSkills.get(p))
+      .filter((s): s is SkillSummary => s !== undefined);
+    const dedup = dedupeByName([...inline, ...linked], (s, other) =>
+      warnings.push(
+        `${name}: skill "${s.name}" at ${s.path} shares its name with ${other.path} — the second is left out`,
+      ),
+    );
+    const mcp = portableMcp(plugin.mcpServers, (name, reason) =>
+      warnings.push(`${plugin.folder}: mcp server "${name}" not shipped — ${reason}`),
+    );
+    if (dedup.length === 0 && mcp === null) continue; // nothing this caller may see
+    // The plugin's identity IS the marketplace slug. Folded once more here
+    // all the same: it becomes a path segment in the compiled tree, and a
+    // checked-in manifest is repository content, not trusted input — the
+    // folding (`[a-z0-9.-]`, no runs, no leading dots) leaves nothing that
+    // can be a separator or a parent reference.
+    const slug = pluginManifestName(name);
+    if (RESERVED_SLUGS.has(slug)) {
+      warnings.push(`${plugin.folder}: manifest name "${slug}" is reserved by the marketplace and cannot be a plugin — plugin skipped`);
+      continue;
+    }
+    if (out.some((p) => p.slug === slug)) {
+      warnings.push(`${plugin.folder}: manifest name "${slug}" is already taken in this marketplace — plugin skipped`);
+      continue;
+    }
+    out.push({
+      slug,
+      displayName: plugin.displayName,
+      description: typeof manifest?.description === 'string' ? manifest.description : undefined,
+      version: typeof manifest?.version === 'string' ? manifest.version : undefined,
+      skills: dedup,
+      folder: plugin.folder,
+      mcp: mcp ?? undefined,
+    });
+  }
+
+  // 2. The leftovers plugin: every readable skill that no plugin above ships.
+  //    Agents install plugins, not loose skills, so a skill in no plugin — or
+  //    only in plugins this caller cannot see anything of — still has to be one
+  //    install away. ONE plugin per caller, not one per scope: there is nothing
+  //    to choose between (the caller may read all of it) and the bundle installs
+  //    it regardless, so scope plugins would only add names and duplicate what
+  //    the real plugins already carry.
+  //    It also carries the knowledge base's own MCP endpoint (URL only — the
+  //    client's OAuth flow signs the person in), so an agent installing from
+  //    the marketplace can read the knowledge its skills point at. With the
+  //    endpoint configured the plugin exists even for a caller with no
+  //    leftover skill: the knowledge is the point.
+  const covered = new Set(out.flatMap((p) => p.skills.map((s) => s.path)));
+  const leftovers = [...readableSkills.values()].filter((s) => !covered.has(s.path));
+  const kbMcp = options.knowledgeBaseMcp
+    ? { [options.knowledgeBaseMcp.name]: { type: 'streamable-http', url: options.knowledgeBaseMcp.url } }
+    : undefined;
+  if (leftovers.length > 0 || kbMcp) {
+    const slug = pluginManifestName(options.skillsPluginName ?? SKILLS_PLUGIN_NAME);
+    if (out.some((p) => p.slug === slug)) {
+      warnings.push(`the skills plugin "${slug}" collides with a plugin's manifest name — standalone skills not shipped`);
+    } else {
+      out.push({
+        slug,
+        displayName: 'Skills and knowledge',
+        description: kbMcp
+          ? 'Every skill you may read that no other plugin here ships, and the knowledge base as an MCP server'
+          : 'Every skill you may read that no other plugin here ships',
+        skills: dedupeByName(leftovers, (s, other) =>
+          warnings.push(`${slug}: "${s.name}" at ${s.path} shares its name with ${other.path} — left out`),
+        ),
+        mcp: kbMcp,
+      });
+    }
+  }
+
+  // 3. Materialise every plugin: the three manifests + copied skill folders.
+  for (const p of out) {
+    const base = `plugins/${p.slug}`;
+    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;
+    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;
+    put(`${base}/.claude-plugin/plugin.json`, `${JSON.stringify(vendor, null, 2)}\n`);
+    put(`${base}/.codex-plugin/plugin.json`, `${JSON.stringify(vendor, 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.
+  const bundle = pluginManifestName(options.bundleName ?? BUNDLE_NAME);
+  const slugs = out.map((p) => p.slug);
+  if (slugs.includes(bundle)) {
+    // 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.
+    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 shortSha = options.sourceCommit.slice(0, 12) || '0';
+    const description = `Everything in ${options.owner}'s marketplace you may read — one install.`;
+    put(
+      `plugins/${bundle}/.claude-plugin/plugin.json`,
+      `${JSON.stringify({ name: bundle, version: `0.0.0-${shortSha}`, description, dependencies: slugs }, null, 2)}\n`,
+    );
+    put(
+      `plugins/${bundle}/${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`,
+    );
+  }
+
+  // 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' }] : [])];
+  put(
+    '.claude-plugin/marketplace.json',
+    `${JSON.stringify(
+      {
+        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 })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  put(
+    '.agents/plugins/marketplace.json',
+    `${JSON.stringify(
+      {
+        name: options.name,
+        plugins: entries.map((e) => ({
+          name: e.slug,
+          source: { source: 'local', path: `./plugins/${e.slug}` },
+          policy: { installation: 'INSTALLED_BY_DEFAULT' },
+          description: e.description,
+        })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  put(
+    'README.md',
+    [
+      `# ${options.name}`,
+      '',
+      `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'}.`,
+      '',
+    ].join('\n'),
+  );
+
+  return { files, warnings, plugins: entries.map((e) => e.slug) };
+}
+
+// --- helpers ------------------------------------------------------------------
+
+/** Copy a skill folder (minus what never ships) under `dest`. */
+async function copySkill(
+  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))) {
+    put(`${dest}/${rel}`, await fs.readFile(path.join(abs, rel)));
+  }
+}
+
+/** First by (name, path) order wins; the loser is reported to `onClash`. */
+function dedupeByName(
+  list: SkillSummary[],
+  onClash: (loser: SkillSummary, winner: SkillSummary) => void,
+): SkillSummary[] {
+  const sorted = [...list].sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+  const seen = new Map<string, SkillSummary>();
+  const out: SkillSummary[] = [];
+  for (const s of sorted) {
+    const winner = seen.get(s.name);
+    if (winner) {
+      if (winner.path !== s.path) onClash(s, winner);
+      continue;
+    }
+    seen.set(s.name, s);
+    out.push(s);
+  }
+  return out;
+}
+
+/**
+ * The portable half of a plugin's `mcpServers`: every entry the ONE
+ * judgement accepts (a name a client can key on, a transport it speaks, the
+ * field that transport needs), normalised, minus what a client cannot use —
+ * `${VAR}` vault references in a url or a header. Null when there is no
+ * server to ship; each server left out is reported with the judgement's
+ * reason, so an omission is diagnosable.
+ */
+function portableMcp(
+  servers: Record<string, unknown> | null,
+  leftOut: (name: string, reason: string) => void,
+): Record<string, Record<string, unknown>> | null {
+  if (!servers) return null;
+  const out: Record<string, Record<string, unknown>> = {};
+  for (const [name, raw] of Object.entries(servers)) {
+    const verdict = judgeMcpServerEntry(name, raw);
+    if (!verdict.ok) {
+      leftOut(name, verdict.reason);
+      continue;
+    }
+    if (verdict.transport === 'stdio') {
+      out[name] = { ...verdict.entry };
+      continue;
+    }
+    const entry: Record<string, unknown> = { type: verdict.entry.type, url: verdict.entry.url };
+    if (containsVariableReference(verdict.entry.url)) {
+      leftOut(name, 'its url is expanded from the vault, which a client cannot do');
+      continue;
+    }
+    if (verdict.entry.headers) {
+      const headers: Record<string, string> = {};
+      for (const [h, v] of Object.entries(verdict.entry.headers)) {
+        if (!containsVariableReference(v)) headers[h] = v;
+      }
+      if (Object.keys(headers).length > 0) entry.headers = headers;
+    }
+    out[name] = entry;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}