@contractspec/bundle.library 3.8.11 → 3.9.0

package/src/application/mcp/contractsMcp.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'bun:test';
+import { buildContractsResources } from './contractsMcpResources';
+import { buildContractsOps } from './contractsMcpTools';
+import type { ContractsMcpServices } from './contractsMcpTypes';
+
+const services: ContractsMcpServices = {
+	async buildSpec() {
+		return { results: [] };
+	},
+	async deleteSpec() {
+		return { cleanedFiles: [], deleted: true, errors: [] };
+	},
+	async fetchRegistryManifest() {
+		return {};
+	},
+	async getSpec() {
+		return null;
+	},
+	async listSpecs() {
+		return [];
+	},
+	async resolveAdoption(options) {
+		return {
+			ambiguous: false,
+			candidates: [],
+			exhausted: false,
+			family: options.family,
+			query: options.query,
+			reason: `Resolved ${options.family}`,
+			selected: null,
+			verdict: 'rewrite',
+		};
+	},
+	async searchAdoptionCatalog() {
+		return [{ packageRef: '@contractspec/lib.contracts-spec' }];
+	},
+	async syncAdoptionCatalog() {
+		return { catalogPath: '.contractspec/adoption/catalog.json', total: 1 };
+	},
+	async updateSpec() {
+		return { errors: [], updated: true, warnings: [] };
+	},
+	async validateSpec() {
+		return { errors: [], valid: true, warnings: [] };
+	},
+};
+
+describe('contracts MCP adoption extensions', () => {
+	it('registers adoption tools alongside contract tools', () => {
+		const registry = buildContractsOps(services);
+		const keys = registry.list().map((spec) => spec.meta.key);
+
+		expect(keys).toContain('adoption.catalog_search');
+		expect(keys).toContain('adoption.resolve');
+		expect(keys).toContain('adoption.sync');
+	});
+
+	it('registers adoption resources', () => {
+		const resources = buildContractsResources(services);
+		const uris = resources.listTemplates().map((tmpl) => tmpl.meta.uriTemplate);
+
+		expect(uris).toContain('adoption://catalog');
+		expect(uris).toContain('adoption://policy/{family}');
+	});
+});

package/src/application/mcp/contractsMcpAdoptionTools.ts

@@ -0,0 +1,131 @@
+import {
+	defineCommand,
+	installOp,
+	type OperationSpecRegistry,
+} from '@contractspec/lib.contracts-spec';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import type { ContractsMcpServices } from './contractsMcpTypes';
+
+const OWNERS = ['@contractspec'];
+const TAGS = ['contracts', 'mcp', 'adoption'];
+
+export function registerAdoptionOps(
+	registry: OperationSpecRegistry,
+	services: ContractsMcpServices
+) {
+	const SearchInput = defineSchemaModel({
+		name: 'AdoptionCatalogSearchInput',
+		fields: {
+			query: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			family: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+			platform: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		},
+	});
+	const SearchOutput = defineSchemaModel({
+		name: 'AdoptionCatalogSearchOutput',
+		fields: {
+			results: { type: ScalarTypeEnum.JSON(), isOptional: false },
+		},
+	});
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'adoption.catalog_search',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: OWNERS,
+				tags: TAGS,
+				description: 'Search the local ContractSpec adoption catalog.',
+				goal: 'Find relevant ContractSpec reuse candidates for a query.',
+				context: 'Contracts MCP server.',
+			},
+			io: { input: SearchInput, output: SearchOutput },
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ family, platform, query }) => ({
+			results: await services.searchAdoptionCatalog({
+				family,
+				platform,
+				query,
+			}),
+		})
+	);
+
+	const ResolveInput = defineSchemaModel({
+		name: 'AdoptionResolveInput',
+		fields: {
+			family: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			query: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			paths: { type: ScalarTypeEnum.JSON(), isOptional: true },
+			platform: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+			runtime: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		},
+	});
+	const ResolveOutput = defineSchemaModel({
+		name: 'AdoptionResolveOutput',
+		fields: {
+			resolution: { type: ScalarTypeEnum.JSON(), isOptional: false },
+		},
+	});
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'adoption.resolve',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: OWNERS,
+				tags: TAGS,
+				description: 'Resolve the best adoption candidate for one family.',
+				goal: 'Provide one ordered recommendation that matches Connect.',
+				context: 'Contracts MCP server.',
+			},
+			io: { input: ResolveInput, output: ResolveOutput },
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ family, paths, platform, query, runtime }) => ({
+			resolution: await services.resolveAdoption({
+				family,
+				paths: Array.isArray(paths) ? (paths as string[]) : undefined,
+				platform,
+				query,
+				runtime,
+			}),
+		})
+	);
+
+	const SyncInput = defineSchemaModel({
+		name: 'AdoptionSyncInput',
+		fields: {},
+	});
+	const SyncOutput = defineSchemaModel({
+		name: 'AdoptionSyncOutput',
+		fields: {
+			catalogPath: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+			total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+		},
+	});
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'adoption.sync',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: OWNERS,
+				tags: TAGS,
+				description:
+					'Mirror the bundled ContractSpec adoption catalog locally.',
+				goal: 'Refresh the local adoption catalog used by Connect and MCP.',
+				context: 'Contracts MCP server.',
+			},
+			io: { input: SyncInput, output: SyncOutput },
+			policy: { auth: 'user' },
+		}),
+		async () => services.syncAdoptionCatalog()
+	);
+}

package/src/application/mcp/contractsMcpResources.ts

@@ -87,6 +87,54 @@ export function buildContractsResources(services: ContractsMcpServices) {
 		})
 	);
 
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'adoption://catalog',
+				title: 'ContractSpec adoption catalog',
+				description:
+					'Bundled ContractSpec adoption catalog used by Connect and MCP.',
+				mimeType: 'application/json',
+				tags: TAGS,
+			},
+			input: z.object({}),
+			resolve: async () => {
+				const results = await services.searchAdoptionCatalog({
+					query: 'contractspec',
+				});
+				return {
+					uri: 'adoption://catalog',
+					mimeType: 'application/json',
+					data: JSON.stringify(results, null, 2),
+				};
+			},
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'adoption://policy/{family}',
+				title: 'ContractSpec adoption policy',
+				description: 'Family-aware adoption recommendation and verdict policy.',
+				mimeType: 'application/json',
+				tags: TAGS,
+			},
+			input: z.object({ family: z.string() }),
+			resolve: async ({ family }) => {
+				const resolution = await services.resolveAdoption({
+					family,
+					query: family,
+				});
+				return {
+					uri: `adoption://policy/${encodeURIComponent(family)}`,
+					mimeType: 'application/json',
+					data: JSON.stringify(resolution, null, 2),
+				};
+			},
+		})
+	);
+
 	return resources;
 }
 
@@ -124,6 +172,7 @@ export function buildContractsPrompts() {
 						'3. Edit content and call contracts.update',
 						'4. Run contracts.validate to verify changes',
 						'5. Run contracts.build to regenerate artifacts',
+						'6. Use adoption.resolve to prefer existing workspace or ContractSpec surfaces before inventing new ones',
 						goal ? `Agent goal: ${goal}` : '',
 					]
 						.filter(Boolean)

package/src/application/mcp/contractsMcpTools.ts

@@ -11,6 +11,7 @@ import {
 	OperationSpecRegistry,
 } from '@contractspec/lib.contracts-spec';
 import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import { registerAdoptionOps } from './contractsMcpAdoptionTools';
 import type { ContractsMcpServices } from './contractsMcpTypes';
 
 const OWNERS = ['@contractspec'];
@@ -161,6 +162,7 @@ export function buildContractsOps(services: ContractsMcpServices) {
 	);
 
 	registerMutationTools(registry, services);
+	registerAdoptionOps(registry, services);
 
 	return registry;
 }

package/src/application/mcp/contractsMcpTypes.ts

@@ -44,4 +44,20 @@ export interface ContractsMcpServices {
 	): Promise<{ deleted: boolean; cleanedFiles: string[]; errors: string[] }>;
 
 	fetchRegistryManifest(): Promise<unknown>;
+
+	searchAdoptionCatalog(options: {
+		family?: string;
+		platform?: string;
+		query: string;
+	}): Promise<unknown[]>;
+
+	resolveAdoption(options: {
+		family: string;
+		paths?: string[];
+		platform?: string;
+		query: string;
+		runtime?: string;
+	}): Promise<unknown>;
+
+	syncAdoptionCatalog(): Promise<{ catalogPath: string; total: number }>;
 }

package/src/components/docs/docsManifest.ts

@@ -418,6 +418,18 @@ export const DOCS_PAGES: readonly DocsPageEntry[] = [
 		audience: 'operator',
 		ctaMode: 'oss-next',
 	},
+	{
+		href: '/docs/guides/release-capsules',
+		title: 'Author release capsules',
+		description:
+			'Pair changesets with structured release capsules, generate release artifacts, and keep changelog plus docs surfaces aligned.',
+		section: 'operate',
+		order: 25,
+		navTitle: 'Release capsules',
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'reference',
+	},
 	{
 		href: '/docs/safety/security-trust',
 		title: 'Security and trust',

package/src/components/docs/examples/DocsExamplesPage.tsx

@@ -8,8 +8,10 @@ import {
 } from '@contractspec/lib.design-system';
 import { HStack, VStack } from '@contractspec/lib.ui-kit-web/ui/stack';
 import { H1, Muted } from '@contractspec/lib.ui-kit-web/ui/typography';
-import { listExamples } from '@contractspec/module.examples';
-import { getExampleShowcaseData } from './exampleShowcaseData';
+import {
+	buildExampleDocsHref,
+	listPublicExamples,
+} from '@contractspec/module.examples';
 
 interface ExampleItem extends Record<string, unknown> {
 	id: string;
@@ -20,25 +22,15 @@ interface ExampleItem extends Record<string, unknown> {
 	sandboxEnabled: boolean;
 }
 
-function buildReferenceRoute(key: string) {
-	return `/docs/reference/${key}/${key}`;
-}
-
-function buildDocsRoute(key: string) {
-	return getExampleShowcaseData(key)?.sandboxHref
-		? `/docs/examples/${key}`
-		: buildReferenceRoute(key);
-}
-
 export function DocsExamplesPage() {
-	const items: ExampleItem[] = listExamples()
+	const items: ExampleItem[] = listPublicExamples()
 		.map((example) => {
 			const title = example.meta.title ?? example.meta.key;
 			return {
 				id: example.meta.key,
 				title,
 				summary: example.meta.summary ?? example.meta.description,
-				route: buildDocsRoute(example.meta.key),
+				route: buildExampleDocsHref(example.meta.key),
 				tags: example.meta.tags,
 				sandboxEnabled: example.surfaces.sandbox.enabled,
 			};

package/src/components/docs/examples/ExampleShowcasePage.tsx

@@ -5,7 +5,7 @@ import { FileCode2, Play, TerminalSquare } from 'lucide-react';
 import { getExampleShowcaseData } from './exampleShowcaseData';
 
 interface ExampleShowcasePageProps {
-	exampleKey: 'agent-console' | 'ai-chat-assistant' | 'messaging-agent-actions';
+	exampleKey: string;
 }
 
 export function ExampleShowcasePage({ exampleKey }: ExampleShowcasePageProps) {
@@ -28,7 +28,9 @@ export function ExampleShowcasePage({ exampleKey }: ExampleShowcasePageProps) {
 				<p className="editorial-subtitle">{showcase.lead}</p>
 				<p className="editorial-copy max-w-4xl">{summary}</p>
 				<div className="flex flex-wrap gap-3">
-					<ButtonLink href={showcase.sandboxHref}>Open sandbox</ButtonLink>
+					{showcase.sandboxHref ? (
+						<ButtonLink href={showcase.sandboxHref}>Open sandbox</ButtonLink>
+					) : null}
 					<ButtonLink href={showcase.referenceHref} variant="outline">
 						Generated reference
 					</ButtonLink>
@@ -36,21 +38,23 @@ export function ExampleShowcasePage({ exampleKey }: ExampleShowcasePageProps) {
 			</section>
 
 			<section className="grid gap-5 lg:grid-cols-3">
-				<article className="editorial-panel space-y-4">
-					<div className="flex items-center gap-3">
-						<div className="rounded-full border border-border/80 bg-background/85 p-2">
-							<Play size={18} />
+				{showcase.sandboxHref ? (
+					<article className="editorial-panel space-y-4">
+						<div className="flex items-center gap-3">
+							<div className="rounded-full border border-border/80 bg-background/85 p-2">
+								<Play size={18} />
+							</div>
+							<h2 className="font-semibold text-xl">Sandbox preview</h2>
 						</div>
-						<h2 className="font-semibold text-xl">Sandbox preview</h2>
-					</div>
-					<p className="editorial-copy text-sm">
-						Load the same public browser surface used for the prepared live
-						demo.
-					</p>
-					<ButtonLink href={showcase.sandboxHref} size="sm">
-						Open preview
-					</ButtonLink>
-				</article>
+						<p className="editorial-copy text-sm">
+							Load the same public browser surface used for the prepared live
+							demo.
+						</p>
+						<ButtonLink href={showcase.sandboxHref} size="sm">
+							Open preview
+						</ButtonLink>
+					</article>
+				) : null}
 
 				<article className="editorial-panel space-y-4">
 					<div className="flex items-center gap-3">
@@ -100,8 +104,8 @@ export function ExampleShowcasePage({ exampleKey }: ExampleShowcasePageProps) {
 						Exact local commands for the meetup lane
 					</h2>
 					<p className="editorial-copy text-sm">
-						Use the package build and test first, then launch the web shell and
-						open the prepared sandbox route.
+						Build the example package, then launch the web shell and open the
+						prepared docs or sandbox route.
 					</p>
 				</div>
 				<CodeBlock

package/src/components/docs/examples/exampleShowcaseData.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'bun:test';
+import { listPublicExamples } from '@contractspec/module.examples';
+import { getExampleShowcaseData } from './exampleShowcaseData';
+
+describe('example showcase data', () => {
+	test('builds showcase data for every public example', () => {
+		for (const example of listPublicExamples()) {
+			expect(getExampleShowcaseData(example.meta.key)).toBeDefined();
+		}
+	});
+
+	test('preserves override copy and generic fallback links', () => {
+		const dataGrid = getExampleShowcaseData('data-grid-showcase');
+		const calendar = getExampleShowcaseData('calendar-google');
+
+		expect(dataGrid?.lead).toContain('Canonical table example');
+		expect(calendar?.sandboxHref).toBe('/sandbox?template=calendar-google');
+		expect(calendar?.referenceHref).toBe(
+			'/docs/reference/calendar-google/calendar-google'
+		);
+	});
+});

package/src/components/docs/examples/exampleShowcaseData.ts

@@ -1,65 +1,90 @@
+import {
+	buildExampleDocsHref,
+	buildExampleReferenceHref,
+	getExamplePreviewHref,
+	getPublicExample,
+} from '@contractspec/module.examples';
+
 export interface ExampleShowcaseData {
-	key: 'agent-console' | 'ai-chat-assistant' | 'messaging-agent-actions';
+	key: string;
 	lead: string;
-	sandboxHref: string;
+	sandboxHref: string | null;
 	referenceHref: string;
 	llmsHref: string;
 	repoHref: string;
 	localCommands: string;
 }
 
-const EXAMPLE_SHOWCASES: Record<string, ExampleShowcaseData> = {
-	'agent-console': {
-		key: 'agent-console',
-		lead: 'Primary meetup path for autonomous agents: typed tools, agent configs, run history, and execution logs in one regenerable surface.',
-		sandboxHref: '/sandbox?template=agent-console',
-		referenceHref: '/docs/reference/agent-console/agent-console',
-		llmsHref: '/llms/example.agent-console',
-		repoHref:
-			'https://github.com/lssm-tech/contractspec/tree/main/packages/examples/agent-console',
-		localCommands: `bun run --cwd packages/examples/agent-console build
-bun run --cwd packages/examples/agent-console test
-bun run --cwd packages/apps/web-landing dev
-
-# Open in the browser
-# http://localhost:3000/sandbox?template=agent-console`,
-	},
-	'ai-chat-assistant': {
-		key: 'ai-chat-assistant',
-		lead: 'Secondary meetup path for MCP-aware assistants: reasoning, sources, suggestions, and a minimal contract-backed search tool.',
-		sandboxHref: '/sandbox?template=ai-chat-assistant',
-		referenceHref: '/docs/reference/ai-chat-assistant/assistant.search',
-		llmsHref: '/llms/example.ai-chat-assistant',
-		repoHref:
-			'https://github.com/lssm-tech/contractspec/tree/main/packages/examples/ai-chat-assistant',
-		localCommands: `bun run --cwd packages/examples/ai-chat-assistant build
-bun run --cwd packages/examples/ai-chat-assistant test
-bun run --cwd packages/apps/web-landing dev
-
-# Open in the browser
-# http://localhost:3000/sandbox?template=ai-chat-assistant`,
-	},
-	'messaging-agent-actions': {
-		key: 'messaging-agent-actions',
-		lead: 'Live messaging lane for the meetup: inbound Slack, WhatsApp, or Telegram messages route through fixed intents, allowlisted actions, and deterministic confirmations.',
-		sandboxHref: '/sandbox?template=messaging-agent-actions',
-		referenceHref:
-			'/docs/reference/messaging-agent-actions/messaging.agentActions.process',
-		llmsHref: '/llms/example.messaging-agent-actions',
-		repoHref:
-			'https://github.com/lssm-tech/contractspec/tree/main/packages/examples/messaging-agent-actions',
-		localCommands: `bun run --cwd packages/examples/messaging-agent-actions build
-bun run --cwd packages/examples/messaging-agent-actions test
-bun run --cwd packages/examples/messaging-agent-actions proof
-bun run --cwd packages/apps/web-landing dev
+const LEAD_OVERRIDES: Record<string, string> = {
+	'agent-console':
+		'Primary meetup path for autonomous agents: typed tools, agent configs, run history, and execution logs in one regenerable surface.',
+	'ai-chat-assistant':
+		'Secondary meetup path for MCP-aware assistants: reasoning, sources, suggestions, and a minimal contract-backed search tool.',
+	'data-grid-showcase':
+		'Canonical table example for the full ContractSpec stack: declarative DataView contract, shared controller, raw web primitive, native-first primitive, and the composed design-system wrapper.',
+	'messaging-agent-actions':
+		'Live messaging lane for the meetup: inbound Slack, WhatsApp, or Telegram messages route through fixed intents, allowlisted actions, and deterministic confirmations.',
+};
 
-# Open in the browser
-# http://localhost:3000/sandbox?template=messaging-agent-actions`,
-	},
+const REFERENCE_HREF_OVERRIDES: Record<string, string> = {
+	'agent-console': '/docs/reference/agent-console/agent-console',
+	'ai-chat-assistant': '/docs/reference/ai-chat-assistant/assistant.search',
+	'data-grid-showcase': '/docs/reference/data-grid-showcase/data-grid-showcase',
+	'messaging-agent-actions':
+		'/docs/reference/messaging-agent-actions/messaging.agentActions.process',
 };
 
 export function getExampleShowcaseData(
 	key: string
 ): ExampleShowcaseData | undefined {
-	return EXAMPLE_SHOWCASES[key];
+	const example = getPublicExample(key);
+
+	if (!example) {
+		return undefined;
+	}
+
+	const directory = example.entrypoints.packageName.replace(
+		'@contractspec/example.',
+		''
+	);
+	const docsHref = buildExampleDocsHref(key);
+	const sandboxHref = getExamplePreviewHref(key);
+
+	return {
+		key,
+		lead:
+			LEAD_OVERRIDES[key] ??
+			example.meta.summary ??
+			example.meta.description ??
+			'Public ContractSpec reference example.',
+		sandboxHref,
+		referenceHref:
+			REFERENCE_HREF_OVERRIDES[key] ?? buildExampleReferenceHref(key),
+		llmsHref: `/llms/${example.entrypoints.packageName.replace(
+			'@contractspec/',
+			''
+		)}`,
+		repoHref: `https://github.com/lssm-tech/contractspec/tree/main/packages/examples/${directory}`,
+		localCommands: buildLocalCommands(directory, docsHref, sandboxHref),
+	};
+}
+
+function buildLocalCommands(
+	directory: string,
+	docsHref: string,
+	sandboxHref: string | null
+): string {
+	const lines = [
+		`bun run --cwd packages/examples/${directory} build`,
+		'bun run --cwd packages/apps/web-landing dev',
+		'',
+		'# Open in the browser',
+		`# http://localhost:3000${docsHref}`,
+	];
+
+	if (sandboxHref) {
+		lines.push(`# http://localhost:3000${sandboxHref}`);
+	}
+
+	return lines.join('\n');
 }