@contractspec/lib.contracts 0.0.0-canary-20260119224949 → 0.0.0-canary-20260128200020

package/dist/docs/queries/docsIndex.query.js

@@ -0,0 +1,130 @@
+import { defineQuery } from "../../operations/operation.js";
+import "../../operations/index.js";
+import { DOCS_CAPABILITY_REF, DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/docs/queries/docsIndex.query.ts
+const DocSummaryModel = new SchemaModel({
+	name: "DocSummary",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		title: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		summary: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		route: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		visibility: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		kind: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		version: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		tags: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		}
+	}
+});
+const DocsIndexInput = new SchemaModel({
+	name: "DocsIndexInput",
+	fields: {
+		query: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		tag: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		},
+		visibility: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		kind: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		limit: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		offset: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const DocsIndexOutput = new SchemaModel({
+	name: "DocsIndexOutput",
+	fields: {
+		items: {
+			type: DocSummaryModel,
+			isOptional: true,
+			isArray: true
+		},
+		docs: {
+			type: DocSummaryModel,
+			isOptional: false,
+			isArray: true
+		},
+		total: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		nextOffset: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const DocsIndexQuery = defineQuery({
+	meta: {
+		key: "docs.search",
+		title: "Docs Index",
+		version: "1.0.0",
+		description: "Search and filter DocBlocks by query, tag, or visibility.",
+		goal: "Provide a consistent index of documentation entries for UI and MCP.",
+		context: "Used by docs surfaces to list and filter DocBlocks without coupling to storage.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [
+			...DOCS_TAGS,
+			"search",
+			"index"
+		],
+		stability: DOCS_STABILITY,
+		docId: [docId("docs.tech.docs-search")]
+	},
+	capability: DOCS_CAPABILITY_REF,
+	io: {
+		input: DocsIndexInput,
+		output: DocsIndexOutput
+	},
+	policy: {
+		auth: "anonymous",
+		pii: []
+	}
+});
+
+//#endregion
+export { DocSummaryModel, DocsIndexInput, DocsIndexOutput, DocsIndexQuery };

package/dist/docs/queries/index.d.ts

@@ -0,0 +1,3 @@
+import { DocSummaryModel, DocsIndexInput, DocsIndexOutput, DocsIndexQuery } from "./docsIndex.query.js";
+import { ContractReferenceInput, ContractReferenceModel, ContractReferenceOutput, ContractReferenceQuery } from "./contractReference.query.js";
+export { ContractReferenceInput, ContractReferenceModel, ContractReferenceOutput, ContractReferenceQuery, DocSummaryModel, DocsIndexInput, DocsIndexOutput, DocsIndexQuery };

package/dist/docs/queries/index.js

@@ -0,0 +1,4 @@
+import { DocSummaryModel, DocsIndexInput, DocsIndexOutput, DocsIndexQuery } from "./docsIndex.query.js";
+import { ContractReferenceInput, ContractReferenceModel, ContractReferenceOutput, ContractReferenceQuery } from "./contractReference.query.js";
+
+export { ContractReferenceInput, ContractReferenceModel, ContractReferenceOutput, ContractReferenceQuery, DocSummaryModel, DocsIndexInput, DocsIndexOutput, DocsIndexQuery };

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

@@ -60,6 +60,10 @@ Generate implementation code from contract specs using AI agents or templates.
 contractspec build src/contracts/signup.contracts.ts --agent-mode claude-code
 \`\`\`
 
+Available agent modes: simple, cursor, claude-code, openai-codex, opencode (alias for opencode-sdk).
+
+OpenCode uses \`@opencode-ai/sdk\` via dynamic import and is ideal for teams running a self-hosted, open backend.
+
 ### \`validate\`
 
 Validate contract specifications and verify implementations.
@@ -68,6 +72,12 @@ Validate contract specifications and verify implementations.
 contractspec validate src/contracts/signup.contracts.ts --check-implementation
 \`\`\`
 
+You can also validate with OpenCode:
+
+\`\`\`bash
+contractspec validate src/contracts/signup.contracts.ts --check-implementation --agent-mode opencode
+\`\`\`
+
 ### \`watch\`
 
 Watch contract specifications and auto-regenerate on changes.

package/dist/docs/tech/docs-system.docblock.d.ts

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

package/dist/docs/tech/docs-system.docblock.js

@@ -0,0 +1,128 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/docs-system.docblock.ts
+registerDocBlocks([
+	{
+		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\`.
+`
+	}
+]);
+
+//#endregion

package/dist/docs/views/contractReference.dataView.d.ts

@@ -0,0 +1,7 @@
+import { DataViewSpec } from "../../data-views/spec.js";
+import "../../index.js";
+
+//#region src/docs/views/contractReference.dataView.d.ts
+declare const ContractReferenceDataView: DataViewSpec;
+//#endregion
+export { ContractReferenceDataView };

package/dist/docs/views/contractReference.dataView.js

@@ -0,0 +1,80 @@
+import { defineDataView } from "../../data-views/spec.js";
+import "../../data-views/index.js";
+import { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { ContractReferenceQuery } from "../queries/contractReference.query.js";
+
+//#region src/docs/views/contractReference.dataView.ts
+const ContractReferenceDataView = defineDataView({
+	meta: {
+		key: "docs.contract.reference.view",
+		title: "Contract Reference",
+		version: "1.0.0",
+		description: "Detail view for a single contract reference.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "reference"],
+		stability: DOCS_STABILITY,
+		entity: "contract-reference",
+		docId: [docId("docs.tech.docs-reference")]
+	},
+	source: { primary: {
+		key: ContractReferenceQuery.meta.key,
+		version: ContractReferenceQuery.meta.version
+	} },
+	view: {
+		kind: "detail",
+		fields: [
+			{
+				key: "key",
+				label: "Key",
+				dataPath: "reference.key"
+			},
+			{
+				key: "version",
+				label: "Version",
+				dataPath: "reference.version"
+			},
+			{
+				key: "type",
+				label: "Type",
+				dataPath: "reference.type"
+			},
+			{
+				key: "title",
+				label: "Title",
+				dataPath: "reference.title"
+			},
+			{
+				key: "description",
+				label: "Description",
+				dataPath: "reference.description"
+			},
+			{
+				key: "tags",
+				label: "Tags",
+				dataPath: "reference.tags"
+			},
+			{
+				key: "owners",
+				label: "Owners",
+				dataPath: "reference.owners"
+			},
+			{
+				key: "stability",
+				label: "Stability",
+				dataPath: "reference.stability"
+			}
+		],
+		primaryField: "title",
+		secondaryFields: ["description"]
+	},
+	policy: {
+		flags: [],
+		pii: []
+	}
+});
+
+//#endregion
+export { ContractReferenceDataView };

package/dist/docs/views/docsIndex.dataView.d.ts

@@ -0,0 +1,7 @@
+import { DataViewSpec } from "../../data-views/spec.js";
+import "../../index.js";
+
+//#region src/docs/views/docsIndex.dataView.d.ts
+declare const DocsIndexDataView: DataViewSpec;
+//#endregion
+export { DocsIndexDataView };

package/dist/docs/views/docsIndex.dataView.js

@@ -0,0 +1,136 @@
+import { defineDataView } from "../../data-views/spec.js";
+import "../../data-views/index.js";
+import { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { DocsIndexQuery } from "../queries/docsIndex.query.js";
+
+//#region src/docs/views/docsIndex.dataView.ts
+const DocsIndexDataView = defineDataView({
+	meta: {
+		key: "docs.index.view",
+		title: "Docs Index",
+		version: "1.0.0",
+		description: "List and filter documentation entries.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "index"],
+		stability: DOCS_STABILITY,
+		entity: "docs",
+		docId: [docId("docs.tech.docs-search")]
+	},
+	source: { primary: {
+		key: DocsIndexQuery.meta.key,
+		version: DocsIndexQuery.meta.version
+	} },
+	view: {
+		kind: "list",
+		fields: [
+			{
+				key: "id",
+				label: "ID",
+				dataPath: "id"
+			},
+			{
+				key: "title",
+				label: "Title",
+				dataPath: "title"
+			},
+			{
+				key: "summary",
+				label: "Summary",
+				dataPath: "summary"
+			},
+			{
+				key: "route",
+				label: "Route",
+				dataPath: "route"
+			},
+			{
+				key: "tags",
+				label: "Tags",
+				dataPath: "tags",
+				format: "badge"
+			},
+			{
+				key: "kind",
+				label: "Kind",
+				dataPath: "kind"
+			},
+			{
+				key: "visibility",
+				label: "Visibility",
+				dataPath: "visibility"
+			}
+		],
+		primaryField: "title",
+		secondaryFields: ["summary", "route"],
+		filters: [
+			{
+				key: "query",
+				label: "Search",
+				field: "query",
+				type: "search"
+			},
+			{
+				key: "visibility",
+				label: "Visibility",
+				field: "visibility",
+				type: "enum",
+				options: [
+					{
+						value: "public",
+						label: "Public"
+					},
+					{
+						value: "internal",
+						label: "Internal"
+					},
+					{
+						value: "mixed",
+						label: "Mixed"
+					}
+				]
+			},
+			{
+				key: "kind",
+				label: "Kind",
+				field: "kind",
+				type: "enum",
+				options: [
+					{
+						value: "goal",
+						label: "Goal"
+					},
+					{
+						value: "how",
+						label: "How"
+					},
+					{
+						value: "usage",
+						label: "Usage"
+					},
+					{
+						value: "reference",
+						label: "Reference"
+					},
+					{
+						value: "faq",
+						label: "FAQ"
+					},
+					{
+						value: "changelog",
+						label: "Changelog"
+					}
+				]
+			}
+		]
+	},
+	policy: {
+		flags: [],
+		pii: []
+	}
+});
+
+//#endregion
+export { DocsIndexDataView };

package/dist/docs/views/exampleCatalog.dataView.d.ts

@@ -0,0 +1,7 @@
+import { DataViewSpec } from "../../data-views/spec.js";
+import "../../index.js";
+
+//#region src/docs/views/exampleCatalog.dataView.d.ts
+declare const ExampleCatalogDataView: DataViewSpec;
+//#endregion
+export { ExampleCatalogDataView };

package/dist/docs/views/exampleCatalog.dataView.js

@@ -0,0 +1,91 @@
+import { defineDataView } from "../../data-views/spec.js";
+import "../../data-views/index.js";
+import { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { DocsIndexQuery } from "../queries/docsIndex.query.js";
+
+//#region src/docs/views/exampleCatalog.dataView.ts
+const ExampleCatalogDataView = defineDataView({
+	meta: {
+		key: "docs.examples.catalog.view",
+		title: "Examples Catalog",
+		version: "1.0.0",
+		description: "Catalog view of ContractSpec examples and demos.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "examples"],
+		stability: DOCS_STABILITY,
+		entity: "docs-examples",
+		docId: [docId("docs.tech.docs-examples")]
+	},
+	source: { primary: {
+		key: DocsIndexQuery.meta.key,
+		version: DocsIndexQuery.meta.version
+	} },
+	view: {
+		kind: "grid",
+		fields: [
+			{
+				key: "id",
+				label: "ID",
+				dataPath: "id"
+			},
+			{
+				key: "title",
+				label: "Title",
+				dataPath: "title"
+			},
+			{
+				key: "summary",
+				label: "Summary",
+				dataPath: "summary"
+			},
+			{
+				key: "route",
+				label: "Route",
+				dataPath: "route"
+			},
+			{
+				key: "tags",
+				label: "Tags",
+				dataPath: "tags",
+				format: "badge"
+			}
+		],
+		primaryField: "title",
+		secondaryFields: ["summary"],
+		filters: [{
+			key: "query",
+			label: "Search",
+			field: "query",
+			type: "search"
+		}, {
+			key: "tags",
+			label: "Tags",
+			field: "tag",
+			type: "enum",
+			options: [
+				{
+					value: "examples",
+					label: "Examples"
+				},
+				{
+					value: "templates",
+					label: "Templates"
+				},
+				{
+					value: "sandbox",
+					label: "Sandbox"
+				}
+			]
+		}]
+	},
+	policy: {
+		flags: [],
+		pii: []
+	}
+});
+
+//#endregion
+export { ExampleCatalogDataView };

package/dist/docs/views/index.d.ts

@@ -0,0 +1,4 @@
+import { DocsIndexDataView } from "./docsIndex.dataView.js";
+import { ContractReferenceDataView } from "./contractReference.dataView.js";
+import { ExampleCatalogDataView } from "./exampleCatalog.dataView.js";
+export { ContractReferenceDataView, DocsIndexDataView, ExampleCatalogDataView };

package/dist/docs/views/index.js

@@ -0,0 +1,5 @@
+import { DocsIndexDataView } from "./docsIndex.dataView.js";
+import { ContractReferenceDataView } from "./contractReference.dataView.js";
+import { ExampleCatalogDataView } from "./exampleCatalog.dataView.js";
+
+export { ContractReferenceDataView, DocsIndexDataView, ExampleCatalogDataView };