@contractspec/lib.contracts-spec 2.0.0

package/dist/examples/index.js

@@ -0,0 +1,604 @@
+// @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/define.ts
+var defineExample = (spec) => spec;
+
+// src/examples/types.ts
+var ExampleKindEnum = {
+  Template: "template",
+  Workflow: "workflow",
+  Integration: "integration",
+  Knowledge: "knowledge",
+  Blueprint: "blueprint",
+  UI: "ui",
+  Script: "script",
+  Library: "library"
+};
+var ExampleVisibilityEnum = {
+  Public: "public",
+  Internal: "internal",
+  Experimental: "experimental"
+};
+var ExampleSandboxModeEnum = {
+  Playground: "playground",
+  Specs: "specs",
+  Builder: "builder",
+  Markdown: "markdown",
+  Evolution: "evolution"
+};
+function isSpecPointer(ref) {
+  if (!ref)
+    return false;
+  return "key" in ref && !("meta" in ref);
+}
+function isFeatureRef(ref) {
+  return "key" in ref && !("meta" in ref);
+}
+function isExampleKind(value) {
+  return typeof value === "string" && Object.values(ExampleKindEnum).includes(value);
+}
+function isExampleVisibility(value) {
+  return typeof value === "string" && Object.values(ExampleVisibilityEnum).includes(value);
+}
+
+// src/examples/schema.ts
+import { z } from "zod";
+var ExampleKindSchema = z.enum([
+  "template",
+  "workflow",
+  "integration",
+  "knowledge",
+  "blueprint",
+  "ui",
+  "script",
+  "library"
+]);
+var ExampleVisibilitySchema = z.enum([
+  "public",
+  "internal",
+  "experimental"
+]);
+var ExampleSandboxModeSchema = z.enum([
+  "playground",
+  "specs",
+  "builder",
+  "markdown",
+  "evolution"
+]);
+var StabilitySchema = z.enum([
+  "idea",
+  "in_creation",
+  "experimental",
+  "beta",
+  "stable",
+  "deprecated"
+]);
+var ExampleDocumentationSchema = z.object({
+  rootDocId: z.string().optional(),
+  goalDocId: z.string().optional(),
+  usageDocId: z.string().optional(),
+  referenceDocId: z.string().optional(),
+  constraintsDocId: z.string().optional()
+});
+var ExampleSandboxSupportSchema = z.object({
+  enabled: z.boolean(),
+  modes: z.array(ExampleSandboxModeSchema)
+});
+var ExampleStudioSupportSchema = z.object({
+  enabled: z.boolean(),
+  installable: z.boolean()
+});
+var ExampleMcpSupportSchema = z.object({
+  enabled: z.boolean()
+});
+var ExampleSurfacesSchema = z.object({
+  templates: z.boolean(),
+  sandbox: ExampleSandboxSupportSchema,
+  studio: ExampleStudioSupportSchema,
+  mcp: ExampleMcpSupportSchema
+});
+var ExampleEntrypointsSchema = z.object({
+  packageName: z.string().min(1),
+  feature: z.string().optional(),
+  blueprint: z.string().optional(),
+  presentations: z.string().optional(),
+  contracts: z.string().optional(),
+  handlers: z.string().optional(),
+  ui: z.string().optional(),
+  docs: z.string().optional()
+});
+var ExampleMetaSchema = z.object({
+  version: z.string(),
+  key: z.string().min(1),
+  title: z.string().optional(),
+  description: z.string().min(1),
+  domain: z.string().optional(),
+  stability: StabilitySchema,
+  owners: z.array(z.string()),
+  tags: z.array(z.string()),
+  docId: z.array(z.string()).optional(),
+  kind: ExampleKindSchema,
+  visibility: ExampleVisibilitySchema,
+  summary: z.string().optional()
+});
+var SpecPointerSchema = z.object({
+  key: z.string().min(1),
+  version: z.string().optional()
+});
+var FeatureRefSchema = z.object({
+  key: z.string().min(1)
+});
+var ExampleSpecSchema = z.object({
+  meta: ExampleMetaSchema,
+  docs: ExampleDocumentationSchema.optional(),
+  surfaces: ExampleSurfacesSchema,
+  entrypoints: ExampleEntrypointsSchema,
+  blueprint: z.union([z.record(z.string(), z.unknown()), SpecPointerSchema]).optional(),
+  features: z.array(z.union([z.record(z.string(), z.unknown()), FeatureRefSchema])).optional()
+});
+function parseExampleSpec(data) {
+  return ExampleSpecSchema.parse(data);
+}
+function safeParseExampleSpec(data) {
+  return ExampleSpecSchema.safeParse(data);
+}
+function parseExampleMeta(data) {
+  return ExampleMetaSchema.parse(data);
+}
+function parseExampleSurfaces(data) {
+  return ExampleSurfacesSchema.parse(data);
+}
+function parseExampleEntrypoints(data) {
+  return ExampleEntrypointsSchema.parse(data);
+}
+function parseExampleDocumentation(data) {
+  return ExampleDocumentationSchema.parse(data);
+}
+
+// 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);
+    });
+  }
+}
+
+// src/examples/validation.ts
+function validateExample(example) {
+  const errors = [];
+  const warnings = [];
+  const parsed = safeParseExampleSpec(example);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      errors.push({
+        exampleKey: example?.meta?.key,
+        message: issue.message,
+        path: issue.path.join("."),
+        code: issue.code
+      });
+    }
+    return { valid: false, errors, warnings };
+  }
+  const spec = parsed.data;
+  validateSemantics(spec, errors, warnings);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateSemantics(spec, errors, warnings) {
+  const key = spec.meta.key;
+  if (!spec.entrypoints.packageName.startsWith("@")) {
+    warnings.push({
+      exampleKey: key,
+      message: "Package name should be scoped (e.g., @contractspec/example.name)",
+      path: "entrypoints.packageName"
+    });
+  }
+  if (spec.surfaces.studio.installable && !spec.surfaces.studio.enabled) {
+    errors.push({
+      exampleKey: key,
+      message: "Studio installable requires studio.enabled to be true",
+      path: "surfaces.studio",
+      code: "STUDIO_INSTALLABLE_REQUIRES_ENABLED"
+    });
+  }
+  if (spec.surfaces.sandbox.enabled && spec.surfaces.sandbox.modes.length === 0) {
+    warnings.push({
+      exampleKey: key,
+      message: "Sandbox is enabled but has no modes configured",
+      path: "surfaces.sandbox.modes"
+    });
+  }
+  if (spec.features && spec.features.length > 0 && !spec.entrypoints.feature) {
+    warnings.push({
+      exampleKey: key,
+      message: "Example has features but no feature entrypoint in entrypoints.feature",
+      path: "entrypoints.feature"
+    });
+  }
+  if (spec.blueprint && !spec.entrypoints.blueprint) {
+    warnings.push({
+      exampleKey: key,
+      message: "Example has blueprint but no blueprint entrypoint in entrypoints.blueprint",
+      path: "entrypoints.blueprint"
+    });
+  }
+  if (spec.meta.visibility === "public" && spec.meta.stability === "idea") {
+    warnings.push({
+      exampleKey: key,
+      message: 'Public examples should not be in "idea" stability',
+      path: "meta.stability"
+    });
+  }
+}
+function validateExamples(examples) {
+  const errors = [];
+  const seen = new Set;
+  const validExamples = [];
+  for (const example of examples) {
+    if (seen.has(example.meta.key)) {
+      errors.push({
+        exampleKey: example.meta.key,
+        message: `Duplicate example key: ${example.meta.key}`,
+        code: "DUPLICATE_KEY"
+      });
+      continue;
+    }
+    seen.add(example.meta.key);
+    const result = validateExample(example);
+    if (!result.valid) {
+      errors.push(...result.errors);
+    } else {
+      validExamples.push(example);
+    }
+  }
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+  return { ok: true, examples: validExamples };
+}
+function validateExampleReferences(example, context) {
+  const errors = [];
+  const warnings = [];
+  const key = example.meta.key;
+  if (context.packageNames && !context.packageNames.has(example.entrypoints.packageName)) {
+    warnings.push({
+      exampleKey: key,
+      message: `Package "${example.entrypoints.packageName}" not found in workspace`,
+      path: "entrypoints.packageName"
+    });
+  }
+  if (example.features && context.featureKeys) {
+    for (const feature of example.features) {
+      if ("key" in feature && !("meta" in feature)) {
+        if (!context.featureKeys.has(feature.key)) {
+          warnings.push({
+            exampleKey: key,
+            message: `Feature "${feature.key}" not found in registry`,
+            path: "features"
+          });
+        }
+      }
+    }
+  }
+  if (example.blueprint && context.blueprintKeys) {
+    if ("key" in example.blueprint && !("meta" in example.blueprint)) {
+      if (!context.blueprintKeys.has(example.blueprint.key)) {
+        warnings.push({
+          exampleKey: key,
+          message: `Blueprint "${example.blueprint.key}" not found in registry`,
+          path: "blueprint"
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+export {
+  validateExamples,
+  validateExampleReferences,
+  validateExample,
+  safeParseExampleSpec,
+  parseExampleSurfaces,
+  parseExampleSpec,
+  parseExampleMeta,
+  parseExampleEntrypoints,
+  parseExampleDocumentation,
+  isSpecPointer,
+  isFeatureRef,
+  isExampleVisibility,
+  isExampleKind,
+  defineExample,
+  ExampleVisibilitySchema,
+  ExampleVisibilityEnum,
+  ExampleSurfacesSchema,
+  ExampleSpecSchema,
+  ExampleSandboxModeSchema,
+  ExampleSandboxModeEnum,
+  ExampleRegistry,
+  ExampleMetaSchema,
+  ExampleKindSchema,
+  ExampleKindEnum,
+  ExampleEntrypointsSchema,
+  ExampleDocumentationSchema
+};

package/dist/examples/registry.d.ts

@@ -0,0 +1,38 @@
+import type { ExampleSpec, ExampleKind, ExampleVisibility } from './types';
+import { SpecContractRegistry } from '../registry';
+/**
+ * In-memory registry for ExampleSpec.
+ *
+ * Provides methods for registering, querying, and filtering examples.
+ *
+ * @example
+ * ```typescript
+ * const registry = new ExampleRegistry();
+ * registry.register(saasBoilerplateExample);
+ * registry.register(workflowSystemExample);
+ *
+ * const templates = registry.listByKind('template');
+ * const publicExamples = registry.listByVisibility('public');
+ * ```
+ */
+export declare class ExampleRegistry extends SpecContractRegistry<'example', ExampleSpec> {
+    constructor(items?: ExampleSpec[]);
+    /** List examples by kind. */
+    listByKind(kind: ExampleKind): ExampleSpec[];
+    /** List examples by visibility. */
+    listByVisibility(visibility: ExampleVisibility): ExampleSpec[];
+    /** List examples by domain. */
+    listByDomain(domain: string): ExampleSpec[];
+    /** List examples that support a specific surface. */
+    listBySurface(surface: 'templates' | 'sandbox' | 'studio' | 'mcp'): ExampleSpec[];
+    /** List examples that are installable via Studio. */
+    listInstallable(): ExampleSpec[];
+    /** Group examples by kind. */
+    groupByKind(): Map<ExampleKind, ExampleSpec[]>;
+    /** Get unique kinds from all examples. */
+    getUniqueKinds(): ExampleKind[];
+    /** Get unique domains from all examples. */
+    getUniqueDomains(): string[];
+    /** Search examples by query (matches key, title, description, tags). */
+    search(query: string): ExampleSpec[];
+}