@contractspec/lib.contracts 1.52.0 → 1.54.0

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

@@ -0,0 +1,125 @@
+import { defineQuery } from "../../operations/operation.js";
+import "../../operations/index.js";
+import { 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/contractReference.query.ts
+const ContractReferenceInput = new SchemaModel({
+	name: "ContractReferenceInput",
+	fields: {
+		key: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		type: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		format: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		includeSchema: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const ContractReferenceModel = new SchemaModel({
+	name: "ContractReference",
+	fields: {
+		key: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		type: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		title: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		description: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		markdown: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		route: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		schema: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: true
+		},
+		policy: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: true
+		},
+		tags: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		},
+		owners: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		},
+		stability: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const ContractReferenceOutput = new SchemaModel({
+	name: "ContractReferenceOutput",
+	fields: { reference: {
+		type: ContractReferenceModel,
+		isOptional: false
+	} }
+});
+const ContractReferenceQuery = defineQuery({
+	meta: {
+		key: "docs.contract.reference",
+		title: "Contract Reference",
+		version: "1.0.0",
+		description: "Resolve a contract into a documentation-ready reference.",
+		goal: "Expose a canonical reference view for any ContractSpec surface.",
+		context: "Used by docs generators and UI to render consistent reference pages.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "reference"],
+		stability: DOCS_STABILITY,
+		docId: [docId("docs.tech.docs-reference")]
+	},
+	capability: {
+		key: "docs.system",
+		version: "1.0.0"
+	},
+	io: {
+		input: ContractReferenceInput,
+		output: ContractReferenceOutput
+	},
+	policy: {
+		auth: "anonymous",
+		pii: []
+	}
+});
+
+//#endregion
+export { ContractReferenceInput, ContractReferenceModel, ContractReferenceOutput, ContractReferenceQuery };

package/dist/docs/queries/docsIndex.query.d.ts

@@ -0,0 +1,272 @@
+import { OperationSpec } from "../../operations/operation.js";
+import "../../index.js";
+import * as _contractspec_lib_schema426 from "@contractspec/lib.schema";
+import { SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/docs/queries/docsIndex.query.d.ts
+declare const DocSummaryModel: SchemaModel<{
+  id: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: false;
+  };
+  title: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: false;
+  };
+  summary: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  route: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  visibility: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  kind: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  version: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  tags: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+}>;
+declare const DocsIndexInput: SchemaModel<{
+  query: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  tag: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+  visibility: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  kind: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  limit: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+  offset: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+}>;
+declare const DocsIndexOutput: SchemaModel<{
+  items: {
+    type: SchemaModel<{
+      id: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      title: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      summary: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      route: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      visibility: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      kind: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      version: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      tags: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+      };
+    }>;
+    isOptional: true;
+    isArray: true;
+  };
+  docs: {
+    type: SchemaModel<{
+      id: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      title: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      summary: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      route: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      visibility: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      kind: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      version: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      tags: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+      };
+    }>;
+    isOptional: false;
+    isArray: true;
+  };
+  total: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+  nextOffset: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+}>;
+declare const DocsIndexQuery: OperationSpec<SchemaModel<{
+  query: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  tag: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+  visibility: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  kind: {
+    type: _contractspec_lib_schema426.FieldType<string, string>;
+    isOptional: true;
+  };
+  limit: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+  offset: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  items: {
+    type: SchemaModel<{
+      id: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      title: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      summary: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      route: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      visibility: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      kind: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      version: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      tags: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+      };
+    }>;
+    isOptional: true;
+    isArray: true;
+  };
+  docs: {
+    type: SchemaModel<{
+      id: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      title: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: false;
+      };
+      summary: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      route: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      visibility: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      kind: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      version: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+      };
+      tags: {
+        type: _contractspec_lib_schema426.FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+      };
+    }>;
+    isOptional: false;
+    isArray: true;
+  };
+  total: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+  nextOffset: {
+    type: _contractspec_lib_schema426.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, undefined>;
+//#endregion
+export { DocSummaryModel, DocsIndexInput, DocsIndexOutput, DocsIndexQuery };

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

@@ -0,0 +1,133 @@
+import { defineQuery } from "../../operations/operation.js";
+import "../../operations/index.js";
+import { 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: {
+		key: "docs.system",
+		version: "1.0.0"
+	},
+	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/tech/report-verification-table.docblock.d.ts

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