@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/examples/registry.d.ts

@@ -0,0 +1,43 @@
+import { SpecContractRegistry } from "../registry.js";
+import { ExampleKind, ExampleSpec, ExampleVisibility } from "./types.js";
+
+//#region src/examples/registry.d.ts
+
+/**
+ * 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');
+ * ```
+ */
+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[];
+}
+//#endregion
+export { ExampleRegistry };

package/dist/examples/registry.js

@@ -0,0 +1,88 @@
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/examples/registry.ts
+/**
+* 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');
+* ```
+*/
+var ExampleRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("example", items);
+	}
+	/** List examples by kind. */
+	listByKind(kind) {
+		return this.list().filter((spec) => spec.meta.kind === kind);
+	}
+	/** List examples by visibility. */
+	listByVisibility(visibility) {
+		return this.list().filter((spec) => spec.meta.visibility === visibility);
+	}
+	/** List examples by domain. */
+	listByDomain(domain) {
+		return this.list().filter((spec) => spec.meta.domain === domain);
+	}
+	/** List examples that support a specific surface. */
+	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;
+		});
+	}
+	/** List examples that are installable via Studio. */
+	listInstallable() {
+		return this.list().filter((spec) => spec.surfaces.studio.installable);
+	}
+	/** Group examples by kind. */
+	groupByKind() {
+		const result = /* @__PURE__ */ 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;
+	}
+	/** Get unique kinds from all examples. */
+	getUniqueKinds() {
+		const kinds = /* @__PURE__ */ new Set();
+		for (const spec of this.list()) kinds.add(spec.meta.kind);
+		return [...kinds];
+	}
+	/** Get unique domains from all examples. */
+	getUniqueDomains() {
+		const domains = /* @__PURE__ */ new Set();
+		for (const spec of this.list()) if (spec.meta.domain) domains.add(spec.meta.domain);
+		return [...domains];
+	}
+	/** Search examples by query (matches key, title, description, tags). */
+	search(query) {
+		const q = query.toLowerCase().trim();
+		if (!q) return this.list();
+		return this.list().filter((spec) => {
+			return [
+				spec.meta.key,
+				spec.meta.title ?? "",
+				spec.meta.description,
+				spec.meta.summary ?? "",
+				...spec.meta.tags
+			].join(" ").toLowerCase().includes(q);
+		});
+	}
+};
+
+//#endregion
+export { ExampleRegistry };

package/dist/examples/schema.d.ts

@@ -0,0 +1,282 @@
+import { ExampleDocumentation, ExampleEntrypoints, ExampleMeta, ExampleSpec, ExampleSurfaces } from "./types.js";
+import { z as z$1 } from "zod";
+
+//#region src/examples/schema.d.ts
+declare const ExampleKindSchema: z$1.ZodEnum<{
+  template: "template";
+  workflow: "workflow";
+  integration: "integration";
+  knowledge: "knowledge";
+  blueprint: "blueprint";
+  ui: "ui";
+  script: "script";
+  library: "library";
+}>;
+declare const ExampleVisibilitySchema: z$1.ZodEnum<{
+  experimental: "experimental";
+  public: "public";
+  internal: "internal";
+}>;
+declare const ExampleSandboxModeSchema: z$1.ZodEnum<{
+  playground: "playground";
+  specs: "specs";
+  builder: "builder";
+  markdown: "markdown";
+  evolution: "evolution";
+}>;
+declare const StabilitySchema: z$1.ZodEnum<{
+  deprecated: "deprecated";
+  idea: "idea";
+  in_creation: "in_creation";
+  experimental: "experimental";
+  beta: "beta";
+  stable: "stable";
+}>;
+declare const ExampleDocumentationSchema: z$1.ZodObject<{
+  rootDocId: z$1.ZodOptional<z$1.ZodString>;
+  goalDocId: z$1.ZodOptional<z$1.ZodString>;
+  usageDocId: z$1.ZodOptional<z$1.ZodString>;
+  referenceDocId: z$1.ZodOptional<z$1.ZodString>;
+  constraintsDocId: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>;
+declare const ExampleSandboxSupportSchema: z$1.ZodObject<{
+  enabled: z$1.ZodBoolean;
+  modes: z$1.ZodArray<z$1.ZodEnum<{
+    playground: "playground";
+    specs: "specs";
+    builder: "builder";
+    markdown: "markdown";
+    evolution: "evolution";
+  }>>;
+}, z$1.core.$strip>;
+declare const ExampleStudioSupportSchema: z$1.ZodObject<{
+  enabled: z$1.ZodBoolean;
+  installable: z$1.ZodBoolean;
+}, z$1.core.$strip>;
+declare const ExampleMcpSupportSchema: z$1.ZodObject<{
+  enabled: z$1.ZodBoolean;
+}, z$1.core.$strip>;
+declare const ExampleSurfacesSchema: z$1.ZodObject<{
+  templates: z$1.ZodBoolean;
+  sandbox: z$1.ZodObject<{
+    enabled: z$1.ZodBoolean;
+    modes: z$1.ZodArray<z$1.ZodEnum<{
+      playground: "playground";
+      specs: "specs";
+      builder: "builder";
+      markdown: "markdown";
+      evolution: "evolution";
+    }>>;
+  }, z$1.core.$strip>;
+  studio: z$1.ZodObject<{
+    enabled: z$1.ZodBoolean;
+    installable: z$1.ZodBoolean;
+  }, z$1.core.$strip>;
+  mcp: z$1.ZodObject<{
+    enabled: z$1.ZodBoolean;
+  }, z$1.core.$strip>;
+}, z$1.core.$strip>;
+declare const ExampleEntrypointsSchema: z$1.ZodObject<{
+  packageName: z$1.ZodString;
+  feature: z$1.ZodOptional<z$1.ZodString>;
+  blueprint: z$1.ZodOptional<z$1.ZodString>;
+  presentations: z$1.ZodOptional<z$1.ZodString>;
+  contracts: z$1.ZodOptional<z$1.ZodString>;
+  handlers: z$1.ZodOptional<z$1.ZodString>;
+  ui: z$1.ZodOptional<z$1.ZodString>;
+  docs: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>;
+declare const ExampleMetaSchema: z$1.ZodObject<{
+  version: z$1.ZodString;
+  key: z$1.ZodString;
+  title: z$1.ZodOptional<z$1.ZodString>;
+  description: z$1.ZodString;
+  domain: z$1.ZodOptional<z$1.ZodString>;
+  stability: z$1.ZodEnum<{
+    deprecated: "deprecated";
+    idea: "idea";
+    in_creation: "in_creation";
+    experimental: "experimental";
+    beta: "beta";
+    stable: "stable";
+  }>;
+  owners: z$1.ZodArray<z$1.ZodString>;
+  tags: z$1.ZodArray<z$1.ZodString>;
+  docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+  kind: z$1.ZodEnum<{
+    template: "template";
+    workflow: "workflow";
+    integration: "integration";
+    knowledge: "knowledge";
+    blueprint: "blueprint";
+    ui: "ui";
+    script: "script";
+    library: "library";
+  }>;
+  visibility: z$1.ZodEnum<{
+    experimental: "experimental";
+    public: "public";
+    internal: "internal";
+  }>;
+  summary: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>;
+declare const SpecPointerSchema: z$1.ZodObject<{
+  key: z$1.ZodString;
+  version: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>;
+declare const FeatureRefSchema: z$1.ZodObject<{
+  key: z$1.ZodString;
+}, z$1.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.
+ */
+declare const ExampleSpecSchema: z$1.ZodObject<{
+  meta: z$1.ZodObject<{
+    version: z$1.ZodString;
+    key: z$1.ZodString;
+    title: z$1.ZodOptional<z$1.ZodString>;
+    description: z$1.ZodString;
+    domain: z$1.ZodOptional<z$1.ZodString>;
+    stability: z$1.ZodEnum<{
+      deprecated: "deprecated";
+      idea: "idea";
+      in_creation: "in_creation";
+      experimental: "experimental";
+      beta: "beta";
+      stable: "stable";
+    }>;
+    owners: z$1.ZodArray<z$1.ZodString>;
+    tags: z$1.ZodArray<z$1.ZodString>;
+    docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+    kind: z$1.ZodEnum<{
+      template: "template";
+      workflow: "workflow";
+      integration: "integration";
+      knowledge: "knowledge";
+      blueprint: "blueprint";
+      ui: "ui";
+      script: "script";
+      library: "library";
+    }>;
+    visibility: z$1.ZodEnum<{
+      experimental: "experimental";
+      public: "public";
+      internal: "internal";
+    }>;
+    summary: z$1.ZodOptional<z$1.ZodString>;
+  }, z$1.core.$strip>;
+  docs: z$1.ZodOptional<z$1.ZodObject<{
+    rootDocId: z$1.ZodOptional<z$1.ZodString>;
+    goalDocId: z$1.ZodOptional<z$1.ZodString>;
+    usageDocId: z$1.ZodOptional<z$1.ZodString>;
+    referenceDocId: z$1.ZodOptional<z$1.ZodString>;
+    constraintsDocId: z$1.ZodOptional<z$1.ZodString>;
+  }, z$1.core.$strip>>;
+  surfaces: z$1.ZodObject<{
+    templates: z$1.ZodBoolean;
+    sandbox: z$1.ZodObject<{
+      enabled: z$1.ZodBoolean;
+      modes: z$1.ZodArray<z$1.ZodEnum<{
+        playground: "playground";
+        specs: "specs";
+        builder: "builder";
+        markdown: "markdown";
+        evolution: "evolution";
+      }>>;
+    }, z$1.core.$strip>;
+    studio: z$1.ZodObject<{
+      enabled: z$1.ZodBoolean;
+      installable: z$1.ZodBoolean;
+    }, z$1.core.$strip>;
+    mcp: z$1.ZodObject<{
+      enabled: z$1.ZodBoolean;
+    }, z$1.core.$strip>;
+  }, z$1.core.$strip>;
+  entrypoints: z$1.ZodObject<{
+    packageName: z$1.ZodString;
+    feature: z$1.ZodOptional<z$1.ZodString>;
+    blueprint: z$1.ZodOptional<z$1.ZodString>;
+    presentations: z$1.ZodOptional<z$1.ZodString>;
+    contracts: z$1.ZodOptional<z$1.ZodString>;
+    handlers: z$1.ZodOptional<z$1.ZodString>;
+    ui: z$1.ZodOptional<z$1.ZodString>;
+    docs: z$1.ZodOptional<z$1.ZodString>;
+  }, z$1.core.$strip>;
+  blueprint: z$1.ZodOptional<z$1.ZodUnion<readonly [z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>, z$1.ZodObject<{
+    key: z$1.ZodString;
+    version: z$1.ZodOptional<z$1.ZodString>;
+  }, z$1.core.$strip>]>>;
+  features: z$1.ZodOptional<z$1.ZodArray<z$1.ZodUnion<readonly [z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>, z$1.ZodObject<{
+    key: z$1.ZodString;
+  }, z$1.core.$strip>]>>>;
+}, z$1.core.$strip>;
+/** Parse and validate an ExampleSpec, throwing on failure */
+declare function parseExampleSpec(data: unknown): ExampleSpec;
+/** Safely parse an ExampleSpec, returning result object */
+declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
+  meta: {
+    version: string;
+    key: string;
+    description: string;
+    stability: "deprecated" | "idea" | "in_creation" | "experimental" | "beta" | "stable";
+    owners: string[];
+    tags: string[];
+    kind: "template" | "workflow" | "integration" | "knowledge" | "blueprint" | "ui" | "script" | "library";
+    visibility: "experimental" | "public" | "internal";
+    title?: string | undefined;
+    domain?: string | undefined;
+    docId?: string[] | undefined;
+    summary?: string | undefined;
+  };
+  surfaces: {
+    templates: boolean;
+    sandbox: {
+      enabled: boolean;
+      modes: ("playground" | "specs" | "builder" | "markdown" | "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 */
+declare function parseExampleMeta(data: unknown): ExampleMeta;
+/** Parse and validate ExampleSurfaces */
+declare function parseExampleSurfaces(data: unknown): ExampleSurfaces;
+/** Parse and validate ExampleEntrypoints */
+declare function parseExampleEntrypoints(data: unknown): ExampleEntrypoints;
+/** Parse and validate ExampleDocumentation */
+declare function parseExampleDocumentation(data: unknown): ExampleDocumentation;
+//#endregion
+export { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindSchema, ExampleMcpSupportSchema, ExampleMetaSchema, ExampleSandboxModeSchema, ExampleSandboxSupportSchema, ExampleSpecSchema, ExampleStudioSupportSchema, ExampleSurfacesSchema, ExampleVisibilitySchema, FeatureRefSchema, SpecPointerSchema, StabilitySchema, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec };

package/dist/examples/schema.js

@@ -0,0 +1,125 @@
+import { z as z$1 } from "zod";
+
+//#region src/examples/schema.ts
+const ExampleKindSchema = z$1.enum([
+	"template",
+	"workflow",
+	"integration",
+	"knowledge",
+	"blueprint",
+	"ui",
+	"script",
+	"library"
+]);
+const ExampleVisibilitySchema = z$1.enum([
+	"public",
+	"internal",
+	"experimental"
+]);
+const ExampleSandboxModeSchema = z$1.enum([
+	"playground",
+	"specs",
+	"builder",
+	"markdown",
+	"evolution"
+]);
+const StabilitySchema = z$1.enum([
+	"idea",
+	"in_creation",
+	"experimental",
+	"beta",
+	"stable",
+	"deprecated"
+]);
+const ExampleDocumentationSchema = z$1.object({
+	rootDocId: z$1.string().optional(),
+	goalDocId: z$1.string().optional(),
+	usageDocId: z$1.string().optional(),
+	referenceDocId: z$1.string().optional(),
+	constraintsDocId: z$1.string().optional()
+});
+const ExampleSandboxSupportSchema = z$1.object({
+	enabled: z$1.boolean(),
+	modes: z$1.array(ExampleSandboxModeSchema)
+});
+const ExampleStudioSupportSchema = z$1.object({
+	enabled: z$1.boolean(),
+	installable: z$1.boolean()
+});
+const ExampleMcpSupportSchema = z$1.object({ enabled: z$1.boolean() });
+const ExampleSurfacesSchema = z$1.object({
+	templates: z$1.boolean(),
+	sandbox: ExampleSandboxSupportSchema,
+	studio: ExampleStudioSupportSchema,
+	mcp: ExampleMcpSupportSchema
+});
+const ExampleEntrypointsSchema = z$1.object({
+	packageName: z$1.string().min(1),
+	feature: z$1.string().optional(),
+	blueprint: z$1.string().optional(),
+	presentations: z$1.string().optional(),
+	contracts: z$1.string().optional(),
+	handlers: z$1.string().optional(),
+	ui: z$1.string().optional(),
+	docs: z$1.string().optional()
+});
+const ExampleMetaSchema = z$1.object({
+	version: z$1.string(),
+	key: z$1.string().min(1),
+	title: z$1.string().optional(),
+	description: z$1.string().min(1),
+	domain: z$1.string().optional(),
+	stability: StabilitySchema,
+	owners: z$1.array(z$1.string()),
+	tags: z$1.array(z$1.string()),
+	docId: z$1.array(z$1.string()).optional(),
+	kind: ExampleKindSchema,
+	visibility: ExampleVisibilitySchema,
+	summary: z$1.string().optional()
+});
+const SpecPointerSchema = z$1.object({
+	key: z$1.string().min(1),
+	version: z$1.string().optional()
+});
+const FeatureRefSchema = z$1.object({ key: z$1.string().min(1) });
+/**
+* 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.
+*/
+const ExampleSpecSchema = z$1.object({
+	meta: ExampleMetaSchema,
+	docs: ExampleDocumentationSchema.optional(),
+	surfaces: ExampleSurfacesSchema,
+	entrypoints: ExampleEntrypointsSchema,
+	blueprint: z$1.union([z$1.record(z$1.string(), z$1.unknown()), SpecPointerSchema]).optional(),
+	features: z$1.array(z$1.union([z$1.record(z$1.string(), z$1.unknown()), FeatureRefSchema])).optional()
+});
+/** Parse and validate an ExampleSpec, throwing on failure */
+function parseExampleSpec(data) {
+	return ExampleSpecSchema.parse(data);
+}
+/** Safely parse an ExampleSpec, returning result object */
+function safeParseExampleSpec(data) {
+	return ExampleSpecSchema.safeParse(data);
+}
+/** Parse and validate ExampleMeta */
+function parseExampleMeta(data) {
+	return ExampleMetaSchema.parse(data);
+}
+/** Parse and validate ExampleSurfaces */
+function parseExampleSurfaces(data) {
+	return ExampleSurfacesSchema.parse(data);
+}
+/** Parse and validate ExampleEntrypoints */
+function parseExampleEntrypoints(data) {
+	return ExampleEntrypointsSchema.parse(data);
+}
+/** Parse and validate ExampleDocumentation */
+function parseExampleDocumentation(data) {
+	return ExampleDocumentationSchema.parse(data);
+}
+
+//#endregion
+export { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindSchema, ExampleMcpSupportSchema, ExampleMetaSchema, ExampleSandboxModeSchema, ExampleSandboxSupportSchema, ExampleSpecSchema, ExampleStudioSupportSchema, ExampleSurfacesSchema, ExampleVisibilitySchema, FeatureRefSchema, SpecPointerSchema, StabilitySchema, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec };