@vibesdotdev/config 0.0.1

package/src/manifest/config-manifest.ts

@@ -0,0 +1,482 @@
+/**
+ * Config Manifest Class
+ *
+ * Extends StorageManifest with form metadata and UI rendering support.
+ * This is the runtime class used by the config module.
+ */
+
+import { StorageManifest } from '@vibesdotdev/storage/manifest';
+import type { Unsubscribe } from '@vibesdotdev/storage/interfaces/document-store';
+import type { StorageManifestDescriptor } from '@vibesdotdev/storage/schemas/manifest-descriptor';
+import { getVibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import type {
+	ConfigManifestDescriptor,
+	ConfigFieldMeta,
+	ConfigFieldGroup,
+	ManifestNavigation,
+	ManifestContext,
+	ConfigTier
+} from '../schemas/config-manifest-descriptor';
+import type {
+	ConfigContext,
+	ConfigRule,
+	FieldDefaults,
+	FieldRules
+} from '../manifest/types';
+import { evaluateRule } from '../form/core/visibility';
+
+import type { ConfigChangeCallback } from './schemas/config-manifest.schema.ts';
+export type { ConfigChangeCallback };
+
+/**
+ * Config Manifest - extends StorageManifest with form metadata.
+ *
+ * Provides:
+ * - All StorageManifest operations (load, save, exists, delete)
+ * - Form field metadata for UI rendering
+ * - Context-aware default values
+ * - Conditional visibility rules
+ * - Navigation configuration
+ * - Field-level get/set/subscribe for reactive config access
+ *
+ * @template T - The type of configuration data
+ *
+ * @example
+ * ```ts
+ * // Create from descriptor (runtime instantiation)
+ * const manifest = new ConfigManifest<AIConfig>(descriptor);
+ *
+ * // Load with defaults applied
+ * const config = await manifest.loadWithDefaults(context);
+ *
+ * // Get visible fields for rendering
+ * const fields = manifest.getVisibleFields(currentValues, context);
+ *
+ * // Reactive field-level access (runtime-aligned, replaces createConfigAccessor)
+ * const config = manifest.get();
+ * manifest.setField('temperature', 0.8);
+ * manifest.subscribe((config) => console.log('Config changed:', config));
+ * ```
+ */
+export class ConfigManifest<T> extends StorageManifest<T> {
+	protected readonly configDescriptor: ConfigManifestDescriptor;
+
+	/**
+	 * Create a config manifest instance.
+	 *
+	 * @param descriptorOrId - Either the full descriptor (for runtime instantiation)
+	 *                         or the manifest ID string (for manual instantiation)
+	 * @param context - Runtime context (optional for manual instantiation, provided by runtime resolution)
+	 */
+	constructor(descriptorOrId: ConfigManifestDescriptor | string, context?: KindContext) {
+		if (typeof descriptorOrId === 'string') {
+			const runtime = getVibesRuntime();
+			const descriptor = runtime
+				.query<ConfigManifestDescriptor, ConfigManifest<T>>('config/manifest')
+				.withId(descriptorOrId)
+				.firstDescriptor() as ConfigManifestDescriptor | null;
+
+			if (!descriptor) {
+				throw new Error(`Config manifest '${descriptorOrId}' not found. Is it registered?`);
+			}
+
+			// Call parent with the looked-up descriptor
+			super(descriptor as unknown as StorageManifestDescriptor, context ?? { runtime });
+
+			this.configDescriptor = descriptor;
+		} else {
+			// Direct descriptor (runtime instantiation)
+			super(descriptorOrId as unknown as StorageManifestDescriptor, context);
+
+			this.configDescriptor = descriptorOrId;
+		}
+	}
+
+	/**
+	 * Create a config manifest by looking up its ID.
+	 */
+	static fromId<T>(manifestId: string): ConfigManifest<T> {
+		return new ConfigManifest<T>(manifestId);
+	}
+
+	// Config-Specific Properties
+
+	/**
+	 * Get the configuration tier.
+	 */
+	get tier(): ConfigTier {
+		return this.configDescriptor.tier;
+	}
+
+	/**
+	 * Get the manifest name.
+	 */
+	get name(): string | undefined {
+		return this.configDescriptor.name;
+	}
+
+	/**
+	 * Get the manifest description.
+	 */
+	get description(): string | undefined {
+		return this.configDescriptor.description;
+	}
+
+	/**
+	 * Get the category within the tier.
+	 */
+	get category(): string | undefined {
+		return this.configDescriptor.category;
+	}
+
+	/**
+	 * Get field metadata for all fields.
+	 */
+	get fields(): Record<string, ConfigFieldMeta> {
+		return this.configDescriptor.fields;
+	}
+
+	/**
+	 * Get field groups for UI organization.
+	 */
+	get groups(): ConfigFieldGroup[] {
+		return this.configDescriptor.groups ?? [];
+	}
+
+	/**
+	 * Get navigation configuration.
+	 */
+	get navigation(): ManifestNavigation | undefined {
+		return this.configDescriptor.navigation;
+	}
+
+	/**
+	 * Get context constraints for this manifest.
+	 * (Named differently from base class 'context' which is runtime context)
+	 */
+	get manifestContext(): ManifestContext | undefined {
+		return this.configDescriptor.context;
+	}
+
+	/**
+	 * Get the manifest icon.
+	 */
+	get icon(): string | undefined {
+		return this.configDescriptor.icon;
+	}
+
+	/**
+	 * Get sensitive fields list.
+	 */
+	get sensitiveFields(): string[] | undefined {
+		return this.configDescriptor.sensitiveFields;
+	}
+
+	// Field Metadata Access
+
+	/**
+	 * Get metadata for a specific field.
+	 */
+	getFieldMeta(fieldPath: string): ConfigFieldMeta | undefined {
+		return this.configDescriptor.fields[fieldPath];
+	}
+
+	/**
+	 * Get all field paths.
+	 */
+	getFieldPaths(): string[] {
+		return Object.keys(this.configDescriptor.fields);
+	}
+
+	/**
+	 * Get fields in a specific group.
+	 */
+	getFieldsInGroup(groupId: string): string[] {
+		return Object.entries(this.configDescriptor.fields)
+			.filter(([_, meta]) => meta.ui.group === groupId)
+			.map(([path]) => path);
+	}
+
+	/**
+	 * Get fields without a group.
+	 */
+	getUngroupedFields(): string[] {
+		return Object.entries(this.configDescriptor.fields)
+			.filter(([_, meta]) => !meta.ui.group)
+			.map(([path]) => path);
+	}
+
+	// Default Values
+
+	/**
+	 * Resolve the default value for a field based on context.
+	 */
+	resolveDefault<V>(fieldPath: string, ctx: ConfigContext): V | undefined {
+		const meta = this.getFieldMeta(fieldPath);
+		if (!meta?.defaults) return undefined;
+
+		const defaults = meta.defaults as FieldDefaults<V>;
+
+		// Check for custom resolver
+		if (defaults.resolver) {
+			return defaults.resolver(ctx);
+		}
+
+		// Check context-specific overrides
+		if (defaults.byHardware?.[ctx.hardware] !== undefined) {
+			return defaults.byHardware[ctx.hardware];
+		}
+		if (defaults.byEnvironment?.[ctx.environment] !== undefined) {
+			return defaults.byEnvironment[ctx.environment];
+		}
+		if (defaults.bySurface?.[ctx.surface] !== undefined) {
+			return defaults.bySurface[ctx.surface];
+		}
+
+		// Fall back to base default
+		return defaults.base;
+	}
+
+	/**
+	 * Get all default values for the current context.
+	 */
+	getDefaults(ctx: ConfigContext): Partial<T> {
+		const defaults: Record<string, unknown> = {};
+
+		for (const fieldPath of this.getFieldPaths()) {
+			const value = this.resolveDefault(fieldPath, ctx);
+			if (value !== undefined) {
+				defaults[fieldPath] = value;
+			}
+		}
+
+		return defaults as Partial<T>;
+	}
+
+	// Visibility Rules
+
+	/**
+	 * Check if a field is visible based on current values and context.
+	 */
+	isFieldVisible(fieldPath: string, values: Record<string, unknown>, ctx: ConfigContext): boolean {
+		const meta = this.getFieldMeta(fieldPath);
+		const rules = meta?.rules as FieldRules | undefined;
+		if (!rules?.visibleWhen) return true;
+
+		return evaluateRule(rules.visibleWhen as ConfigRule, values, ctx);
+	}
+
+	/**
+	 * Check if a field is disabled based on current values and context.
+	 */
+	isFieldDisabled(fieldPath: string, values: Record<string, unknown>, ctx: ConfigContext): boolean {
+		const meta = this.getFieldMeta(fieldPath);
+		const rules = meta?.rules as FieldRules | undefined;
+		if (!rules?.disabledWhen) return false;
+
+		return evaluateRule(rules.disabledWhen as ConfigRule, values, ctx);
+	}
+
+	/**
+	 * Check if a field is required based on current values and context.
+	 */
+	isFieldRequired(fieldPath: string, values: Record<string, unknown>, ctx: ConfigContext): boolean {
+		const meta = this.getFieldMeta(fieldPath);
+		const rules = meta?.rules as FieldRules | undefined;
+		if (!rules?.requiredWhen) return false;
+
+		return evaluateRule(rules.requiredWhen as ConfigRule, values, ctx);
+	}
+
+	/**
+	 * Get all visible fields for the current values and context.
+	 */
+	getVisibleFields(values: Record<string, unknown>, ctx: ConfigContext): string[] {
+		return this.getFieldPaths().filter((path) => this.isFieldVisible(path, values, ctx));
+	}
+
+	/**
+	 * Check if a group is visible based on current values and context.
+	 */
+	isGroupVisible(groupId: string, values: Record<string, unknown>, ctx: ConfigContext): boolean {
+		const group = this.groups.find((g) => g.id === groupId);
+		// Groups can have optional visibility rules stored in descriptor
+		const groupWithRules = group as (typeof group & { visibleWhen?: ConfigRule }) | undefined;
+		if (!groupWithRules?.visibleWhen) return true;
+
+		return evaluateRule(groupWithRules.visibleWhen, values, ctx);
+	}
+
+	// Context Checks
+
+	/**
+	 * Check if this manifest applies to the given context.
+	 */
+	appliesToContext(ctx: ConfigContext): boolean {
+		const constraints = this.manifestContext;
+		if (!constraints) return true;
+
+		// Check hardware constraint
+		if (constraints.hardware && !constraints.hardware.includes(ctx.hardware)) {
+			return false;
+		}
+
+		// Check environment constraint
+		if (constraints.environment && !constraints.environment.includes(ctx.environment)) {
+			return false;
+		}
+
+		// Check surface constraint
+		if (constraints.surfaces && !constraints.surfaces.includes(ctx.surface)) {
+			return false;
+		}
+
+		// Check required features
+		if (constraints.requiredFeatures) {
+			for (const feature of constraints.requiredFeatures) {
+				if (!ctx.enabledFeatures.has(feature)) {
+					return false;
+				}
+			}
+		}
+
+		return true;
+	}
+
+	// Extended Load/Save
+
+	/**
+	 * Load configuration with context-aware defaults applied.
+	 *
+	 * @param ctx - Current config context
+	 * @returns Merged config with defaults applied for missing fields
+	 */
+	async loadWithDefaults(ctx: ConfigContext): Promise<T> {
+		const stored = await this.load();
+		const defaults = this.getDefaults(ctx);
+
+		// Merge defaults under stored values
+		return {
+			...defaults,
+			...stored
+		} as T;
+	}
+
+	/**
+	 * Save configuration, optionally running onSave lifecycle hook.
+	 *
+	 * @param data - Configuration data to save
+	 * @param ctx - Current config context (for lifecycle hooks)
+	 */
+	async saveWithHooks(data: T, ctx?: ConfigContext): Promise<void> {
+		// If we have a context and onSave hook, run it
+		// Note: Lifecycle hooks are defined in the full ConfigManifest interface
+		// but stored in the descriptor as function references
+		const descriptor = this.configDescriptor as unknown as {
+			onSave?: (config: T, ctx: ConfigContext) => T | Promise<T>;
+		};
+
+		let finalData = data;
+		if (ctx && descriptor.onSave) {
+			finalData = await descriptor.onSave(data, ctx);
+		}
+
+		await this.save(finalData);
+	}
+
+	// Field-Level Reactive API (Runtime-Aligned, replaces createConfigAccessor)
+
+	/**
+	 * Get the current configuration (from cache if available).
+	 * Loads from storage if not cached.
+	 *
+	 * @returns Current config or null if not loaded
+	 */
+	get(): T | null {
+		return this.getCachedData() ?? null;
+	}
+
+	/**
+	 * Get a specific field value from the cached config.
+	 *
+	 * @param fieldPath - Dot-notation path to the field
+	 * @returns The field value or undefined if not found
+	 */
+	getField<K extends keyof T>(fieldPath: K): T[K] | undefined;
+	getField(fieldPath: string): unknown;
+	getField(fieldPath: string | keyof T): unknown {
+		const data = this.get();
+		if (!data) return undefined;
+
+		// Handle dot notation
+		const path = String(fieldPath);
+		if (path.includes('.')) {
+			const parts = path.split('.');
+			let current: unknown = data;
+			for (const part of parts) {
+				if (current && typeof current === 'object') {
+					current = (current as Record<string, unknown>)[part];
+				} else {
+					return undefined;
+				}
+			}
+			return current;
+		}
+
+		return (data as Record<string, unknown>)[path];
+	}
+
+	/**
+	 * Set a single field value and save to storage.
+	 *
+	 * @param fieldPath - Dot-notation path to the field
+	 * @param value - The value to set
+	 */
+	async setField<K extends keyof T>(fieldPath: K, value: T[K]): Promise<void>;
+	async setField(fieldPath: string, value: unknown): Promise<void>;
+	async setField(fieldPath: string | keyof T, value: unknown): Promise<void> {
+		const data = (this.get() ?? {}) as T;
+		const path = String(fieldPath);
+
+		// Handle dot notation
+		if (path.includes('.')) {
+			const parts = path.split('.');
+			const last = parts.pop()!;
+			let current: Record<string, unknown> = data as Record<string, unknown>;
+
+			for (const part of parts) {
+				if (!(part in current) || typeof current[part] !== 'object') {
+					current[part] = {};
+				}
+				current = current[part] as Record<string, unknown>;
+			}
+			current[last] = value;
+		} else {
+			(data as Record<string, unknown>)[path] = value;
+		}
+
+		await this.save(data);
+	}
+
+	/**
+	 * Set multiple field values at once and save to storage.
+	 *
+	 * @param fields - Partial object with fields to update
+	 */
+	async setFields(fields: Partial<T>): Promise<void> {
+		const data = { ...this.get(), ...fields } as T;
+		await this.save(data);
+	}
+
+	/**
+	 * Subscribe to configuration changes.
+	 * Replaces the createConfigAccessor subscribe pattern.
+	 *
+	 * @param callback - Function called when config changes
+	 * @returns Unsubscribe function
+	 */
+	override subscribe(callback: ConfigChangeCallback<T>): Unsubscribe {
+		return super.subscribe(callback as (data: T | null) => void);
+	}
+}

package/src/manifest/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Configuration Manifest Module
+ *
+ * Types and utilities for defining configuration manifests.
+ */
+
+// Runtime-aware ConfigManifest class (extends StorageManifest)
+export { ConfigManifest } from './config-manifest.ts';
+
+// Types
+export type {
+	ConfigTier,
+	StorageAdapterType,
+	StorageScope,
+	ConfigSurface,
+	HardwareContext,
+	EnvironmentContext,
+	ConfigContext,
+	ConfigRule,
+	ConfigFieldRule,
+	ConfigContextRule,
+	ConfigAndRule,
+	ConfigOrRule,
+	ConfigNotRule,
+	ConfigFunctionRule,
+	FieldComponent,
+	FieldWidth,
+	FieldUI,
+	FieldOption,
+	FieldAccess,
+	FieldRules,
+	FieldDefaults,
+	ConfigFieldMeta,
+	ConfigFieldGroup,
+	ManifestStorage,
+	ManifestContext,
+	// ConfigManifest interface is deprecated - use the class from config-manifest.js
+	ConfigManifest as ConfigManifestInterface,
+	InferConfigType,
+	FieldPaths
+} from './types.ts';
+
+// Schemas (for validation/serialization)
+export {
+	configTierSchema,
+	storageAdapterSchema,
+	storageScopeSchema,
+	configSurfaceSchema,
+	hardwareContextSchema,
+	environmentContextSchema,
+	fieldComponentSchema,
+	fieldWidthSchema,
+	fieldUISchema,
+	fieldOptionSchema,
+	fieldAccessSchema,
+	fieldRulesSchema,
+	fieldDefaultsSchema,
+	configFieldMetaSchema,
+	configFieldGroupSchema,
+	manifestStorageSchema,
+	manifestContextSchema,
+	configManifestMetaSchema,
+	configRuleSchema
+} from './schema.ts';
+
+// Builder
+export {
+	createConfigManifest,
+	ManifestBuilder,
+	type CreateManifestOptions,
+	// Field helpers
+	inputField,
+	textareaField,
+	numberField,
+	booleanField,
+	selectField,
+	radioField,
+	sliderField,
+	secretField,
+	jsonField,
+	// Option helpers
+	option,
+	optionsFromEnum,
+	// Defaults helpers
+	defaults,
+	// Rules helpers
+	whenField,
+	whenContext,
+	allOf,
+	anyOf,
+	not
+} from './builder.ts';