@vibesdotdev/config 0.0.1

package/src/schema/extend-zod.ts

@@ -0,0 +1,289 @@
+/**
+ * Zod Schema Extensions for Config Fields
+ *
+ * Provides a fluent builder pattern to attach reference and UI metadata
+ * to Zod schemas. This enables schema-driven form generation with
+ * dynamic option resolution.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   widgetId: configField(z.string())
+ *     .references('example.widgets', { labelField: 'name' })
+ *     .label('Widget')
+ *     .emptyState({ message: 'No widgets configured' })
+ *     .build()
+ * });
+ * ```
+ */
+
+import type { ZodTypeAny } from 'zod/v4';
+import type {
+	ReferenceMeta,
+	ConfigReference,
+	NestedReference,
+	ComputedReference,
+	EnumReference,
+	EmptyStateConfig
+} from './references.ts';
+
+// Symbols for storing metadata on schemas (non-enumerable)
+const REFERENCE_META = Symbol.for('vibes.config.referenceMeta');
+const UI_META = Symbol.for('vibes.config.uiMeta');
+
+import type { UIMeta, ConfigFieldMeta } from './schemas/extend-zod.schema.ts';
+
+export type { UIMeta, ConfigFieldMeta } from './schemas/extend-zod.schema.ts';
+
+/**
+ * Fluent builder for config-aware schemas
+ */
+export class ConfigFieldBuilder<T extends ZodTypeAny> {
+	private _schema: T;
+	private _referenceMeta?: ReferenceMeta;
+	private _uiMeta: UIMeta = {};
+
+	constructor(schema: T) {
+		this._schema = schema;
+	}
+
+	/**
+	 * Reference another config collection
+	 * @example .references('example.things')
+	 * @example .references('example.widgets', { labelField: 'name', filter: 'isActive' })
+	 */
+	references(path: string, options?: Omit<ConfigReference, 'type' | 'path'>): this {
+		this._referenceMeta = {
+			source: { type: 'config', path, ...options },
+			as: 'select'
+		};
+		return this;
+	}
+
+	/**
+	 * Reference nested data within a parent config item
+	 * @example .referencesNested('example.widgets', 'widgetId', 'parts')
+	 */
+	referencesNested(
+		parentPath: string,
+		parentField: string,
+		nestedPath: string,
+		options?: Omit<NestedReference, 'type' | 'parentPath' | 'parentField' | 'nestedPath'>
+	): this {
+		this._referenceMeta = {
+			source: { type: 'nested', parentPath, parentField, nestedPath, ...options },
+			as: 'select'
+		};
+		return this;
+	}
+
+	/**
+	 * Resolve options via async function
+	 * @example .computed('fetchWidgetParts', { dependsOn: ['widgetId'] })
+	 */
+	computed(resolver: string, options?: Omit<ComputedReference, 'type' | 'resolver'>): this {
+		this._referenceMeta = {
+			source: { type: 'computed', resolver, ...options },
+			as: 'select'
+		};
+		return this;
+	}
+
+	/**
+	 * Static enum options
+	 * @example .options([{ value: 'a', label: 'Option A' }])
+	 */
+	options(values: EnumReference['values']): this {
+		this._referenceMeta = {
+			source: { type: 'enum', values },
+			as: 'select'
+		};
+		return this;
+	}
+
+	/**
+	 * UI rendering style
+	 */
+	as(style: NonNullable<ReferenceMeta['as']>): this {
+		if (this._referenceMeta) {
+			this._referenceMeta.as = style;
+		}
+		return this;
+	}
+
+	/**
+	 * Allow multiple selection
+	 */
+	multiple(allow: boolean = true): this {
+		if (this._referenceMeta) {
+			this._referenceMeta.multiple = allow;
+		}
+		return this;
+	}
+
+	/**
+	 * Configure empty state
+	 */
+	emptyState(config: EmptyStateConfig): this {
+		if (this._referenceMeta) {
+			this._referenceMeta.emptyState = config;
+		}
+		return this;
+	}
+
+	/**
+	 * Set UI label
+	 */
+	label(text: string): this {
+		this._uiMeta.label = text;
+		return this;
+	}
+
+	/**
+	 * Set UI description (shown as subtitle)
+	 */
+	description(text: string): this {
+		this._uiMeta.description = text;
+		return this;
+	}
+
+	/**
+	 * Set help text (shown as tooltip or hint)
+	 */
+	helpText(text: string): this {
+		this._uiMeta.helpText = text;
+		return this;
+	}
+
+	/**
+	 * Set placeholder text
+	 */
+	placeholder(text: string): this {
+		this._uiMeta.placeholder = text;
+		if (this._referenceMeta) {
+			this._referenceMeta.placeholder = text;
+		}
+		return this;
+	}
+
+	/**
+	 * Set field order (lower = earlier)
+	 */
+	order(n: number): this {
+		this._uiMeta.order = n;
+		return this;
+	}
+
+	/**
+	 * Set field group for sectioning
+	 */
+	group(id: string): this {
+		this._uiMeta.group = id;
+		return this;
+	}
+
+	/**
+	 * Hide field from UI
+	 */
+	hidden(hide: boolean = true): this {
+		this._uiMeta.hidden = hide;
+		return this;
+	}
+
+	/**
+	 * Mark field as read-only
+	 */
+	readOnly(ro: boolean = true): this {
+		this._uiMeta.readOnly = ro;
+		return this;
+	}
+
+	/**
+	 * Set component type hint
+	 */
+	component(type: NonNullable<UIMeta['component']>): this {
+		this._uiMeta.component = type;
+		return this;
+	}
+
+	/**
+	 * Build the final schema with metadata attached
+	 */
+	build(): T {
+		// Attach metadata to schema using symbols (non-enumerable)
+		Object.defineProperty(this._schema, REFERENCE_META, {
+			value: this._referenceMeta,
+			enumerable: false,
+			writable: false,
+			configurable: true
+		});
+		Object.defineProperty(this._schema, UI_META, {
+			value: this._uiMeta,
+			enumerable: false,
+			writable: false,
+			configurable: true
+		});
+		return this._schema;
+	}
+}
+
+/**
+ * Create a config-aware field builder
+ *
+ * @example
+ * ```typescript
+ * const widgetId = configField(z.string())
+ *   .references('example.widgets')
+ *   .label('Widget')
+ *   .build();
+ * ```
+ */
+export function configField<T extends ZodTypeAny>(schema: T): ConfigFieldBuilder<T> {
+	return new ConfigFieldBuilder(schema);
+}
+
+/**
+ * Extract reference metadata from schema
+ */
+export function getReferenceMeta(schema: ZodTypeAny): ReferenceMeta | undefined {
+	// Cast through unknown to access symbol-keyed metadata
+	const schemaWithMeta = schema as unknown as Record<symbol, unknown>;
+	return schemaWithMeta[REFERENCE_META] as ReferenceMeta | undefined;
+}
+
+/**
+ * Extract UI metadata from schema
+ */
+export function getUIMeta(schema: ZodTypeAny): UIMeta | undefined {
+	// Cast through unknown to access symbol-keyed metadata
+	const schemaWithMeta = schema as unknown as Record<symbol, unknown>;
+	return schemaWithMeta[UI_META] as UIMeta | undefined;
+}
+
+/**
+ * Extract all config field metadata from schema
+ */
+export function getConfigFieldMeta(schema: ZodTypeAny): ConfigFieldMeta {
+	return {
+		referenceMeta: getReferenceMeta(schema),
+		uiMeta: getUIMeta(schema)
+	};
+}
+
+/**
+ * Check if schema has reference metadata
+ */
+export function hasReference(schema: ZodTypeAny): boolean {
+	return getReferenceMeta(schema) !== undefined;
+}
+
+/**
+ * Check if schema has any config field metadata
+ */
+export function hasConfigFieldMeta(schema: ZodTypeAny): boolean {
+	const meta = getConfigFieldMeta(schema);
+	return (
+		meta.referenceMeta !== undefined ||
+		(meta.uiMeta !== undefined && Object.keys(meta.uiMeta).length > 0)
+	);
+}

package/src/schema/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Config Schema Extensions
+ *
+ * Schema-driven references and metadata for config fields.
+ */
+
+// Reference types
+export type {
+	ReferenceSource,
+	ConfigReference,
+	NestedReference,
+	ComputedReference,
+	EnumReference,
+	EmptyStateConfig,
+	ReferenceMeta,
+	ResolvedOption,
+	ResolutionResult,
+	ResolutionContext,
+	ComputedResolverFn
+} from './references.ts';
+
+// Zod extension builder
+export {
+	configField,
+	ConfigFieldBuilder,
+	getReferenceMeta,
+	getUIMeta,
+	getConfigFieldMeta,
+	hasReference,
+	hasConfigFieldMeta,
+	type UIMeta,
+	type ConfigFieldMeta
+} from './extend-zod.ts';
+
+// Option resolver
+export {
+	resolveOptions,
+	resolveOptionsSync,
+	registerResolver,
+	unregisterResolver,
+	getRegisteredResolvers,
+	createResolutionContext,
+	getDependencyFields
+} from './resolver.ts';

package/src/schema/references.ts

@@ -0,0 +1,21 @@
+/**
+ * Config Reference Types
+ *
+ * Defines types for schema-driven references between config entities.
+ * Enables fields to dynamically reference other config collections,
+ * nested data, or computed values.
+ */
+
+export type {
+	ReferenceSource,
+	ConfigReference,
+	NestedReference,
+	ComputedReference,
+	EnumReference,
+	EmptyStateConfig,
+	ReferenceMeta,
+	ResolvedOption,
+	ResolutionResult,
+	ResolutionContext,
+	ComputedResolverFn
+} from './schemas/references.schema.ts';

package/src/schema/resolver.ts

@@ -0,0 +1,343 @@
+/**
+ * Config Reference Option Resolver
+ *
+ * Resolves options for reference fields at runtime by fetching
+ * from config stores, nested data, or computed functions.
+ */
+
+import type {
+	ReferenceMeta,
+	ConfigReference,
+	NestedReference,
+	ComputedReference,
+	ResolvedOption,
+	ResolutionResult,
+	ResolutionContext,
+	ComputedResolverFn
+} from './references.ts';
+
+/**
+ * Registry for computed resolvers
+ */
+const computedResolvers = new Map<string, ComputedResolverFn>();
+
+/**
+ * Register a computed resolver function
+ *
+ * @example
+ * ```typescript
+ * registerResolver('fetchWidgetParts', async (deps, ctx) => {
+ *   const widget = ctx.getConfig<Widget>(`example.widgets.${deps.widgetId}`);
+ *   return widget?.parts?.map(p => ({ value: p.id, label: p.name })) ?? [];
+ * });
+ * ```
+ */
+export function registerResolver(name: string, fn: ComputedResolverFn): void {
+	computedResolvers.set(name, fn);
+}
+
+/**
+ * Unregister a computed resolver
+ */
+export function unregisterResolver(name: string): boolean {
+	return computedResolvers.delete(name);
+}
+
+/**
+ * Get all registered resolver names
+ */
+export function getRegisteredResolvers(): string[] {
+	return Array.from(computedResolvers.keys());
+}
+
+/**
+ * Resolve options for a reference field
+ */
+export async function resolveOptions(
+	meta: ReferenceMeta,
+	context: ResolutionContext
+): Promise<ResolutionResult> {
+	const { source } = meta;
+
+	try {
+		switch (source.type) {
+			case 'config':
+				return resolveConfigReference(source, context);
+
+			case 'nested':
+				return resolveNestedReference(source, context);
+
+			case 'computed':
+				return await resolveComputedReference(source, context);
+
+			case 'enum':
+				return {
+					options: source.values.map((v) => ({
+						value: v.value,
+						label: v.label ?? v.value,
+						description: v.description,
+						icon: v.icon
+					})),
+					isLoading: false,
+					isEmpty: source.values.length === 0
+				};
+
+			default:
+				return { options: [], isLoading: false, isEmpty: true };
+		}
+	} catch (error) {
+		return {
+			options: [],
+			isLoading: false,
+			isEmpty: true,
+			error: error instanceof Error ? error.message : 'Failed to resolve options'
+		};
+	}
+}
+
+/**
+ * Resolve options synchronously (for enum types only, returns empty for async types)
+ */
+export function resolveOptionsSync(
+	meta: ReferenceMeta,
+	context: ResolutionContext
+): ResolutionResult {
+	const { source } = meta;
+
+	if (source.type === 'enum') {
+		return {
+			options: source.values.map((v) => ({
+				value: v.value,
+				label: v.label ?? v.value,
+				description: v.description,
+				icon: v.icon
+			})),
+			isLoading: false,
+			isEmpty: source.values.length === 0
+		};
+	}
+
+	if (source.type === 'config') {
+		return resolveConfigReference(source, context);
+	}
+
+	if (source.type === 'nested') {
+		return resolveNestedReference(source, context);
+	}
+
+	// Computed requires async - return loading state
+	return { options: [], isLoading: true, isEmpty: true };
+}
+
+/**
+ * Resolve config reference - fetches from a config collection
+ */
+function resolveConfigReference(
+	ref: ConfigReference,
+	context: ResolutionContext
+): ResolutionResult {
+	const configData = context.getConfig<Record<string, unknown>>(ref.path);
+
+	if (!configData || typeof configData !== 'object') {
+		return { options: [], isLoading: false, isEmpty: true };
+	}
+
+	// Handle both object (keyed by id) and array formats
+	const items = Array.isArray(configData) ? configData : Object.values(configData);
+	const valueField = ref.valueField ?? 'id';
+	const labelField = ref.labelField ?? 'name';
+
+	let filteredItems = items;
+
+	// Apply filter
+	if (ref.filter) {
+		if (typeof ref.filter === 'string') {
+			filteredItems = items.filter(
+				(item) =>
+					item &&
+					typeof item === 'object' &&
+					(item as Record<string, unknown>)[ref.filter as string]
+			);
+		} else {
+			filteredItems = items.filter(ref.filter);
+		}
+	}
+
+	const options: ResolvedOption[] = filteredItems
+		.filter((item): item is Record<string, unknown> => item !== null && typeof item === 'object')
+		.map((item) => ({
+			value: String(item[valueField] ?? ''),
+			label: String(item[labelField] ?? item[valueField] ?? ''),
+			description: ref.descriptionField ? String(item[ref.descriptionField] ?? '') : undefined,
+			icon: ref.iconField ? String(item[ref.iconField] ?? '') : undefined
+		}))
+		.filter((opt) => opt.value !== ''); // Filter out empty values
+
+	return {
+		options,
+		isLoading: false,
+		isEmpty: options.length === 0
+	};
+}
+
+/**
+ * Resolve nested reference - fetches from nested data within a parent config item
+ */
+function resolveNestedReference(
+	ref: NestedReference,
+	context: ResolutionContext
+): ResolutionResult {
+	// Get the parent field value from form (supports nested paths like 'configuration.providerId')
+	const parentId = getValueAtPath(context.formValues, ref.parentField);
+
+	if (!parentId) {
+		return { options: [], isLoading: false, isEmpty: true };
+	}
+
+	// Get the parent config collection
+	const parentConfig = context.getConfig<Record<string, unknown>>(ref.parentPath);
+
+	if (!parentConfig) {
+		return { options: [], isLoading: false, isEmpty: true };
+	}
+
+	// Find the parent item - handle both keyed object and array formats
+	let parentItem: Record<string, unknown> | undefined;
+
+	if (Array.isArray(parentConfig)) {
+		parentItem = parentConfig.find(
+			(item) =>
+				item && typeof item === 'object' && (item as Record<string, unknown>).id === parentId
+		) as Record<string, unknown> | undefined;
+	} else {
+		parentItem = parentConfig[String(parentId)] as Record<string, unknown> | undefined;
+	}
+
+	if (!parentItem || typeof parentItem !== 'object') {
+		return { options: [], isLoading: false, isEmpty: true };
+	}
+
+	// Navigate to nested path (uses the same path-based access)
+	const nestedData = getValueAtPath(parentItem, ref.nestedPath);
+
+	if (!nestedData) {
+		return { options: [], isLoading: false, isEmpty: true };
+	}
+
+	// Convert to array if needed
+	const items = Array.isArray(nestedData)
+		? nestedData
+		: Object.values(nestedData as Record<string, unknown>);
+
+	const valueField = ref.valueField ?? 'id';
+	const labelField = ref.labelField ?? 'name';
+
+	const options: ResolvedOption[] = items
+		.filter((item): item is Record<string, unknown> => item !== null && typeof item === 'object')
+		.map((item) => ({
+			value: String(item[valueField] ?? ''),
+			label: String(item[labelField] ?? item[valueField] ?? ''),
+			description: ref.descriptionField ? String(item[ref.descriptionField] ?? '') : undefined
+		}))
+		.filter((opt) => opt.value !== '');
+
+	return {
+		options,
+		isLoading: false,
+		isEmpty: options.length === 0
+	};
+}
+
+/**
+ * Resolve computed reference - calls registered resolver function
+ */
+async function resolveComputedReference(
+	ref: ComputedReference,
+	context: ResolutionContext
+): Promise<ResolutionResult> {
+	const resolver = computedResolvers.get(ref.resolver);
+
+	if (!resolver) {
+		return {
+			options: [],
+			isLoading: false,
+			isEmpty: true,
+			error: `Unknown resolver: ${ref.resolver}`
+		};
+	}
+
+	// Collect dependency values (supports nested paths)
+	const deps: Record<string, unknown> = {};
+	for (const field of ref.dependsOn ?? []) {
+		deps[field] = getValueAtPath(context.formValues, field);
+	}
+
+	try {
+		const options = await resolver(deps, context);
+
+		return {
+			options,
+			isLoading: false,
+			isEmpty: options.length === 0
+		};
+	} catch (error) {
+		return {
+			options: [],
+			isLoading: false,
+			isEmpty: true,
+			error: error instanceof Error ? error.message : 'Resolver failed'
+		};
+	}
+}
+
+/**
+ * Get value at path from 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)
+	return path.split('.').reduce<unknown>((acc, key) => {
+		if (acc && typeof acc === 'object') {
+			return (acc as Record<string, unknown>)[key];
+		}
+		return undefined;
+	}, obj);
+}
+
+/**
+ * Create a resolution context from common parameters
+ */
+export function createResolutionContext(
+	getConfig: <T = unknown>(path: string) => T | undefined,
+	formValues: Record<string, unknown>,
+	runtimeContext: Record<string, unknown> = {}
+): ResolutionContext {
+	return {
+		getConfig,
+		formValues,
+		runtimeContext
+	};
+}
+
+/**
+ * Get dependency fields from reference metadata
+ * Useful for determining when to re-resolve options
+ */
+export function getDependencyFields(meta: ReferenceMeta): string[] {
+	const { source } = meta;
+
+	switch (source.type) {
+		case 'nested':
+			return [source.parentField];
+		case 'computed':
+			return source.dependsOn ?? [];
+		default:
+			return [];
+	}
+}

package/src/schema/schemas/extend-zod.schema.ts

@@ -0,0 +1,16 @@
+export interface UIMeta {
+	label?: string;
+	description?: string;
+	helpText?: string;
+	placeholder?: string;
+	order?: number;
+	group?: string;
+	hidden?: boolean;
+	readOnly?: boolean;
+	component?: 'input' | 'textarea' | 'select' | 'checkbox' | 'radio-group' | 'number' | 'password' | 'code' | 'json';
+}
+
+export interface ConfigFieldMeta {
+	referenceMeta?: unknown;
+	uiMeta?: UIMeta;
+}