@contractspec/lib.contracts 0.0.0-canary-20260113162409

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

@@ -0,0 +1,175 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { PolicyRef } from "../policy/spec.js";
+import { CapabilityRef } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { ExperimentRef } from "../experiments/spec.js";
+import { FeatureModuleSpec, FeatureRef } from "../features/types.js";
+import "../features/index.js";
+import { ThemeRef } from "../themes.js";
+import { IntegrationCategory, IntegrationOwnershipMode } from "../integrations/spec.js";
+import { AppIntegrationBinding } from "../integrations/binding.js";
+import { AppKnowledgeBinding } from "../knowledge/binding.js";
+import { BrandingDefaults, TenantBrandingConfig } from "./branding.js";
+import { Locale, TranslationEntry } from "../translations/catalog.js";
+import { ConfigStatus } from "./lifecycle.js";
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/app-config/spec.d.ts
+interface SpecPointer {
+  key: string;
+  version?: string;
+}
+interface AppRouteConfig {
+  path: string;
+  label?: string;
+  dataView?: string;
+  workflow?: string;
+  guard?: PolicyRef;
+  featureFlag?: string;
+  experiment?: ExperimentRef;
+}
+interface TranslationCatalogPointer {
+  key: string;
+  version: string;
+}
+interface AppIntegrationSlot {
+  /** Slot identifier unique within the blueprint (e.g., "primaryPayments"). */
+  slotId: string;
+  /** Integration category required to satisfy this slot. */
+  requiredCategory: IntegrationCategory;
+  /** Ownership modes allowed for this slot (defaults to any supported mode). */
+  allowedModes?: IntegrationOwnershipMode[];
+  /** Capabilities that must be provided by the integration spec. */
+  requiredCapabilities?: CapabilityRef[];
+  /** Whether this slot must be satisfied for the app to function. */
+  required?: boolean;
+  /** Description for App Studio UX. */
+  description?: string;
+}
+interface FeatureFlagState {
+  key: string;
+  enabled: boolean;
+  variant?: string;
+  description?: string;
+}
+interface TelemetryBinding {
+  spec?: SpecPointer;
+  disabledEvents?: string[];
+  samplingOverrides?: Record<string, number>;
+}
+interface AppThemeBinding {
+  primary: ThemeRef;
+  fallbacks?: ThemeRef[];
+}
+interface AppBlueprintMeta extends OwnerShipMeta {
+  /** Logical application id (e.g. "artisan"). */
+  appId: string;
+}
+interface AppBlueprintSpec {
+  meta: AppBlueprintMeta;
+  capabilities?: {
+    enabled?: CapabilityRef[];
+    disabled?: CapabilityRef[];
+  };
+  features?: {
+    include?: FeatureRef[];
+    exclude?: FeatureRef[];
+  };
+  integrationSlots?: AppIntegrationSlot[];
+  branding?: BrandingDefaults;
+  translationCatalog?: TranslationCatalogPointer;
+  dataViews?: Record<string, SpecPointer>;
+  workflows?: Record<string, SpecPointer>;
+  policies?: PolicyRef[];
+  theme?: AppThemeBinding;
+  telemetry?: TelemetryBinding;
+  experiments?: {
+    active?: ExperimentRef[];
+    paused?: ExperimentRef[];
+  };
+  featureFlags?: FeatureFlagState[];
+  routes?: AppRouteConfig[];
+  notes?: string;
+}
+declare class AppBlueprintRegistry extends SpecContractRegistry<'app-config', AppBlueprintSpec> {
+  constructor(items?: AppBlueprintSpec[]);
+}
+declare function makeAppBlueprintKey(meta: AppBlueprintMeta): string;
+interface TenantAppConfigMeta {
+  id: string;
+  tenantId: string;
+  appId: string;
+  blueprintName: string;
+  blueprintVersion: string;
+  environment?: string;
+  /** Monotonic version for auditing changes to the tenant config. */
+  version: string;
+  status: ConfigStatus;
+  createdBy?: string;
+  publishedBy?: string;
+  publishedAt?: string | Date;
+  rolledBackFrom?: string;
+  rolledBackTo?: string;
+  changeSummary?: string;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+}
+interface TenantSpecOverride {
+  slot: string;
+  pointer?: SpecPointer | null;
+}
+interface TenantRouteOverride {
+  path: string;
+  label?: string | null;
+  dataView?: string | null;
+  workflow?: string | null;
+  guard?: PolicyRef | null;
+  featureFlag?: string | null;
+  experiment?: ExperimentRef | null;
+}
+interface TenantAppConfig {
+  meta: TenantAppConfigMeta;
+  capabilities?: {
+    enable?: CapabilityRef[];
+    disable?: CapabilityRef[];
+  };
+  features?: {
+    include?: FeatureRef[];
+    exclude?: FeatureRef[];
+  };
+  dataViewOverrides?: TenantSpecOverride[];
+  workflowOverrides?: TenantSpecOverride[];
+  additionalPolicies?: PolicyRef[];
+  themeOverride?: {
+    primary?: ThemeRef | null;
+    fallbacks?: ThemeRef[];
+  };
+  telemetryOverride?: {
+    spec?: SpecPointer | null;
+    disabledEvents?: string[];
+    samplingOverrides?: Record<string, number>;
+  };
+  experiments?: {
+    active?: ExperimentRef[];
+    paused?: ExperimentRef[];
+  };
+  featureFlags?: FeatureFlagState[];
+  routeOverrides?: TenantRouteOverride[];
+  integrations?: AppIntegrationBinding[];
+  knowledge?: AppKnowledgeBinding[];
+  locales?: {
+    defaultLocale: Locale;
+    enabledLocales: Locale[];
+  };
+  translationOverrides?: {
+    entries?: TranslationEntry[];
+  };
+  branding?: TenantBrandingConfig;
+  notes?: string;
+}
+/**
+ * Helper to define an AppConfig.
+ */
+declare const defineAppConfig: (spec: FeatureModuleSpec) => FeatureModuleSpec;
+//#endregion
+export { AppBlueprintMeta, AppBlueprintRegistry, AppBlueprintSpec, AppIntegrationSlot, AppRouteConfig, AppThemeBinding, FeatureFlagState, SpecPointer, TelemetryBinding, TenantAppConfig, TenantAppConfigMeta, TenantRouteOverride, TenantSpecOverride, TranslationCatalogPointer, defineAppConfig, makeAppBlueprintKey };

package/dist/app-config/spec.js

@@ -0,0 +1,19 @@
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/app-config/spec.ts
+const blueprintKey = (meta) => `${meta.key}.v${meta.version}`;
+var AppBlueprintRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("app-config", items);
+	}
+};
+function makeAppBlueprintKey(meta) {
+	return blueprintKey(meta);
+}
+/**
+* Helper to define an AppConfig.
+*/
+const defineAppConfig = (spec) => spec;
+
+//#endregion
+export { AppBlueprintRegistry, defineAppConfig, makeAppBlueprintKey };

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

@@ -0,0 +1,49 @@
+import { CapabilityRegistry } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { DataViewRegistry } from "../data-views/registry.js";
+import "../data-views/index.js";
+import { WorkflowRegistry } from "../workflow/spec.js";
+import { IntegrationSpecRegistry } from "../integrations/spec.js";
+import { IntegrationConnection } from "../integrations/connection.js";
+import { KnowledgeSpaceRegistry } from "../knowledge/spec.js";
+import { KnowledgeSourceConfig } from "../knowledge/source.js";
+import { BlueprintTranslationCatalog, PlatformTranslationCatalog } from "../translations/catalog.js";
+import { AppBlueprintSpec, TenantAppConfig } from "./spec.js";
+import { ResolvedAppConfig } from "./runtime.js";
+
+//#region src/app-config/validation.d.ts
+type ValidationSeverity = 'error' | 'warning' | 'info';
+interface ValidationIssue {
+  code: string;
+  severity: ValidationSeverity;
+  path: string;
+  message: string;
+  suggestion?: string;
+  docsUrl?: string;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+  info: ValidationIssue[];
+}
+interface ValidationContext {
+  integrationSpecs?: IntegrationSpecRegistry;
+  knowledgeSpaces?: KnowledgeSpaceRegistry;
+  knowledgeSources?: KnowledgeSourceConfig[];
+  capabilities?: CapabilityRegistry;
+  dataViews?: DataViewRegistry;
+  workflows?: WorkflowRegistry;
+  tenantConnections?: IntegrationConnection[];
+  existingConfigs?: TenantAppConfig[];
+  translationCatalogs?: {
+    platform?: PlatformTranslationCatalog | PlatformTranslationCatalog[] | undefined;
+    blueprint?: BlueprintTranslationCatalog | BlueprintTranslationCatalog[] | undefined;
+  };
+}
+declare function validateConfig(blueprint: AppBlueprintSpec, tenant: TenantAppConfig, context?: ValidationContext): ValidationResult;
+declare function validateBlueprint(blueprint: AppBlueprintSpec, context?: ValidationContext): ValidationResult;
+declare function validateTenantConfig(blueprint: AppBlueprintSpec, tenant: TenantAppConfig, context?: ValidationContext): ValidationResult;
+declare function validateResolvedConfig(blueprint: AppBlueprintSpec, resolved: ResolvedAppConfig, context?: ValidationContext): ValidationResult;
+//#endregion
+export { ValidationContext, ValidationIssue, ValidationResult, ValidationSeverity, validateBlueprint, validateConfig, validateResolvedConfig, validateTenantConfig };