@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/__tests__/env-setup.ts

@@ -0,0 +1,4 @@
+// Set dummy env var using a value that satisfies the Prisma client check
+process.env.CONTRACTSPEC_STUDIO_POSTGRES_PRISMA_URL =
+  'postgresql://postgres:postgres@localhost:5432/studio';
+console.log('[library env-setup] Env var set');

package/src/__tests__/mocks/prisma.ts

@@ -0,0 +1,94 @@
+import { vi } from 'bun:test';
+
+type MockFn = ReturnType<typeof vi.fn>;
+
+function createModel<T extends string>(
+  methods: readonly T[]
+): Record<T, MockFn> {
+  return methods.reduce<Record<T, MockFn>>(
+    (acc, method) => {
+      acc[method] = vi.fn();
+      return acc;
+    },
+    {} as Record<T, MockFn>
+  );
+}
+
+export const prismaMock = {
+  organizationLifecycleProfile: createModel([
+    'upsert',
+    'findUnique',
+    'findUniqueOrThrow',
+    'create',
+    'update',
+  ] as const),
+  lifecycleAssessment: createModel(['findMany', 'create'] as const),
+  lifecycleMilestoneProgress: createModel([
+    'findMany',
+    'findFirst',
+    'create',
+    'update',
+  ] as const),
+  studioProject: createModel([
+    'findMany',
+    'findFirst',
+    'create',
+    'update',
+  ] as const),
+  studioSpec: createModel([
+    'count',
+    'findMany',
+    'findUnique',
+    'create',
+    'update',
+    'findFirst',
+  ] as const),
+  studioOverlay: createModel([
+    'count',
+    'findFirst',
+    'create',
+    'findUnique',
+    'update',
+  ] as const),
+  studioIntegration: createModel([
+    'count',
+    'findMany',
+    'findFirst',
+    'findUnique',
+    'findUniqueOrThrow',
+    'create',
+    'update',
+    'updateMany',
+  ] as const),
+  knowledgeSource: createModel(['create', 'findMany', 'count'] as const),
+  studioDeployment: createModel([
+    'create',
+    'aggregate',
+    'findMany',
+    'update',
+    'findFirst',
+    'findUnique',
+  ] as const),
+  evolutionSession: createModel(['create', 'update'] as const),
+  organization: createModel(['findFirst'] as const),
+  $transaction: vi.fn(async (actions: Promise<unknown>[]) =>
+    Promise.all(actions)
+  ),
+};
+
+export function resetPrismaMock() {
+  resetObject(prismaMock);
+  prismaMock.$transaction.mockImplementation(
+    async (actions: Promise<unknown>[]) => Promise.all(actions)
+  );
+}
+
+function resetObject(target: Record<string, unknown>) {
+  Object.values(target).forEach((value) => {
+    if (typeof value === 'function' && 'mockReset' in value) {
+      (value as ReturnType<typeof vi.fn>).mockReset();
+    } else if (value && typeof value === 'object') {
+      resetObject(value as Record<string, unknown>);
+    }
+  });
+}

package/src/__tests__/setup.ts

@@ -0,0 +1,11 @@
+import { afterEach, beforeEach } from 'bun:test';
+import { resetPrismaMock } from './mocks/prisma';
+
+// Reset mocks before each test
+beforeEach(() => {
+  resetPrismaMock();
+});
+
+afterEach(() => {
+  resetPrismaMock();
+});

package/src/application/index.ts

@@ -0,0 +1 @@
+export * from './mcp';

package/src/application/mcp/cliMcp.ts

@@ -0,0 +1,273 @@
+import fs from 'node:fs/promises';
+import path from 'path';
+import {
+  defineCommand,
+  definePrompt,
+  defineResourceTemplate,
+  installOp,
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry,
+} from '@contractspec/lib.contracts';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import z from 'zod';
+import { createMcpElysiaHandler } from './common';
+import { appLogger } from '../../infrastructure/elysia/logger';
+
+const CLI_DOC_PATHS = {
+  quickstart: 'packages/apps/cli-contractspec/QUICK_START.md',
+  reference: 'packages/apps/cli-contractspec/QUICK_REFERENCE.md',
+  readme: 'packages/apps/cli-contractspec/README.md',
+};
+
+const CLI_DOC_FALLBACK = {
+  quickstart:
+    '# ContractSpec CLI quickstart\n\ncontractspec create\ncontractspec build <spec>\ncontractspec validate <spec>',
+  reference:
+    '# ContractSpec CLI reference\n\nKey commands: create, build, validate. See README for full options.',
+  readme:
+    '# ContractSpec CLI\n\nStabilize AI-generated code across API, DB, UI, events. Use create/build/validate commands.',
+};
+
+const CLI_DOC_TAGS = ['cli', 'mcp'];
+const CLI_OWNERS = ['@contractspec'];
+
+const candidateRoots = (() => {
+  const roots = new Set<string>([
+    process.cwd(),
+    path.resolve(process.cwd(), '..'),
+    path.resolve(process.cwd(), '../..'),
+    path.resolve(process.cwd(), '../../..'),
+  ]);
+  if (typeof __dirname === 'string') {
+    roots.add(path.resolve(__dirname, '../../../../..'));
+  }
+  return [...roots];
+})();
+
+const docCache = new Map<string, string>();
+
+async function loadCliDoc(key: keyof typeof CLI_DOC_PATHS): Promise<string> {
+  if (docCache.has(key)) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return docCache.get(key)!;
+  }
+
+  const relative = CLI_DOC_PATHS[key];
+  for (const root of candidateRoots) {
+    const candidate = path.resolve(root, relative);
+    try {
+      const data = await fs.readFile(candidate, 'utf8');
+      docCache.set(key, data);
+      return data;
+    } catch {
+      // try next candidate
+    }
+  }
+
+  const fallback = CLI_DOC_FALLBACK[key];
+  docCache.set(key, fallback);
+  return fallback;
+}
+
+function buildCliResources() {
+  const resources = new ResourceRegistry();
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'cli://doc/{slug}',
+        title: 'CLI documentation',
+        description: 'Quickstart, reference, and README for the CLI.',
+        mimeType: 'text/markdown',
+        tags: CLI_DOC_TAGS,
+      },
+      input: z.object({
+        slug: z.enum(['quickstart', 'reference', 'readme']),
+      }),
+      resolve: async ({ slug }) => {
+        const data = await loadCliDoc(slug);
+        return {
+          uri: `cli://doc/${slug}`,
+          mimeType: 'text/markdown',
+          data,
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'cli://commands',
+        title: 'CLI commands summary',
+        description: 'Key ContractSpec CLI commands and when to use them.',
+        mimeType: 'application/json',
+        tags: CLI_DOC_TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => {
+        const commands = [
+          {
+            command: 'contractspec create',
+            summary: 'Interactive wizard to author specs (with optional AI).',
+            doc: 'cli://doc/quickstart',
+          },
+          {
+            command: 'contractspec build <specPath>',
+            summary:
+              'Generate implementation code from a ContractSpec (agents + templates).',
+            doc: 'cli://doc/reference',
+          },
+          {
+            command: 'contractspec validate <specPath>',
+            summary:
+              'Validate specs and optionally check implementations against them.',
+            doc: 'cli://doc/reference',
+          },
+        ];
+
+        return {
+          uri: 'cli://commands',
+          mimeType: 'application/json',
+          data: JSON.stringify(commands, null, 2),
+        };
+      },
+    })
+  );
+
+  return resources;
+}
+
+function buildCliPrompts() {
+  const prompts = new PromptRegistry();
+
+  prompts.register(
+    definePrompt({
+      meta: {
+        key: 'cli.usage',
+        version: '1.0.0',
+        title: 'Use ContractSpec CLI safely',
+        description:
+          'Remind agents to read CLI docs and pick commands from the canonical list.',
+        tags: CLI_DOC_TAGS,
+        stability: 'beta',
+        owners: CLI_OWNERS,
+      },
+      args: [
+        {
+          name: 'goal',
+          description: 'Task the user wants to achieve.',
+          required: false,
+          schema: z.string().optional(),
+        },
+      ],
+      input: z.object({ goal: z.string().optional() }),
+      render: async ({ goal }) => [
+        {
+          type: 'text',
+          text: `Use CLI commands only from cli://commands. Prefer quickstart for newcomers and reference for options.${goal ? ` Goal: ${goal}.` : ''}`,
+        },
+        { type: 'resource' as const, uri: 'cli://commands', title: 'Commands' },
+        {
+          type: 'resource' as const,
+          uri: 'cli://doc/quickstart',
+          title: 'Quickstart',
+        },
+      ],
+    })
+  );
+
+  return prompts;
+}
+
+function buildCliOps() {
+  const registry = new OperationSpecRegistry();
+
+  const CliSuggestInput = defineSchemaModel({
+    name: 'CliSuggestInput',
+    fields: {
+      goal: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      prefersAi: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    },
+  });
+
+  const CliSuggestOutput = defineSchemaModel({
+    name: 'CliSuggestOutput',
+    fields: {
+      command: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      docUri: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    },
+  });
+
+  const suggestSpec = defineCommand({
+    meta: {
+      key: 'cli.suggestCommand',
+      version: '1.0.0',
+      stability: 'stable',
+      owners: CLI_OWNERS,
+      tags: CLI_DOC_TAGS,
+      description: 'Recommend a CLI command for the requested goal.',
+      goal: 'Help AI agents choose the correct CLI entrypoint quickly.',
+      context: 'Used inside the CLI MCP server.',
+    },
+    io: {
+      input: CliSuggestInput,
+      output: CliSuggestOutput,
+    },
+    policy: {
+      auth: 'anonymous',
+    },
+  });
+
+  installOp(registry, suggestSpec, async ({ goal, prefersAi }) => {
+    const lower = goal.toLowerCase();
+
+    if (lower.includes('create') || lower.includes('new')) {
+      return {
+        command: prefersAi ? 'contractspec create --ai' : 'contractspec create',
+        docUri: 'cli://doc/quickstart',
+        reason:
+          'Creates a new ContractSpec interactively (optionally with AI).',
+      };
+    }
+
+    if (lower.includes('build') || lower.includes('generate')) {
+      return {
+        command: 'contractspec build <path-to-spec>',
+        docUri: 'cli://doc/reference',
+        reason:
+          'Builds implementation code from a spec using agents + templates.',
+      };
+    }
+
+    if (lower.includes('validate') || lower.includes('check')) {
+      return {
+        command: 'contractspec validate <path-to-spec>',
+        docUri: 'cli://doc/reference',
+        reason:
+          'Validates a spec and optionally checks its implementation for drift.',
+      };
+    }
+
+    return {
+      command: 'contractspec --help',
+      docUri: 'cli://doc/readme',
+      reason: 'Fallback when the goal is unclear; read README for options.',
+    };
+  });
+
+  return registry;
+}
+
+export function createCliMcpHandler(path = '/api/mcp/cli') {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path,
+    serverName: 'contractspec-cli-mcp',
+    ops: buildCliOps(),
+    resources: buildCliResources(),
+    prompts: buildCliPrompts(),
+  });
+}

package/src/application/mcp/common.ts

@@ -0,0 +1,128 @@
+import type {
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry,
+} from '@contractspec/lib.contracts';
+import {
+  createMcpServer,
+  PresentationRegistry,
+} from '@contractspec/lib.contracts';
+import type { PresentationSpec } from '@contractspec/lib.contracts/presentations';
+import { mcp } from 'elysia-mcp';
+import { Logger } from '@contractspec/lib.logger';
+
+function createConsoleLikeLogger(logger: Logger) {
+  const isDebug = process.env.CONTRACTSPEC_MCP_DEBUG === '1';
+
+  const toMessage = (args: unknown[]) =>
+    args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ');
+
+  return {
+    log: (...args: unknown[]) => {
+      if (!isDebug) return;
+      logger.info(toMessage(args));
+    },
+    info: (...args: unknown[]) => {
+      if (!isDebug) return;
+      logger.info(toMessage(args));
+    },
+    warn: (...args: unknown[]) => {
+      logger.warn(toMessage(args));
+    },
+    error: (...args: unknown[]) => {
+      logger.error(toMessage(args));
+    },
+    debug: (...args: unknown[]) => {
+      if (!isDebug) return;
+      logger.debug(toMessage(args));
+    },
+  };
+}
+
+interface McpHttpHandlerConfig {
+  path: string;
+  serverName: string;
+  ops: OperationSpecRegistry;
+  resources: ResourceRegistry;
+  prompts: PromptRegistry;
+  presentations?: PresentationSpec[];
+  logger: Logger;
+}
+
+const baseCtx = {
+  actor: 'anonymous' as const,
+  decide: async () => ({ effect: 'allow' as const }),
+};
+
+// export function createMcpNextjsHandler({
+//   path,
+//   serverName,
+//   ops,
+//   resources,
+//   prompts,
+//   presentationsV2,
+// }: McpHttpHandlerConfig) {
+//   return createMcpHandler(
+//     (server) => {
+//       createMcpServer(server, ops, resources, prompts, {
+//         toolCtx: () => baseCtx,
+//         promptCtx: () => ({ locale: 'en' }),
+//         resourceCtx: () => ({ locale: 'en' }),
+//         presentationsV2,
+//       });
+//     },
+//     {
+//       serverInfo: {
+//         name: serverName,
+//         version: '1.0.0',
+//       },
+//     },
+//     {
+//       // basePath: path,
+//       disableSse: true,
+//       verboseLogs: true,
+//     }
+//   );
+// }
+
+export function createMcpElysiaHandler({
+  logger,
+  path,
+  serverName,
+  ops,
+  resources,
+  prompts,
+  presentations,
+}: McpHttpHandlerConfig) {
+  logger.info('Setting up MCP handler...');
+  return mcp({
+    basePath: path,
+    // Do NOT use console.* in production paths; adapt to console-like interface for the plugin.
+    logger: createConsoleLikeLogger(logger),
+    serverInfo: {
+      name: serverName,
+      version: '1.0.0',
+    },
+    // Cursor MCP HTTP clients may not persist Mcp-Session-Id headers reliably.
+    // Run in stateless + JSON response mode by default to maximize compatibility.
+    // Set CONTRACTSPEC_MCP_STATEFUL=1 to restore sessionful behavior.
+    stateless: process.env.CONTRACTSPEC_MCP_STATEFUL !== '1',
+    enableJsonResponse: true,
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+      logging: {},
+    },
+    setupServer: (server) => {
+      logger.info('Setting up MCP server...');
+      createMcpServer(server, ops, resources, prompts, {
+        logger,
+        toolCtx: () => baseCtx,
+        promptCtx: () => ({ locale: 'en' }),
+        resourceCtx: () => ({ locale: 'en' }),
+        presentations: new PresentationRegistry(presentations),
+      });
+    },
+  });
+}

package/src/application/mcp/docsMcp.ts

@@ -0,0 +1,193 @@
+import {
+  defaultDocRegistry,
+  definePrompt,
+  defineResourceTemplate,
+  installOp,
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry,
+} from '@contractspec/lib.contracts';
+import z from 'zod';
+import type { DocPresentationRoute } from '@contractspec/lib.contracts/docs';
+import { createMcpElysiaHandler } from './common';
+import { appLogger } from '../../infrastructure/elysia/logger';
+import { docsSearchSpec } from '../../features/docs';
+
+const DOC_OWNERS = ['@contractspec'];
+const DOC_TAGS = ['docs', 'mcp'];
+
+function buildDocResources(routes: DocPresentationRoute[]) {
+  const resources = new ResourceRegistry();
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'docs://list',
+        title: 'DocBlocks index',
+        description:
+          'All registered DocBlocks with route, visibility, tags, and summary.',
+        mimeType: 'application/json',
+        tags: DOC_TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => {
+        const docs = routes.map(({ block, route }) => ({
+          id: block.id,
+          title: block.title,
+          summary: block.summary ?? '',
+          tags: block.tags ?? [],
+          visibility: block.visibility ?? 'public',
+          route,
+        }));
+
+        return {
+          uri: 'docs://list',
+          mimeType: 'application/json',
+          data: JSON.stringify(docs, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'docs://doc/{id}',
+        title: 'DocBlock markdown',
+        description: 'Fetch DocBlock body by id as markdown.',
+        mimeType: 'text/markdown',
+        tags: DOC_TAGS,
+      },
+      input: z.object({ id: z.string() }),
+      resolve: async ({ id }) => {
+        const found = defaultDocRegistry.get(id);
+        if (!found) {
+          return {
+            uri: `docs://doc/${encodeURIComponent(id)}`,
+            mimeType: 'text/plain',
+            data: `DocBlock not found: ${id}`,
+          };
+        }
+
+        return {
+          uri: `docs://doc/${encodeURIComponent(id)}`,
+          mimeType: 'text/markdown',
+          data: String(found.block.body ?? ''),
+        };
+      },
+    })
+  );
+
+  return resources;
+}
+
+function buildDocPrompts() {
+  const prompts = new PromptRegistry();
+
+  prompts.register(
+    definePrompt({
+      meta: {
+        key: 'docs.navigator',
+        version: '1.0.0',
+        title: 'Find relevant ContractSpec docs',
+        description: 'Guide agents to pick the right DocBlock by topic or tag.',
+        tags: DOC_TAGS,
+        stability: 'beta',
+        owners: DOC_OWNERS,
+      },
+      args: [
+        {
+          name: 'topic',
+          description: 'Goal or subject to search for.',
+          required: false,
+          schema: z.string().optional(),
+        },
+        {
+          name: 'tag',
+          description: 'Optional tag filter.',
+          required: false,
+          schema: z.string().optional(),
+        },
+      ],
+      input: z.object({
+        topic: z.string().optional(),
+        tag: z.string().optional(),
+      }),
+      render: async ({ topic, tag }) => {
+        const parts = [
+          {
+            type: 'text' as const,
+            text: `Use the docs index to choose DocBlocks. If a specific topic is provided, prefer docs whose id/title/summary match it.${topic ? ` Topic: ${topic}.` : ''}${tag ? ` Tag: ${tag}.` : ''}`,
+          },
+          {
+            type: 'resource' as const,
+            uri: 'docs://list',
+            title: 'DocBlocks index',
+          },
+        ];
+        return parts;
+      },
+    })
+  );
+
+  return prompts;
+}
+
+function buildDocOps(routes: DocPresentationRoute[]) {
+  const registry = new OperationSpecRegistry();
+
+  // Use the module-level spec from docs.contracts.ts
+  installOp(registry, docsSearchSpec, async (args) => {
+    const query = args.query?.toLowerCase().trim();
+    const tagsFilter = args.tag?.map((t) => t.toLowerCase().trim()) ?? [];
+    const visibility = args.visibility?.toLowerCase().trim();
+
+    const docs = routes
+      .map(({ block, route }) => ({
+        id: block.id,
+        title: block.title,
+        summary: block.summary ?? '',
+        tags: block.tags ?? [],
+        visibility: (block.visibility ?? 'public').toLowerCase(),
+        route,
+      }))
+      .filter((doc) => {
+        const matchesQuery = query
+          ? doc.id.toLowerCase().includes(query) ||
+            doc.title.toLowerCase().includes(query) ||
+            doc.summary.toLowerCase().includes(query)
+          : true;
+        const matchesTags = tagsFilter.length
+          ? tagsFilter.every((t) =>
+              doc.tags.some((tag) => tag.toLowerCase().includes(t))
+            )
+          : true;
+        const matchesVisibility = visibility
+          ? doc.visibility === visibility
+          : true;
+        return matchesQuery && matchesTags && matchesVisibility;
+      });
+
+    return {
+      docs,
+      items: docs,
+      total: docs.length,
+    };
+  });
+
+  return registry;
+}
+
+export function createDocsMcpHandler(path = '/api/mcp/docs') {
+  const routes = defaultDocRegistry.list();
+
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path,
+    serverName: 'contractspec-docs-mcp',
+    ops: buildDocOps(routes),
+    resources: buildDocResources(routes),
+    prompts: buildDocPrompts(),
+    presentations: routes.map(({ descriptor }) => descriptor),
+  });
+}