@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @contractspec/lib.contracts
+
+[![npm version](https://img.shields.io/npm/v/@contractspec/lib.contracts)](https://www.npmjs.com/package/@contractspec/lib.contracts)
+[![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts)](https://www.npmjs.com/package/@contractspec/lib.contracts)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/lssm-tech/contractspec)
+
+
+Website: https://contractspec.io/
+
+
+**The core of ContractSpec** — Define contracts once, generate consistent code across all surfaces.
+
+Unified specifications for Operations (commands/queries), Events, and Presentations. Contracts serve as the canonical source of truth that AI agents and code generators read to understand system constraints.
+
+## Purpose
+
+To provide a single, typed source of truth for backend operations (`ContractSpec`), events (`EventSpec`), and UI/data presentations. This enables **runtime adapters** (REST, GraphQL, MCP, UI) to automatically generate endpoints, schemas, and user interfaces without code duplication.
+
+## Installation
+
+```bash
+npm install @contractspec/lib.contracts @contractspec/lib.schema
+# or
+bun add @contractspec/lib.contracts @contractspec/lib.schema
+```
+
+## Key Concepts
+
+- **Spec-First, TypeScript-First**: Define operations in pure TypeScript (no YAML).
+- **Runtime Adapters**: The `OperationSpecRegistry` is passed to adapters (e.g., `makeNextAppHandler`) to serve APIs dynamically. There is no intermediate "compile" step to generate code; the spec _is_ the code.
+- **Capabilities**: `defineCommand` (writes) and `defineQuery` (reads) with Zod-backed I/O.
+- **Events**: `defineEvent` for type-safe side effects.
+- **Presentations**: (V2) Describe how data is rendered (Web Components, Markdown, Data) for automated UI generation.
+
+## Exports
+
+- **Core**: `OperationSpecRegistry`, `defineCommand`, `defineQuery`, `defineEvent`.
+- **Config**: `SchemaFormat` ('contractspec' | 'zod' | 'json-schema' | 'graphql').
+- **Adapters**:
+  - `server/rest-next-app`: Next.js App Router adapter.
+  - `server/provider-mcp`: Model Context Protocol (MCP) adapter for AI agents.
+  - `server/graphql-pothos`: GraphQL schema generator.
+- **Docs**: `markdown` utilities to generate human-readable documentation from specs.
+
+## Usage
+
+### 1. Define a Spec
+
+```ts
+import { defineCommand, defineQuery } from '@contractspec/lib.contracts';
+import * as z from "zod";
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const UserInput = new SchemaModel({
+  name: 'UserInput',
+  fields: {
+    email: { type: ScalarTypeEnum.Email(), isOptional: false },
+  },
+});
+
+export const CreateUser = defineCommand({
+  meta: {
+    name: 'user.create',
+    version: '1.0.0',
+    description: 'Register a new user',
+    owners: ['team-auth'],
+    tags: ['auth'],
+    goal: 'Onboard users',
+    context: 'Public registration',
+    stability: 'stable',
+  },
+  io: {
+    input: UserInput,
+    output: new SchemaModel({
+      name: 'UserOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+  },
+  policy: {
+    auth: 'anonymous',
+  },
+});
+```
+
+### 2. Register and Implement
+
+```ts
+import { OperationSpecRegistry, installOp } from '@contractspec/lib.contracts';
+
+const reg = new OperationSpecRegistry();
+
+installOp(reg, CreateUser, async (ctx, input) => {
+  // Implementation logic here
+  return { id: '123' };
+});
+```
+
+### 3. Serve (Next.js Adapter)
+
+```ts
+// app/api/[...route]/route.ts
+import { makeNextAppHandler } from '@contractspec/lib.contracts/server/rest-next-app';
+
+const handler = makeNextAppHandler(reg, (req) => ({ actor: 'anonymous' }));
+
+export { handler as GET, handler as POST };
+```

package/dist/_virtual/rolldown_runtime.js

@@ -0,0 +1,37 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+//#endregion
+export { __esmMin, __exportAll, __toCommonJS };

package/dist/app-config/app-config.capability.d.ts

@@ -0,0 +1,7 @@
+import { CapabilitySpec } from "../capabilities/capabilities.js";
+import "../index.js";
+
+//#region src/app-config/app-config.capability.d.ts
+declare const AppConfigCapability: CapabilitySpec;
+//#endregion
+export { AppConfigCapability };

package/dist/app-config/app-config.capability.js

@@ -0,0 +1,23 @@
+import { defineCapability } from "../capabilities/capabilities.js";
+import { OwnersEnum, StabilityEnum, TagsEnum } from "../ownership.js";
+import "../capabilities/index.js";
+
+//#region src/app-config/app-config.capability.ts
+const AppConfigCapability = defineCapability({
+	meta: {
+		key: "app-config",
+		version: "1.0.0",
+		title: "App Configuration Capability",
+		description: "Provides tenant app configuration lifecycle management.",
+		domain: "platform",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: [TagsEnum.Hygiene],
+		kind: "api",
+		stability: StabilityEnum.Stable
+	},
+	provides: [],
+	requires: []
+});
+
+//#endregion
+export { AppConfigCapability };

package/dist/app-config/app-config.feature.d.ts

@@ -0,0 +1,11 @@
+import { FeatureModuleSpec } from "../features/types.js";
+import "../index.js";
+
+//#region src/app-config/app-config.feature.d.ts
+/**
+ * App Config feature module that bundles tenant configuration
+ * lifecycle events for draft, preview, publish, and rollback stages.
+ */
+declare const AppConfigFeature: FeatureModuleSpec;
+//#endregion
+export { AppConfigFeature };

package/dist/app-config/app-config.feature.js

@@ -0,0 +1,61 @@
+import { defineAppConfig } from "./spec.js";
+
+//#region src/app-config/app-config.feature.ts
+/**
+* App Config Feature Module Specification
+*
+* Defines the feature module for tenant app configuration lifecycle.
+*/
+/**
+* App Config feature module that bundles tenant configuration
+* lifecycle events for draft, preview, publish, and rollback stages.
+*/
+const AppConfigFeature = defineAppConfig({
+	meta: {
+		key: "app-config",
+		version: "1.0.0",
+		title: "App Configuration",
+		description: "Tenant app configuration lifecycle management with draft, preview, and publish stages",
+		domain: "platform",
+		owners: ["@platform.sigil"],
+		tags: [
+			"app-config",
+			"lifecycle",
+			"configuration",
+			"tenant"
+		],
+		stability: "beta"
+	},
+	operations: [],
+	events: [
+		{
+			key: "app_config.draft_created",
+			version: "1.0.0"
+		},
+		{
+			key: "app_config.promoted_to_preview",
+			version: "1.0.0"
+		},
+		{
+			key: "app_config.published",
+			version: "1.0.0"
+		},
+		{
+			key: "app_config.rolled_back",
+			version: "1.0.0"
+		}
+	],
+	presentations: [],
+	opToPresentation: [],
+	presentationsTargets: [],
+	capabilities: {
+		provides: [{
+			key: "app-config",
+			version: "1.0.0"
+		}],
+		requires: []
+	}
+});
+
+//#endregion
+export { AppConfigFeature };

package/dist/app-config/branding.d.ts

@@ -0,0 +1,55 @@
+//#region src/app-config/branding.d.ts
+interface BrandingAssetRef {
+  type: 'logo' | 'logo-dark' | 'favicon' | 'og-image';
+  url?: string;
+  dimensions?: {
+    width: number;
+    height: number;
+  };
+}
+interface BrandingDefaults {
+  appNameKey: string;
+  assets?: BrandingAssetRef[];
+  colorTokens?: {
+    primary?: string;
+    secondary?: string;
+  };
+}
+interface TenantBrandingAsset {
+  type: 'logo' | 'logo-dark' | 'favicon' | 'og-image';
+  url: string;
+  metadata?: {
+    mimeType?: string;
+    sizeBytes?: number;
+    dimensions?: {
+      width: number;
+      height: number;
+    };
+  };
+}
+interface TenantBrandingConfig {
+  appName?: Record<string, string>;
+  assets?: TenantBrandingAsset[];
+  colors?: {
+    primary?: string;
+    secondary?: string;
+  };
+  customDomain?: string;
+  subdomain?: string;
+}
+interface ResolvedBranding {
+  appName: string;
+  assets: {
+    logo?: string;
+    logoDark?: string;
+    favicon?: string;
+    ogImage?: string;
+  };
+  colors: {
+    primary: string;
+    secondary: string;
+  };
+  domain: string;
+}
+//#endregion
+export { BrandingAssetRef, BrandingDefaults, ResolvedBranding, TenantBrandingAsset, TenantBrandingConfig };

package/dist/app-config/contracts.d.ts

@@ -0,0 +1,245 @@
+import { OperationSpec } from "../operations/operation.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import "../operations/index.js";
+import * as _contractspec_lib_schema146 from "@contractspec/lib.schema";
+import { SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/app-config/contracts.d.ts
+declare const UpdateTenantBrandingCommand: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  appId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  environment: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+  appName: {
+    type: _contractspec_lib_schema146.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    isOptional: true;
+  };
+  assets: {
+    type: SchemaModel<{
+      type: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      url: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      mimeType: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isOptional: true;
+    isArray: true;
+  };
+  colors: {
+    type: _contractspec_lib_schema146.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    isOptional: true;
+  };
+  customDomain: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+  subdomain: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  success: {
+    type: _contractspec_lib_schema146.FieldType<boolean, boolean>;
+    isOptional: false;
+  };
+  updatedAt: {
+    type: _contractspec_lib_schema146.FieldType<Date, string>;
+    isOptional: false;
+  };
+}>, undefined>;
+declare const VerifyCustomDomainCommand: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  appId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  domain: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+}>, SchemaModel<{
+  status: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  message: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, undefined>;
+declare const UpdateBlueprintTranslationCatalogCommand: OperationSpec<SchemaModel<{
+  blueprintName: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  blueprintVersion: {
+    type: _contractspec_lib_schema146.FieldType<number, number>;
+    isOptional: false;
+  };
+  catalogName: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  catalogVersion: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  defaultLocale: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  supportedLocales: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+    isArray: true;
+  };
+  entries: {
+    type: SchemaModel<{
+      key: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      locale: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      value: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      context: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isOptional: false;
+    isArray: true;
+  };
+}>, SchemaModel<{
+  success: {
+    type: _contractspec_lib_schema146.FieldType<boolean, boolean>;
+    isOptional: false;
+  };
+  updatedAt: {
+    type: _contractspec_lib_schema146.FieldType<Date, string>;
+    isOptional: false;
+  };
+}>, undefined>;
+declare const UpdateTenantTranslationOverridesCommand: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  appId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  entries: {
+    type: SchemaModel<{
+      key: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      locale: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      value: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: false;
+      };
+      context: {
+        type: _contractspec_lib_schema146.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isOptional: false;
+    isArray: true;
+  };
+  defaultLocale: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+  enabledLocales: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+}>, SchemaModel<{
+  success: {
+    type: _contractspec_lib_schema146.FieldType<boolean, boolean>;
+    isOptional: false;
+  };
+  updatedAt: {
+    type: _contractspec_lib_schema146.FieldType<Date, string>;
+    isOptional: false;
+  };
+}>, undefined>;
+declare const GetResolvedBrandingQuery: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  appId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  environment: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  branding: {
+    type: _contractspec_lib_schema146.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    isOptional: false;
+  };
+}>, undefined>;
+declare const ResolveMessageQuery: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  appId: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  locale: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+  key: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: false;
+  };
+}>, SchemaModel<{
+  value: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+  source: {
+    type: _contractspec_lib_schema146.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, undefined>;
+declare const appConfigOperations: Record<string, OperationSpec<any, any>>;
+declare function registerAppConfigOperations(registry: OperationSpecRegistry): OperationSpecRegistry;
+//#endregion
+export { GetResolvedBrandingQuery, ResolveMessageQuery, UpdateBlueprintTranslationCatalogCommand, UpdateTenantBrandingCommand, UpdateTenantTranslationOverridesCommand, VerifyCustomDomainCommand, appConfigOperations, registerAppConfigOperations };