@contractspec/lib.contracts-spec 2.0.0

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

@@ -0,0 +1,255 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/registry-utils.ts
+var exports_registry_utils = {};
+__export(exports_registry_utils, {
+  groupByToArray: () => groupByToArray,
+  groupByMultiple: () => groupByMultiple,
+  groupBy: () => groupBy,
+  getUniqueTags: () => getUniqueTags,
+  getUniqueOwners: () => getUniqueOwners,
+  getUniqueDomains: () => getUniqueDomains,
+  filterBy: () => filterBy,
+  GroupingStrategies: () => GroupingStrategies
+});
+function filterBy(items, filter) {
+  return items.filter((item) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.domain) {
+      const itemDomain = GroupingStrategies.byDomain(item);
+      if (itemDomain !== filter.domain)
+        return false;
+    }
+    if (filter.keyPattern) {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(name))
+        return false;
+    }
+    return true;
+  });
+}
+function groupBy(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupByToArray(items, keyFn) {
+  const map = groupBy(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
+}
+function groupByMultiple(items, keysFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const keys = keysFn(item);
+    for (const key of keys) {
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+  }
+  return groups;
+}
+function getUniqueTags(items) {
+  const tags = new Set;
+  for (const item of items) {
+    for (const tag of item.meta.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueOwners(items) {
+  const owners = new Set;
+  for (const item of items) {
+    for (const owner of item.meta.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueDomains(items) {
+  const domains = new Set;
+  for (const item of items) {
+    domains.add(GroupingStrategies.byDomain(item));
+  }
+  return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esm(() => {
+  GroupingStrategies = {
+    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+    byDomain: (item) => {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      return name.split(".")[0] ?? "default";
+    },
+    byStability: (item) => item.meta.stability ?? "stable",
+    byUrlPath: (level) => (item) => {
+      if (!item.path)
+        return "root";
+      const segments = item.path.split("/").filter(Boolean);
+      return segments.slice(0, level).join("/") || "root";
+    }
+  };
+});
+
+// src/registry.ts
+init_registry_utils();
+import { compareVersions } from "compare-versions";
+var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
+
+class SpecContractRegistry {
+  contractType;
+  items = new Map;
+  constructor(contractType, items) {
+    this.contractType = contractType;
+    if (items) {
+      items.forEach((p) => this.register(p));
+    }
+  }
+  register(p) {
+    const key = keyOfSpecContract(p);
+    if (this.items.has(key))
+      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
+    this.items.set(key, p);
+    return this;
+  }
+  count() {
+    return this.items.size;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, p] of this.items.entries()) {
+      if (!k.startsWith(`${key}.v`))
+        continue;
+      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
+        candidate = p;
+      }
+    }
+    return candidate;
+  }
+  has(key, version) {
+    return !!this.get(key, version);
+  }
+  filter(criteria) {
+    return filterBy(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((p) => p.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((p) => p.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    return groupBy(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    return getUniqueTags(this.list());
+  }
+}
+
+// src/app-config/spec.ts
+var blueprintKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class AppBlueprintRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("app-config", items);
+  }
+}
+function makeAppBlueprintKey(meta) {
+  return blueprintKey(meta);
+}
+var defineAppConfig = (spec) => spec;
+
+// src/app-config/app-config.feature.ts
+var 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: []
+  }
+});
+export {
+  AppConfigFeature
+};

package/dist/node/app-config/docs/app-config.docblock.js

@@ -0,0 +1,383 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/app-config/docs/app-config.docblock.ts
+var tech_contracts_app_config_DocBlocks = [
+  {
+    id: "docs.tech.contracts.app-config",
+    title: "App Configuration Layers",
+    summary: "App orchestration is split into three explicit layers:",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/contracts/app-config",
+    tags: ["tech", "contracts", "app-config"],
+    body: `## App Configuration Layers
+
+App orchestration is split into three explicit layers:
+
+1. **AppBlueprintSpec** – global, versioned description of what an app can look like. Stored in Git, no tenant/environment data.
+2. **TenantAppConfig** – tenant/environment overrides that the future Studio edits. Stored per tenant (DB/contract), mutable at runtime.
+3. **ResolvedAppConfig** – pure, merged view consumed by the runtime. Derived in-memory from a blueprint + tenant config.
+
+- Types & registry: \`packages/libs/contracts/src/app-config/spec.ts\`
+- Resolution helpers: \`packages/libs/contracts/src/app-config/runtime.ts\`
+- CLI wizard (blueprint scaffolding): \`contractspec create app-config\`
+
+### 1. AppBlueprintSpec
+
+\`\`\`ts
+export interface AppBlueprintSpec {
+  meta: AppBlueprintMeta;          // { name, version, appId, ownership }
+  capabilities?: { enabled?: CapabilityRef[]; disabled?: CapabilityRef[] };
+  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };
+  integrationSlots?: AppIntegrationSlot[];
+  branding?: BrandingDefaults;
+  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;
+}
+\`\`\`
+
+Register blueprints with \`AppBlueprintRegistry\`. Blueprints only capture the default/global experience.
+
+- **Integration slots** declare the categories and capability requirements an app expects (e.g. \`"primary-payments"\` must be a payments provider that supports managed or BYOK credentials). Slots never include secrets; tenants bind concrete connections later.
+- **Branding defaults** provide message-key based names, placeholder assets, and theme token references that downstream tenants can override.
+
+### 2. TenantAppConfig
+
+\`\`\`ts
+export interface TenantAppConfig {
+  meta: TenantAppConfigMeta;  // { id, tenantId, appId, blueprintName/version, environment?, version, timestamps }
+  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[] };
+  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };
+  featureFlags?: FeatureFlagState[];
+  routeOverrides?: TenantRouteOverride[];
+  integrations?: AppIntegrationBinding[];
+  knowledge?: AppKnowledgeBinding[];
+  branding?: TenantBrandingConfig;
+  notes?: string;
+}
+\`\`\`
+
+This object represents what a tenant edits via the Studio (stored in DB/contracts later).
+
+- **AppIntegrationBinding** now maps \`slotId\` → \`connectionId\` (plus optional workflow scopes). It no longer carries capability lists; those are defined once in the slot.
+- **TenantBrandingConfig** allows per-tenant names, assets, and domain overrides while keeping secrets and large files out of blueprints.
+
+### 3. ResolvedAppConfig
+
+\`\`\`ts
+export interface ResolvedAppConfig {
+  appId: string;
+  tenantId: string;
+  environment?: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+  capabilities: { enabled: CapabilityRef[]; disabled: CapabilityRef[] };
+  features: { include: FeatureRef[]; exclude: FeatureRef[] };
+  dataViews: Record<string, SpecPointer>;
+  workflows: Record<string, SpecPointer>;
+  policies: PolicyRef[];
+  theme?: AppThemeBinding;
+  telemetry?: TelemetryBinding;
+  experiments: { catalog: ExperimentRef[]; active: ExperimentRef[]; paused: ExperimentRef[] };
+  featureFlags: FeatureFlagState[];
+  routes: AppRouteConfig[];
+  integrations: ResolvedIntegration[];
+  knowledge: ResolvedKnowledge[];
+  branding: ResolvedBranding;
+  notes?: string;
+}
+\`\`\`
+
+Use \`resolveAppConfig(blueprint, tenant)\` to produce this merged view. No IO, no registry lookups—pure data merge.
+
+- \`resolveAppConfig\` validates slot/category/mode constraints when \`integrationConnections\` and \`integrationSpecs\` are provided.
+- \`branding\` merges blueprint defaults with tenant overrides, producing a runtime-friendly shape (resolved asset URLs, color values, and effective domain).
+
+### Materializing specs
+
+\`composeAppConfig(blueprint, tenant, registries, { strict })\`:
+
+1. Calls \`resolveAppConfig\` to build the merged pointers.
+2. Looks up referenced specs in the provided registries.
+3. Returns:
+   - \`resolved\` – the merged pointer view
+   - \`capabilities\`, \`features\`, \`dataViews\`, \`workflows\`, \`policies\`, \`theme\`, \`telemetry\`, \`experiments\`
+   - \`missing\` – unresolved references (strict mode throws).
+
+\`\`\`ts
+const blueprint = blueprintRegistry.get('core.app', 1)!;
+const tenant = loadTenantConfigFromDB();
+
+const composition = composeAppConfig(blueprint, tenant, {
+  capabilities,
+  features,
+  dataViews,
+  workflows,
+  policies,
+  themes,
+  telemetry,
+  experiments,
+});
+
+if (composition.missing.length) {
+  console.warn('Unresolved references', composition.missing);
+}
+\`\`\`
+
+### CLI workflow
+
+\`\`\`
+contractspec create app-config
+\`\`\`
+
+Generates an \`AppBlueprintSpec\`. A separate flow will later scaffold tenant configs.
+
+### Best practices
+
+1. Keep blueprint and tenant versions monotonic; bump when referenced spec versions change.
+2. Favor stable slot keys (e.g. \`dataViews.dashboard\`) to align with Studio UX.
+3. Reference telemetry and experiments declared in their respective specs to maintain observability.
+4. Run \`resolveAppConfig\` in pure unit tests and \`composeAppConfig(..., { strict: true })\` in CI to catch drift early.
+5. Pair resolved configs with \`TestSpec\` scenarios to guard tenant experiences end-to-end.
+
+### Static validation
+
+Use the validation helpers in \`@contractspec/lib.contracts-spec/app-config/validation\` to keep blueprints and tenant configs safe before publish time.
+
+\`\`\`ts
+import {
+  validateConfig,
+  validateBlueprint,
+  validateTenantConfig,
+  validateResolvedConfig,
+} from '@contractspec/lib.contracts-spec/app-config/validation';
+
+const context = {
+  integrationSpecs,
+  tenantConnections,
+  knowledgeSpaces,
+  knowledgeSources,
+  translationCatalogs: {
+    blueprint: blueprintCatalog,
+    platform: platformCatalog,
+  },
+  existingConfigs,
+};
+
+const blueprintReport = validateBlueprint(blueprint, context);
+const tenantReport = validateTenantConfig(blueprint, tenant, context);
+const publishReport = validateConfig(blueprint, tenant, context);
+\`\`\`
+
+- \`ValidationResult\` exposes \`valid\`, plus structured \`errors\`, \`warnings\`, and \`info\`.
+- Core rules cover capability references, integration slot bindings (category/ownership/capabilities), knowledge bindings, branding constraints (domains + assets), and translation coverage.
+- Call \`validateBlueprint\` in CI when committing new specs, and \`validateConfig\` before promoting/publishing a tenant config.
+- \`validateResolvedConfig\` can be used as a runtime pre-flight check when composing full configs for workflows.
+- CLI usage example (blueprint + tenant):
+
+\`\`\`
+buncontractspec validate \\
+  packages/examples/integration-stripe/blueprint.ts \\
+  --blueprint packages/examples/integration-stripe/blueprint.ts \\
+  --tenant-config packages/examples/integration-stripe/tenant.ts
+\`\`\`
+- Repository script:
+
+\`\`\`
+bun run validate:blueprints
+\`\`\`
+
+Runs the static validator for the sample blueprints/tenants and is wired into CI.
+
+
+### Lifecycle types & events
+
+To model multi-step configuration changes, use the lifecycle helpers exported from \`@contractspec/lib.contracts-spec/app-config\`:
+
+\`\`\`ts
+import type {
+  ConfigStatus,
+  TenantAppConfigVersion,
+  ConfigTransition,
+} from '@contractspec/lib.contracts-spec/app-config';
+import {
+  ConfigDraftCreatedEvent,
+  ConfigPromotedToPreviewEvent,
+  ConfigPublishedEvent,
+  ConfigRolledBackEvent,
+} from '@contractspec/lib.contracts-spec/app-config';
+\`\`\`
+
+- \`ConfigStatus\` enumerates the canonical states: \`draft\`, \`preview\`, \`published\`, \`archived\`, \`superseded\`.
+- \`TenantAppConfigMeta\` now includes lifecycle metadata (\`status\`, \`createdBy\`, \`publishedBy\`, \`publishedAt\`, \`rolledBackFrom\`, \`rolledBackTo\`, \`changeSummary\`).
+- \`TenantAppConfigVersion\` couples the lifecycle-aware metadata with the \`TenantAppConfig\` payload for history views.
+- \`ConfigTransition\` captures state changes with actor, timestamp, and optional reason.
+- Lifecycle events (\`app_config.draft_created\`, \`app_config.promoted_to_preview\`, \`app_config.published\`, \`app_config.rolled_back\`) standardize observability across services.
+- Lifecycle contract specs (\`appConfig.lifecycle.*\`) expose typed commands/queries for create → preview → publish → rollback flows.
+
+`
+  }
+];
+registerDocBlocks(tech_contracts_app_config_DocBlocks);
+export {
+  tech_contracts_app_config_DocBlocks
+};