@contractspec/bundle.library 1.11.1 → 1.13.0

package/dist/application/mcp/index.js

@@ -1,5 +1,697 @@
-import { createDocsMcpHandler } from "./docsMcp.js";
-import { createCliMcpHandler } from "./cliMcp.js";
-import { createInternalMcpHandler } from "./internalMcp.js";
+// @bun
+// src/application/mcp/common.ts
+import {
+  createMcpServer,
+  PresentationRegistry
+} from "@contractspec/lib.contracts";
+import { mcp } from "elysia-mcp";
+function createConsoleLikeLogger(logger) {
+  const isDebug = process.env.CONTRACTSPEC_MCP_DEBUG === "1";
+  const toMessage = (args) => args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+  return {
+    log: (...args) => {
+      if (!isDebug)
+        return;
+      logger.info(toMessage(args));
+    },
+    info: (...args) => {
+      if (!isDebug)
+        return;
+      logger.info(toMessage(args));
+    },
+    warn: (...args) => {
+      logger.warn(toMessage(args));
+    },
+    error: (...args) => {
+      logger.error(toMessage(args));
+    },
+    debug: (...args) => {
+      if (!isDebug)
+        return;
+      logger.debug(toMessage(args));
+    }
+  };
+}
+var baseCtx = {
+  actor: "anonymous",
+  decide: async () => ({ effect: "allow" })
+};
+function createMcpElysiaHandler({
+  logger,
+  path,
+  serverName,
+  ops,
+  resources,
+  prompts,
+  presentations
+}) {
+  logger.info("Setting up MCP handler...");
+  return mcp({
+    basePath: path,
+    logger: createConsoleLikeLogger(logger),
+    serverInfo: {
+      name: serverName,
+      version: "1.0.0"
+    },
+    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)
+      });
+    }
+  });
+}
 
-export { createCliMcpHandler, createDocsMcpHandler, createInternalMcpHandler };
+// src/infrastructure/elysia/logger.ts
+import { Logger, LogLevel } from "@contractspec/lib.logger";
+var createAppLogger = () => new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: true
+});
+var appLogger = createAppLogger();
+var dbLogger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: true
+});
+var authLogger = new Logger({
+  level: LogLevel.INFO,
+  environment: "development",
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: true
+});
+// src/features/docs/docs.contracts.ts
+import {
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery,
+  DocsIndexQuery as DocsIndexQuery2,
+  ContractReferenceQuery
+} from "@contractspec/lib.contracts/docs";
+// src/application/mcp/docsMcp.ts
+import {
+  defaultDocRegistry,
+  definePrompt,
+  defineResourceTemplate,
+  installOp,
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry
+} from "@contractspec/lib.contracts";
+import z from "zod";
+var DOC_OWNERS = ["@contractspec"];
+var DOC_TAGS = ["docs", "mcp"];
+function buildDocResources(routes) {
+  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",
+          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",
+          uri: "docs://list",
+          title: "DocBlocks index"
+        }
+      ];
+      return parts;
+    }
+  }));
+  return prompts;
+}
+function buildDocOps(routes) {
+  const registry = new OperationSpecRegistry;
+  installOp(registry, DocsIndexQuery, 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;
+}
+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)
+  });
+}
+
+// src/application/mcp/cliMcp.ts
+import fs from "fs/promises";
+import path from "path";
+import {
+  defineCommand,
+  definePrompt as definePrompt2,
+  defineResourceTemplate as defineResourceTemplate2,
+  installOp as installOp2,
+  OperationSpecRegistry as OperationSpecRegistry2,
+  PromptRegistry as PromptRegistry2,
+  ResourceRegistry as ResourceRegistry2
+} from "@contractspec/lib.contracts";
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+import z2 from "zod";
+var __dirname = "/home/runner/work/contractspec/contractspec/packages/bundles/library/src/application/mcp";
+var 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"
+};
+var CLI_DOC_FALLBACK = {
+  quickstart: `# ContractSpec CLI quickstart
+
+contractspec create
+contractspec build <spec>
+contractspec validate <spec>`,
+  reference: `# ContractSpec CLI reference
+
+Key commands: create, build, validate. See README for full options.`,
+  readme: `# ContractSpec CLI
+
+Stabilize AI-generated code across API, DB, UI, events. Use create/build/validate commands.`
+};
+var CLI_DOC_TAGS = ["cli", "mcp"];
+var CLI_OWNERS = ["@contractspec"];
+var candidateRoots = (() => {
+  const roots = new Set([
+    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];
+})();
+var docCache = new Map;
+async function loadCliDoc(key) {
+  if (docCache.has(key)) {
+    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 {}
+  }
+  const fallback = CLI_DOC_FALLBACK[key];
+  docCache.set(key, fallback);
+  return fallback;
+}
+function buildCliResources() {
+  const resources = new ResourceRegistry2;
+  resources.register(defineResourceTemplate2({
+    meta: {
+      uriTemplate: "cli://doc/{slug}",
+      title: "CLI documentation",
+      description: "Quickstart, reference, and README for the CLI.",
+      mimeType: "text/markdown",
+      tags: CLI_DOC_TAGS
+    },
+    input: z2.object({
+      slug: z2.enum(["quickstart", "reference", "readme"])
+    }),
+    resolve: async ({ slug }) => {
+      const data = await loadCliDoc(slug);
+      return {
+        uri: `cli://doc/${slug}`,
+        mimeType: "text/markdown",
+        data
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate2({
+    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: z2.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 PromptRegistry2;
+  prompts.register(definePrompt2({
+    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: z2.string().optional()
+      }
+    ],
+    input: z2.object({ goal: z2.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", uri: "cli://commands", title: "Commands" },
+      {
+        type: "resource",
+        uri: "cli://doc/quickstart",
+        title: "Quickstart"
+      }
+    ]
+  }));
+  return prompts;
+}
+function buildCliOps() {
+  const registry = new OperationSpecRegistry2;
+  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"
+    }
+  });
+  installOp2(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;
+}
+function createCliMcpHandler(path2 = "/api/mcp/cli") {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path: path2,
+    serverName: "contractspec-cli-mcp",
+    ops: buildCliOps(),
+    resources: buildCliResources(),
+    prompts: buildCliPrompts()
+  });
+}
+
+// src/application/mcp/internalMcp.ts
+import {
+  defineCommand as defineCommand2,
+  definePrompt as definePrompt3,
+  defineResourceTemplate as defineResourceTemplate3,
+  installOp as installOp3,
+  OperationSpecRegistry as OperationSpecRegistry3,
+  PromptRegistry as PromptRegistry3,
+  ResourceRegistry as ResourceRegistry3
+} from "@contractspec/lib.contracts";
+import { defineSchemaModel as defineSchemaModel2, ScalarTypeEnum as ScalarTypeEnum2 } from "@contractspec/lib.schema";
+import z3 from "zod";
+import {
+  getExample,
+  listExamples,
+  searchExamples
+} from "@contractspec/module.examples";
+var INTERNAL_TAGS = ["internal", "mcp"];
+var INTERNAL_OWNERS = ["@contractspec"];
+var ENDPOINTS = {
+  docs: "/api/mcp/docs",
+  cli: "/api/mcp/cli",
+  internal: "/api/mcp/internal",
+  graphql: "/graphql",
+  health: "/health"
+};
+function buildInternalResources() {
+  const resources = new ResourceRegistry3;
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "examples://list{?q}",
+      title: "ContractSpec examples registry",
+      description: "List available examples (templates, integrations, knowledge, scripts). Optional query `q` filters results.",
+      mimeType: "application/json",
+      tags: ["examples", ...INTERNAL_TAGS]
+    },
+    input: z3.object({ q: z3.string().optional() }),
+    resolve: async ({ q }) => {
+      const items = q ? searchExamples(q) : [...listExamples()];
+      return {
+        uri: q ? `examples://list?q=${encodeURIComponent(q)}` : "examples://list",
+        mimeType: "application/json",
+        data: JSON.stringify(items, null, 2)
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "examples://example/{id}",
+      title: "ContractSpec example (by id)",
+      description: "Fetch a single example manifest by id.",
+      mimeType: "application/json",
+      tags: ["examples", ...INTERNAL_TAGS]
+    },
+    input: z3.object({ id: z3.string().min(1) }),
+    resolve: async ({ id }) => {
+      const example = getExample(id);
+      if (!example) {
+        return {
+          uri: `examples://example/${encodeURIComponent(id)}`,
+          mimeType: "application/json",
+          data: JSON.stringify({ error: "not_found", id, message: `Unknown example id: ${id}` }, null, 2)
+        };
+      }
+      return {
+        uri: `examples://example/${encodeURIComponent(id)}`,
+        mimeType: "application/json",
+        data: JSON.stringify(example, null, 2)
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "internal://endpoints",
+      title: "ContractSpec MCP endpoints",
+      description: "Endpoints for docs, CLI, internal MCP servers.",
+      mimeType: "application/json",
+      tags: INTERNAL_TAGS
+    },
+    input: z3.object({}),
+    resolve: async () => ({
+      uri: "internal://endpoints",
+      mimeType: "application/json",
+      data: JSON.stringify(ENDPOINTS, null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "internal://playbook",
+      title: "Internal MCP usage playbook",
+      description: "How internal agents should discover docs, CLI usage, and endpoints.",
+      mimeType: "text/markdown",
+      tags: INTERNAL_TAGS
+    },
+    input: z3.object({}),
+    resolve: async () => ({
+      uri: "internal://playbook",
+      mimeType: "text/markdown",
+      data: [
+        "# Internal MCP playbook",
+        "- Connect to docs MCP first for canonical specs.",
+        "- Use CLI MCP to surface quickstart/reference before running commands.",
+        "- Keep calls read-only unless explicitly approved.",
+        `- Endpoints: ${ENDPOINTS.docs}, ${ENDPOINTS.cli}, ${ENDPOINTS.internal}.`,
+        "- For API work, GraphQL at /graphql; health at /health."
+      ].join(`
+`)
+    })
+  }));
+  return resources;
+}
+function buildInternalPrompts() {
+  const prompts = new PromptRegistry3;
+  prompts.register(definePrompt3({
+    meta: {
+      key: "internal.bootstrap",
+      version: "1.0.0",
+      title: "Bootstrap internal ContractSpec agent",
+      description: "Points agents to the correct MCP endpoints and guardrails.",
+      tags: INTERNAL_TAGS,
+      owners: INTERNAL_OWNERS,
+      stability: "beta"
+    },
+    args: [],
+    input: z3.object({}),
+    render: async () => [
+      {
+        type: "text",
+        text: "Start with internal://endpoints to pick the right MCP. Use docs MCP for specifications and CLI MCP for commands. Keep actions read-only unless explicitly approved."
+      },
+      {
+        type: "resource",
+        uri: "internal://endpoints",
+        title: "Endpoints"
+      }
+    ]
+  }));
+  return prompts;
+}
+function buildInternalOps() {
+  const registry = new OperationSpecRegistry3;
+  const InternalDescribeOutput = defineSchemaModel2({
+    name: "InternalDescribeOutput",
+    fields: {
+      endpoints: {
+        type: ScalarTypeEnum2.JSONObject(),
+        isOptional: false
+      },
+      notes: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+    }
+  });
+  const describeSpec = defineCommand2({
+    meta: {
+      key: "internal.describe",
+      version: "1.0.0",
+      stability: "stable",
+      owners: INTERNAL_OWNERS,
+      tags: INTERNAL_TAGS,
+      description: "Return MCP endpoints and guidance for internal ContractSpec agents.",
+      goal: "Speed up internal development with the correct MCP entrypoints.",
+      context: "Used by internal MCP surface; read-only."
+    },
+    io: {
+      input: defineSchemaModel2({
+        name: "InternalDescribeInput",
+        fields: {}
+      }),
+      output: InternalDescribeOutput
+    },
+    policy: {
+      auth: "anonymous"
+    }
+  });
+  installOp3(registry, describeSpec, async () => ({
+    endpoints: ENDPOINTS,
+    notes: "Use docs MCP for canonical specs, CLI MCP for contractspec commands, and keep side-effecting actions gated behind human review."
+  }));
+  return registry;
+}
+function createInternalMcpHandler(path2 = "/api/mcp/internal") {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path: path2,
+    serverName: "contractspec-internal-mcp",
+    ops: buildInternalOps(),
+    resources: buildInternalResources(),
+    prompts: buildInternalPrompts()
+  });
+}
+export {
+  createInternalMcpHandler,
+  createDocsMcpHandler,
+  createCliMcpHandler
+};