@contractspec/lib.contracts 1.46.2 → 1.48.0

package/dist/data-views/runtime.d.ts

@@ -1,10 +1,14 @@
+import { OperationSpecRegistry } from "../operations/registry.js";
+import "../operations/index.js";
 import { DataViewSpec } from "./spec.js";
 import { DataViewRegistry } from "./registry.js";
 import "./index.js";
+import { HandlerCtx } from "../types.js";
 
 //#region src/data-views/runtime.d.ts
 interface DataViewRuntimeConfig {
   registry: DataViewRegistry;
+  operationRegistry: OperationSpecRegistry;
 }
 interface DataViewResult<T = unknown> {
   data: T[];
@@ -19,7 +23,7 @@ declare class DataViewRuntime {
   constructor(config: DataViewRuntimeConfig);
   register(spec: DataViewSpec): void;
   getSpec(name: string, version?: string): DataViewSpec | undefined;
-  executeQuery(specName: string, _params: unknown): Promise<DataViewResult>;
+  executeQuery(specName: string, params: unknown, ctx: HandlerCtx): Promise<DataViewResult>;
   invalidate(specName: string): void;
   subscribe(specName: string, callback: () => void): () => void;
   private notifySubscribers;

package/dist/data-views/runtime.js

@@ -1,6 +1,10 @@
+import "../operations/index.js";
 import "./index.js";
 
 //#region src/data-views/runtime.ts
+function isPaginatedResult(value) {
+	return typeof value === "object" && value !== null && "items" in value && Array.isArray(value.items);
+}
 var DataViewRuntime = class {
 	cache = /* @__PURE__ */ new Map();
 	subscriptions = /* @__PURE__ */ new Map();
@@ -13,13 +17,36 @@ var DataViewRuntime = class {
 	getSpec(name, version) {
 		return this.config.registry.get(name, version);
 	}
-	async executeQuery(specName, _params) {
-		if (!this.getSpec(specName)) throw new Error(`DataView spec not found: ${specName}`);
-		return {
-			data: [],
-			total: 0,
-			loading: false
-		};
+	async executeQuery(specName, params, ctx) {
+		const spec = this.getSpec(specName);
+		if (!spec) throw new Error(`DataView spec not found: ${specName}`);
+		const opRef = spec.source.primary;
+		if (!opRef) throw new Error(`DataView spec ${specName} missing primary source`);
+		try {
+			const result = await this.config.operationRegistry.execute(opRef.key, opRef.version, params, ctx);
+			if (Array.isArray(result)) return {
+				data: result,
+				total: result.length,
+				loading: false
+			};
+			if (isPaginatedResult(result)) return {
+				data: result.items,
+				total: result.total ?? result.items.length,
+				loading: false
+			};
+			return {
+				data: [result],
+				total: 1,
+				loading: false
+			};
+		} catch (error) {
+			return {
+				data: [],
+				total: 0,
+				loading: false,
+				error: error instanceof Error ? error : new Error(String(error))
+			};
+		}
 	}
 	invalidate(specName) {
 		this.cache.delete(specName);

package/dist/data-views/spec.d.ts

@@ -1,5 +1,5 @@
-import { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from "./types.js";
 import { ExperimentRef } from "../experiments/spec.js";
+import { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from "./types.js";
 
 //#region src/data-views/spec.d.ts
 

package/dist/docs/index.js

@@ -7,11 +7,11 @@ import "./tech/lifecycle-stage-system.docblock.js";
 import "./tech/presentation-runtime.docblock.js";
 import "./tech/auth/better-auth-nextjs.docblock.js";
 import "./tech/schema/README.docblock.js";
-import "./tech/templates/runtime.docblock.js";
 import "../workflow/overview.docblock.js";
 import "./tech/mcp-endpoints.docblock.js";
 import "./tech/vscode-extension.docblock.js";
 import "./tech/telemetry-ingest.docblock.js";
+import "./tech/contracts/README.docblock.js";
 import "./tech/contracts/openapi-export.docblock.js";
 import "./tech/contracts/openapi-import.docblock.js";
 import "../workspace-config/workspace-config.docblock.js";
@@ -25,5 +25,6 @@ import "./tech/studio/learning-journeys.docblock.js";
 import "./tech/studio/project-access-teams.docblock.js";
 import "./tech/studio/team-invitations.docblock.js";
 import "./tech/llm/llm-integration.docblock.js";
+import "./tech/cli.docblock.js";
 
 export { DocRegistry, defaultDocRegistry, docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };

package/dist/docs/tech/cli.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "../types.js";
+
+//#region src/docs/tech/cli.docblock.d.ts
+declare const tech_cli_DocBlocks: DocBlock[];
+//#endregion
+export { tech_cli_DocBlocks };

package/dist/docs/tech/cli.docblock.js

@@ -0,0 +1,138 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/cli.docblock.ts
+const tech_cli_DocBlocks = [{
+	id: "docs.tech.cli.contractspec",
+	title: "ContractSpec CLI",
+	summary: "The command-line interface for creating, building, and validating contract specifications.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/cli/contractspec",
+	tags: [
+		"cli",
+		"tooling",
+		"reference"
+	],
+	owners: ["@contractspec/app.cli-contractspec"],
+	body: `# ContractSpec CLI
+
+The \`@contractspec/app.cli-contractspec\` package provides the command-line interface for the ContractSpec ecosystem.
+
+It is also exposed via \`@contractspec/apps-registry/contractspec\` for convenience.
+
+## Installation
+
+\`\`\`bash
+bun add -D @contractspec/app.cli-contractspec
+\`\`\`
+
+## Quick Start
+
+\`\`\`bash
+# Create a new contract spec interactively
+contractspec create
+
+# Create with AI assistance
+contractspec create --ai
+
+# Build implementation from spec
+contractspec build src/contracts/mySpec.ts
+
+# Validate a spec
+contractspec validate src/contracts/mySpec.ts
+\`\`\`
+
+## Core Commands
+
+### \`create\`
+
+Interactive wizard to create contract specifications.
+
+\`\`\`bash
+contractspec create --type operation --ai
+\`\`\`
+
+### \`build\`
+
+Generate implementation code from contract specs using AI agents or templates.
+
+\`\`\`bash
+contractspec build src/contracts/signup.contracts.ts --agent-mode claude-code
+\`\`\`
+
+### \`validate\`
+
+Validate contract specifications and verify implementations.
+
+\`\`\`bash
+contractspec validate src/contracts/signup.contracts.ts --check-implementation
+\`\`\`
+
+### \`watch\`
+
+Watch contract specifications and auto-regenerate on changes.
+
+\`\`\`bash
+contractspec watch --build --validate
+\`\`\`
+
+### \`list\`
+
+List all contract specifications in the project.
+
+\`\`\`bash
+contractspec list --owner @team-platform
+\`\`\`
+
+### \`cleanup\` / \`clean\`
+
+Clean generated files and build artifacts.
+
+\`\`\`bash
+contractspec clean
+\`\`\`
+
+### \`deps\`
+
+Analyze contract dependencies and relationships (circular dependencies, missing refs).
+
+\`\`\`bash
+contractspec deps --circular
+\`\`\`
+
+### \`diff\`
+
+Compare contract specifications and show differences (breaking changes, semantic diff).
+
+\`\`\`bash
+contractspec diff spec1.ts spec2.ts --breaking
+\`\`\`
+
+### \`ci\`
+
+Run all validation checks for CI/CD pipelines (structure, integrity, deps, doctor, handlers, tests).
+
+\`\`\`bash
+contractspec ci --format sarif --output results.sarif
+\`\`\`
+
+## Configuration
+
+The CLI is configured via \`.contractsrc.json\` in your project root.
+
+\`\`\`json
+{
+  "aiProvider": "claude",
+  "aiModel": "claude-3-7-sonnet-20250219",
+  "agentMode": "claude-code",
+  "outputDir": "./src"
+}
+\`\`\`
+
+For full documentation, refer to the [package README](https://github.com/contractspec/monorepo/tree/main/packages/apps/cli-contractspec).
+`
+}];
+registerDocBlocks(tech_cli_DocBlocks);
+
+//#endregion
+export { tech_cli_DocBlocks };

package/dist/docs/tech/contracts/vertical-pocket-family-office.docblock.js

@@ -13,7 +13,112 @@ const tech_contracts_vertical_pocket_family_office_DocBlocks = [{
 		"contracts",
 		"vertical-pocket-family-office"
 	],
-	body: "# Pocket Family Office Vertical\n\nPocket Family Office is a ContractSpec reference vertical that\ndemonstrates finance automation atop the integration and knowledge\nlayers. It is optimised for the hackathon stack (Google Cloud, Mistral,\nQdrant, ElevenLabs) while remaining provider-agnostic.\n\n## Goals\n\n- Ingest household financial documents (uploads + Gmail threads).\n- Generate AI summaries and optionally deliver them as voice notes.\n- Schedule multi-channel reminders for upcoming bills.\n- Showcase spec-first composition of integrations, knowledge spaces, and\n  workflows.\n\n## Blueprint Overview\n\nSource: `packages/verticals/pocket-family-office/blueprint.ts`\n\n- **Integration slots**\n  - `primaryLLM` → Mistral chat/embeddings\n  - `primaryVectorDb` → Qdrant\n  - `primaryStorage` → Google Cloud Storage\n  - `primaryOpenBanking` → Powens BYOK project for account aggregation\n  - `emailInbound` / `emailOutbound` → Gmail + Postmark\n  - `calendarScheduling` → Google Calendar\n  - `voicePlayback` → ElevenLabs (optional)\n  - `smsNotifications` → Twilio (optional)\n  - `paymentsProcessing` → Stripe (optional)\n- **Workflows**\n  - `process-uploaded-document`\n  - `upcoming-payments-reminder`\n  - `generate-financial-summary`\n  - `ingest-email-threads`\n  - `sync-openbanking-accounts`\n  - `sync-openbanking-transactions`\n  - `refresh-openbanking-balances`\n  - `generate-openbanking-overview`\n- **Policies/Telemetry** – references tenant policy specs and\n  `pfo.telemetry` for observability.\n\n## Tenant Sample\n\n`tenant.sample.ts` binds each slot to sample connections defined in\n`connections/samples.ts`. Key details:\n\n- Uses Google Cloud Secret Manager URIs for all credentials.\n- Enables knowledge spaces `knowledge.financial-docs` and\n  `knowledge.email-threads`, plus the derived summaries space\n  `knowledge.financial-overview` populated by open banking workflows.\n- Keeps `voicePlayback` and `paymentsProcessing` optional so tenants can\n  enable them incrementally.\n\n## Contracts\n\n`contracts/index.ts` defines command/query specs that power the\nworkflows:\n\n- `pfo.documents.upload` – store object + enqueue ingestion.\n- `pfo.reminders.schedule-payment` – send email/SMS/calendar reminders.\n- `pfo.summary.generate` – run RAG over knowledge spaces.\n- `pfo.summary.dispatch` – deliver summaries via email / voice.\n- `pfo.email.sync-threads` – ingest Gmail threads.\n\n## Workflows\n\n- **Process Uploaded Document**\n  1. Upload to storage / queue ingestion.\n  2. Optional human review step.\n- **Upcoming Payments Reminder**\n  1. Human review (confirm due date / channel).\n  2. Automation schedules reminders (email/SMS/calendar).\n- **Generate Financial Summary**\n  1. Run RAG to produce Markdown summary.\n  2. Dispatch summary (email + optional ElevenLabs voice note).\n- **Ingest Email Threads**\n  1. Sync Gmail threads into knowledge space.\n  2. Triage step for operators when nothing new is ingested.\n\n## Knowledge & Jobs\n\n- Knowledge spaces registered via\n  `registerFinancialDocsKnowledgeSpace` and\n  `registerEmailThreadsKnowledgeSpace`.\n- Ingestion adapters (`GmailIngestionAdapter`, `StorageIngestionAdapter`)\n  and job handlers (`createGmailSyncHandler`,\n  `createStorageDocumentHandler`) wire Gmail labels & GCS prefixes into\n  Qdrant.\n- `KnowledgeQueryService` provides summarisation + references for the\n  summary generation workflow.\n\n## Tests & Usage\n\n`tests/pocket-family-office.test.ts` exercises:\n\n- Blueprint validation + config composition.\n- In-memory ingestion of a sample invoice.\n- Retrieval augmented generation producing a summary with references.\n\nUse these files as scaffolding for new tenants or as a template for the\nhackathon deliverable. Replace the sample connection metadata with\ntenant-specific IDs/secret references before deploying.\n\n\n\n"
+	body: `# Pocket Family Office Vertical
+
+Pocket Family Office is a ContractSpec reference vertical that
+demonstrates finance automation atop the integration and knowledge
+layers. It is optimised for the hackathon stack (Google Cloud, Mistral,
+Qdrant, ElevenLabs) while remaining provider-agnostic.
+
+## Goals
+
+- Ingest household financial documents (uploads + Gmail threads).
+- Generate AI summaries and optionally deliver them as voice notes.
+- Schedule multi-channel reminders for upcoming bills.
+- Showcase spec-first composition of integrations, knowledge spaces, and
+  workflows.
+
+## Blueprint Overview
+
+Source: \`packages/examples/pocket-family-office/blueprint.ts\`
+
+- **Integration slots**
+  - \`primaryLLM\` \u2192 Mistral chat/embeddings
+  - \`primaryVectorDb\` \u2192 Qdrant
+  - \`primaryStorage\` \u2192 Google Cloud Storage
+  - \`primaryOpenBanking\` \u2192 Powens BYOK project for account aggregation
+  - \`emailInbound\` / \`emailOutbound\` \u2192 Gmail + Postmark
+  - \`calendarScheduling\` \u2192 Google Calendar
+  - \`voicePlayback\` \u2192 ElevenLabs (optional)
+  - \`smsNotifications\` \u2192 Twilio (optional)
+  - \`paymentsProcessing\` \u2192 Stripe (optional)
+- **Workflows**
+  - \`process-uploaded-document\`
+  - \`upcoming-payments-reminder\`
+  - \`generate-financial-summary\`
+  - \`ingest-email-threads\`
+  - \`sync-openbanking-accounts\`
+  - \`sync-openbanking-transactions\`
+  - \`refresh-openbanking-balances\`
+  - \`generate-openbanking-overview\`
+- **Policies/Telemetry** \u2013 references tenant policy specs and
+  \`pfo.telemetry\` for observability.
+
+## Tenant Sample
+
+\`tenant.sample.ts\` binds each slot to sample connections defined in
+\`connections/samples.ts\`. Key details:
+
+- Uses Google Cloud Secret Manager URIs for all credentials.
+- Enables knowledge spaces \`knowledge.financial-docs\` and
+  \`knowledge.email-threads\`, plus the derived summaries space
+  \`knowledge.financial-overview\` populated by open banking workflows.
+- Keeps \`voicePlayback\` and \`paymentsProcessing\` optional so tenants can
+  enable them incrementally.
+
+## Contracts
+
+\`contracts/index.ts\` defines command/query specs that power the
+workflows:
+
+- \`pfo.documents.upload\` \u2013 store object + enqueue ingestion.
+- \`pfo.reminders.schedule-payment\` \u2013 send email/SMS/calendar reminders.
+- \`pfo.summary.generate\` \u2013 run RAG over knowledge spaces.
+- \`pfo.summary.dispatch\` \u2013 deliver summaries via email / voice.
+- \`pfo.email.sync-threads\` \u2013 ingest Gmail threads.
+
+## Workflows
+
+- **Process Uploaded Document**
+  1. Upload to storage / queue ingestion.
+  2. Optional human review step.
+- **Upcoming Payments Reminder**
+  1. Human review (confirm due date / channel).
+  2. Automation schedules reminders (email/SMS/calendar).
+- **Generate Financial Summary**
+  1. Run RAG to produce Markdown summary.
+  2. Dispatch summary (email + optional ElevenLabs voice note).
+- **Ingest Email Threads**
+  1. Sync Gmail threads into knowledge space.
+  2. Triage step for operators when nothing new is ingested.
+
+## Knowledge & Jobs
+
+- Knowledge spaces registered via
+  \`registerFinancialDocsKnowledgeSpace\` and
+  \`registerEmailThreadsKnowledgeSpace\`.
+- Ingestion adapters (\`GmailIngestionAdapter\`, \`StorageIngestionAdapter\`)
+  and job handlers (\`createGmailSyncHandler\`,
+  \`createStorageDocumentHandler\`) wire Gmail labels & GCS prefixes into
+  Qdrant.
+- \`KnowledgeQueryService\` provides summarisation + references for the
+  summary generation workflow.
+
+## Tests & Usage
+
+\`tests/pocket-family-office.test.ts\` exercises:
+
+- Blueprint validation + config composition.
+- In-memory ingestion of a sample invoice.
+- Retrieval augmented generation producing a summary with references.
+
+Use these files as scaffolding for new tenants or as a template for the
+hackathon deliverable. Replace the sample connection metadata with
+tenant-specific IDs/secret references before deploying.
+
+
+
+`
 }];
 registerDocBlocks(tech_contracts_vertical_pocket_family_office_DocBlocks);
 

package/dist/docs/tech/studio/project-access-teams.docblock.js

@@ -33,7 +33,9 @@ Studio access control is **organization-first** with optional **team-based shari
 
 ## GraphQL surfaces
 
-- Read:\n  - \`myStudioProjects\` (returns only projects you can access)\n  - \`studioProjectBySlug(slug)\` (enforces the same access rules)\n  - \`myTeams\`\n  - \`projectTeams(projectId)\`\n\n- Write:\n  - \`createStudioProject(input.teamIds?)\` (teamIds optional)\n  - \`setProjectTeams(projectId, teamIds)\` (admin-only)\n
+- Read:
+  - \`myStudioProjects\` (returns only projects you can access)\n  - \`studioProjectBySlug(slug)\` (enforces the same access rules)\n  - \`myTeams\`\n  - \`projectTeams(projectId)\`\n\n- Write:\n  - \`createStudioProject(input.teamIds?)\` (teamIds optional)\n  - \`setProjectTeams(projectId, teamIds)\` (admin-only)\n
+
 ## Related\n+\n+- Team administration + invitations: see \`/docs/tech/studio/team-invitations\`.\n+
 ## Notes
 

package/dist/examples/index.d.ts

@@ -2,4 +2,12 @@ import { ExampleDocumentation, ExampleEntrypoints, ExampleKind, ExampleKindEnum,
 import { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindSchema, ExampleMetaSchema, ExampleSandboxModeSchema, ExampleSpecSchema, ExampleSurfacesSchema, ExampleVisibilitySchema, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec } from "./schema.js";
 import { ExampleRegistry } from "./registry.js";
 import { CrossValidationContext, ExampleValidationError, ExampleValidationWarning, ValidateExampleResult, ValidateExamplesResult, validateExample, validateExampleReferences, validateExamples } from "./validation.js";
-export { type CrossValidationContext, type ExampleDocumentation, ExampleDocumentationSchema, type ExampleEntrypoints, ExampleEntrypointsSchema, type ExampleKind, ExampleKindEnum, ExampleKindSchema, type ExampleMcpSupport, type ExampleMeta, ExampleMetaSchema, ExampleRegistry, type ExampleSandboxMode, ExampleSandboxModeEnum, ExampleSandboxModeSchema, type ExampleSandboxSupport, type ExampleSpec, ExampleSpecSchema, type ExampleStudioSupport, type ExampleSurfaces, ExampleSurfacesSchema, type ExampleValidationError, type ExampleValidationWarning, type ExampleVisibility, ExampleVisibilityEnum, ExampleVisibilitySchema, type ValidateExampleResult, type ValidateExamplesResult, isExampleKind, isExampleVisibility, isFeatureRef, isSpecPointer, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec, validateExample, validateExampleReferences, validateExamples };
+
+//#region src/examples/index.d.ts
+
+/**
+ * Helper to define an Example.
+ */
+declare const defineExample: (spec: ExampleSpec) => ExampleSpec;
+//#endregion
+export { type CrossValidationContext, type ExampleDocumentation, ExampleDocumentationSchema, type ExampleEntrypoints, ExampleEntrypointsSchema, type ExampleKind, ExampleKindEnum, ExampleKindSchema, type ExampleMcpSupport, type ExampleMeta, ExampleMetaSchema, ExampleRegistry, type ExampleSandboxMode, ExampleSandboxModeEnum, ExampleSandboxModeSchema, type ExampleSandboxSupport, type ExampleSpec, ExampleSpecSchema, type ExampleStudioSupport, type ExampleSurfaces, ExampleSurfacesSchema, type ExampleValidationError, type ExampleValidationWarning, type ExampleVisibility, ExampleVisibilityEnum, ExampleVisibilitySchema, type ValidateExampleResult, type ValidateExamplesResult, defineExample, isExampleKind, isExampleVisibility, isFeatureRef, isSpecPointer, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec, validateExample, validateExampleReferences, validateExamples };

package/dist/examples/index.js

@@ -3,4 +3,11 @@ import { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindSchema
 import { ExampleRegistry } from "./registry.js";
 import { validateExample, validateExampleReferences, validateExamples } from "./validation.js";
 
-export { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindEnum, ExampleKindSchema, ExampleMetaSchema, ExampleRegistry, ExampleSandboxModeEnum, ExampleSandboxModeSchema, ExampleSpecSchema, ExampleSurfacesSchema, ExampleVisibilityEnum, ExampleVisibilitySchema, isExampleKind, isExampleVisibility, isFeatureRef, isSpecPointer, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec, validateExample, validateExampleReferences, validateExamples };
+//#region src/examples/index.ts
+/**
+* Helper to define an Example.
+*/
+const defineExample = (spec) => spec;
+
+//#endregion
+export { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindEnum, ExampleKindSchema, ExampleMetaSchema, ExampleRegistry, ExampleSandboxModeEnum, ExampleSandboxModeSchema, ExampleSpecSchema, ExampleSurfacesSchema, ExampleVisibilityEnum, ExampleVisibilitySchema, defineExample, isExampleKind, isExampleVisibility, isFeatureRef, isSpecPointer, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec, validateExample, validateExampleReferences, validateExamples };

package/dist/examples/registry.d.ts

@@ -1,4 +1,4 @@
-import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { SpecContractRegistry } from "../registry.js";
 import { ExampleKind, ExampleSpec, ExampleVisibility } from "./types.js";
 
 //#region src/examples/registry.d.ts
@@ -18,42 +18,20 @@ import { ExampleKind, ExampleSpec, ExampleVisibility } from "./types.js";
  * const publicExamples = registry.listByVisibility('public');
  * ```
  */
-declare class ExampleRegistry {
-  private items;
-  /** Register an example. Throws when the key already exists. */
-  register(spec: ExampleSpec): this;
-  /** List all registered examples. */
-  list(): ExampleSpec[];
-  /** Get an example by its key. */
-  get(key: string, version?: string): ExampleSpec | undefined;
-  /** Check if an example with the given key exists. */
-  has(key: string, version?: string): boolean;
-  /** Get the number of registered examples. */
-  get size(): number;
-  /** Clear all registered examples. */
-  clear(): void;
-  /** Filter examples by criteria. */
-  filter(criteria: RegistryFilter): ExampleSpec[];
+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 with specific tag. */
-  listByTag(tag: string): ExampleSpec[];
-  /** List examples by owner. */
-  listByOwner(owner: string): 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 key function. */
-  groupBy(keyFn: GroupKeyFn<ExampleSpec>): Map<string, ExampleSpec[]>;
   /** Group examples by kind. */
   groupByKind(): Map<ExampleKind, ExampleSpec[]>;
-  /** Get unique tags from all examples. */
-  getUniqueTags(): string[];
   /** Get unique kinds from all examples. */
   getUniqueKinds(): ExampleKind[];
   /** Get unique domains from all examples. */

package/dist/examples/registry.js

@@ -1,11 +1,6 @@
-import { filterBy, getUniqueTags, groupBy, init_registry_utils } from "../registry-utils.js";
-import { compareVersions } from "compare-versions";
+import { SpecContractRegistry } from "../registry.js";
 
 //#region src/examples/registry.ts
-init_registry_utils();
-function exampleKey(meta) {
-	return `${meta.key}.v${meta.version}`;
-}
 /**
 * In-memory registry for ExampleSpec.
 *
@@ -21,44 +16,9 @@ function exampleKey(meta) {
 * const publicExamples = registry.listByVisibility('public');
 * ```
 */
-var ExampleRegistry = class {
-	items = /* @__PURE__ */ new Map();
-	/** Register an example. Throws when the key already exists. */
-	register(spec) {
-		const key = exampleKey(spec.meta);
-		if (this.items.has(key)) throw new Error(`Duplicate example: ${key}`);
-		this.items.set(key, spec);
-		return this;
-	}
-	/** List all registered examples. */
-	list() {
-		return [...this.items.values()];
-	}
-	/** Get an example by its key. */
-	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;
-	}
-	/** Check if an example with the given key exists. */
-	has(key, version) {
-		return !!this.get(key, version);
-	}
-	/** Get the number of registered examples. */
-	get size() {
-		return this.items.size;
-	}
-	/** Clear all registered examples. */
-	clear() {
-		this.items.clear();
-	}
-	/** Filter examples by criteria. */
-	filter(criteria) {
-		return filterBy(this.list(), criteria);
+var ExampleRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("example", items);
 	}
 	/** List examples by kind. */
 	listByKind(kind) {
@@ -68,14 +28,6 @@ var ExampleRegistry = class {
 	listByVisibility(visibility) {
 		return this.list().filter((spec) => spec.meta.visibility === visibility);
 	}
-	/** List examples with specific tag. */
-	listByTag(tag) {
-		return this.list().filter((spec) => spec.meta.tags.includes(tag));
-	}
-	/** List examples by owner. */
-	listByOwner(owner) {
-		return this.list().filter((spec) => spec.meta.owners.includes(owner));
-	}
 	/** List examples by domain. */
 	listByDomain(domain) {
 		return this.list().filter((spec) => spec.meta.domain === domain);
@@ -94,10 +46,6 @@ var ExampleRegistry = class {
 	listInstallable() {
 		return this.list().filter((spec) => spec.surfaces.studio.installable);
 	}
-	/** Group examples by key function. */
-	groupBy(keyFn) {
-		return groupBy(this.list(), keyFn);
-	}
 	/** Group examples by kind. */
 	groupByKind() {
 		const result = /* @__PURE__ */ new Map();
@@ -108,10 +56,6 @@ var ExampleRegistry = class {
 		}
 		return result;
 	}
-	/** Get unique tags from all examples. */
-	getUniqueTags() {
-		return getUniqueTags(this.list());
-	}
 	/** Get unique kinds from all examples. */
 	getUniqueKinds() {
 		const kinds = /* @__PURE__ */ new Set();

package/dist/examples/schema.d.ts

@@ -3,14 +3,14 @@ import { z as z$1 } from "zod";
 
 //#region src/examples/schema.d.ts
 declare const ExampleKindSchema: z$1.ZodEnum<{
-  integration: "integration";
-  template: "template";
+  library: "library";
   workflow: "workflow";
+  template: "template";
+  integration: "integration";
   knowledge: "knowledge";
   blueprint: "blueprint";
   ui: "ui";
   script: "script";
-  library: "library";
 }>;
 declare const ExampleVisibilitySchema: z$1.ZodEnum<{
   experimental: "experimental";
@@ -25,12 +25,12 @@ declare const ExampleSandboxModeSchema: z$1.ZodEnum<{
   evolution: "evolution";
 }>;
 declare const StabilitySchema: z$1.ZodEnum<{
+  deprecated: "deprecated";
   idea: "idea";
   in_creation: "in_creation";
   experimental: "experimental";
   beta: "beta";
   stable: "stable";
-  deprecated: "deprecated";
 }>;
 declare const ExampleDocumentationSchema: z$1.ZodObject<{
   rootDocId: z$1.ZodOptional<z$1.ZodString>;
@@ -93,25 +93,25 @@ declare const ExampleMetaSchema: z$1.ZodObject<{
   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";
-    deprecated: "deprecated";
   }>;
   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<{
-    integration: "integration";
-    template: "template";
+    library: "library";
     workflow: "workflow";
+    template: "template";
+    integration: "integration";
     knowledge: "knowledge";
     blueprint: "blueprint";
     ui: "ui";
     script: "script";
-    library: "library";
   }>;
   visibility: z$1.ZodEnum<{
     experimental: "experimental";
@@ -141,25 +141,25 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     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";
-      deprecated: "deprecated";
     }>;
     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<{
-      integration: "integration";
-      template: "template";
+      library: "library";
       workflow: "workflow";
+      template: "template";
+      integration: "integration";
       knowledge: "knowledge";
       blueprint: "blueprint";
       ui: "ui";
       script: "script";
-      library: "library";
     }>;
     visibility: z$1.ZodEnum<{
       experimental: "experimental";
@@ -221,10 +221,10 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     version: string;
     key: string;
     description: string;
-    stability: "idea" | "in_creation" | "experimental" | "beta" | "stable" | "deprecated";
+    stability: "deprecated" | "idea" | "in_creation" | "experimental" | "beta" | "stable";
     owners: string[];
     tags: string[];
-    kind: "integration" | "template" | "workflow" | "knowledge" | "blueprint" | "ui" | "script" | "library";
+    kind: "library" | "workflow" | "template" | "integration" | "knowledge" | "blueprint" | "ui" | "script";
     visibility: "experimental" | "public" | "internal";
     title?: string | undefined;
     domain?: string | undefined;