@contractspec/lib.contracts-spec 2.0.0

package/dist/examples/registry.js

@@ -0,0 +1,286 @@
+// @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/registry.ts
+init_registry_utils();
+import { compareVersions } from "compare-versions";
+var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
+
+class SpecContractRegistry {
+  contractType;
+  items = new Map;
+  constructor(contractType, items) {
+    this.contractType = contractType;
+    if (items) {
+      items.forEach((p) => this.register(p));
+    }
+  }
+  register(p) {
+    const key = keyOfSpecContract(p);
+    if (this.items.has(key))
+      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
+    this.items.set(key, p);
+    return this;
+  }
+  count() {
+    return this.items.size;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, p] of this.items.entries()) {
+      if (!k.startsWith(`${key}.v`))
+        continue;
+      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
+        candidate = p;
+      }
+    }
+    return candidate;
+  }
+  has(key, version) {
+    return !!this.get(key, version);
+  }
+  filter(criteria) {
+    return filterBy(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((p) => p.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((p) => p.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    return groupBy(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    return getUniqueTags(this.list());
+  }
+}
+
+// src/examples/registry.ts
+class ExampleRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("example", items);
+  }
+  listByKind(kind) {
+    return this.list().filter((spec) => spec.meta.kind === kind);
+  }
+  listByVisibility(visibility) {
+    return this.list().filter((spec) => spec.meta.visibility === visibility);
+  }
+  listByDomain(domain) {
+    return this.list().filter((spec) => spec.meta.domain === domain);
+  }
+  listBySurface(surface) {
+    return this.list().filter((spec) => {
+      if (surface === "templates")
+        return spec.surfaces.templates;
+      if (surface === "sandbox")
+        return spec.surfaces.sandbox.enabled;
+      if (surface === "studio")
+        return spec.surfaces.studio.enabled;
+      if (surface === "mcp")
+        return spec.surfaces.mcp.enabled;
+      return false;
+    });
+  }
+  listInstallable() {
+    return this.list().filter((spec) => spec.surfaces.studio.installable);
+  }
+  groupByKind() {
+    const result = new Map;
+    for (const spec of this.list()) {
+      const existing = result.get(spec.meta.kind) ?? [];
+      existing.push(spec);
+      result.set(spec.meta.kind, existing);
+    }
+    return result;
+  }
+  getUniqueKinds() {
+    const kinds = new Set;
+    for (const spec of this.list()) {
+      kinds.add(spec.meta.kind);
+    }
+    return [...kinds];
+  }
+  getUniqueDomains() {
+    const domains = new Set;
+    for (const spec of this.list()) {
+      if (spec.meta.domain) {
+        domains.add(spec.meta.domain);
+      }
+    }
+    return [...domains];
+  }
+  search(query) {
+    const q = query.toLowerCase().trim();
+    if (!q)
+      return this.list();
+    return this.list().filter((spec) => {
+      const hay = [
+        spec.meta.key,
+        spec.meta.title ?? "",
+        spec.meta.description,
+        spec.meta.summary ?? "",
+        ...spec.meta.tags
+      ].join(" ").toLowerCase();
+      return hay.includes(q);
+    });
+  }
+}
+export {
+  ExampleRegistry
+};

package/dist/examples/registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/schema.d.ts

@@ -0,0 +1,278 @@
+import { z } from 'zod';
+import type { ExampleSpec, ExampleMeta, ExampleSurfaces, ExampleEntrypoints, ExampleDocumentation } from './types';
+export declare const ExampleKindSchema: z.ZodEnum<{
+    workflow: "workflow";
+    ui: "ui";
+    integration: "integration";
+    knowledge: "knowledge";
+    library: "library";
+    template: "template";
+    blueprint: "blueprint";
+    script: "script";
+}>;
+export declare const ExampleVisibilitySchema: z.ZodEnum<{
+    public: "public";
+    internal: "internal";
+    experimental: "experimental";
+}>;
+export declare const ExampleSandboxModeSchema: z.ZodEnum<{
+    markdown: "markdown";
+    playground: "playground";
+    specs: "specs";
+    builder: "builder";
+    evolution: "evolution";
+}>;
+export declare const StabilitySchema: z.ZodEnum<{
+    idea: "idea";
+    in_creation: "in_creation";
+    experimental: "experimental";
+    beta: "beta";
+    stable: "stable";
+    deprecated: "deprecated";
+}>;
+export declare const ExampleDocumentationSchema: z.ZodObject<{
+    rootDocId: z.ZodOptional<z.ZodString>;
+    goalDocId: z.ZodOptional<z.ZodString>;
+    usageDocId: z.ZodOptional<z.ZodString>;
+    referenceDocId: z.ZodOptional<z.ZodString>;
+    constraintsDocId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ExampleSandboxSupportSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    modes: z.ZodArray<z.ZodEnum<{
+        markdown: "markdown";
+        playground: "playground";
+        specs: "specs";
+        builder: "builder";
+        evolution: "evolution";
+    }>>;
+}, z.core.$strip>;
+export declare const ExampleStudioSupportSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    installable: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const ExampleMcpSupportSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const ExampleSurfacesSchema: z.ZodObject<{
+    templates: z.ZodBoolean;
+    sandbox: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        modes: z.ZodArray<z.ZodEnum<{
+            markdown: "markdown";
+            playground: "playground";
+            specs: "specs";
+            builder: "builder";
+            evolution: "evolution";
+        }>>;
+    }, z.core.$strip>;
+    studio: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        installable: z.ZodBoolean;
+    }, z.core.$strip>;
+    mcp: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const ExampleEntrypointsSchema: z.ZodObject<{
+    packageName: z.ZodString;
+    feature: z.ZodOptional<z.ZodString>;
+    blueprint: z.ZodOptional<z.ZodString>;
+    presentations: z.ZodOptional<z.ZodString>;
+    contracts: z.ZodOptional<z.ZodString>;
+    handlers: z.ZodOptional<z.ZodString>;
+    ui: z.ZodOptional<z.ZodString>;
+    docs: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ExampleMetaSchema: z.ZodObject<{
+    version: z.ZodString;
+    key: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    domain: z.ZodOptional<z.ZodString>;
+    stability: z.ZodEnum<{
+        idea: "idea";
+        in_creation: "in_creation";
+        experimental: "experimental";
+        beta: "beta";
+        stable: "stable";
+        deprecated: "deprecated";
+    }>;
+    owners: z.ZodArray<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    docId: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodEnum<{
+        workflow: "workflow";
+        ui: "ui";
+        integration: "integration";
+        knowledge: "knowledge";
+        library: "library";
+        template: "template";
+        blueprint: "blueprint";
+        script: "script";
+    }>;
+    visibility: z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+        experimental: "experimental";
+    }>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SpecPointerSchema: z.ZodObject<{
+    key: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FeatureRefSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zod schema for validating ExampleSpec objects.
+ *
+ * Note: blueprint and features are loosely validated since they can be
+ * inline specs or references. Full validation requires registry lookups.
+ */
+export declare const ExampleSpecSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        version: z.ZodString;
+        key: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        domain: z.ZodOptional<z.ZodString>;
+        stability: z.ZodEnum<{
+            idea: "idea";
+            in_creation: "in_creation";
+            experimental: "experimental";
+            beta: "beta";
+            stable: "stable";
+            deprecated: "deprecated";
+        }>;
+        owners: z.ZodArray<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        docId: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodEnum<{
+            workflow: "workflow";
+            ui: "ui";
+            integration: "integration";
+            knowledge: "knowledge";
+            library: "library";
+            template: "template";
+            blueprint: "blueprint";
+            script: "script";
+        }>;
+        visibility: z.ZodEnum<{
+            public: "public";
+            internal: "internal";
+            experimental: "experimental";
+        }>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    docs: z.ZodOptional<z.ZodObject<{
+        rootDocId: z.ZodOptional<z.ZodString>;
+        goalDocId: z.ZodOptional<z.ZodString>;
+        usageDocId: z.ZodOptional<z.ZodString>;
+        referenceDocId: z.ZodOptional<z.ZodString>;
+        constraintsDocId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    surfaces: z.ZodObject<{
+        templates: z.ZodBoolean;
+        sandbox: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            modes: z.ZodArray<z.ZodEnum<{
+                markdown: "markdown";
+                playground: "playground";
+                specs: "specs";
+                builder: "builder";
+                evolution: "evolution";
+            }>>;
+        }, z.core.$strip>;
+        studio: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            installable: z.ZodBoolean;
+        }, z.core.$strip>;
+        mcp: z.ZodObject<{
+            enabled: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    entrypoints: z.ZodObject<{
+        packageName: z.ZodString;
+        feature: z.ZodOptional<z.ZodString>;
+        blueprint: z.ZodOptional<z.ZodString>;
+        presentations: z.ZodOptional<z.ZodString>;
+        contracts: z.ZodOptional<z.ZodString>;
+        handlers: z.ZodOptional<z.ZodString>;
+        ui: z.ZodOptional<z.ZodString>;
+        docs: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    blueprint: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodObject<{
+        key: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    features: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strip>]>>>;
+}, z.core.$strip>;
+/** Parse and validate an ExampleSpec, throwing on failure */
+export declare function parseExampleSpec(data: unknown): ExampleSpec;
+/** Safely parse an ExampleSpec, returning result object */
+export declare function safeParseExampleSpec(data: unknown): z.ZodSafeParseResult<{
+    meta: {
+        version: string;
+        key: string;
+        description: string;
+        stability: "idea" | "in_creation" | "experimental" | "beta" | "stable" | "deprecated";
+        owners: string[];
+        tags: string[];
+        kind: "workflow" | "ui" | "integration" | "knowledge" | "library" | "template" | "blueprint" | "script";
+        visibility: "public" | "internal" | "experimental";
+        title?: string | undefined;
+        domain?: string | undefined;
+        docId?: string[] | undefined;
+        summary?: string | undefined;
+    };
+    surfaces: {
+        templates: boolean;
+        sandbox: {
+            enabled: boolean;
+            modes: ("markdown" | "playground" | "specs" | "builder" | "evolution")[];
+        };
+        studio: {
+            enabled: boolean;
+            installable: boolean;
+        };
+        mcp: {
+            enabled: boolean;
+        };
+    };
+    entrypoints: {
+        packageName: string;
+        feature?: string | undefined;
+        blueprint?: string | undefined;
+        presentations?: string | undefined;
+        contracts?: string | undefined;
+        handlers?: string | undefined;
+        ui?: string | undefined;
+        docs?: string | undefined;
+    };
+    docs?: {
+        rootDocId?: string | undefined;
+        goalDocId?: string | undefined;
+        usageDocId?: string | undefined;
+        referenceDocId?: string | undefined;
+        constraintsDocId?: string | undefined;
+    } | undefined;
+    blueprint?: Record<string, unknown> | {
+        key: string;
+        version?: string | undefined;
+    } | undefined;
+    features?: (Record<string, unknown> | {
+        key: string;
+    })[] | undefined;
+}>;
+/** Parse and validate ExampleMeta */
+export declare function parseExampleMeta(data: unknown): ExampleMeta;
+/** Parse and validate ExampleSurfaces */
+export declare function parseExampleSurfaces(data: unknown): ExampleSurfaces;
+/** Parse and validate ExampleEntrypoints */
+export declare function parseExampleEntrypoints(data: unknown): ExampleEntrypoints;
+/** Parse and validate ExampleDocumentation */
+export declare function parseExampleDocumentation(data: unknown): ExampleDocumentation;