@contractspec/lib.contracts-spec 2.0.0

package/dist/docs/forms/index.js

@@ -0,0 +1,676 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/registry-utils.ts
+var exports_registry_utils = {};
+__export(exports_registry_utils, {
+  groupByToArray: () => groupByToArray,
+  groupByMultiple: () => groupByMultiple,
+  groupBy: () => groupBy,
+  getUniqueTags: () => getUniqueTags,
+  getUniqueOwners: () => getUniqueOwners,
+  getUniqueDomains: () => getUniqueDomains,
+  filterBy: () => filterBy,
+  GroupingStrategies: () => GroupingStrategies
+});
+function filterBy(items, filter) {
+  return items.filter((item) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.domain) {
+      const itemDomain = GroupingStrategies.byDomain(item);
+      if (itemDomain !== filter.domain)
+        return false;
+    }
+    if (filter.keyPattern) {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(name))
+        return false;
+    }
+    return true;
+  });
+}
+function groupBy(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupByToArray(items, keyFn) {
+  const map = groupBy(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
+}
+function groupByMultiple(items, keysFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const keys = keysFn(item);
+    for (const key of keys) {
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+  }
+  return groups;
+}
+function getUniqueTags(items) {
+  const tags = new Set;
+  for (const item of items) {
+    for (const tag of item.meta.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueOwners(items) {
+  const owners = new Set;
+  for (const item of items) {
+    for (const owner of item.meta.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueDomains(items) {
+  const domains = new Set;
+  for (const item of items) {
+    domains.add(GroupingStrategies.byDomain(item));
+  }
+  return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esm(() => {
+  GroupingStrategies = {
+    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+    byDomain: (item) => {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      return name.split(".")[0] ?? "default";
+    },
+    byStability: (item) => item.meta.stability ?? "stable",
+    byUrlPath: (level) => (item) => {
+      if (!item.path)
+        return "root";
+      const segments = item.path.split("/").filter(Boolean);
+      return segments.slice(0, level).join("/") || "root";
+    }
+  };
+});
+
+// src/ownership.ts
+var StabilityEnum = {
+  Idea: "idea",
+  InCreation: "in_creation",
+  Experimental: "experimental",
+  Beta: "beta",
+  Stable: "stable",
+  Deprecated: "deprecated"
+};
+var OwnersEnum = {
+  PlatformCore: "platform.core",
+  PlatformSigil: "platform.sigil",
+  PlatformMarketplace: "platform.marketplace",
+  PlatformMessaging: "platform.messaging",
+  PlatformContent: "platform.content",
+  PlatformFeatureFlags: "platform.featureflags",
+  PlatformFinance: "platform.finance"
+};
+var Owners = OwnersEnum;
+var TagsEnum = {
+  Spots: "spots",
+  Collectivity: "collectivity",
+  Marketplace: "marketplace",
+  Sellers: "sellers",
+  Auth: "auth",
+  Login: "login",
+  Signup: "signup",
+  Guide: "guide",
+  Docs: "docs",
+  I18n: "i18n",
+  Incident: "incident",
+  Automation: "automation",
+  Hygiene: "hygiene"
+};
+var Tags = TagsEnum;
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/docs/constants.ts
+var DOCS_DOMAIN = "docs";
+var DOCS_OWNERS = ["docs-platform"];
+var DOCS_TAGS = ["docs", "documentation"];
+var DOCS_STABILITY = StabilityEnum.Experimental;
+
+// src/docs/tech/docs-system.docblock.ts
+var docsSystemDocBlocks = [
+  {
+    id: "docs.tech.docs-system",
+    title: "Docs system overview",
+    summary: "How ContractSpec generates, indexes, and presents documentation.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/system",
+    tags: ["docs", "system", "contracts"],
+    body: `# Docs system overview
+
+ContractSpec treats documentation as a first-class output of your specs. The docs system combines:
+
+- Contract operations and schemas
+- DocBlocks (goal/how/usage/reference)
+- Presentations for rendering
+
+The result is a consistent docs surface across CLI, web, and MCP.
+
+## Key surfaces
+
+- Generation: \`docs.generate\`
+- Index/search: \`docs.search\`
+- Contract reference: \`docs.contract.reference\`
+- Publish: \`docs.publish\`
+`
+  },
+  {
+    id: "docs.tech.docs-generator",
+    title: "Docs generator",
+    summary: "Generate reference docs and metadata from ContractSpecs.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/docs/generator",
+    tags: ["docs", "generator", "cli"],
+    body: `# Docs generator
+
+The generator produces documentation artifacts from registered ContractSpecs and DocBlocks.
+
+## Outputs
+
+- Reference pages for operations, events, forms, data views, and presentations
+- Search index metadata (DocBlocks + routes)
+- Contract schemas rendered to markdown or JSON
+`
+  },
+  {
+    id: "docs.tech.docs-search",
+    title: "Docs index and search",
+    summary: "Search DocBlocks by query, tag, kind, or visibility.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/search",
+    tags: ["docs", "search"],
+    body: `# Docs index and search
+
+The docs index is the canonical list of DocBlocks exposed to UI and MCP surfaces.
+
+## Query
+
+- Operation: \`docs.search\`
+- Filters: query, tag, kind, visibility
+`
+  },
+  {
+    id: "docs.tech.docs-reference",
+    title: "Contract reference pages",
+    summary: "Resolve any spec into a docs-ready reference payload.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/reference",
+    tags: ["docs", "reference"],
+    body: `# Contract reference
+
+Contract reference pages are generated from spec metadata plus schema details.
+
+## Query
+
+- Operation: \`docs.contract.reference\`
+`
+  },
+  {
+    id: "docs.tech.docs-publish",
+    title: "Docs publish",
+    summary: "Publish generated artifacts to the docs host.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/docs/publish",
+    tags: ["docs", "publish"],
+    body: `# Docs publish
+
+Publishing moves generated artifacts to a hosting target with versioning.
+
+## Command
+
+- Operation: \`docs.publish\`
+`
+  },
+  {
+    id: "docs.tech.docs-examples",
+    title: "Examples catalog",
+    summary: "Document and surface example projects with sandbox support.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/examples",
+    tags: ["docs", "examples"],
+    body: `# Examples catalog
+
+Examples are registered as ExampleSpecs and surface DocBlocks for discovery.
+
+- Docs index tags should include \`examples\` to populate the catalog.
+- Sandbox support is available under \`/sandbox\`.
+`
+  }
+];
+registerDocBlocks(docsSystemDocBlocks);
+// src/forms/forms.ts
+import { compareVersions } from "compare-versions";
+function formKey(meta) {
+  return `${meta.key}.v${meta.version}`;
+}
+
+class FormRegistry {
+  items = new Map;
+  register(spec) {
+    const key = formKey(spec.meta);
+    if (this.items.has(key))
+      throw new Error(`Duplicate form ${key}`);
+    this.items.set(key, spec);
+    return this;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, v] of this.items.entries()) {
+      if (v.meta.key !== key)
+        continue;
+      if (!candidate || compareVersions(v.meta.version, candidate.meta.version) > 0) {
+        candidate = v;
+      }
+    }
+    return candidate;
+  }
+  filter(criteria) {
+    const { filterBy: filterBy2 } = (init_registry_utils(), __toCommonJS(exports_registry_utils));
+    return filterBy2(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((f) => f.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((f) => f.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    const { groupBy: groupBy2 } = (init_registry_utils(), __toCommonJS(exports_registry_utils));
+    return groupBy2(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    const { getUniqueTags: getUniqueTags2 } = (init_registry_utils(), __toCommonJS(exports_registry_utils));
+    return getUniqueTags2(this.list());
+  }
+}
+function getAtPath(values, path) {
+  if (!path)
+    return;
+  const segs = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  let cur = values;
+  for (const s of segs) {
+    if (cur == null)
+      return;
+    if (cur && typeof cur === "object" && s in cur) {
+      cur = cur[s];
+    } else {
+      return;
+    }
+  }
+  return cur;
+}
+function evalPredicate(values, pred) {
+  if (!pred)
+    return true;
+  if (pred.not)
+    return !evalPredicate(values, pred.not);
+  if (pred.all && pred.all.length)
+    return pred.all.every((p) => evalPredicate(values, p));
+  if (pred.anyOf && pred.anyOf.length)
+    return pred.anyOf.some((p) => evalPredicate(values, p));
+  if (pred.when) {
+    const { path, op = "truthy", value } = pred.when;
+    const v = getAtPath(values, path);
+    switch (op) {
+      case "equals":
+        return v === value;
+      case "notEquals":
+        return v !== value;
+      case "in":
+        return Array.isArray(value) && value.includes(v);
+      case "notIn":
+        return Array.isArray(value) && !value.includes(v);
+      case "gt":
+        return Number(v) > Number(value);
+      case "gte":
+        return Number(v) >= Number(value);
+      case "lt":
+        return Number(v) < Number(value);
+      case "lte":
+        return Number(v) <= Number(value);
+      case "empty":
+        return v == null || (Array.isArray(v) ? v.length === 0 : String(v).length === 0);
+      case "lengthGt":
+        return (Array.isArray(v) || typeof v === "string") && v.length > Number(value ?? 0);
+      case "lengthGte":
+        return (Array.isArray(v) || typeof v === "string") && v.length >= Number(value ?? 0);
+      case "lengthLt":
+        return (Array.isArray(v) || typeof v === "string") && v.length < Number(value ?? 0);
+      case "lengthLte":
+        return (Array.isArray(v) || typeof v === "string") && v.length <= Number(value ?? 0);
+      case "truthy":
+      default:
+        return Boolean(v);
+    }
+  }
+  return true;
+}
+function buildZodWithRelations(spec, handlers) {
+  const base = spec.model.getZod();
+  return base.superRefine((values, ctx) => {
+    const visit = (field, parentPath) => {
+      const path = field.name ? parentPath ? `${parentPath}.${field.name}` : field.name : parentPath ?? "";
+      if (field.requiredWhen) {
+        const should = evalPredicate(values, field.requiredWhen);
+        if (should) {
+          const v = getAtPath(values, path);
+          const empty = v == null || typeof v === "string" && v.trim().length === 0 || Array.isArray(v) && v.length === 0;
+          if (empty)
+            ctx.addIssue({
+              code: "custom",
+              path: path.split("."),
+              message: "required"
+            });
+        }
+      }
+      if (field.kind === "array") {
+        const arr = getAtPath(values, path);
+        if (field.min != null && Array.isArray(arr) && arr.length < field.min) {
+          ctx.addIssue({
+            code: "custom",
+            path: path.split("."),
+            message: `min:${field.min}`
+          });
+        }
+        if (field.max != null && Array.isArray(arr) && arr.length > field.max) {
+          ctx.addIssue({
+            code: "custom",
+            path: path.split("."),
+            message: `max:${field.max}`
+          });
+        }
+        visit(field.of, path);
+      } else if (field.kind === "group") {
+        for (const child of field.fields)
+          visit(child, path);
+      }
+    };
+    for (const f of spec.fields)
+      visit(f);
+    if (spec.constraints && handlers) {
+      for (const c of spec.constraints) {
+        const fn = handlers[c.key];
+        if (!fn)
+          continue;
+        const res = fn(values, c.paths, c.args);
+        if (!res.ok) {
+          ctx.addIssue({
+            code: "custom",
+            path: (res.path ?? c.paths[0] ?? "").split(".").filter(Boolean),
+            message: res.message ?? c.messageI18n
+          });
+        }
+      }
+    }
+  });
+}
+function defineFormSpec(spec) {
+  return spec;
+}
+
+// src/docs/forms/docsSearch.form.ts
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var DocsSearchFormModel = new SchemaModel({
+  name: "DocsSearchFormModel",
+  fields: {
+    query: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    visibility: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var DocsSearchForm = defineFormSpec({
+  meta: {
+    key: "docs.search.form",
+    title: "Docs Search",
+    version: "1.0.0",
+    description: "Search form for documentation discovery.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "search"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-search")]
+  },
+  model: DocsSearchFormModel,
+  fields: [
+    {
+      kind: "text",
+      name: "query",
+      labelI18n: "Search",
+      placeholderI18n: "Search docs"
+    },
+    {
+      kind: "select",
+      name: "visibility",
+      labelI18n: "Visibility",
+      options: {
+        kind: "static",
+        options: [
+          { labelI18n: "Public", value: "public" },
+          { labelI18n: "Internal", value: "internal" },
+          { labelI18n: "Mixed", value: "mixed" }
+        ]
+      }
+    },
+    {
+      kind: "select",
+      name: "kind",
+      labelI18n: "Kind",
+      options: {
+        kind: "static",
+        options: [
+          { labelI18n: "Goal", value: "goal" },
+          { labelI18n: "How", value: "how" },
+          { labelI18n: "Usage", value: "usage" },
+          { labelI18n: "Reference", value: "reference" },
+          { labelI18n: "FAQ", value: "faq" },
+          { labelI18n: "Changelog", value: "changelog" }
+        ]
+      }
+    }
+  ],
+  actions: [
+    {
+      key: "search",
+      labelI18n: "Search"
+    }
+  ],
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+export {
+  DocsSearchForm
+};

package/dist/docs/index.d.ts

@@ -0,0 +1,40 @@
+export * from './types';
+export * from './constants';
+export * from './commands';
+export * from './queries';
+export * from './events';
+export * from './capabilities';
+export * from './contracts';
+export * from './presentations';
+export * from './presentations/index';
+export * from './forms';
+export * from './views';
+export * from './registry';
+export * from './tech-contracts.docs';
+export * from './meta.docs';
+import './accessibility_wcag_compliance_specs.docblock';
+import './tech/lifecycle-stage-system.docblock';
+import './tech/presentation-runtime.docblock';
+import './tech/auth/better-auth-nextjs.docblock';
+import './tech/schema/README.docblock';
+import '../workflow/overview.docblock';
+import './tech/mcp-endpoints.docblock';
+import './tech/vscode-extension.docblock';
+import './tech/telemetry-ingest.docblock';
+import './tech/contracts/README.docblock';
+import './tech/contracts/openapi-export.docblock';
+import './tech/contracts/openapi-import.docblock';
+import '../workspace-config/workspace-config.docblock';
+import './tech/studio/workspaces.docblock';
+import './tech/studio/sandbox-unlogged.docblock';
+import './tech/studio/workspace-ops.docblock';
+import './tech/studio/project-routing.docblock';
+import './tech/studio/platform-admin-panel.docblock';
+import './tech/studio/learning-events.docblock';
+import './tech/studio/learning-journeys.docblock';
+import './tech/studio/project-access-teams.docblock';
+import './tech/studio/team-invitations.docblock';
+import './tech/llm/llm-integration.docblock';
+import './tech/cli.docblock';
+import './tech/docs-system.docblock';
+import './tech/report-verification-table.docblock';