@lssm/lib.contracts 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/contracts-adapter-input.js

@@ -1 +1,77 @@
-function e(e){return typeof e?.getPothosInput==`function`&&typeof e?.getZod==`function`}function t(e){return typeof e?.getPothos==`function`}function n(e){return typeof e?.getEnumValues==`function`&&typeof e?.getPothos==`function`}function r(e){return e===`Boolean_unsecure`?`Boolean`:e===`ID_unsecure`?`ID`:e===`String_unsecure`?`String`:e===`Int_unsecure`?`Int`:e===`Float_unsecure`?`Float`:e}function i(i){let a=new Map,o=new Set;function s(t){let r=Object.entries(t.config.fields);for(let[,t]of r)if(e(t.type))s(t.type);else if(n(t.type)){let e=t.type,n=e.getName?.()??e.getPothos().name;o.has(n)||(i.enumType(n,{values:e.getEnumValues()}),o.add(n))}}function c(n){let o=String(n.config?.name??`Input`),l=a.get(o);if(l)return l;s(n);let u=i.inputType(n.getPothosInput(),{fields:i=>{let a=Object.entries(n.config.fields),o={};for(let[n,s]of a)if(e(s.type)){let e=c(s.type),t=s.isArray?[e]:e;o[n]=i.field({type:t,required:!s.isOptional})}else if(t(s.type)){let e=r(String(s.type.getPothos().name)),t=s.isArray?[e]:e;o[n]=i.field({type:t,required:!s.isOptional})}else{let e=s.isArray?[`JSON`]:`JSON`;o[n]=i.field({type:e,required:!s.isOptional})}return o}});return a.set(o,u),u}function l(e){return!e||!e.config?.fields||Object.keys(e.config.fields).length===0?null:c(e)}return{buildInputFieldArgs:l}}export{i as createInputTypeBuilder,e as isSchemaModel};
+//#region src/contracts-adapter-input.ts
+function isSchemaModel(x) {
+	return typeof x?.getPothosInput === "function" && typeof x?.getZod === "function";
+}
+function isFieldType(x) {
+	return typeof x?.getPothos === "function";
+}
+function isEnumType(x) {
+	return typeof x?.getEnumValues === "function" && typeof x?.getPothos === "function";
+}
+function mapScalarName(name) {
+	if (name === "Boolean_unsecure") return "Boolean";
+	if (name === "ID_unsecure") return "ID";
+	if (name === "String_unsecure") return "String";
+	if (name === "Int_unsecure") return "Int";
+	if (name === "Float_unsecure") return "Float";
+	return name;
+}
+function createInputTypeBuilder(builder) {
+	const inputTypeCache = /* @__PURE__ */ new Map();
+	const enumTypeCache = /* @__PURE__ */ new Set();
+	function registerEnumsForModel(model) {
+		const entries = Object.entries(model.config.fields);
+		for (const [, field] of entries) if (isSchemaModel(field.type)) registerEnumsForModel(field.type);
+		else if (isEnumType(field.type)) {
+			const enumObj = field.type;
+			const name = enumObj.getName?.() ?? enumObj.getPothos().name;
+			if (!enumTypeCache.has(name)) {
+				builder.enumType(name, { values: enumObj.getEnumValues() });
+				enumTypeCache.add(name);
+			}
+		}
+	}
+	function ensureInputTypeForModel(model) {
+		const typeName = String(model.config?.name ?? "Input");
+		const cached = inputTypeCache.get(typeName);
+		if (cached) return cached;
+		registerEnumsForModel(model);
+		const created = builder.inputType(model.getPothosInput(), { fields: (t) => {
+			const entries = Object.entries(model.config.fields);
+			const acc = {};
+			for (const [key, field] of entries) if (isSchemaModel(field.type)) {
+				const nested = ensureInputTypeForModel(field.type);
+				const typeRef = field.isArray ? [nested] : nested;
+				acc[key] = t.field({
+					type: typeRef,
+					required: !field.isOptional
+				});
+			} else if (isFieldType(field.type)) {
+				const typeName$1 = mapScalarName(String(field.type.getPothos().name));
+				const typeRef = field.isArray ? [typeName$1] : typeName$1;
+				acc[key] = t.field({
+					type: typeRef,
+					required: !field.isOptional
+				});
+			} else {
+				const typeRef = field.isArray ? ["JSON"] : "JSON";
+				acc[key] = t.field({
+					type: typeRef,
+					required: !field.isOptional
+				});
+			}
+			return acc;
+		} });
+		inputTypeCache.set(typeName, created);
+		return created;
+	}
+	function buildInputFieldArgs(model) {
+		if (!model) return null;
+		if (!model.config?.fields || Object.keys(model.config.fields).length === 0) return null;
+		return ensureInputTypeForModel(model);
+	}
+	return { buildInputFieldArgs };
+}
+
+//#endregion
+export { createInputTypeBuilder, isSchemaModel };

package/dist/data-views/docs/data-views.docblock.js

@@ -1 +1,22 @@
-import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.data-views`,title:`DataViewSpec Overview`,summary:"`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/data-views`,tags:[`tech`,`contracts`,`data-views`],body:"# DataViewSpec Overview\n\n## Purpose\n\n`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.\n\n## Location\n\n- Type definitions and registry: `packages/libs/contracts/src/data-views.ts`\n- React renderers: `packages/libs/design-system/src/components/data-view`\n- CLI scaffolding: `contractspec create --type data-view`\n\n## Schema Highlights\n\n```ts\nexport interface DataViewSpec {\n  meta: DataViewMeta;       // ownership meta + { name, version, entity }\n  source: DataViewSource;   // contract operations and refresh events\n  view: DataViewConfig;     // union of list/detail/table/grid definitions\n  states?: DataViewStates;  // optional empty/error/loading presentations\n  policy?: { flags?: string[]; pii?: string[] };\n}\n```\n\n- **DataViewMeta**: `name`, `version`, `entity`, ownership metadata (title, description, domain, owners, tags, stability).\n- **DataViewSource**:\n  - `primary`: required query operation (`OpRef`) for fetching collections.\n  - `item`: optional detail query (recommended for `detail` views).\n  - `mutations`: optional create/update/delete operation refs.\n  - `refreshEvents`: events that should trigger refresh.\n- **DataViewConfig** (union):\n  - `list`: card/compact list, `primaryField`, `secondaryFields`.\n  - `table`: column configuration (`columns`, alignments, density).\n  - `detail`: sections of fields for record inspection.\n  - `grid`: multi-column grid (rendered as card list today).\n- **DataViewField**: `key`, `label`, `dataPath`, formatting hints (`format`), sort/filter toggles, optional presentation override.\n- **DataViewFilter**: describes filter inputs (search, enum, number, date, boolean).\n- **DataViewAction**: simple declarative actions (`navigation` or `operation`).\n\n## Registry Usage\n\n```ts\nimport { DataViewRegistry } from '@lssm/lib.contracts/data-views';\nimport { ResidentsDataView } from './data-views/residents.data-view';\n\nconst registry = new DataViewRegistry();\nregistry.register(ResidentsDataView);\n\nconst listView = registry.get('residents.admin.list');\n```\n\nRegistries guard against duplicate `(name, version)` pairs and make latest-version lookup trivial.\n\n## Rendering\n\n```tsx\nimport { DataViewRenderer } from '@lssm/lib.design-system';\nimport { ResidentsDataView } from '../contracts/data-views/residents.data-view';\n\nfunction ResidentsTable({ rows }: { rows: Record<string, unknown>[] }) {\n  return (\n    <DataViewRenderer\n      spec={ResidentsDataView}\n      items={rows}\n      onRowClick={(row) => console.log('Selected', row)}\n    />\n  );\n}\n```\n\nFor more control, use specific components:\n\n- `DataViewList` – friendly cards/rows\n- `DataViewTable` – tabular presentation with optional header/footers\n- `DataViewDetail` – two-column grouped layout for record inspection\n\nRenderers rely on the field definitions (`dataPath`, `format`) to extract values and render them consistently.\n\n## CLI Scaffolding\n\n```bash\n# Interactive wizard\ncontractspec create --type data-view\n\n# Generates packages/.../data-views/<name>.data-view.ts\n\n# Optional renderer scaffold\ncontractspec build path/to/<name>.data-view.ts\n# → produces <name>.renderer.tsx that wraps DataViewRenderer with sensible props\n```\n\nWizard prompts:\n- name (dot notation), version, entity\n- kind (`list`, `table`, `detail`, `grid`)\n- primary query operation (required) and optional item query\n- fields (label, data path, format, sorting/filtering)\n\n## Authoring Guidelines\n\n1. **Separation of data & presentation**: keep fetching logic inside contract operations; DataViewSpec only references them via `source`.\n2. **Versioning**: bump `meta.version` when field membership, ordering, or semantics change.\n3. **Consistency**: reuse common field keys across modules to enable shared renderers and filters.\n4. **States**: reference `PresentationRef` for empty/error/loader states to ensure consistent UX.\n5. **Actions**: prefer referencing contract operations instead of embedding business logic in the UI.\n\n## Roadmap\n\n- Derived filters from `fields.filterable` (auto-generated UI).\n- Table density presets per platform.\n- Bridge to PolicySpec for field-level visibility (Phase 2 policy expansion).\n- Automated docs/LLM sync via CLI.\n\n"}];e(t);export{t as tech_contracts_data_views_DocBlocks};
+import { registerDocBlocks } from "../../docs/registry.js";
+import "../../registry.js";
+
+//#region src/data-views/docs/data-views.docblock.ts
+const tech_contracts_data_views_DocBlocks = [{
+	id: "docs.tech.contracts.data-views",
+	title: "DataViewSpec Overview",
+	summary: "`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/data-views",
+	tags: [
+		"tech",
+		"contracts",
+		"data-views"
+	],
+	body: "# DataViewSpec Overview\n\n## Purpose\n\n`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.\n\n## Location\n\n- Type definitions and registry: `packages/libs/contracts/src/data-views.ts`\n- React renderers: `packages/libs/design-system/src/components/data-view`\n- CLI scaffolding: `contractspec create --type data-view`\n\n## Schema Highlights\n\n```ts\nexport interface DataViewSpec {\n  meta: DataViewMeta;       // ownership meta + { name, version, entity }\n  source: DataViewSource;   // contract operations and refresh events\n  view: DataViewConfig;     // union of list/detail/table/grid definitions\n  states?: DataViewStates;  // optional empty/error/loading presentations\n  policy?: { flags?: string[]; pii?: string[] };\n}\n```\n\n- **DataViewMeta**: `name`, `version`, `entity`, ownership metadata (title, description, domain, owners, tags, stability).\n- **DataViewSource**:\n  - `primary`: required query operation (`OpRef`) for fetching collections.\n  - `item`: optional detail query (recommended for `detail` views).\n  - `mutations`: optional create/update/delete operation refs.\n  - `refreshEvents`: events that should trigger refresh.\n- **DataViewConfig** (union):\n  - `list`: card/compact list, `primaryField`, `secondaryFields`.\n  - `table`: column configuration (`columns`, alignments, density).\n  - `detail`: sections of fields for record inspection.\n  - `grid`: multi-column grid (rendered as card list today).\n- **DataViewField**: `key`, `label`, `dataPath`, formatting hints (`format`), sort/filter toggles, optional presentation override.\n- **DataViewFilter**: describes filter inputs (search, enum, number, date, boolean).\n- **DataViewAction**: simple declarative actions (`navigation` or `operation`).\n\n## Registry Usage\n\n```ts\nimport { DataViewRegistry } from '@lssm/lib.contracts/data-views';\nimport { ResidentsDataView } from './data-views/residents.data-view';\n\nconst registry = new DataViewRegistry();\nregistry.register(ResidentsDataView);\n\nconst listView = registry.get('residents.admin.list');\n```\n\nRegistries guard against duplicate `(name, version)` pairs and make latest-version lookup trivial.\n\n## Rendering\n\n```tsx\nimport { DataViewRenderer } from '@lssm/lib.design-system';\nimport { ResidentsDataView } from '../contracts/data-views/residents.data-view';\n\nfunction ResidentsTable({ rows }: { rows: Record<string, unknown>[] }) {\n  return (\n    <DataViewRenderer\n      spec={ResidentsDataView}\n      items={rows}\n      onRowClick={(row) => console.log('Selected', row)}\n    />\n  );\n}\n```\n\nFor more control, use specific components:\n\n- `DataViewList` – friendly cards/rows\n- `DataViewTable` – tabular presentation with optional header/footers\n- `DataViewDetail` – two-column grouped layout for record inspection\n\nRenderers rely on the field definitions (`dataPath`, `format`) to extract values and render them consistently.\n\n## CLI Scaffolding\n\n```bash\n# Interactive wizard\ncontractspec create --type data-view\n\n# Generates packages/.../data-views/<name>.data-view.ts\n\n# Optional renderer scaffold\ncontractspec build path/to/<name>.data-view.ts\n# → produces <name>.renderer.tsx that wraps DataViewRenderer with sensible props\n```\n\nWizard prompts:\n- name (dot notation), version, entity\n- kind (`list`, `table`, `detail`, `grid`)\n- primary query operation (required) and optional item query\n- fields (label, data path, format, sorting/filtering)\n\n## Authoring Guidelines\n\n1. **Separation of data & presentation**: keep fetching logic inside contract operations; DataViewSpec only references them via `source`.\n2. **Versioning**: bump `meta.version` when field membership, ordering, or semantics change.\n3. **Consistency**: reuse common field keys across modules to enable shared renderers and filters.\n4. **States**: reference `PresentationRef` for empty/error/loader states to ensure consistent UX.\n5. **Actions**: prefer referencing contract operations instead of embedding business logic in the UI.\n\n## Roadmap\n\n- Derived filters from `fields.filterable` (auto-generated UI).\n- Table density presets per platform.\n- Bridge to PolicySpec for field-level visibility (Phase 2 policy expansion).\n- Automated docs/LLM sync via CLI.\n\n"
+}];
+registerDocBlocks(tech_contracts_data_views_DocBlocks);
+
+//#endregion
+export { tech_contracts_data_views_DocBlocks };

package/dist/data-views/query-generator.js

@@ -1 +1,48 @@
-var e=class{constructor(e){this.spec=e}generate(e){let{primary:t}=this.spec.source,n=e.pagination?.page??1,r=e.pagination?.pageSize??20,i=(n-1)*r,a=r,o={skip:i,take:a,...e.filters};return e.search&&(o.search=e.search),e.sort&&(o.orderBy={[e.sort.field]:e.sort.direction}),{operationName:t.name,input:o,meta:{pagination:{page:n,pageSize:r,skip:i,take:a},sorting:e.sort}}}validateParams(e){let t=[];if(e.filters&&this.spec.view.filters)for(let n of Object.keys(e.filters))this.spec.view.filters.find(e=>e.key===n)||t.push(`Unknown filter key: ${n}`);if(e.sort){let n=this.spec.view.fields.find(t=>t.key===e.sort.field);n?n.sortable===!1&&t.push(`Field is not sortable: ${e.sort.field}`):t.push(`Unknown sort field: ${e.sort.field}`)}return t}};export{e as DataViewQueryGenerator};
+//#region src/data-views/query-generator.ts
+var DataViewQueryGenerator = class {
+	constructor(spec) {
+		this.spec = spec;
+	}
+	generate(params) {
+		const { primary } = this.spec.source;
+		const page = params.pagination?.page ?? 1;
+		const pageSize = params.pagination?.pageSize ?? 20;
+		const skip = (page - 1) * pageSize;
+		const take = pageSize;
+		const input = {
+			skip,
+			take,
+			...params.filters
+		};
+		if (params.search) input.search = params.search;
+		if (params.sort) input.orderBy = { [params.sort.field]: params.sort.direction };
+		return {
+			operationName: primary.name,
+			input,
+			meta: {
+				pagination: {
+					page,
+					pageSize,
+					skip,
+					take
+				},
+				sorting: params.sort
+			}
+		};
+	}
+	validateParams(params) {
+		const errors = [];
+		if (params.filters && this.spec.view.filters) {
+			for (const key of Object.keys(params.filters)) if (!this.spec.view.filters.find((f) => f.key === key)) errors.push(`Unknown filter key: ${key}`);
+		}
+		if (params.sort) {
+			const field = this.spec.view.fields.find((f) => f.key === params.sort.field);
+			if (!field) errors.push(`Unknown sort field: ${params.sort.field}`);
+			else if (field.sortable === false) errors.push(`Field is not sortable: ${params.sort.field}`);
+		}
+		return errors;
+	}
+};
+
+//#endregion
+export { DataViewQueryGenerator };

package/dist/data-views/runtime.js

@@ -1 +1,39 @@
-var e=class{cache=new Map;subscriptions=new Map;constructor(e){this.config=e}register(e){this.config.registry.register(e)}getSpec(e,t){return this.config.registry.get(e,t)}async executeQuery(e,t){if(!this.getSpec(e))throw Error(`DataView spec not found: ${e}`);return{data:[],total:0,loading:!1}}invalidate(e){this.cache.delete(e),this.notifySubscribers(e)}subscribe(e,t){return this.subscriptions.has(e)||this.subscriptions.set(e,new Set),this.subscriptions.get(e).add(t),()=>{this.subscriptions.get(e)?.delete(t)}}notifySubscribers(e){this.subscriptions.get(e)?.forEach(e=>e())}};export{e as DataViewRuntime};
+//#region src/data-views/runtime.ts
+var DataViewRuntime = class {
+	cache = /* @__PURE__ */ new Map();
+	subscriptions = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.config = config;
+	}
+	register(spec) {
+		this.config.registry.register(spec);
+	}
+	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
+		};
+	}
+	invalidate(specName) {
+		this.cache.delete(specName);
+		this.notifySubscribers(specName);
+	}
+	subscribe(specName, callback) {
+		if (!this.subscriptions.has(specName)) this.subscriptions.set(specName, /* @__PURE__ */ new Set());
+		this.subscriptions.get(specName).add(callback);
+		return () => {
+			this.subscriptions.get(specName)?.delete(callback);
+		};
+	}
+	notifySubscribers(specName) {
+		this.subscriptions.get(specName)?.forEach((cb) => cb());
+	}
+};
+
+//#endregion
+export { DataViewRuntime };

package/dist/data-views.js

@@ -1 +1,35 @@
-function e(e){return`${e.meta.name}.v${e.meta.version}`}var t=class{items=new Map;register(t){let n=e(t);if(this.items.has(n))throw Error(`Duplicate data view ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let t of this.items.values())t.meta.name===e&&t.meta.version>r&&(r=t.meta.version,n=t);return n}};function n(t){return e(t)}export{t as DataViewRegistry,n as dataViewKey};
+//#region src/data-views.ts
+function keyOf(spec) {
+	return `${spec.meta.name}.v${spec.meta.version}`;
+}
+var DataViewRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = keyOf(spec);
+		if (this.items.has(key)) throw new Error(`Duplicate data view ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.name !== name) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+};
+function dataViewKey(spec) {
+	return keyOf(spec);
+}
+
+//#endregion
+export { DataViewRegistry, dataViewKey };

package/dist/docs/PUBLISHING.docblock.js

@@ -1,76 +1,17 @@
-import{registerDocBlocks as e}from"./registry.js";const t=[{id:`docs.PUBLISHING`,title:`Publishing ContractSpec Libraries`,summary:`This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).`,kind:`reference`,visibility:`public`,route:`/docs/PUBLISHING`,tags:[`PUBLISHING`],body:`# Publishing ContractSpec Libraries
-
-This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).
-
-## Release Tracks
-
-| Track | Branch | npm Tag | Frequency | Versioning | Use Case |
-|-------|--------|---------|-----------|------------|----------|
-| **Stable** | \`release\` | \`latest\` | Manual | SemVer (e.g., \`1.7.4\`) | Production, external users |
-| **Canary** | \`main\` | \`canary\` | Every Push | Snapshot (e.g., \`1.7.4-canary...\`) | Dev, internal testing |
-
-## Prerequisites
-
-- ✅ \`NPM_TOKEN\` secret is configured in GitHub (owner or automation token with _publish_ scope).
-- ✅ \`GITHUB_TOKEN\` (built-in) has permissions to create PRs (enabled by default in new repos).
-- ✅ For stable releases: \`release\` branch exists and is protected.
-
-## Canary Workflow (Automatic)
-
-Every commit pushed to \`main\` triggers the \`.github/workflows/publish-canary.yml\` workflow.
-
-1. **Trigger**: Push to \`main\`.
-2. **Versioning**: Runs \`changeset version --snapshot canary\` to generate a temporary snapshot version.
-3. **Publish**: Packages are published to npm with the \`canary\` tag using \`changeset publish --tag canary\`.
-
-### Consuming Canary Builds
-
-To install the latest bleeding-edge version:
-
-\`\`\`bash
-npm install @lssm/lib.contracts@canary
-# or
-bun add @lssm/lib.contracts@canary
-\`\`\`
-
-## Stable Release Workflow (Manual)
-
-Stable releases are managed via the \`release\` branch using the standard [Changesets Action](https://github.com/changesets/action).
-
-1. **Develop on \`main\`**: Create features and fixes.
-2. **Add Changesets**: Run \`bun changeset\` to document changes and impact (major/minor/patch).
-3. **Merge to \`release\`**: When ready to ship, open a PR from \`main\` to \`release\` or merge manually.
-4. **"Version Packages" PR**:
-   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **"Version Packages"**.
-   - This PR contains the version bumps and updated \`CHANGELOG.md\` files.
-5. **Merge & Publish**:
-   - Review and merge the "Version Packages" PR.
-   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the \`latest\` tag.
-
-### Publishing Steps
-
-1. Ensure all changesets are present on \`main\`.
-2. Merge \`main\` into \`release\`:
-   \`\`\`bash
-   git checkout release
-   git pull origin release
-   git merge main
-   git push origin release
-   \`\`\`
-3. Go to GitHub Pull Requests. You will see a **"Version Packages"** PR created by the bot.
-4. Merge that PR.
-5. The release is now live on npm!
-
-## Manual Verification (Optional)
-
-Before publishing a new version you can run:
-
-\`\`\`bash
-bun run build:not-apps
-npx npm-packlist --json packages/libs/contracts
-\`\`\`
-
-## Rollback
-
-If a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use \`npm deprecate <package>@<version>\` if we need to warn consumers about a broken release.
-`}];e(t);export{t as PUBLISHING_DocBlocks};
+import { registerDocBlocks } from "./registry.js";
+
+//#region src/docs/PUBLISHING.docblock.ts
+const PUBLISHING_DocBlocks = [{
+	id: "docs.PUBLISHING",
+	title: "Publishing ContractSpec Libraries",
+	summary: "This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/PUBLISHING",
+	tags: ["PUBLISHING"],
+	body: "# Publishing ContractSpec Libraries\n\nThis guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).\n\n## Release Tracks\n\n| Track | Branch | npm Tag | Frequency | Versioning | Use Case |\n|-------|--------|---------|-----------|------------|----------|\n| **Stable** | `release` | `latest` | Manual | SemVer (e.g., `1.7.4`) | Production, external users |\n| **Canary** | `main` | `canary` | Every Push | Snapshot (e.g., `1.7.4-canary...`) | Dev, internal testing |\n\n## Prerequisites\n\n- ✅ `NPM_TOKEN` secret is configured in GitHub (owner or automation token with _publish_ scope).\n- ✅ `GITHUB_TOKEN` (built-in) has permissions to create PRs (enabled by default in new repos).\n- ✅ For stable releases: `release` branch exists and is protected.\n\n## Canary Workflow (Automatic)\n\nEvery commit pushed to `main` triggers the `.github/workflows/publish-canary.yml` workflow.\n\n1. **Trigger**: Push to `main`.\n2. **Versioning**: Runs `changeset version --snapshot canary` to generate a temporary snapshot version.\n3. **Publish**: Packages are published to npm with the `canary` tag using `changeset publish --tag canary`.\n\n### Consuming Canary Builds\n\nTo install the latest bleeding-edge version:\n\n```bash\nnpm install @lssm/lib.contracts@canary\n# or\nbun add @lssm/lib.contracts@canary\n```\n\n## Stable Release Workflow (Manual)\n\nStable releases are managed via the `release` branch using the standard [Changesets Action](https://github.com/changesets/action).\n\n1. **Develop on `main`**: Create features and fixes.\n2. **Add Changesets**: Run `bun changeset` to document changes and impact (major/minor/patch).\n3. **Merge to `release`**: When ready to ship, open a PR from `main` to `release` or merge manually.\n4. **\"Version Packages\" PR**:\n   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **\"Version Packages\"**.\n   - This PR contains the version bumps and updated `CHANGELOG.md` files.\n5. **Merge & Publish**:\n   - Review and merge the \"Version Packages\" PR.\n   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the `latest` tag.\n\n### Publishing Steps\n\n1. Ensure all changesets are present on `main`.\n2. Merge `main` into `release`:\n   ```bash\n   git checkout release\n   git pull origin release\n   git merge main\n   git push origin release\n   ```\n3. Go to GitHub Pull Requests. You will see a **\"Version Packages\"** PR created by the bot.\n4. Merge that PR.\n5. The release is now live on npm!\n\n## Manual Verification (Optional)\n\nBefore publishing a new version you can run:\n\n```bash\nbun run build:not-apps\nnpx npm-packlist --json packages/libs/contracts\n```\n\n## Rollback\n\nIf a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use `npm deprecate <package>@<version>` if we need to warn consumers about a broken release.\n"
+}];
+registerDocBlocks(PUBLISHING_DocBlocks);
+
+//#endregion
+export { PUBLISHING_DocBlocks };