@contractspec/bundle.library 3.8.12 → 3.9.2

package/src/application/mcp/cliMcp.onboarding.ts

@@ -0,0 +1,297 @@
+import { createNodeAdapters, onboarding } from '@contractspec/bundle.workspace';
+import {
+	defineCommand,
+	definePrompt,
+	defineResourceTemplate,
+	installOp,
+	type OperationSpecRegistry,
+	type PromptRegistry,
+	type ResourceRegistry,
+} from '@contractspec/lib.contracts-spec';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import z from 'zod';
+
+const ONBOARDING_TAGS = ['cli', 'mcp', 'onboarding'];
+const ONBOARDING_OWNERS = ['@contractspec'];
+
+function parseTrackIds(tracks: string | undefined) {
+	return tracks
+		?.split(',')
+		.map((track) => track.trim())
+		.filter(Boolean) as onboarding.OnboardingTrackId[] | undefined;
+}
+
+async function buildPlan(args: { tracks?: string; example?: string } = {}) {
+	const adapters = createNodeAdapters({
+		cwd: process.cwd(),
+		silent: true,
+	});
+	return onboarding.buildOnboardingPlan(adapters, {
+		forcedExampleKey: args.example,
+		selectedTracks: parseTrackIds(args.tracks),
+	});
+}
+
+export function registerCliOnboardingResources(resources: ResourceRegistry) {
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'onboarding://tracks',
+				title: 'Onboarding tracks',
+				description:
+					'Primary ContractSpec onboarding tracks exposed by the CLI.',
+				mimeType: 'application/json',
+				tags: ONBOARDING_TAGS,
+			},
+			input: z.object({}),
+			resolve: async () => ({
+				uri: 'onboarding://tracks',
+				mimeType: 'application/json',
+				data: JSON.stringify(onboarding.listOnboardingTracks(), null, 2),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'onboarding://track/{id}',
+				title: 'Onboarding track',
+				description:
+					'Track-specific onboarding metadata and recommended commands.',
+				mimeType: 'application/json',
+				tags: ONBOARDING_TAGS,
+			},
+			input: z.object({ id: z.string() }),
+			resolve: async ({ id }) => ({
+				uri: `onboarding://track/${id}`,
+				mimeType: 'application/json',
+				data: JSON.stringify(
+					onboarding.getOnboardingTrack(id) ?? null,
+					null,
+					2
+				),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'onboarding://artifacts/{id}{?tracks,example}',
+				title: 'Rendered onboarding artifact',
+				description:
+					'Render AGENTS.md or USAGE.md content for the current repo.',
+				mimeType: 'text/markdown',
+				tags: ONBOARDING_TAGS,
+			},
+			input: z.object({
+				example: z.string().optional(),
+				id: z.enum(['agent-guide', 'human-guide']),
+				tracks: z.string().optional(),
+			}),
+			resolve: async ({ example, id, tracks }) => {
+				const plan = await buildPlan({ example, tracks });
+				return {
+					uri: `onboarding://artifacts/${id}`,
+					mimeType: 'text/markdown',
+					data:
+						id === 'agent-guide'
+							? plan.guides.agentGuide
+							: plan.guides.humanGuide,
+				};
+			},
+		})
+	);
+}
+
+export function registerCliOnboardingPrompts(prompts: PromptRegistry) {
+	prompts.register(
+		definePrompt({
+			meta: {
+				key: 'cli.onboarding',
+				version: '1.0.0',
+				title: 'Plan a ContractSpec onboarding flow',
+				description:
+					'Suggest the right onboarding track and artifacts for a repo.',
+				tags: ONBOARDING_TAGS,
+				stability: 'beta',
+				owners: ONBOARDING_OWNERS,
+			},
+			args: [
+				{
+					name: 'goal',
+					description: 'Repository onboarding goal or focus area.',
+					required: false,
+					schema: z.string().optional(),
+				},
+			],
+			input: z.object({ goal: z.string().optional() }),
+			render: async ({ goal }) => [
+				{
+					type: 'text',
+					text: `Use onboarding://tracks and onboarding_suggestTracks-v1_0_0 before recommending repo-local ContractSpec adoption steps.${goal ? ` Goal: ${goal}.` : ''}`,
+				},
+				{
+					type: 'resource' as const,
+					uri: 'onboarding://tracks',
+					title: 'Tracks',
+				},
+			],
+		})
+	);
+}
+
+export function registerCliOnboardingOps(registry: OperationSpecRegistry) {
+	const SuggestTracksInput = defineSchemaModel({
+		name: 'OnboardingSuggestTracksInput',
+		fields: {
+			example: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+			tracks: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		},
+	});
+	const SuggestTracksOutput = defineSchemaModel({
+		name: 'OnboardingSuggestTracksOutput',
+		fields: {
+			nextCommands: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isArray: true,
+				isOptional: false,
+			},
+			primaryTrack: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+			reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			tracks: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isArray: true,
+				isOptional: false,
+			},
+		},
+	});
+	const RenderArtifactsOutput = defineSchemaModel({
+		name: 'OnboardingRenderArtifactOutput',
+		fields: {
+			content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			primaryTrack: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+		},
+	});
+	const NextCommandOutput = defineSchemaModel({
+		name: 'OnboardingNextCommandOutput',
+		fields: {
+			nextCommand: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+			primaryTrack: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+		},
+	});
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'onboarding.suggestTracks',
+				version: '1.0.0',
+				stability: 'stable',
+				owners: ONBOARDING_OWNERS,
+				tags: ONBOARDING_TAGS,
+				description: 'Suggest the recommended ContractSpec onboarding tracks.',
+				goal: 'Help agents choose the right onboarding track before editing repo-local guides.',
+				context: 'Used inside the CLI MCP server.',
+			},
+			io: { input: SuggestTracksInput, output: SuggestTracksOutput },
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ example, tracks }) => {
+			const plan = await buildPlan({ example, tracks });
+			return {
+				nextCommands: plan.nextCommands,
+				primaryTrack: plan.primaryTrack.id,
+				reason: plan.recommendations[0]?.reason ?? plan.primaryTrack.summary,
+				tracks: plan.recommendations.map(
+					(recommendation) => recommendation.track.id
+				),
+			};
+		}
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'onboarding.renderArtifacts',
+				version: '1.0.0',
+				stability: 'stable',
+				owners: ONBOARDING_OWNERS,
+				tags: ONBOARDING_TAGS,
+				description: 'Render onboarding artifacts for the current repo.',
+				goal: 'Provide AGENTS.md or USAGE.md content without mutating the repo.',
+				context: 'Used inside the CLI MCP server.',
+			},
+			io: {
+				input: defineSchemaModel({
+					name: 'OnboardingRenderArtifactInput',
+					fields: {
+						artifact: {
+							type: ScalarTypeEnum.String_unsecure(),
+							isOptional: false,
+						},
+						example: {
+							type: ScalarTypeEnum.String_unsecure(),
+							isOptional: true,
+						},
+						tracks: {
+							type: ScalarTypeEnum.String_unsecure(),
+							isOptional: true,
+						},
+					},
+				}),
+				output: RenderArtifactsOutput,
+			},
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ artifact, example, tracks }) => {
+			const plan = await buildPlan({ example, tracks });
+			return {
+				content:
+					artifact === 'agent-guide'
+						? plan.guides.agentGuide
+						: plan.guides.humanGuide,
+				primaryTrack: plan.primaryTrack.id,
+			};
+		}
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'onboarding.nextCommand',
+				version: '1.0.0',
+				stability: 'stable',
+				owners: ONBOARDING_OWNERS,
+				tags: ONBOARDING_TAGS,
+				description: 'Return the next recommended CLI command for onboarding.',
+				goal: 'Help agents choose the next onboarding command without mutating the repo.',
+				context: 'Used inside the CLI MCP server.',
+			},
+			io: { input: SuggestTracksInput, output: NextCommandOutput },
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ example, tracks }) => {
+			const plan = await buildPlan({ example, tracks });
+			return {
+				nextCommand: plan.nextCommands[0] ?? 'contractspec onboard',
+				primaryTrack: plan.primaryTrack.id,
+			};
+		}
+	);
+}

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

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'bun:test';
+import { Elysia } from 'elysia';
+import { createCliMcpHandler } from './cliMcp';
+
+function createTestApp() {
+	return new Elysia().use(createCliMcpHandler('/mcp/cli'));
+}
+
+async function mcpRequest(
+	method: string,
+	params: Record<string, unknown> = {}
+) {
+	return createTestApp().handle(
+		new Request('http://localhost/mcp/cli', {
+			method: 'POST',
+			headers: {
+				accept: 'application/json',
+				'content-type': 'application/json',
+			},
+			body: JSON.stringify({
+				jsonrpc: '2.0',
+				id: 1,
+				method,
+				params,
+			}),
+		})
+	);
+}
+
+async function initialize() {
+	const response = await mcpRequest('initialize', {
+		protocolVersion: '2024-11-05',
+		capabilities: {},
+		clientInfo: { name: 'cli-mcp-test', version: '1.0.0' },
+	});
+	expect(response.status).toBe(200);
+}
+
+describe('cli MCP handler', () => {
+	it('exposes onboarding resources, prompts, and tools', async () => {
+		await initialize();
+
+		const toolsResponse = await mcpRequest('tools/list');
+		const toolsBody = await toolsResponse.json();
+		const toolNames = toolsBody.result.tools.map(
+			(tool: { name: string }) => tool.name
+		);
+		expect(toolNames).toContain('cli_suggestCommand-v1_0_0');
+		expect(toolNames).toContain('onboarding_suggestTracks-v1_0_0');
+		expect(toolNames).toContain('onboarding_renderArtifacts-v1_0_0');
+		expect(toolNames).toContain('onboarding_nextCommand-v1_0_0');
+
+		const promptsResponse = await mcpRequest('prompts/list');
+		const promptsBody = await promptsResponse.json();
+		const promptNames = promptsBody.result.prompts.map(
+			(prompt: { name: string }) => prompt.name
+		);
+		expect(promptNames).toContain('cli_usage');
+		expect(promptNames).toContain('cli_onboarding');
+
+		const resourcesResponse = await mcpRequest('resources/list');
+		const resourcesBody = await resourcesResponse.json();
+		const resourceUris = (resourcesBody.result.resources ?? []).map(
+			(resource: { uri?: string; uriTemplate?: string }) =>
+				resource.uriTemplate ?? resource.uri
+		);
+		expect(resourceUris).toContain('cli://commands');
+		expect(resourceUris).toContain('onboarding://tracks');
+	});
+
+	it('renders onboarding artifacts and next-command guidance', async () => {
+		await initialize();
+
+		const artifactResponse = await mcpRequest('tools/call', {
+			name: 'onboarding_renderArtifacts-v1_0_0',
+			arguments: {
+				artifact: 'human-guide',
+				tracks: 'knowledge',
+			},
+		});
+		const artifactBody = await artifactResponse.json();
+		const artifactResult = JSON.parse(artifactBody.result.content[0].text);
+		expect(artifactResult.primaryTrack).toBe('knowledge');
+		expect(artifactResult.content).toContain('ContractSpec Repo Onboarding');
+
+		const nextCommandResponse = await mcpRequest('tools/call', {
+			name: 'onboarding_nextCommand-v1_0_0',
+			arguments: {
+				tracks: 'ai-agents',
+			},
+		});
+		const nextCommandBody = await nextCommandResponse.json();
+		const nextCommandResult = JSON.parse(
+			nextCommandBody.result.content[0].text
+		);
+		expect(nextCommandResult.primaryTrack).toBe('ai-agents');
+		expect(nextCommandResult.nextCommand).toContain('contractspec onboard');
+	});
+});

package/src/application/mcp/cliMcp.ts

@@ -12,6 +12,11 @@ import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 import path from 'path';
 import z from 'zod';
 import { appLogger } from '../../infrastructure/elysia/logger';
+import {
+	registerCliOnboardingOps,
+	registerCliOnboardingPrompts,
+	registerCliOnboardingResources,
+} from './cliMcp.onboarding';
 import { createMcpElysiaHandler } from './common';
 
 const CLI_DOC_PATHS = {
@@ -22,11 +27,11 @@ const CLI_DOC_PATHS = {
 
 const CLI_DOC_FALLBACK = {
 	quickstart:
-		'# ContractSpec CLI quickstart\n\ncontractspec create\ncontractspec build <spec>\ncontractspec validate <spec>',
+		'# ContractSpec CLI quickstart\n\ncontractspec quickstart\ncontractspec onboard\ncontractspec validate',
 	reference:
-		'# ContractSpec CLI reference\n\nKey commands: create, build, validate. See README for full options.',
+		'# ContractSpec CLI reference\n\nKey commands: onboard, create, generate, validate. See README for full options.',
 	readme:
-		'# ContractSpec CLI\n\nStabilize AI-generated code across API, DB, UI, events. Use create/build/validate commands.',
+		'# ContractSpec CLI\n\nStabilize AI-generated code across API, DB, UI, events. Use onboard/create/generate/validate commands.',
 };
 
 const CLI_DOC_TAGS = ['cli', 'mcp'];
@@ -108,6 +113,12 @@ function buildCliResources() {
 			input: z.object({}),
 			resolve: async () => {
 				const commands = [
+					{
+						command: 'contractspec onboard',
+						summary:
+							'Generate repo-local AGENTS.md and USAGE.md guidance plus recommended tracks.',
+						doc: 'cli://doc/quickstart',
+					},
 					{
 						command: 'contractspec create',
 						summary: 'Interactive wizard to author specs (with optional AI).',
@@ -136,6 +147,7 @@ function buildCliResources() {
 		})
 	);
 
+	registerCliOnboardingResources(resources);
 	return resources;
 }
 
@@ -178,6 +190,7 @@ function buildCliPrompts() {
 		})
 	);
 
+	registerCliOnboardingPrompts(prompts);
 	return prompts;
 }
 
@@ -224,6 +237,19 @@ function buildCliOps() {
 	installOp(registry, suggestSpec, async ({ goal, prefersAi }) => {
 		const lower = goal.toLowerCase();
 
+		if (
+			lower.includes('onboard') ||
+			lower.includes('start') ||
+			lower.includes('guide') ||
+			lower.includes('install')
+		) {
+			return {
+				command: 'contractspec onboard',
+				docUri: 'cli://doc/quickstart',
+				reason: 'Starts the CLI-first onboarding flow for the current repo.',
+			};
+		}
+
 		if (lower.includes('create') || lower.includes('new')) {
 			return {
 				command: prefersAi ? 'contractspec create --ai' : 'contractspec create',
@@ -258,6 +284,7 @@ function buildCliOps() {
 		};
 	});
 
+	registerCliOnboardingOps(registry);
 	return registry;
 }
 

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()
+	);
+}