@vibesdotdev/config 0.0.1

package/src/routing/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Discriminated Routing System
+ *
+ * Provides discriminated field routing for manifests - where a discriminator
+ * field value dynamically loads variant-specific fields, schemas, and overrides.
+ *
+ * @example
+ * ```typescript
+ * // Define a base manifest with routing
+ * const widgetManifest: RecordManifest = {
+ *   id: 'example.widgets',
+ *   // ... base fields ...
+ *   routing: {
+ *     discriminator: 'widgetType',
+ *     variants: () => import('./registry.js').then(m => m.getAllWidgetVariants())
+ *   }
+ * };
+ *
+ * // In form hook, resolve variant based on selected widget type
+ * const variant = await resolveVariant('example.widgets', manifest.routing, 'circle');
+ * const mergedManifest = mergeManifestWithVariant(widgetManifest, variant);
+ * ```
+ */
+
+// Types
+export type {
+	ManifestVariant,
+	ManifestRouting,
+	VariantLoader,
+	VariantSurfaceOverrides,
+	ResolvedVariant,
+	GetVariantOverridesOptions,
+	ProviderModule,
+	ProviderMeta,
+	ProviderAdapter,
+	ProviderClient,
+	ProviderClientFactory,
+	ProviderAuthType,
+	ProviderCategory,
+	// Nested routing types
+	NestedRouting,
+	ActiveNestedVariant,
+	ResolvedNestedVariant
+} from './types.ts';
+
+export {
+	hasLazyVariants,
+	hasEagerVariants,
+	isManifestVariant,
+	isProviderModule,
+	// Nested routing type guards and helpers
+	hasNestedLazyVariants,
+	hasNestedEagerVariants,
+	isNestedRouting,
+	getNestedDiscriminatorPath,
+	getNestedEnablePath
+} from './types.ts';
+
+// Registry
+export {
+	registerVariant,
+	registerVariants,
+	getVariant,
+	getAllVariants,
+	hasVariant,
+	clearVariants,
+	clearRegistry,
+	loadVariantsFromRouting,
+	resolveVariant,
+	resolveVariantSync,
+	getRegistryStatus,
+	areVariantsLoaded,
+	// Nested routing registry functions
+	loadNestedVariantsFromRouting,
+	resolveNestedVariant,
+	resolveAllNestedVariants,
+	getActiveNestedVariants,
+	resolveNestedVariantSync,
+	areNestedVariantsLoaded,
+	getAllNestedVariants
+} from './registry.ts';
+
+// Merging utilities
+export {
+	mergeFields,
+	mergeGroups,
+	mergeFormConfig,
+	mergeManifestWithVariant,
+	injectVariantFieldsIntoSteps,
+	getVariantOverrides,
+	hasVariantOverrides,
+	getAllFieldKeys,
+	getVisibleFieldsWithVariant,
+	mergeDefaults,
+	// Nested variant merging
+	prefixVariantFields,
+	prefixVariantGroups,
+	mergeNestedVariantFields,
+	mergeNestedVariantGroups,
+	mergeManifestWithNestedVariants,
+	getVisibleFieldsWithNestedVariants,
+	mergeNestedDefaults
+} from './merge.ts';
+
+export type { MergeManifestOptions } from './merge.ts';

package/src/routing/merge.ts

@@ -0,0 +1,589 @@
+/**
+ * Manifest Merging Utilities
+ *
+ * Functions for merging base manifests with variants to create
+ * a complete manifest with variant-specific fields, groups, and steps.
+ */
+
+import type { z } from 'zod/v4';
+import type { ConfigFieldGroup, ConfigFieldMeta } from '../manifest/types.ts';
+import type { RecordManifest, FormViewConfig, FormStep } from '../crud/types.ts';
+import type { ManifestVariant, ActiveNestedVariant } from './types.ts';
+import type { ExtensionSurface } from '../extensions/types.ts';
+
+/**
+ * Type guard to check if a schema is a ZodObject with merge capability
+ */
+function isZodObjectWithMerge(schema: unknown): schema is z.ZodObject<z.ZodRawShape> & {
+	merge: (other: z.ZodObject<z.ZodRawShape>) => z.ZodObject<z.ZodRawShape>;
+} {
+	return (
+		schema !== null &&
+		typeof schema === 'object' &&
+		'merge' in schema &&
+		typeof (schema as { merge: unknown }).merge === 'function'
+	);
+}
+
+// Field Merging
+
+/**
+ * Merge base manifest fields with variant fields
+ * Variant fields override/extend base fields
+ *
+ * @param baseFields - Fields from the base manifest
+ * @param variantFields - Fields from the variant
+ * @returns Merged fields
+ */
+export function mergeFields(
+	baseFields: Record<string, ConfigFieldMeta>,
+	variantFields: Record<string, ConfigFieldMeta>
+): Record<string, ConfigFieldMeta> {
+	return {
+		...baseFields,
+		...variantFields
+	};
+}
+
+// Group Merging
+
+/**
+ * Merge base manifest groups with variant groups
+ * Variant groups override by ID or are added
+ *
+ * @param baseGroups - Groups from the base manifest
+ * @param variantGroups - Groups from the variant
+ * @returns Merged groups sorted by order
+ */
+export function mergeGroups(
+	baseGroups: ConfigFieldGroup[] = [],
+	variantGroups: ConfigFieldGroup[] = []
+): ConfigFieldGroup[] {
+	const groupMap = new Map<string, ConfigFieldGroup>();
+
+	// Add base groups
+	for (const group of baseGroups) {
+		groupMap.set(group.id, group);
+	}
+
+	// Override/add variant groups
+	for (const group of variantGroups) {
+		const existing = groupMap.get(group.id);
+		if (existing) {
+			// Merge with existing
+			groupMap.set(group.id, {
+				...existing,
+				...group
+			});
+		} else {
+			groupMap.set(group.id, group);
+		}
+	}
+
+	// Sort by order
+	return Array.from(groupMap.values()).sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+}
+
+// Form Step Merging
+
+/**
+ * Get the group ID a field belongs to
+ */
+function getFieldGroup(
+	fields: Record<string, ConfigFieldMeta>,
+	fieldKey: string
+): string | undefined {
+	return fields[fieldKey]?.ui?.group;
+}
+
+/**
+ * Inject variant fields into form steps by matching group IDs
+ *
+ * For each step, finds variant fields whose group matches:
+ * 1. The step ID itself
+ * 2. The group of any field already in the step
+ *
+ * @param baseSteps - Form steps from base manifest
+ * @param variantFields - Fields from the variant
+ * @param allFields - All merged fields (base + variant)
+ * @returns Enhanced steps with variant fields injected
+ */
+export function injectVariantFieldsIntoSteps(
+	baseSteps: FormStep[],
+	variantFields: Record<string, ConfigFieldMeta>,
+	allFields: Record<string, ConfigFieldMeta>
+): FormStep[] {
+	return baseSteps.map((step) => {
+		// Collect groups that this step is associated with
+		const stepGroups = new Set<string>();
+
+		// The step ID itself might be a group
+		stepGroups.add(step.id);
+
+		// Add groups from existing step fields
+		for (const fieldKey of step.fields) {
+			const group = getFieldGroup(allFields, fieldKey);
+			if (group) {
+				stepGroups.add(group);
+			}
+		}
+
+		// Find variant fields that should be added to this step
+		const variantFieldsForStep = Object.entries(variantFields)
+			.filter(([_, meta]) => {
+				const fieldGroup = meta.ui?.group;
+				return fieldGroup && stepGroups.has(fieldGroup);
+			})
+			.sort((a, b) => (a[1].ui?.order ?? 100) - (b[1].ui?.order ?? 100))
+			.map(([key]) => key);
+
+		// Only add fields that aren't already in the step
+		const existingFields = new Set(step.fields);
+		const newFields = variantFieldsForStep.filter((f) => !existingFields.has(f));
+
+		if (newFields.length === 0) {
+			return step;
+		}
+
+		return {
+			...step,
+			fields: [...step.fields, ...newFields]
+		};
+	});
+}
+
+/**
+ * Merge form configuration with variant
+ *
+ * If variant has explicit step overrides, uses those.
+ * Otherwise, auto-injects variant fields by group matching.
+ *
+ * @param baseForm - Form config from base manifest
+ * @param variant - The variant to merge
+ * @param allFields - All merged fields
+ * @returns Merged form configuration
+ */
+export function mergeFormConfig(
+	baseForm: FormViewConfig | undefined,
+	variant: ManifestVariant,
+	allFields: Record<string, ConfigFieldMeta>
+): FormViewConfig | undefined {
+	if (!baseForm) return baseForm;
+
+	// If variant has explicit step overrides, use them
+	if (variant.stepOverrides) {
+		return {
+			...baseForm,
+			steps: variant.stepOverrides
+		};
+	}
+
+	// If no steps in base, nothing to merge
+	if (!baseForm.steps) {
+		return baseForm;
+	}
+
+	// Auto-inject variant fields into steps by group
+	const enhancedSteps = injectVariantFieldsIntoSteps(baseForm.steps, variant.fields, allFields);
+
+	return {
+		...baseForm,
+		steps: enhancedSteps
+	};
+}
+
+// Full Manifest Merging
+
+import type { MergeManifestOptions } from './schemas/merge.schema.ts';
+
+export type { MergeManifestOptions } from './schemas/merge.schema.ts';
+
+const DEFAULT_MERGE_OPTIONS: MergeManifestOptions = {
+	mergeSchemas: true,
+	injectIntoSteps: true
+};
+
+/**
+ * Merge a base manifest with a variant to create a complete manifest
+ *
+ * @param base - The base record manifest
+ * @param variant - The variant to merge
+ * @param options - Merge options
+ * @returns The merged manifest
+ */
+export function mergeManifestWithVariant<T extends Record<string, unknown>>(
+	base: RecordManifest<T>,
+	variant: ManifestVariant,
+	options: MergeManifestOptions = {}
+): RecordManifest<T> {
+	const opts = { ...DEFAULT_MERGE_OPTIONS, ...options };
+
+	// Merge fields
+	const mergedFields = mergeFields(base.fields, variant.fields);
+
+	// Merge groups
+	const mergedGroups = mergeGroups(base.groups, variant.groups);
+
+	// Build merged manifest
+	const merged: RecordManifest<T> = {
+		...base,
+		fields: mergedFields,
+		groups: mergedGroups
+	};
+
+	// Merge schema if requested and variant has schema
+	if (opts.mergeSchemas && variant.schema) {
+		// For Zod schemas, we can use .merge() if they're both objects
+		// This is a simplified approach - complex schema merging may need more logic
+		try {
+			// Check if both schemas have merge capability (ZodObject)
+			if (isZodObjectWithMerge(base.schema) && isZodObjectWithMerge(variant.schema)) {
+				merged.schema = base.schema.merge(variant.schema) as typeof base.schema;
+			} else {
+				// Fall back to using variant schema for validation
+				// This is a limitation - complex schemas need manual handling
+				merged.schema = variant.schema as typeof base.schema;
+			}
+		} catch {
+			// If merge fails, keep base schema
+			// Variant schema validation should happen separately
+		}
+	}
+
+	// Merge CRUD form config if present
+	if (base.crud?.form && opts.injectIntoSteps) {
+		merged.crud = {
+			...base.crud,
+			form: mergeFormConfig(base.crud.form, variant, mergedFields)
+		};
+	}
+
+	return merged;
+}
+
+// Surface Override Helpers
+
+/**
+ * Get surface-specific overrides from a variant
+ *
+ * @param variant - The variant to get overrides from
+ * @param surface - Target surface
+ * @returns Field overrides for the surface, or empty object
+ */
+export function getVariantOverrides(
+	variant: ManifestVariant,
+	surface: ExtensionSurface
+): Record<string, unknown> {
+	return variant.overrides?.[surface] ?? {};
+}
+
+/**
+ * Check if a variant has overrides for a specific surface
+ */
+export function hasVariantOverrides(variant: ManifestVariant, surface: ExtensionSurface): boolean {
+	const overrides = variant.overrides?.[surface];
+	return overrides !== undefined && Object.keys(overrides).length > 0;
+}
+
+// Field Visibility with Variants
+
+/**
+ * Get all field keys from a merged manifest (base + variant)
+ *
+ * @param base - Base manifest
+ * @param variant - Optional variant
+ * @returns Array of all field keys
+ */
+export function getAllFieldKeys(base: RecordManifest<any>, variant?: ManifestVariant): string[] {
+	const fields = new Set<string>(Object.keys(base.fields));
+
+	if (variant) {
+		for (const key of Object.keys(variant.fields)) {
+			fields.add(key);
+		}
+	}
+
+	return Array.from(fields);
+}
+
+/**
+ * Determine which fields should be visible based on variant
+ *
+ * With routing, base fields are always visible (unless hidden by rules),
+ * and variant fields are only visible when their variant is active.
+ *
+ * @param baseFields - Fields from base manifest
+ * @param activeVariant - Currently active variant (or undefined)
+ * @returns Set of visible field keys
+ */
+export function getVisibleFieldsWithVariant(
+	baseFields: Record<string, ConfigFieldMeta>,
+	activeVariant?: ManifestVariant
+): Set<string> {
+	const visible = new Set<string>();
+
+	// Base fields are always potentially visible
+	// (actual visibility determined by rules)
+	for (const key of Object.keys(baseFields)) {
+		visible.add(key);
+	}
+
+	// Add variant fields when variant is active
+	if (activeVariant) {
+		for (const key of Object.keys(activeVariant.fields)) {
+			visible.add(key);
+		}
+	}
+
+	return visible;
+}
+
+// Default Value Merging
+
+/**
+ * Merge default values from base and variant
+ * Variant defaults win on conflict
+ *
+ * @param baseDefaults - Defaults from base manifest/schema
+ * @param variantDefaults - Defaults from variant
+ * @returns Merged defaults
+ */
+export function mergeDefaults<T extends Record<string, unknown>>(
+	baseDefaults: Partial<T>,
+	variantDefaults?: Partial<T>
+): Partial<T> {
+	if (!variantDefaults) {
+		return baseDefaults;
+	}
+
+	return {
+		...baseDefaults,
+		...variantDefaults
+	};
+}
+
+// Nested Variant Merging
+
+/**
+ * Prefix all field keys in a variant with a path prefix
+ * Used for nested routing where variant fields need to be namespaced
+ *
+ * @param variant - The variant to prefix
+ * @param pathPrefix - The dot-notation prefix (e.g., 'agents.orchestration')
+ * @returns Fields with prefixed keys
+ */
+export function prefixVariantFields(
+	variant: ManifestVariant,
+	pathPrefix: string
+): Record<string, ConfigFieldMeta> {
+	const prefixed: Record<string, ConfigFieldMeta> = {};
+	for (const [key, meta] of Object.entries(variant.fields)) {
+		const prefixedKey = `${pathPrefix}.${key}`;
+		prefixed[prefixedKey] = {
+			...meta,
+			ui: {
+				...meta.ui,
+				// Also prefix the group if it exists
+				group: meta.ui.group ? `${pathPrefix}.${meta.ui.group}` : meta.ui.group
+			}
+		};
+	}
+	return prefixed;
+}
+
+/**
+ * Prefix all groups in a variant with a path prefix
+ *
+ * @param groups - The groups to prefix
+ * @param pathPrefix - The dot-notation prefix
+ * @returns Groups with prefixed IDs
+ */
+export function prefixVariantGroups(
+	groups: ConfigFieldGroup[] | undefined,
+	pathPrefix: string
+): ConfigFieldGroup[] {
+	if (!groups) return [];
+	return groups.map((group) => ({
+		...group,
+		id: `${pathPrefix}.${group.id}`
+	}));
+}
+
+/**
+ * Merge multiple nested variants into base fields
+ * Each active variant's fields are prefixed with their path
+ *
+ * @param baseFields - Fields from the base manifest
+ * @param activeVariants - Map of active nested variants keyed by path
+ * @returns Merged fields with nested variant fields prefixed by path
+ */
+export function mergeNestedVariantFields(
+	baseFields: Record<string, ConfigFieldMeta>,
+	activeVariants: Map<string, ActiveNestedVariant>
+): Record<string, ConfigFieldMeta> {
+	let merged = { ...baseFields };
+
+	for (const [path, activeVariant] of activeVariants) {
+		if (activeVariant.enabled && activeVariant.variant) {
+			const prefixedFields = prefixVariantFields(activeVariant.variant, path);
+			merged = { ...merged, ...prefixedFields };
+		}
+	}
+
+	return merged;
+}
+
+/**
+ * Merge multiple nested variants' groups into base groups
+ *
+ * @param baseGroups - Groups from the base manifest
+ * @param activeVariants - Map of active nested variants keyed by path
+ * @returns Merged groups sorted by order
+ */
+export function mergeNestedVariantGroups(
+	baseGroups: ConfigFieldGroup[] | undefined,
+	activeVariants: Map<string, ActiveNestedVariant>
+): ConfigFieldGroup[] {
+	const groupMap = new Map<string, ConfigFieldGroup>();
+
+	// Add base groups
+	for (const group of baseGroups ?? []) {
+		groupMap.set(group.id, group);
+	}
+
+	// Add variant groups (prefixed)
+	for (const [path, activeVariant] of activeVariants) {
+		if (activeVariant.enabled && activeVariant.variant?.groups) {
+			const prefixedGroups = prefixVariantGroups(activeVariant.variant.groups, path);
+			for (const group of prefixedGroups) {
+				const existing = groupMap.get(group.id);
+				if (existing) {
+					groupMap.set(group.id, { ...existing, ...group });
+				} else {
+					groupMap.set(group.id, group);
+				}
+			}
+		}
+	}
+
+	return Array.from(groupMap.values()).sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+}
+
+/**
+ * Merge a manifest with multiple active nested variants
+ *
+ * @param base - The base record manifest
+ * @param activeVariants - Map of active nested variants keyed by path
+ * @param options - Merge options
+ * @returns The merged manifest
+ */
+export function mergeManifestWithNestedVariants<T extends Record<string, unknown>>(
+	base: RecordManifest<T>,
+	activeVariants: Map<string, ActiveNestedVariant>,
+	options: MergeManifestOptions = {}
+): RecordManifest<T> {
+	const _opts = { ...DEFAULT_MERGE_OPTIONS, ...options };
+
+	// Merge fields from all active variants
+	const mergedFields = mergeNestedVariantFields(base.fields, activeVariants);
+
+	// Merge groups from all active variants
+	const mergedGroups = mergeNestedVariantGroups(base.groups, activeVariants);
+
+	// Build merged manifest
+	const merged: RecordManifest<T> = {
+		...base,
+		fields: mergedFields,
+		groups: mergedGroups
+	};
+
+	// Nested-variant schemas are not merged; validation stays at base schema + per-path.
+	return merged;
+}
+
+/**
+ * Get all field keys visible based on active nested variants
+ *
+ * @param baseFields - Fields from base manifest
+ * @param activeVariants - Map of active nested variants
+ * @returns Set of visible field keys
+ */
+export function getVisibleFieldsWithNestedVariants(
+	baseFields: Record<string, ConfigFieldMeta>,
+	activeVariants: Map<string, ActiveNestedVariant>
+): Set<string> {
+	const visible = new Set<string>();
+
+	// Base fields are always potentially visible
+	for (const key of Object.keys(baseFields)) {
+		visible.add(key);
+	}
+
+	// Add variant fields when their section is enabled
+	for (const [path, activeVariant] of activeVariants) {
+		if (activeVariant.enabled && activeVariant.variant) {
+			for (const key of Object.keys(activeVariant.variant.fields)) {
+				visible.add(`${path}.${key}`);
+			}
+		}
+	}
+
+	return visible;
+}
+
+/**
+ * Merge default values from base and multiple nested variants
+ *
+ * @param baseDefaults - Defaults from base manifest
+ * @param activeVariants - Map of active nested variants
+ * @returns Merged defaults with nested values
+ */
+export function mergeNestedDefaults<T extends Record<string, unknown>>(
+	baseDefaults: Partial<T>,
+	activeVariants: Map<string, ActiveNestedVariant>
+): Partial<T> {
+	const merged = { ...baseDefaults } as Record<string, unknown>;
+
+	for (const [path, activeVariant] of activeVariants) {
+		if (activeVariant.enabled && activeVariant.variant?.defaults) {
+			// Set nested defaults at the path
+			setValueAtPath(merged, path, {
+				...((getValueAtPath(merged, path) as Record<string, unknown> | undefined) ?? {}),
+				...activeVariant.variant.defaults
+			});
+		}
+	}
+
+	return merged as Partial<T>;
+}
+
+/**
+ * Helper to get a value at a dot-notation path
+ */
+function getValueAtPath(obj: Record<string, unknown>, path: string): unknown {
+	const parts = path.split('.');
+	let current: unknown = obj;
+	for (const part of parts) {
+		if (current == null || typeof current !== 'object') {
+			return undefined;
+		}
+		current = (current as Record<string, unknown>)[part];
+	}
+	return current;
+}
+
+/**
+ * Helper to set a value at a dot-notation path
+ */
+function setValueAtPath(obj: Record<string, unknown>, path: string, value: unknown): void {
+	const parts = path.split('.');
+	let current = obj;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const part = parts[i];
+		if (!(part in current) || typeof current[part] !== 'object') {
+			current[part] = {};
+		}
+		current = current[part] as Record<string, unknown>;
+	}
+	current[parts[parts.length - 1]] = value;
+}