@contractspec/bundle.library 3.8.4 → 3.8.5

package/dist/node/application/mcp/docsMcp.resources.js

@@ -0,0 +1,519 @@
+// src/application/mcp/docsMcp.data.ts
+import { defaultDocRegistry } from "@contractspec/lib.contracts-spec/docs";
+var DEFAULT_LIMIT = 20;
+var MAX_LIMIT = 100;
+function normalizeText(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+function normalizeRoute(route) {
+  const decoded = decodeURIComponent(route).trim();
+  if (!decoded)
+    return "/";
+  return decoded.startsWith("/") ? decoded : `/${decoded}`;
+}
+function normalizeTags(value) {
+  const tags = Array.isArray(value) ? value : value ? [value] : [];
+  return tags.map((tag) => normalizeText(tag)).filter(Boolean);
+}
+function clampLimit(limit) {
+  if (!limit || Number.isNaN(limit))
+    return DEFAULT_LIMIT;
+  return Math.min(Math.max(limit, 1), MAX_LIMIT);
+}
+function clampOffset(offset) {
+  if (!offset || Number.isNaN(offset))
+    return 0;
+  return Math.max(offset, 0);
+}
+function toDocSummary({ block, route }) {
+  return {
+    id: block.id,
+    title: block.title,
+    summary: block.summary ?? "",
+    route,
+    visibility: block.visibility ?? "public",
+    kind: block.kind ?? "reference",
+    version: block.version ?? "1.0.0",
+    tags: block.tags ?? []
+  };
+}
+function scoreDoc(route, query) {
+  if (!query)
+    return 1;
+  const tokens = query.split(/\s+/).filter(Boolean);
+  const title = normalizeText(route.block.title);
+  const id = normalizeText(route.block.id);
+  const summary = normalizeText(route.block.summary);
+  const body = normalizeText(route.block.body);
+  const path = normalizeText(route.route);
+  const tags = (route.block.tags ?? []).map((tag) => normalizeText(tag));
+  const haystack = [title, id, summary, body, path, ...tags].join(" ");
+  if (tokens.some((token) => !haystack.includes(token)))
+    return 0;
+  let score = 0;
+  for (const token of tokens) {
+    if (id.includes(token))
+      score += 8;
+    if (title.includes(token))
+      score += 7;
+    if (tags.some((tag) => tag.includes(token)))
+      score += 5;
+    if (summary.includes(token))
+      score += 4;
+    if (path.includes(token))
+      score += 3;
+    if (body.includes(token))
+      score += 2;
+  }
+  return score;
+}
+function searchDocs(routes, args) {
+  const query = normalizeText(typeof args.query === "string" ? args.query : undefined);
+  const tags = normalizeTags(args.tag);
+  const visibility = normalizeText(typeof args.visibility === "string" ? args.visibility : undefined);
+  const kind = normalizeText(typeof args.kind === "string" ? args.kind : undefined);
+  const limit = clampLimit(typeof args.limit === "number" ? args.limit : undefined);
+  const offset = clampOffset(typeof args.offset === "number" ? args.offset : undefined);
+  const ranked = routes.map((route) => ({
+    doc: toDocSummary(route),
+    score: scoreDoc(route, query)
+  })).filter(({ doc, score }) => {
+    const matchesQuery = query ? score > 0 : true;
+    const matchesTags = tags.length ? tags.every((tag) => doc.tags.some((docTag) => normalizeText(docTag).includes(tag))) : true;
+    const matchesVisibility = visibility ? normalizeText(doc.visibility) === visibility : true;
+    const matchesKind = kind ? normalizeText(doc.kind) === kind : true;
+    return matchesQuery && matchesTags && matchesVisibility && matchesKind;
+  }).sort((left, right) => {
+    if (right.score !== left.score)
+      return right.score - left.score;
+    return left.doc.title.localeCompare(right.doc.title);
+  });
+  const docs = ranked.slice(offset, offset + limit).map(({ doc }) => doc);
+  const nextOffset = offset + docs.length < ranked.length ? offset + docs.length : undefined;
+  return {
+    docs,
+    items: docs,
+    total: ranked.length,
+    ...nextOffset != null ? { nextOffset } : {}
+  };
+}
+function getDocById(id) {
+  const normalizedId = decodeURIComponent(id);
+  const found = defaultDocRegistry.get(normalizedId);
+  if (!found)
+    return;
+  return {
+    doc: toDocSummary(found),
+    content: String(found.block.body ?? "")
+  };
+}
+function getDocByRoute(routes, routePath) {
+  const normalizedPath = normalizeRoute(routePath);
+  const found = routes.find((route) => normalizeRoute(route.route) === normalizedPath);
+  if (!found)
+    return;
+  return {
+    doc: toDocSummary(found),
+    content: String(found.block.body ?? "")
+  };
+}
+function listDocFacets(routes) {
+  const tags = new Map;
+  const kinds = new Map;
+  const visibilities = new Map;
+  for (const route of routes) {
+    const kind = route.block.kind ?? "reference";
+    const visibility = route.block.visibility ?? "public";
+    kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+    visibilities.set(visibility, (visibilities.get(visibility) ?? 0) + 1);
+    for (const tag of route.block.tags ?? []) {
+      tags.set(tag, (tags.get(tag) ?? 0) + 1);
+    }
+  }
+  const toEntries = (values, key) => [...values.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).map(([value, count]) => ({ [key]: value, count }));
+  return {
+    totalDocs: routes.length,
+    tags: toEntries(tags, "tag"),
+    kinds: toEntries(kinds, "kind"),
+    visibilities: toEntries(visibilities, "visibility")
+  };
+}
+
+// src/features/contracts-registry.ts
+import {
+  EventRegistry,
+  OperationSpecRegistry
+} from "@contractspec/lib.contracts-spec";
+import {
+  DataViewRegistry
+} from "@contractspec/lib.contracts-spec/data-views";
+import {
+  ContractReferenceDataView,
+  ContractReferenceQuery,
+  DocsGenerateCommand,
+  DocsGeneratedEvent,
+  DocsIndexDataView,
+  DocsIndexQuery,
+  DocsLayoutPresentation,
+  DocsPublishCommand,
+  DocsPublishedEvent,
+  DocsReferencePagePresentation,
+  DocsSearchForm,
+  ExampleCatalogDataView
+} from "@contractspec/lib.contracts-spec/docs";
+import { FormRegistry } from "@contractspec/lib.contracts-spec/forms";
+import {
+  PresentationRegistry
+} from "@contractspec/lib.contracts-spec/presentations";
+import {
+  serializeDataViewSpec,
+  serializeEventSpec,
+  serializeFormSpec,
+  serializeOperationSpec,
+  serializePresentationSpec
+} from "@contractspec/lib.contracts-spec/serialization";
+var operationRegistry = null;
+function createContractSpecOperationRegistry() {
+  const registry = new OperationSpecRegistry;
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
+  return registry;
+}
+function getContractSpecOperationRegistry() {
+  if (!operationRegistry) {
+    operationRegistry = createContractSpecOperationRegistry();
+  }
+  return operationRegistry;
+}
+function resolveOperationSpec(key, version) {
+  return getContractSpecOperationRegistry().get(key, version);
+}
+var eventRegistry = null;
+function createContractSpecEventRegistry() {
+  const registry = new EventRegistry;
+  registry.register(DocsGeneratedEvent).register(DocsPublishedEvent);
+  return registry;
+}
+function getContractSpecEventRegistry() {
+  if (!eventRegistry) {
+    eventRegistry = createContractSpecEventRegistry();
+  }
+  return eventRegistry;
+}
+function resolveEventSpec(key, version) {
+  return getContractSpecEventRegistry().get(key, version);
+}
+var presentationRegistry = null;
+function createContractSpecPresentationRegistry() {
+  const registry = new PresentationRegistry;
+  registry.register(DocsLayoutPresentation).register(DocsReferencePagePresentation);
+  return registry;
+}
+function getContractSpecPresentationRegistry() {
+  if (!presentationRegistry) {
+    presentationRegistry = createContractSpecPresentationRegistry();
+  }
+  return presentationRegistry;
+}
+function resolvePresentationSpec(key, version) {
+  return getContractSpecPresentationRegistry().get(key, version);
+}
+var dataViewRegistry = null;
+function createContractSpecDataViewRegistry() {
+  const registry = new DataViewRegistry;
+  registry.register(DocsIndexDataView).register(ContractReferenceDataView).register(ExampleCatalogDataView);
+  return registry;
+}
+function getContractSpecDataViewRegistry() {
+  if (!dataViewRegistry) {
+    dataViewRegistry = createContractSpecDataViewRegistry();
+  }
+  return dataViewRegistry;
+}
+function resolveDataViewSpec(key, version) {
+  return getContractSpecDataViewRegistry().get(key, version);
+}
+var formRegistry = null;
+function createContractSpecFormRegistry() {
+  const registry = new FormRegistry;
+  registry.register(DocsSearchForm);
+  return registry;
+}
+function getContractSpecFormRegistry() {
+  if (!formRegistry) {
+    formRegistry = createContractSpecFormRegistry();
+  }
+  return formRegistry;
+}
+function resolveFormSpec(key, _version) {
+  return getContractSpecFormRegistry().get(key);
+}
+function resolveSerializedOperationSpec(key, version) {
+  const spec = resolveOperationSpec(key, version);
+  return serializeOperationSpec(spec) ?? undefined;
+}
+function resolveSerializedEventSpec(key, version) {
+  const spec = resolveEventSpec(key, version);
+  return serializeEventSpec(spec) ?? undefined;
+}
+function resolveSerializedPresentationSpec(key, version) {
+  const spec = resolvePresentationSpec(key, version);
+  return serializePresentationSpec(spec) ?? undefined;
+}
+function resolveSerializedDataViewSpec(key, version) {
+  const spec = resolveDataViewSpec(key, version);
+  return serializeDataViewSpec(spec) ?? undefined;
+}
+function resolveSerializedFormSpec(key, version) {
+  const spec = resolveFormSpec(key, version);
+  return serializeFormSpec(spec) ?? undefined;
+}
+function resetContractSpecOperationRegistry() {
+  operationRegistry = null;
+}
+function resetContractSpecEventRegistry() {
+  eventRegistry = null;
+}
+function resetContractSpecPresentationRegistry() {
+  presentationRegistry = null;
+}
+function resetContractSpecDataViewRegistry() {
+  dataViewRegistry = null;
+}
+function resetContractSpecFormRegistry() {
+  formRegistry = null;
+}
+function resetAllContractSpecRegistries() {
+  resetContractSpecOperationRegistry();
+  resetContractSpecEventRegistry();
+  resetContractSpecPresentationRegistry();
+  resetContractSpecDataViewRegistry();
+  resetContractSpecFormRegistry();
+}
+
+// src/application/mcp/docsMcp.reference.ts
+import { defaultDocRegistry as defaultDocRegistry2 } from "@contractspec/lib.contracts-spec/docs";
+function normalizeText2(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+function routeFromDocIds(docIds) {
+  for (const docId of docIds ?? []) {
+    const doc = defaultDocRegistry2.get(docId);
+    if (doc)
+      return doc.route;
+  }
+  return;
+}
+function toReference(spec, type, schema, policy) {
+  const title = spec.meta.title ?? spec.meta.key;
+  const route = routeFromDocIds(spec.meta.docId);
+  const description = spec.meta.description;
+  return {
+    key: spec.meta.key,
+    version: spec.meta.version,
+    type,
+    title,
+    description,
+    markdown: [
+      `# ${title}`,
+      `- Key: ${spec.meta.key}`,
+      `- Type: ${type}`,
+      `- Version: ${spec.meta.version}`,
+      route ? `- Docs route: ${route}` : "",
+      description ? `
+${description}` : ""
+    ].filter(Boolean).join(`
+`),
+    ...route ? { route } : {},
+    ...schema ? { schema } : {},
+    ...policy ? { policy } : {},
+    tags: spec.meta.tags ?? [],
+    owners: spec.meta.owners ?? [],
+    stability: spec.meta.stability
+  };
+}
+function resolveContractReference(args) {
+  const includeSchema = args.includeSchema ?? false;
+  const requestedType = normalizeText2(args.type);
+  const operation = resolveOperationSpec(args.key, args.version);
+  if (operation && (!requestedType || requestedType === "operation" || requestedType === operation.meta.kind)) {
+    return {
+      reference: toReference(operation, operation.meta.kind, includeSchema ? resolveSerializedOperationSpec(args.key, args.version) : undefined, operation.policy)
+    };
+  }
+  const resolvers = [
+    {
+      type: "data-view",
+      spec: resolveDataViewSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedDataViewSpec(args.key, args.version) : undefined
+    },
+    {
+      type: "form",
+      spec: resolveFormSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedFormSpec(args.key, args.version) : undefined
+    },
+    {
+      type: "presentation",
+      spec: resolvePresentationSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedPresentationSpec(args.key, args.version) : undefined
+    },
+    {
+      type: "event",
+      spec: resolveEventSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedEventSpec(args.key, args.version) : undefined
+    }
+  ];
+  for (const candidate of resolvers) {
+    if (candidate.spec && (!requestedType || requestedType === candidate.type)) {
+      return {
+        reference: toReference(candidate.spec, candidate.type, candidate.schema)
+      };
+    }
+  }
+  throw new Error(`Contract reference not found: ${args.key}`);
+}
+
+// src/application/mcp/docsMcp.resources.ts
+import {
+  defineResourceTemplate,
+  ResourceRegistry
+} from "@contractspec/lib.contracts-spec";
+import z from "zod";
+var DOC_TAGS = ["docs", "mcp"];
+function buildDocResources(routes) {
+  const resources = new ResourceRegistry;
+  const readDocIndex = (input) => searchDocs(routes, input);
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://index",
+      title: "DocBlocks index",
+      description: "Default ContractSpec docs index resource.",
+      mimeType: "application/json",
+      tags: DOC_TAGS
+    },
+    input: z.object({}),
+    resolve: async () => ({
+      uri: "docs://index",
+      mimeType: "application/json",
+      data: JSON.stringify(readDocIndex({}), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://index{?query,tag,kind,visibility,limit,offset}",
+      title: "DocBlocks index",
+      description: "Search and paginate ContractSpec docs by query, tag, kind, or visibility.",
+      mimeType: "application/json",
+      tags: DOC_TAGS
+    },
+    input: z.object({
+      query: z.string().optional(),
+      tag: z.string().optional(),
+      kind: z.string().optional(),
+      visibility: z.string().optional(),
+      limit: z.coerce.number().optional(),
+      offset: z.coerce.number().optional()
+    }),
+    resolve: async (input) => ({
+      uri: "docs://index",
+      mimeType: "application/json",
+      data: JSON.stringify(readDocIndex(input), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://list",
+      title: "DocBlocks index (legacy alias)",
+      description: "Compatibility alias for the docs index resource.",
+      mimeType: "application/json",
+      tags: DOC_TAGS
+    },
+    input: z.object({}),
+    resolve: async () => ({
+      uri: "docs://list",
+      mimeType: "application/json",
+      data: JSON.stringify(readDocIndex({}), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://doc/{id}",
+      title: "Doc markdown",
+      description: "Fetch a single DocBlock body by id as markdown.",
+      mimeType: "text/markdown",
+      tags: DOC_TAGS
+    },
+    input: z.object({ id: z.string() }),
+    resolve: async ({ id }) => {
+      const found = getDocById(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: found.content
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://route/{routePath}",
+      title: "Doc by route",
+      description: "Resolve a docs route to the matching DocBlock summary and body.",
+      mimeType: "application/json",
+      tags: DOC_TAGS
+    },
+    input: z.object({ routePath: z.string() }),
+    resolve: async ({ routePath }) => ({
+      uri: `docs://route/${encodeURIComponent(routePath)}`,
+      mimeType: "application/json",
+      data: JSON.stringify(getDocByRoute(routes, routePath) ?? {
+        error: "not_found",
+        route: routePath
+      }, null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://facets",
+      title: "Docs facets",
+      description: "Counts of available tags, kinds, and visibilities across docs.",
+      mimeType: "application/json",
+      tags: DOC_TAGS
+    },
+    input: z.object({}),
+    resolve: async () => ({
+      uri: "docs://facets",
+      mimeType: "application/json",
+      data: JSON.stringify(listDocFacets(routes), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "docs://contract-reference/{key}{?version,type,includeSchema}",
+      title: "Contract reference",
+      description: "Resolve a ContractSpec surface into a docs-ready reference payload.",
+      mimeType: "application/json",
+      tags: DOC_TAGS
+    },
+    input: z.object({
+      key: z.string(),
+      version: z.string().optional(),
+      type: z.string().optional(),
+      includeSchema: z.coerce.boolean().optional()
+    }),
+    resolve: async ({ key, version, type, includeSchema }) => ({
+      uri: `docs://contract-reference/${encodeURIComponent(key)}`,
+      mimeType: "application/json",
+      data: JSON.stringify(resolveContractReference({ key, version, type, includeSchema }), null, 2)
+    })
+  }));
+  return resources;
+}
+export {
+  buildDocResources
+};