@contractspec/bundle.library 3.8.4 → 3.8.5

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

@@ -0,0 +1,518 @@
+// 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.tools.ts
+import {
+  defineCommand,
+  defineSchemaModel,
+  installOp,
+  OperationSpecRegistry as OperationSpecRegistry2
+} from "@contractspec/lib.contracts-spec";
+import {
+  ContractReferenceInput,
+  ContractReferenceOutput,
+  DocsIndexInput,
+  DocsIndexOutput
+} from "@contractspec/lib.contracts-spec/docs";
+import { ScalarTypeEnum } from "@contractspec/lib.schema";
+var DOC_OWNERS = ["@contractspec"];
+var DOC_TAGS = ["docs", "mcp"];
+var DocsGetInput = defineSchemaModel({
+  name: "DocsGetInput",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var DocsGetOutput = defineSchemaModel({
+  name: "DocsGetOutput",
+  fields: {
+    doc: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var DocsResolveRouteInput = defineSchemaModel({
+  name: "DocsResolveRouteInput",
+  fields: {
+    route: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var DocsResolveRouteOutput = defineSchemaModel({
+  name: "DocsResolveRouteOutput",
+  fields: {
+    doc: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var DocsFacetsInput = defineSchemaModel({
+  name: "DocsFacetsInput",
+  fields: {}
+});
+var DocsFacetsOutput = defineSchemaModel({
+  name: "DocsFacetsOutput",
+  fields: {
+    facets: { type: ScalarTypeEnum.JSON(), isOptional: false }
+  }
+});
+function buildDocOps(routes) {
+  const registry = new OperationSpecRegistry2;
+  installOp(registry, defineCommand({
+    meta: {
+      key: "docs.search",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS,
+      tags: DOC_TAGS,
+      description: "Search ContractSpec docs by query, tag, kind, or visibility.",
+      goal: "Find the most relevant DocBlocks without browsing the full corpus.",
+      context: "Read-only docs MCP search surface."
+    },
+    io: { input: DocsIndexInput, output: DocsIndexOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_search-v1_0_0" } }
+  }), async (args) => searchDocs(routes, args));
+  installOp(registry, defineCommand({
+    meta: {
+      key: "docs.get",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS,
+      tags: DOC_TAGS,
+      description: "Read a single DocBlock by id.",
+      goal: "Fetch the exact markdown content and metadata for a known doc id.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: DocsGetInput, output: DocsGetOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_get-v1_0_0" } }
+  }), async ({ id }) => {
+    const found = getDocById(id);
+    if (!found)
+      throw new Error(`DocBlock not found: ${id}`);
+    return found;
+  });
+  installOp(registry, defineCommand({
+    meta: {
+      key: "docs.resolveRoute",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS,
+      tags: DOC_TAGS,
+      description: "Resolve a docs route to the matching DocBlock.",
+      goal: "Turn a route or URL path into a canonical doc id and markdown body.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: DocsResolveRouteInput, output: DocsResolveRouteOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_resolve_route-v1_0_0" } }
+  }), async ({ route }) => {
+    const found = getDocByRoute(routes, route);
+    if (!found)
+      throw new Error(`Doc route not found: ${route}`);
+    return found;
+  });
+  installOp(registry, defineCommand({
+    meta: {
+      key: "docs.contract.lookup",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS,
+      tags: DOC_TAGS,
+      description: "Resolve a ContractSpec surface into a docs-ready reference payload.",
+      goal: "Get canonical docs metadata, route, and optional schema for a spec key.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: ContractReferenceInput, output: ContractReferenceOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_contract_reference-v1_0_0" } }
+  }), async (args) => resolveContractReference(args));
+  installOp(registry, defineCommand({
+    meta: {
+      key: "docs.list.facets",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS,
+      tags: DOC_TAGS,
+      description: "List docs taxonomy facets such as tags, kinds, and visibilities.",
+      goal: "Help agents browse the docs corpus before making targeted reads.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: DocsFacetsInput, output: DocsFacetsOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_list_facets-v1_0_0" } }
+  }), async () => ({ facets: listDocFacets(routes) }));
+  return registry;
+}
+export {
+  buildDocOps
+};