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

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -1,4 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('mcp-oauth');
 import { and, eq, gt, isNull, lt, or } from 'drizzle-orm';
 import type { Response } from 'express';
 import type {
@@ -167,6 +170,9 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     userId: string,
     st: McpAuthRequestState,
   ): Promise<{ redirectTo: string }> {
+    // A state without a PKCE challenge is a Claude-link request, which the
+    // marketplace bridge finishes; it must never reach the SDK's code store.
+    if (!st.cc) throw new InvalidGrantError('Authorization request carries no PKCE challenge');
     const code = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     await this.deps.db.insert(oauthAuthCodes).values({
       codeHash: hashToken(code),
@@ -304,7 +310,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       .update(oauthTokens)
       .set({ lastUsedAt: now })
       .where(eq(oauthTokens.id, row.id))
-      .then(undefined, (err) => console.warn('[mcp-oauth] touch lastUsedAt failed:', err));
+      .then(undefined, (err) => log.warn('touch lastUsedAt failed:', { err }));
     return {
       token,
       clientId: row.clientId,
@@ -374,7 +380,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       );
       await this.deps.db.delete(oauthAuthCodes).where(lt(oauthAuthCodes.expiresAt, cutoff));
     } catch (err) {
-      console.warn('[mcp-oauth] token-table prune failed (non-fatal):', err instanceof Error ? err.message : err);
+      log.warn('token-table prune failed (non-fatal):', { err });
     }
     await this.deps.db.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),

package/src/modules/mcp/oauth/oauth-consent.routes.ts

@@ -1,12 +1,26 @@
 import express from 'express';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('mcp-oauth');
 import type { BevelOAuthProvider } from './bevel-oauth-provider.js';
-import { verifyAuthRequest } from './oauth-state.js';
+import { verifyAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 import '../../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface OAuthConsentRoutesDeps {
   provider: BevelOAuthProvider;
   /** Same HMAC secret the provider signs the authorize state with. */
   stateSecret: string;
+  /**
+   * The GitHub facade, when the deployment has one: a state it signed
+   * (`gh`) is a person connecting an account on a product that speaks to
+   * this deployment as a GitHub Enterprise host (claude.ai), and the code
+   * that flow needs is the facade's, not the SDK's.
+   */
+  facade?: {
+    isFacadeRequest(st: McpAuthRequestState): boolean;
+    clientNameFor(st: McpAuthRequestState): string;
+    completeConsent(userId: string, st: McpAuthRequestState): Promise<{ redirectTo: string }>;
+  };
 }
 
 /**
@@ -17,6 +31,9 @@ export interface OAuthConsentRoutesDeps {
  * landing from the redirect chain authenticates via the HttpOnly bevel_token
  * cookie fallback, so THIS is where a Bevel user attaches to the flow.
  */
+/** A facade state reaching a deployment whose routes were built without the facade. */
+const NO_FACADE = 'Connecting an external account this way is not enabled on this deployment.';
+
 export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.Router {
   const router = express.Router();
 
@@ -26,6 +43,11 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     const raw = typeof req.query.state === 'string' ? req.query.state : '';
     const st = raw ? verifyAuthRequest(deps.stateSecret, raw) : null;
     if (!st) return void res.status(400).json({ error: 'Invalid or expired authorization request. Restart the connection from your agent.' });
+    if (st.gh) {
+      if (!deps.facade) return void res.status(400).json({ error: NO_FACADE });
+      res.json({ clientName: deps.facade.clientNameFor(st), scope: null, resource: null });
+      return;
+    }
     const client = await deps.provider.clientsStore.getClient(st.c);
     res.json({
       clientName: client?.client_name ?? null,
@@ -42,16 +64,16 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     const raw = typeof (req.body ?? {}).state === 'string' ? req.body.state : '';
     const st = raw ? verifyAuthRequest(deps.stateSecret, raw) : null;
     if (!st) return void res.status(400).json({ error: 'Invalid or expired authorization request. Restart the connection from your agent.' });
+    if (st.gh && !deps.facade) return void res.status(400).json({ error: NO_FACADE });
     try {
-      const { redirectTo } = await deps.provider.issueAuthCode(userId, st);
+      const { redirectTo } = st.gh && deps.facade
+        ? await deps.facade.completeConsent(userId, st)
+        : await deps.provider.issueAuthCode(userId, st);
       res.json({ redirectTo });
     } catch (err) {
       // Message only — the raw error object can carry sensitive context
       // (redirect URIs with tokens, DB details) that must not hit stdout.
-      console.error(
-        `[mcp-oauth] complete failed for client=${st.c}:`,
-        err instanceof Error ? err.message : String(err),
-      );
+      log.error(`complete failed for client=${st.c}:`, { detail: err instanceof Error ? err.message : String(err) });
       res.status(500).json({ error: 'Internal error' });
     }
   });

package/src/modules/mcp/oauth/oauth-state.ts

@@ -18,8 +18,19 @@ export interface McpAuthRequestState {
   c: string;
   /** redirect_uri (already validated against the client's registration). */
   r: string;
-  /** PKCE code_challenge (S256 — the SDK authorize handler enforces it). */
-  cc: string;
+  /**
+   * PKCE code_challenge (S256 — the SDK authorize handler enforces it).
+   * Absent only on a GitHub-facade request (`gh`), whose client is a
+   * confidential one that proves itself with a secret at the token exchange.
+   */
+  cc?: string;
+  /**
+   * A GitHub-shaped authorize request from a product that treats this
+   * deployment as a GitHub Enterprise host (the marketplace facade), not an
+   * MCP client: the consent routes hand it to the facade, which mints a code
+   * of its own instead of the SDK's.
+   */
+  gh?: true;
   /** The client's own `state` parameter, echoed back on the code redirect. */
   s?: string;
   /** Requested scope (space-joined). */
@@ -51,7 +62,8 @@ export function verifyAuthRequest(secret: string, token: string): McpAuthRequest
   if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
   try {
     const parsed = JSON.parse(Buffer.from(body, 'base64url').toString()) as McpAuthRequestState;
-    if (typeof parsed.iat !== 'number' || !parsed.c || !parsed.r || !parsed.cc) return null;
+    if (typeof parsed.iat !== 'number' || !parsed.c || !parsed.r) return null;
+    if (!parsed.cc && parsed.gh !== true) return null;
     const age = Date.now() - parsed.iat;
     if (age > STATE_MAX_AGE_MS || age < -STATE_SKEW_MS) return null;
     return parsed;

package/src/modules/mcp/surface-log-throttle.ts

@@ -0,0 +1,120 @@
+/**
+ * Decides whether a request's surface-build line is worth a log entry.
+ *
+ * The stateless endpoint rebuilds the tool surface on EVERY request, and the
+ * line that reports how long that took is the measurement the design's
+ * per-request overhead is judged by — it has to keep appearing. It must not
+ * appear per request: at the measured ~100 ms a request, an active client
+ * produces thousands of identical lines a minute, and the log stops carrying
+ * the one signal it exists for (a surface that changed, or got slow).
+ *
+ * So a line is logged for a user when its SHAPE changed since the last
+ * logged line (tool or manual count — a manual that appeared, failed, or
+ * was fixed), or when a quiet interval has passed since that line, whichever
+ * comes first. In between, identical rebuilds are counted, and the next
+ * logged line carries the count so nothing is hidden, only compressed.
+ *
+ * Bounded: an entry per user, dropped once they have been quiet for the
+ * interval, so a long-running process never accumulates departed users. The
+ * pruning is one sweep per interval, not one per request — a request must
+ * not pay for every other active user — which puts the bound at TWO
+ * intervals, not one: a user who goes quiet just after a sweep is not yet
+ * quiet enough at the next one and goes at the one after. Departed users
+ * therefore cost at most the number who were active in the last two
+ * intervals, which is the price of the O(1) request.
+ */
+
+export const DEFAULT_SURFACE_LOG_INTERVAL_MS = 60_000;
+
+export interface SurfaceShape {
+  tools: number;
+  manuals: number;
+}
+
+export interface SurfaceLogDecision {
+  log: boolean;
+  /** Rebuilds with the same shape suppressed since the last logged line for this user. */
+  suppressed: number;
+}
+
+interface LastLogged {
+  /** When this user's line was last LOGGED — the interval counts from here. */
+  at: number;
+  /**
+   * When this user last rebuilt at all, logged or suppressed — what pruning
+   * counts from. A user rebuilding every second inside the interval is
+   * active, and forgetting them on a sweep would discard the suppressed count
+   * their next logged line owes.
+   */
+  seenAt: number;
+  shape: string;
+  suppressed: number;
+}
+
+export class SurfaceLogThrottle {
+  private readonly last = new Map<string, LastLogged>();
+  /** When the last sweep ran; a sweep is owed once per interval, not per request. */
+  private lastPruneAt = Number.NEGATIVE_INFINITY;
+
+  constructor(
+    private readonly intervalMs: number = DEFAULT_SURFACE_LOG_INTERVAL_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** Record a rebuild for `userId` and say whether to log it. */
+  decide(userId: string, shape: SurfaceShape): SurfaceLogDecision {
+    const now = this.now();
+    // One sweep per interval, amortized over every request in it: a request
+    // costs O(1), not a walk of every active user, and an entry that goes
+    // quiet is gone by the second sweep after (see the class doc). The sweep
+    // skips THIS user: its entry is about to be read, and at exactly the
+    // interval it still carries the suppressed count the next line owes.
+    //
+    // `now` is the wall clock, which can step backwards (an NTP correction, a
+    // VM restored from suspend). Waiting for it to climb back past the last
+    // sweep would stall pruning for as long as the step was; a clock that
+    // went backwards instead resets the cadence, and pruning resumes in the
+    // clock's new domain on the next request.
+    const clockSteppedBack = now < this.lastPruneAt;
+    if (clockSteppedBack || now - this.lastPruneAt >= this.intervalMs) {
+      this.prune(now, userId);
+      this.lastPruneAt = now;
+    }
+    const key = `${shape.tools}/${shape.manuals}`;
+    const prev = this.last.get(userId);
+    if (prev && prev.shape === key && now - prev.at < this.intervalMs) {
+      prev.suppressed += 1;
+      prev.seenAt = now;
+      return { log: false, suppressed: prev.suppressed };
+    }
+    const suppressed = prev?.suppressed ?? 0;
+    this.last.set(userId, { at: now, seenAt: now, shape: key, suppressed: 0 });
+    return { log: true, suppressed };
+  }
+
+  /** Users currently remembered; diagnostics and tests. */
+  size(): number {
+    return this.last.size;
+  }
+
+  /**
+   * Entries for users quiet for the interval or longer carry no information;
+   * drop them. Quiet means no rebuild at all, logged or suppressed (`seenAt`):
+   * a user whose every rebuild in the interval was suppressed is not quiet,
+   * and dropping them would lose the count their next line reports. An entry
+   * stamped LATER than now was written before the clock stepped backwards:
+   * its age is unknowable across the step, so it is restamped as seen now and
+   * ages from here — otherwise a large step would keep every pre-step user
+   * for as long as the step, past the stated bound.
+   */
+  private prune(now: number, except: string): void {
+    for (const [userId, entry] of this.last) {
+      if (entry.seenAt > now) {
+        entry.seenAt = now;
+        if (entry.at > now) entry.at = now;
+      } else if (userId !== except && now - entry.seenAt >= this.intervalMs) {
+        this.last.delete(userId);
+      }
+    }
+  }
+}

package/src/modules/plugins/__tests__/bundle-dialect.e2e.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, afterEach } 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_BRANCH, DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../../access/access-control.service.js';
+import { SkillService } from '../../skills/skills.service.js';
+import { ToolManualService } from '../../tool-manuals/tool-manuals.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { PluginIndexService } from '../plugins.service.js';
+import { PluginLinkIndex } from '../plugin-links.js';
+import { PluginLinksService } from '../plugin-links.service.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
+import { MarketplaceCompilerService } from '../compile/marketplace-compiler.service.js';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+
+/**
+ * A customer's repository, read as-is: lowercase `skills/` and `plugins/`
+ * roots, bundles at the depths their org uses, a registry with a profile
+ * chain, and a committed `dist/` beside the source. Every consumer — catalog,
+ * plugin index, link index, tool manuals, compiler — must read the SOURCE
+ * trees and agree on what a plugin holds, with nothing written back.
+ */
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+describe('bundle dialect, end to end', () => {
+  let root: string;
+  let repo: string;
+  let access: AccessControlService;
+  let skills: SkillService;
+  let tools: ToolManualService;
+  let links: PluginLinkIndex;
+  let index: PluginIndexService;
+  let compiler: MarketplaceCompilerService;
+  let linkService: PluginLinksService;
+
+  const write = async (rel: string, text: string) => {
+    const abs = path.join(repo, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+
+  beforeEach(async () => {
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-dialect-'));
+    repo = path.join(root, wsId, KB_DIR);
+    const workspaceService = {
+      getOrCreateForBranch: async () => ({ id: wsId }),
+      getWorkspacePath: async (id: string) => path.join(root, id),
+      readFile: async (id: string, rel: string) => fs.readFile(path.join(root, id, rel), 'utf-8'),
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+
+    await write('roles.yaml', 'roles:\n  Admin:\n    - admin@x.io\n');
+    // Their scopes decide readability; everything here is open to signed-in people.
+    await write('access.md', '---\nwrite:\n  - Admin\n---\nread:\n  - everyone\n');
+    await write(
+      'configs/mcp/registry.json',
+      JSON.stringify({
+        servers: [
+          { id: 'jira', config: { command: 'npx', args: ['-y', 'jira-mcp'] } },
+          { id: 'confluence', config: { type: 'http', url: 'https://mcp.confluence.example' } },
+        ],
+        profiles: [{ id: 'base', servers: ['jira'] }, { id: 'global', servers: ['confluence'], extends: 'base' }],
+      }),
+    );
+    // Skills at their four depths; a build output that must be ignored.
+    await write('skills/functional/cluster-a/one-skill/SKILL.md', '---\nname: one-skill\ndescription: One.\nmetadata:\n  version: "1.4.0"\n  author: "acme"\n---\n');
+    await write('skills/departments/business/finance/close-books/SKILL.md', '---\ndescription: Close.\n---\n');
+    await write('skills/departments/engineering/shared/cluster-a/deploy/SKILL.md', '---\ndescription: Deploy.\n---\n');
+    await write('skills/departments/engineering/shared/cluster-a/rollback/SKILL.md', '---\ndescription: Undo.\n---\n');
+    await write('skills/departments/engineering/team-x/team-only/SKILL.md', '---\ndescription: Ours.\n---\n');
+    await write('dist/docs/plugins/functional/example/skills/deploy/SKILL.md', '---\ndescription: compiled copy\n---\n');
+    // Plugins: one links a cluster + a single skill; one links a department.
+    await write(
+      'plugins/functional/cluster-a/example-plugin/plugin.bundle.json',
+      JSON.stringify({
+        name: 'example-plugin',
+        version: '1.3.1',
+        description: 'Example',
+        mcpProfile: 'global',
+        interface: { displayName: 'Example Plugin' },
+        sourceSkillRoots: ['skills/departments/engineering/shared/cluster-a', 'skills/functional/cluster-a/one-skill'],
+      }),
+    );
+    await write(
+      'plugins/departments/business/finance/finance-kit/plugin.bundle.json',
+      JSON.stringify({ name: 'finance-kit', sourceSkillRoots: ['skills/departments/business/finance'] }),
+    );
+
+    const disk = new NodeFs();
+    const source = new KbPluginSource(disk);
+    access = new AccessControlService(workspaceService, KB_DIR, disk);
+    skills = new SkillService(workspaceService, access, KB_DIR, disk);
+    tools = new ToolManualService(workspaceService, access, KB_DIR, disk, source);
+    links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, source);
+    index = new PluginIndexService(workspaceService, access, skills, tools, KB_DIR, source, Date.now, links);
+    compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, KB_DIR, { name: 'acme', owner: 'Acme' }, source, disk, new NodeGitRunner());
+    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, skills, links, KB_DIR);
+  });
+  afterEach(async () => {
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('reads the source trees: skills at any depth, plugins as skill lists, servers from the registry', async () => {
+    const catalog = await skills.listSkills();
+    expect(catalog.map((s) => s.name).sort()).toEqual(['close-books', 'deploy', 'one-skill', 'rollback', 'team-only']);
+    expect(catalog.find((s) => s.name === 'one-skill')?.version).toBe('1.4.0');
+    expect(catalog.some((s) => s.path.startsWith('dist/'))).toBe(false);
+
+    const membership = await links.membership();
+    expect(membership.byPlugin.get('example-plugin')?.linkedSkills.sort()).toEqual([
+      'skills/departments/engineering/shared/cluster-a/deploy',
+      'skills/departments/engineering/shared/cluster-a/rollback',
+      'skills/functional/cluster-a/one-skill',
+    ]);
+    expect(membership.byPlugin.get('example-plugin')?.linksAreManaged).toBe(false);
+    expect(membership.bySkill.get('skills/departments/business/finance/close-books')).toEqual([
+      { name: 'finance-kit', linked: true, granted: true },
+    ]);
+    // A standalone skill is in no plugin, and that is a normal state.
+    expect(membership.bySkill.get('skills/departments/engineering/team-x/team-only')).toBeUndefined();
+
+    const plugins = await index.catalog();
+    expect(plugins.map((p) => [p.name, p.skillCount, p.toolCount])).toEqual([
+      ['example-plugin', 3, 2],
+      ['finance-kit', 1, 0],
+    ]);
+    expect(plugins[0].folders).toEqual(['plugins/functional/cluster-a/example-plugin']);
+
+    const manuals = await tools.listAllSummaries();
+    expect(manuals.map((m) => m.name).sort()).toEqual(['confluence', 'jira']);
+  });
+
+  it('compiles a marketplace from the source trees, per caller', async () => {
+    const tree = await compiler.compileFor({ userEmail: 'someone@x.io' });
+    const paths = [...tree.files.keys()];
+    expect(paths).toContain('plugins/example-plugin/skills/deploy/SKILL.md');
+    expect(paths).toContain('plugins/example-plugin/skills/one-skill/SKILL.md');
+    expect(paths).toContain('plugins/finance-kit/skills/close-books/SKILL.md');
+    // The standalone team skill rides in the leftovers plugin; linked ones do not repeat there.
+    expect(paths).toContain('plugins/skills-and-knowledge/skills/team-only/SKILL.md');
+    expect(paths).not.toContain('plugins/skills-and-knowledge/skills/deploy/SKILL.md');
+    const manifest = JSON.parse(tree.files.get('plugins/example-plugin/plugin.json')!.toString());
+    expect(manifest).toMatchObject({ name: 'example-plugin', version: '1.3.1', description: 'Example' });
+    const mcp = JSON.parse(tree.files.get('plugins/example-plugin/.mcp.json')!.toString());
+    expect(Object.keys(mcp.mcpServers).sort()).toEqual(['confluence', 'jira']);
+    expect(paths.some((p) => p.includes('dist/'))).toBe(false);
+  });
+
+  it('never writes into the dialect: linking through hexis is refused as read-only', async () => {
+    const user = { id: 'u1', email: 'admin@x.io', name: 'Admin' };
+    await expect(linkService.link(user, 'example-plugin', 'skills/departments/engineering/team-x/team-only')).rejects.toMatchObject({
+      status: 409,
+      payload: { kind: 'read-only-links' },
+    });
+    const before = await fs.readFile(path.join(repo, 'plugins/functional/cluster-a/example-plugin/plugin.bundle.json'), 'utf-8');
+    expect(JSON.parse(before).sourceSkillRoots).toHaveLength(2);
+  });
+});

package/src/modules/plugins/__tests__/bundle-dialect.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { expandProfile, parseRegistry } from '../discovery/bundle-dialect/registry.js';
+import { readBundlePlugin } from '../discovery/bundle-dialect/bundle.source.js';
+
+/**
+ * The customer's registry and bundle, read as they mean them: a server is
+ * CALLED by its `name` (the `mcp__<name>__*` namespace skills are written
+ * against) and selected by its `id`; every field of a server the platform
+ * does not know rides along; a server the registry could not keep is named
+ * with the reason wherever a profile asks for it; and what a bundle says
+ * about itself beyond name, version and description survives to the
+ * compiled plugin. Driven through the two public readers, on crafted input.
+ */
+
+const registryText = (extra: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    version: 1,
+    servers: [
+      { id: 'ado', name: 'ado', config: { command: 'npx', args: ['-y', '@azure-devops/mcp', 'acme'], startup_timeout_sec: 120 } },
+      { id: 'figma-stdio', name: 'figma', config: { command: 'npx', args: ['-y', 'figma-mcp'] } },
+      { id: 'figma-remote', name: 'figma', config: { type: 'http', url: 'https://mcp.figma.com/mcp' } },
+      { id: 'docs', name: 'acme-docs', config: { command: 'node', args: ['server.js', { $fromFile: 'x.json' }] } },
+    ],
+    profiles: [
+      { id: 'global', servers: ['ado', 'figma-stdio', 'docs'] },
+      { id: 'remote', extends: 'global', servers: ['figma-remote'] },
+    ],
+    ...extra,
+  });
+
+describe('registry: servers are called by name, selected by id', () => {
+  it('keys an expanded profile by the running name, with the id as the name when none is given', () => {
+    const registry = parseRegistry(
+      JSON.stringify({
+        servers: [
+          { id: 'figma-stdio', name: 'figma', config: { command: 'npx', args: ['-y', 'figma-mcp'] } },
+          { id: 'jira', config: { command: 'npx', args: ['-y', 'jira-mcp'] } },
+        ],
+        profiles: [{ id: 'global', servers: ['figma-stdio', 'jira'] }],
+      }),
+    );
+    const { mcpServers, warnings } = expandProfile(registry, 'global');
+    expect(Object.keys(mcpServers).sort()).toEqual(['figma', 'jira']);
+    expect(warnings).toEqual([]);
+  });
+
+  it('carries every field it does not read — the customer\'s startup_timeout_sec survives', () => {
+    const registry = parseRegistry(registryText());
+    const { mcpServers } = expandProfile(registry, 'global');
+    expect(mcpServers.ado).toEqual({
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', '@azure-devops/mcp', 'acme'],
+      startup_timeout_sec: 120,
+    });
+  });
+
+  it('two transports of one server: a profile picks one, and picking both is a reported conflict the nearer profile wins', () => {
+    const registry = parseRegistry(registryText());
+    // `remote` extends `global`: its own figma-remote is nearer than global's figma-stdio.
+    const remote = expandProfile(registry, 'remote');
+    expect(remote.mcpServers.figma).toMatchObject({ type: 'streamable-http', url: 'https://mcp.figma.com/mcp' });
+    expect(remote.warnings).toContainEqual(
+      expect.stringContaining('selects both "figma-remote" and "figma-stdio", which are both named "figma" — "figma-stdio" left out'),
+    );
+    const global = expandProfile(registry, 'global');
+    expect(global.mcpServers.figma).toMatchObject({ type: 'stdio', command: 'npx' });
+  });
+
+  it('names a selected server the registry could not keep, with the reason, where the profile asks for it', () => {
+    const registry = parseRegistry(registryText());
+    expect(registry.rejected.get('docs')).toBe('args must be a list of strings');
+    const { mcpServers, warnings } = expandProfile(registry, 'global');
+    expect(mcpServers['acme-docs']).toBeUndefined();
+    expect(warnings).toContainEqual(
+      'registry.json: profile "global" selects server "docs", which was left out — args must be a list of strings',
+    );
+  });
+
+  it('a name a client cannot key on does not lose the server: it runs under its id, and the author is told', () => {
+    const registry = parseRegistry(
+      JSON.stringify({
+        servers: [{ id: 'ok-id', name: 'Not A Name', config: { command: 'x' } }],
+        profiles: [{ id: 'p', servers: ['ok-id'] }],
+      }),
+    );
+    expect(registry.warnings).toEqual([
+      'registry.json: server "ok-id" is named "Not A Name", which cannot be a server name (lowercase alphanumeric with `_`/`-`) — it runs as "ok-id"',
+    ]);
+    expect(Object.keys(expandProfile(registry, 'p').mcpServers)).toEqual(['ok-id']);
+  });
+
+  it('a name that is present but blank, or not a string, is said too — the server runs under its id', () => {
+    const registry = parseRegistry(
+      JSON.stringify({
+        servers: [
+          { id: 'a', name: '   ', config: { command: 'x' } },
+          { id: 'b', name: 42, config: { command: 'x' } },
+          { id: 'c', name: 'c', config: { command: 'x' } },
+        ],
+      }),
+    );
+    expect(registry.warnings).toEqual([
+      'registry.json: server "a" has a name that is blank or not a string — it runs as "a"',
+      'registry.json: server "b" has a name that is blank or not a string — it runs as "b"',
+    ]);
+    expect([...registry.servers.values()].map((s) => s.name)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('carries a field spelled __proto__ as a field, not as a prototype', () => {
+    // Raw text on purpose: in a JavaScript literal `__proto__` sets the
+    // prototype and never reaches JSON; from a file it is an ordinary key.
+    const registry = parseRegistry('{"servers":[{"id":"odd","config":{"command":"x","__proto__":{"polluted":true}}}]}');
+    const entry = registry.servers.get('odd')!.entry as Record<string, unknown>;
+    expect(Object.prototype.hasOwnProperty.call(entry, '__proto__')).toBe(true);
+    expect((entry as { polluted?: unknown }).polluted).toBeUndefined();
+  });
+
+  it('a rejected server carries the reason the entry failed, not its name', () => {
+    const registry = parseRegistry(
+      JSON.stringify({ servers: [{ id: 'docs', name: 'acme-docs', config: { command: 'node', args: [{ x: 1 }] } }] }),
+    );
+    expect(registry.rejected.get('docs')).toBe('args must be a list of strings');
+  });
+});
+
+describe('bundle: what it says about itself survives', () => {
+  it('carries author, keywords and the interface block into the manifest, beside name, version and description', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-bundle-'));
+    try {
+      const dir = path.join(root, 'plugins', 'ado');
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(
+        path.join(dir, 'plugin.bundle.json'),
+        JSON.stringify({
+          name: 'ado',
+          version: '1.3.5',
+          description: 'Azure DevOps skills.',
+          author: { name: 'acme' },
+          keywords: ['ado', 'mcp'],
+          interface: { displayName: 'Azure DevOps', category: 'Productivity', brandColor: '#2563EB', defaultPrompt: ['Show my work.'] },
+          sourceSkillRoots: ['skills/ado'],
+        }),
+      );
+      const warnings: string[] = [];
+      const plugin = await readBundlePlugin(dir, 'plugins/ado', 'ado', null, warnings, []);
+      expect(plugin?.manifest).toEqual({
+        name: 'ado',
+        version: '1.3.5',
+        description: 'Azure DevOps skills.',
+        displayName: 'Azure DevOps',
+        author: { name: 'acme' },
+        keywords: ['ado', 'mcp'],
+        interface: { displayName: 'Azure DevOps', category: 'Productivity', brandColor: '#2563EB', defaultPrompt: ['Show my work.'] },
+      });
+      expect(plugin?.displayName).toBe('Azure DevOps');
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});