@contractspec/bundle.library 3.8.2 → 3.8.5

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

@@ -0,0 +1,521 @@
+// 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.prompts.ts
+import { definePrompt, PromptRegistry } from "@contractspec/lib.contracts-spec";
+import z from "zod";
+var DOC_OWNERS = ["@contractspec"];
+var DOC_TAGS = ["docs", "mcp"];
+function buildDocPrompts(routes) {
+  const prompts = new PromptRegistry;
+  prompts.register(definePrompt({
+    meta: {
+      key: "docs.navigator",
+      version: "1.0.0",
+      title: "Find relevant ContractSpec docs",
+      description: "Guide agents to search, filter, and open the right ContractSpec docs.",
+      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: "kind",
+        description: "Optional doc kind filter.",
+        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(),
+      kind: z.string().optional(),
+      tag: z.string().optional()
+    }),
+    render: async ({ topic, kind, tag }) => {
+      const matches = searchDocs(routes, {
+        query: topic,
+        kind,
+        tag,
+        limit: 3
+      });
+      const suggestedDocs = matches.docs.length ? matches.docs.map((doc) => `- ${doc.title} (${doc.id}) -> ${doc.route}`).join(`
+`) : "- No direct pre-match. Use docs_list_facets-v1_0_0 to browse tags and kinds.";
+      return [
+        {
+          type: "text",
+          text: [
+            "Use docs_search-v1_0_0 first, then read docs://doc/{id} for the strongest matches.",
+            "Use docs_resolve_route-v1_0_0 when the user already gives you a docs URL or route.",
+            "Use docs_list_facets-v1_0_0 or docs://facets to browse the docs taxonomy before guessing.",
+            topic ? `Topic: ${topic}` : "",
+            kind ? `Kind: ${kind}` : "",
+            tag ? `Tag: ${tag}` : "",
+            "Suggested starting docs:",
+            suggestedDocs
+          ].filter(Boolean).join(`
+`)
+        },
+        {
+          type: "resource",
+          uri: "docs://index",
+          title: "DocBlocks index"
+        },
+        {
+          type: "resource",
+          uri: "docs://facets",
+          title: "Docs facets"
+        }
+      ];
+    }
+  }));
+  prompts.register(definePrompt({
+    meta: {
+      key: "docs.reference.guide",
+      version: "1.0.0",
+      title: "Resolve a ContractSpec reference",
+      description: "Guide agents to fetch the canonical reference payload for a ContractSpec surface.",
+      tags: DOC_TAGS,
+      stability: "beta",
+      owners: DOC_OWNERS
+    },
+    args: [
+      {
+        name: "key",
+        description: "ContractSpec key to resolve.",
+        required: true,
+        schema: z.string()
+      },
+      {
+        name: "version",
+        description: "Optional version override.",
+        required: false,
+        schema: z.string().optional()
+      },
+      {
+        name: "type",
+        description: "Optional surface type: command, query, form, data-view, presentation, event.",
+        required: false,
+        schema: z.string().optional()
+      }
+    ],
+    input: z.object({
+      key: z.string(),
+      version: z.string().optional(),
+      type: z.string().optional()
+    }),
+    render: async ({ key, version, type }) => {
+      const reference = resolveContractReference({
+        key,
+        version,
+        type,
+        includeSchema: true
+      }).reference;
+      return [
+        {
+          type: "text",
+          text: [
+            "Use docs_contract_reference-v1_0_0 when you need the canonical docs payload for a ContractSpec surface.",
+            "Use docs_get-v1_0_0 only when you already know the exact DocBlock id and need raw markdown.",
+            `Resolved key: ${reference.key}`,
+            `Resolved type: ${reference.type}`,
+            reference.route ? `Docs route: ${reference.route}` : "",
+            `Resource URI: docs://contract-reference/${encodeURIComponent(key)}`
+          ].filter(Boolean).join(`
+`)
+        },
+        {
+          type: "resource",
+          uri: `docs://contract-reference/${encodeURIComponent(key)}`,
+          title: "Contract reference"
+        }
+      ];
+    }
+  }));
+  return prompts;
+}
+export {
+  buildDocPrompts
+};