test: pin the public package topology and export maps

Pin the manifest-level surface of all eight public packages (client, server,
server-legacy, express, fastify, hono, node, codemod): package names and
private flags, exact export-map keys, ESM-only conditions (no require),
files: ['dist'], and the codemod bin entry — plus the private status of core
and the workspace root. Adding, removing, or renaming an export-map entry is
a consumer-visible act and now requires updating this pin deliberately.

Runtime resolvability of built entries remains covered by the integration
test workspace; the type-level surface per entry is covered by the committed
API reports.

Author: felixweinberger

packages/core/test/packageTopologyPins.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Behavior-surface pins: workspace package topology and export maps.
+ *
+ * The published surface of the SDK is the set of public packages and their
+ * export-map entries. Consumers resolve deep subpaths through these maps, so
+ * adding, removing, or renaming an entry — or flipping a private flag — is a
+ * consumer-visible change. This pins the manifest-level topology: every change
+ * to it must be deliberate (update the pin, add a changeset, and document the
+ * migration). Runtime resolvability of the built entries is covered by the
+ * integration test workspace; the type-level surface of each entry is covered
+ * by the committed API reports.
+ *
+ * See docs/behavior-surface-pins.md for the full sweep inventory.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, test } from 'vitest';
+
+const packagesDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+interface PackageManifest {
+    name: string;
+    private?: boolean;
+    type?: string;
+    files?: string[];
+    bin?: Record<string, string>;
+    exports?: Record<string, unknown>;
+}
+
+function readManifest(relativeDir: string): PackageManifest {
+    return JSON.parse(readFileSync(join(packagesDir, relativeDir, 'package.json'), 'utf8')) as PackageManifest;
+}
+
+/** dir (relative to packages/) → expected manifest shape */
+const PUBLIC_PACKAGES: Record<string, { name: string; exportKeys: string[]; bin?: Record<string, string> }> = {
+    client: {
+        name: '@modelcontextprotocol/client',
+        exportKeys: ['.', './stdio', './validators/ajv', './validators/cf-worker', './_shims']
+    },
+    server: {
+        name: '@modelcontextprotocol/server',
+        exportKeys: ['.', './stdio', './validators/ajv', './validators/cf-worker', './_shims']
+    },
+    'server-legacy': {
+        name: '@modelcontextprotocol/server-legacy',
+        exportKeys: ['.', './sse', './auth']
+    },
+    'middleware/express': { name: '@modelcontextprotocol/express', exportKeys: ['.'] },
+    'middleware/fastify': { name: '@modelcontextprotocol/fastify', exportKeys: ['.'] },
+    'middleware/hono': { name: '@modelcontextprotocol/hono', exportKeys: ['.'] },
+    'middleware/node': { name: '@modelcontextprotocol/node', exportKeys: ['.'] },
+    codemod: {
+        name: '@modelcontextprotocol/codemod',
+        exportKeys: ['.'],
+        bin: { 'mcp-codemod': './dist/cli.mjs' }
+    }
+};
+
+describe('public package topology', () => {
+    for (const [dir, expected] of Object.entries(PUBLIC_PACKAGES)) {
+        describe(expected.name, () => {
+            const manifest = readManifest(dir);
+
+            test('is published under the pinned name', () => {
+                expect(manifest.name).toBe(expected.name);
+                expect(manifest.private).not.toBe(true);
+            });
+
+            test('export-map keys are pinned exactly', () => {
+                expect(Object.keys(manifest.exports ?? {})).toEqual(expected.exportKeys);
+            });
+
+            test('ships ESM only', () => {
+                expect(manifest.type).toBe('module');
+                // No entry may grow a 'require' condition: the v2 packages are
+                // ESM-only by design (a CJS build would be a new public surface).
+                const conditionsOf = (entry: unknown): string[] =>
+                    entry !== null && typeof entry === 'object'
+                        ? Object.entries(entry).flatMap(([key, value]) => [key, ...conditionsOf(value)])
+                        : [];
+                for (const entry of Object.values(manifest.exports ?? {})) {
+                    expect(conditionsOf(entry)).not.toContain('require');
+                }
+            });
+
+            test('publishes only dist', () => {
+                expect(manifest.files).toEqual(['dist']);
+            });
+
+            if (expected.bin) {
+                test('bin entries are pinned', () => {
+                    expect(manifest.bin).toEqual(expected.bin);
+                });
+            } else {
+                test('declares no bin entries', () => {
+                    expect(manifest.bin).toBeUndefined();
+                });
+            }
+        });
+    }
+});
+
+describe('internal packages stay private', () => {
+    test('@modelcontextprotocol/core is private (bundled into client/server dists)', () => {
+        const manifest = readManifest('core');
+        expect(manifest.name).toBe('@modelcontextprotocol/core');
+        expect(manifest.private).toBe(true);
+    });
+
+    test('the workspace root is private', () => {
+        const manifest = JSON.parse(readFileSync(join(packagesDir, '..', 'package.json'), 'utf8')) as PackageManifest;
+        expect(manifest.private).toBe(true);
+    });
+});