@vibesdotdev/config 0.0.1

package/src/extensions/registry.ts

@@ -0,0 +1,179 @@
+/**
+ * Extension Registry
+ *
+ * Global registry for surface-specific manifest extensions.
+ * Extensions self-register on import from surface entry points.
+ */
+
+import type { BaseRecord } from '../crud/types.ts';
+import type { ExtensionSurface, ManifestSurfaceExtension, LoadedExtension } from './types.ts';
+
+// Registry Storage
+
+/**
+ * Global registry - maps "manifestId:surface" to extension
+ * Uses BaseRecord as the common type for storage
+ */
+const extensions = new Map<string, ManifestSurfaceExtension<BaseRecord>>();
+
+/**
+ * Cache for loaded extensions (with components resolved)
+ */
+const loadedCache = new Map<string, LoadedExtension<BaseRecord>>();
+
+// Registration
+
+/**
+ * Build registry key from manifest ID and surface
+ */
+function buildKey(manifestId: string, surface: ExtensionSurface): string {
+	return `${manifestId}:${surface}`;
+}
+
+/**
+ * Register a surface extension for a manifest
+ */
+export function registerExtension<T extends BaseRecord = BaseRecord>(
+	extension: ManifestSurfaceExtension<T>
+): void {
+	const key = buildKey(extension.manifestId, extension.surface);
+
+	if (extensions.has(key)) {
+		console.warn(
+			`[ExtensionRegistry] Extension for "${extension.manifestId}" on "${extension.surface}" already registered. Skipping.`
+		);
+		return;
+	}
+
+	// Registry stores base type; callers retrieve with their specific generic
+	extensions.set(key, extension as unknown as ManifestSurfaceExtension<BaseRecord>);
+}
+
+// Retrieval
+
+/**
+ * Get a registered extension (not yet loaded)
+ */
+export function getExtension(
+	manifestId: string,
+	surface: ExtensionSurface
+): ManifestSurfaceExtension | null {
+	return extensions.get(buildKey(manifestId, surface)) ?? null;
+}
+
+/**
+ * Check if an extension exists
+ */
+export function hasExtension(manifestId: string, surface: ExtensionSurface): boolean {
+	return extensions.has(buildKey(manifestId, surface));
+}
+
+/**
+ * Get all registered extension keys
+ */
+export function getAllExtensionKeys(): string[] {
+	return Array.from(extensions.keys());
+}
+
+/**
+ * Get all extensions for a specific surface
+ */
+export function getExtensionsForSurface(surface: ExtensionSurface): ManifestSurfaceExtension[] {
+	return Array.from(extensions.values()).filter((ext) => ext.surface === surface);
+}
+
+// Loading (Lazy Component Resolution)
+
+/**
+ * Load an extension, resolving all lazy loaders
+ */
+export async function loadExtension<T extends BaseRecord = BaseRecord>(
+	manifestId: string,
+	surface: ExtensionSurface
+): Promise<LoadedExtension<T> | null> {
+	const key = buildKey(manifestId, surface);
+
+	// Check cache first
+	const cached = loadedCache.get(key);
+	if (cached) {
+		// Cache stores base type; caller retrieves with their specific generic
+		return cached as unknown as LoadedExtension<T>;
+	}
+
+	// Get the raw extension
+	const extension = getExtension(manifestId, surface);
+	if (!extension) {
+		return null;
+	}
+
+	// Resolve all field override loaders in parallel
+	const loadedOverrides: LoadedExtension['fieldOverrides'] = {};
+
+	if (extension.fieldOverrides) {
+		const entries = Object.entries(extension.fieldOverrides);
+		const loadPromises = entries.map(async ([fieldKey, override]) => {
+			if (override.loader) {
+				const loaded = await override.loader();
+				return [
+					fieldKey,
+					{
+						component: loaded.component,
+						props: { ...override.props, ...loaded.props },
+						propsFactory: override.propsFactory,
+						hidden: override.hidden,
+						render: override.render
+					}
+				] as const;
+			}
+			return [
+				fieldKey,
+				{
+					component: override.component,
+					props: override.props,
+					propsFactory: override.propsFactory,
+					hidden: override.hidden,
+					render: override.render
+				}
+			] as const;
+		});
+
+		const results = await Promise.all(loadPromises);
+		for (const [fieldKey, override] of results) {
+			loadedOverrides[fieldKey] = override;
+		}
+	}
+
+	// Build loaded extension
+	const loaded: LoadedExtension<T> = {
+		manifestId: extension.manifestId,
+		surface: extension.surface,
+		fieldOverrides: loadedOverrides,
+		renderHeader: extension.renderHeader as LoadedExtension<T>['renderHeader'],
+		renderFooter: extension.renderFooter as LoadedExtension<T>['renderFooter'],
+		renderListRow: extension.renderListRow as LoadedExtension<T>['renderListRow'],
+		renderEmpty: extension.renderEmpty,
+		renderCreate: extension.renderCreate as LoadedExtension<T>['renderCreate'],
+		renderEdit: extension.renderEdit as LoadedExtension<T>['renderEdit']
+	};
+
+	// Cache and return
+	loadedCache.set(key, loaded as unknown as LoadedExtension<BaseRecord>);
+	return loaded;
+}
+
+// Cache Management
+
+/**
+ * Clear the loaded extension cache
+ */
+export function clearExtensionCache(): void {
+	loadedCache.clear();
+}
+
+/**
+ * Clear all registered extensions (for testing)
+ */
+export function clearAllExtensions(): void {
+	extensions.clear();
+	loadedCache.clear();
+}

package/src/extensions/types.ts

@@ -0,0 +1,123 @@
+/**
+ * Surface-Specific Manifest Extensions
+ *
+ * Enables surface-specific (TUI/Web/CLI) component overrides for manifests.
+ * Extensions are loaded on-demand like the tools/manifests.ts pattern.
+ */
+
+import type { ConfigFieldMeta } from '../manifest/types.ts';
+import type { CRUDViewMode, BaseRecord } from '../crud/shared.ts';
+
+// Re-export BaseRecord for convenience
+export type { BaseRecord } from '../crud/shared.ts';
+
+// Surface Types
+
+/**
+ * Supported surface types
+ */
+export type ExtensionSurface = 'tui' | 'web' | 'cli';
+
+// Lazy Loading
+
+/**
+ * Lazy component loader - returns component and optional props
+ */
+export type LazyComponentLoader<T = unknown> = () => Promise<{
+	component: T;
+	props?: Record<string, unknown>;
+}>;
+
+/**
+ * Component override with lazy loading support
+ */
+export interface LazyComponentOverride {
+	/** Lazy loader for the component */
+	loader?: LazyComponentLoader;
+	/** Pre-loaded component (alternative to loader) */
+	component?: unknown;
+	/** Factory to generate props from field and context */
+	propsFactory?: (
+		field: ConfigFieldMeta,
+		context: { values: Record<string, unknown>; mode: 'create' | 'edit' }
+	) => Record<string, unknown>;
+	/** Additional static props */
+	props?: Record<string, unknown>;
+	/** Hide this field entirely */
+	hidden?: boolean;
+	/** Custom render function */
+	render?: (field: ConfigFieldMeta, defaultRender: () => unknown) => unknown;
+}
+
+// Extension Definition
+
+/**
+ * View render context for custom create/edit views
+ */
+export interface ViewRenderContext<T extends BaseRecord = BaseRecord> {
+	/** Current record (undefined for create mode) */
+	record?: T;
+	/** Submit handler */
+	onSubmit: (values: T) => void;
+	/** Cancel/back handler */
+	onCancel: () => void;
+	/** Whether a save operation is in progress */
+	isSubmitting?: boolean;
+}
+
+/**
+ * Surface-specific extension for a manifest
+ */
+export interface ManifestSurfaceExtension<T extends BaseRecord = BaseRecord> {
+	/** Manifest ID this extension applies to */
+	manifestId: string;
+	/** Surface this extension is for */
+	surface: ExtensionSurface;
+	/** Field-level component overrides */
+	fieldOverrides?: Record<string, LazyComponentOverride>;
+	/** Custom header renderer */
+	renderHeader?: (mode: CRUDViewMode, record?: T) => unknown;
+	/** Custom footer renderer */
+	renderFooter?: (mode: CRUDViewMode, record?: T) => unknown;
+	/** Custom list row renderer */
+	renderListRow?: (record: T, defaultRender: () => unknown) => unknown;
+	/** Custom empty state renderer */
+	renderEmpty?: () => unknown;
+	/**
+	 * Custom create view renderer.
+	 * When provided, replaces the entire create form with a custom component.
+	 * Use for wizard-style flows or complex template-based creation.
+	 */
+	renderCreate?: (context: ViewRenderContext<T>) => unknown;
+	/**
+	 * Custom edit view renderer.
+	 * When provided, replaces the entire edit form with a custom component.
+	 */
+	renderEdit?: (context: ViewRenderContext<T>) => unknown;
+}
+
+// Loaded Extension State
+
+/**
+ * An extension with components already loaded
+ */
+export interface LoadedExtension<T extends BaseRecord = BaseRecord> extends Omit<
+	ManifestSurfaceExtension<T>,
+	'fieldOverrides'
+> {
+	/** Loaded component overrides (loaders resolved) */
+	fieldOverrides: Record<
+		string,
+		{
+			component?: unknown;
+			props?: Record<string, unknown>;
+			propsFactory?: LazyComponentOverride['propsFactory'];
+			hidden?: boolean;
+			render?: LazyComponentOverride['render'];
+		}
+	>;
+	/** Custom create view renderer */
+	renderCreate?: ManifestSurfaceExtension<T>['renderCreate'];
+	/** Custom edit view renderer */
+	renderEdit?: ManifestSurfaceExtension<T>['renderEdit'];
+}

package/src/form/core/field-resolver.ts

@@ -0,0 +1,380 @@
+/**
+ * Field Resolver
+ *
+ * Maps manifest field definitions to component types and resolves field state.
+ * Also provides default resolution based on context.
+ */
+import type { z, ZodTypeAny, ZodObject } from 'zod/v4';
+import type {
+	ConfigManifest,
+	ConfigFieldMeta,
+	FieldComponent,
+	ConfigContext
+} from '../../manifest/types.ts';
+import type { ResolvedField, ComponentOverride } from './types.ts';
+import { getUIMeta } from '../../schema/extend-zod.ts';
+
+/**
+ * Infer component type from field metadata
+ */
+export function inferFieldComponent(fieldMeta: ConfigFieldMeta): FieldComponent {
+	// Explicit component takes precedence
+	if (fieldMeta.ui.component) {
+		return fieldMeta.ui.component;
+	}
+
+	// Infer from options presence
+	if (fieldMeta.options && fieldMeta.options.length > 0) {
+		// Few options = radio, many = select
+		return fieldMeta.options.length <= 4 ? 'radio-group' : 'select';
+	}
+
+	// Default to input
+	return 'input';
+}
+
+/**
+ * Get default value for a field considering context
+ */
+export function getFieldDefault(
+	fieldMeta: ConfigFieldMeta,
+	context: { hardware?: string; environment?: string; surface?: string }
+): unknown {
+	const defaults = fieldMeta.defaults;
+	if (!defaults) return undefined;
+
+	// Check surface-specific default
+	if (context.surface && defaults.bySurface?.[context.surface as keyof typeof defaults.bySurface]) {
+		return defaults.bySurface[context.surface as keyof typeof defaults.bySurface];
+	}
+
+	// Check hardware-specific default
+	if (
+		context.hardware &&
+		defaults.byHardware?.[context.hardware as keyof typeof defaults.byHardware]
+	) {
+		return defaults.byHardware[context.hardware as keyof typeof defaults.byHardware];
+	}
+
+	// Check environment-specific default
+	if (
+		context.environment &&
+		defaults.byEnvironment?.[context.environment as keyof typeof defaults.byEnvironment]
+	) {
+		return defaults.byEnvironment[context.environment as keyof typeof defaults.byEnvironment];
+	}
+
+	// Return base default
+	return defaults.base;
+}
+
+/**
+ * Get a value at a dot-notation path from an object
+ * Supports both flat keys (e.g., obj['configuration.apiKey'])
+ * and nested objects (e.g., obj.configuration.apiKey)
+ */
+function getValueAtPath(obj: Record<string, unknown>, path: string): unknown {
+	// First try direct key lookup (for flat form values)
+	if (path in obj) {
+		return obj[path];
+	}
+
+	// Then try dot-notation path lookup (for nested objects)
+	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;
+}
+
+/**
+ * Get a schema at a dot-notation path
+ * Drills down through nested ZodObject shapes
+ */
+function getSchemaAtPath(rootSchema: ZodTypeAny, path: string): ZodTypeAny | undefined {
+	const parts = path.split('.');
+	let current: ZodTypeAny | undefined = rootSchema;
+
+	for (const part of parts) {
+		if (!current) return undefined;
+
+		// Try to get shape from current schema
+		const zodObj = current as ZodObject<Record<string, ZodTypeAny>>;
+		if (zodObj.shape && typeof zodObj.shape === 'object') {
+			current = zodObj.shape[part] as ZodTypeAny | undefined;
+		} else {
+			return undefined;
+		}
+	}
+
+	return current;
+}
+
+/**
+ * Type guard to check if a manifest has a recordSchema property
+ */
+function hasRecordSchema(
+	manifest: ConfigManifest
+): manifest is ConfigManifest & { recordSchema: ZodTypeAny } {
+	return 'recordSchema' in manifest && manifest.recordSchema != null;
+}
+
+/**
+ * Extract field schemas from a manifest's Zod schema
+ * Handles dot-notation field keys for nested fields
+ */
+function extractFieldSchemas(manifest: ConfigManifest): Record<string, ZodTypeAny> {
+	const schemas: Record<string, ZodTypeAny> = {};
+
+	// Use recordSchema if available (for RecordManifests), otherwise use schema
+	const baseSchema = hasRecordSchema(manifest) ? manifest.recordSchema : manifest.schema;
+	if (!baseSchema || typeof baseSchema !== 'object' || !('_zod' in baseSchema)) {
+		return schemas;
+	}
+
+	// For each field key in the manifest, try to find its schema
+	for (const key of Object.keys(manifest.fields)) {
+		if (key.includes('.')) {
+			// Dot-notation path - drill down into nested schemas
+			const fieldSchema = getSchemaAtPath(baseSchema, key);
+			if (fieldSchema) {
+				schemas[key] = fieldSchema;
+			}
+		} else {
+			// Top-level field - get directly from shape
+			const zodSchema = baseSchema as ZodObject<Record<string, ZodTypeAny>>;
+			if (zodSchema.shape && zodSchema.shape[key]) {
+				schemas[key] = zodSchema.shape[key] as ZodTypeAny;
+			}
+		}
+	}
+
+	return schemas;
+}
+
+/**
+ * Resolve all fields from a manifest
+ */
+export function resolveFields(
+	manifest: ConfigManifest,
+	values: Record<string, unknown>,
+	overrides: Record<string, ComponentOverride> = {},
+	context: { hardware?: string; environment?: string; surface?: string } = {}
+): ResolvedField[] {
+	const fields: ResolvedField[] = [];
+	const fieldSchemas = extractFieldSchemas(manifest);
+
+	for (const [key, meta] of Object.entries(manifest.fields)) {
+		const override = overrides[key];
+		const fieldSchema = fieldSchemas[key];
+
+		// Skip if override says hidden
+		if (override?.hidden) continue;
+
+		// Check if schema has UI metadata that should override manifest meta
+		const schemaUIMeta = fieldSchema ? getUIMeta(fieldSchema) : undefined;
+		const enhancedMeta = schemaUIMeta ? mergeUIMeta(meta, schemaUIMeta) : meta;
+
+		const resolved: ResolvedField = {
+			key,
+			meta: enhancedMeta,
+			component: inferFieldComponent(enhancedMeta),
+			// Use path-based access for nested fields (e.g., configuration.apiKey)
+			value: getValueAtPath(values, key) ?? getFieldDefault(enhancedMeta, context),
+			visible: true, // Will be evaluated by visibility module
+			disabled: false, // Will be evaluated by visibility module
+			required: false, // Will be evaluated by visibility module
+			override,
+			fieldSchema
+		};
+
+		fields.push(resolved);
+	}
+
+	// Sort by order
+	fields.sort((a, b) => (a.meta.ui.order ?? 999) - (b.meta.ui.order ?? 999));
+
+	return fields;
+}
+
+/**
+ * Merge schema UI metadata into field meta
+ */
+function mergeUIMeta(
+	meta: ConfigFieldMeta,
+	schemaUI: ReturnType<typeof getUIMeta>
+): ConfigFieldMeta {
+	if (!schemaUI) return meta;
+
+	return {
+		...meta,
+		ui: {
+			...meta.ui,
+			// Schema UI overrides manifest UI where defined
+			...(schemaUI.label && { label: schemaUI.label }),
+			...(schemaUI.description && { description: schemaUI.description }),
+			...(schemaUI.helpText && { helpText: schemaUI.helpText }),
+			...(schemaUI.placeholder && { placeholder: schemaUI.placeholder }),
+			...(schemaUI.order !== undefined && { order: schemaUI.order }),
+			...(schemaUI.group && { group: schemaUI.group }),
+			...(schemaUI.component && { component: schemaUI.component as FieldComponent }),
+			...(schemaUI.hidden !== undefined && { hidden: schemaUI.hidden })
+		}
+	};
+}
+
+/**
+ * Group resolved fields by their group ID
+ */
+export function groupFields(
+	fields: ResolvedField[],
+	_groups: ConfigManifest['groups'] = []
+): Map<string | undefined, ResolvedField[]> {
+	const grouped = new Map<string | undefined, ResolvedField[]>();
+
+	for (const field of fields) {
+		const groupId = field.meta.ui.group;
+		if (!grouped.has(groupId)) {
+			grouped.set(groupId, []);
+		}
+		grouped.get(groupId)!.push(field);
+	}
+
+	return grouped;
+}
+
+// Default Resolution (formerly in registry/resolution.ts)
+
+/**
+ * Get defaults from a Zod schema
+ */
+function getSchemaDefaults(schema: ZodTypeAny): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	// Handle ZodObject
+	const zodObj = schema as ZodObject<Record<string, ZodTypeAny>>;
+	if (zodObj.shape && typeof zodObj.shape === 'object') {
+		for (const [key, fieldSchema] of Object.entries(zodObj.shape)) {
+			const def = (fieldSchema as { _def?: { defaultValue?: unknown } })._def;
+			if (def?.defaultValue !== undefined) {
+				result[key] =
+					typeof def.defaultValue === 'function'
+						? (def.defaultValue as () => unknown)()
+						: def.defaultValue;
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(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;
+}
+
+/**
+ * Set nested value in object using dot notation
+ */
+function setNestedValue(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;
+}
+
+/**
+ * Resolve default value for a single field with full context
+ */
+export function resolveFieldDefault(
+	_fieldPath: string,
+	fieldMeta: ConfigFieldMeta,
+	schemaDefault: unknown,
+	ctx: ConfigContext
+): unknown {
+	const defaults = fieldMeta.defaults;
+
+	if (!defaults) {
+		return schemaDefault;
+	}
+
+	// Check for custom resolver
+	if (defaults.resolver) {
+		return defaults.resolver(ctx);
+	}
+
+	// Check hardware-specific default
+	if (defaults.byHardware?.[ctx.hardware] !== undefined) {
+		return defaults.byHardware[ctx.hardware];
+	}
+
+	// Check environment-specific default
+	if (defaults.byEnvironment?.[ctx.environment] !== undefined) {
+		return defaults.byEnvironment[ctx.environment];
+	}
+
+	// Check surface-specific default
+	if (defaults.bySurface?.[ctx.surface] !== undefined) {
+		return defaults.bySurface[ctx.surface];
+	}
+
+	// Use base default
+	if (defaults.base !== undefined) {
+		return defaults.base;
+	}
+
+	// Fall back to schema default
+	return schemaDefault;
+}
+
+/**
+ * Resolve default values for a manifest based on context
+ */
+export function resolveDefaults<T extends z.ZodTypeAny>(
+	manifest: ConfigManifest<T>,
+	ctx: ConfigContext
+): z.infer<T> {
+	const result: Record<string, unknown> = {};
+
+	// Get defaults from schema
+	const schemaDefaults = getSchemaDefaults(manifest.schema);
+
+	// Merge with field-specific defaults
+	for (const [fieldPath, fieldMeta] of Object.entries(manifest.fields)) {
+		const schemaDefault = getNestedValue(schemaDefaults, fieldPath);
+		const resolvedDefault = resolveFieldDefault(fieldPath, fieldMeta, schemaDefault, ctx);
+
+		if (resolvedDefault !== undefined) {
+			setNestedValue(result, fieldPath, resolvedDefault);
+		}
+	}
+
+	// Merge schema defaults for fields without explicit metadata
+	for (const [key, value] of Object.entries(schemaDefaults)) {
+		if (!(key in result) && value !== undefined) {
+			result[key] = value;
+		}
+	}
+
+	return result as z.infer<T>;
+}