@vibesdotdev/config 0.0.1

package/src/loader/validation.ts

@@ -0,0 +1,261 @@
+/**
+ * Per-Field Config Validation
+ *
+ * Validates config data field-by-field, keeping valid fields and
+ * discarding invalid ones. This allows multi-source configs to
+ * gracefully merge even when individual sources have invalid fields.
+ *
+ * @example
+ * ```ts
+ * // Project config has invalid toolApprovalMode
+ * const projectData = { name: 'Dev', toolApprovalMode: 'invalid', agentId: 'agent-1' };
+ * const { valid, issues } = validateFieldsGracefully(ChatModeRecordSchema, projectData);
+ * // valid = { name: 'Dev', agentId: 'agent-1' }
+ * // issues = [{ path: ['toolApprovalMode'], message: '...' }]
+ *
+ * // User config has valid toolApprovalMode
+ * const userData = { toolApprovalMode: 'auto-approve-safe' };
+ * const merged = deepMerge(valid, userData);
+ * // merged = { name: 'Dev', toolApprovalMode: 'auto-approve-safe', agentId: 'agent-1' }
+ * ```
+ */
+
+import type { z } from 'zod/v4';
+
+import type { FieldValidationIssue, FieldValidationResult, RecordValidationResult } from './schemas/validation.schema.ts';
+
+export type { FieldValidationIssue, FieldValidationResult, RecordValidationResult } from './schemas/validation.schema.ts';
+
+/**
+ * Check if a Zod schema is an object schema
+ */
+function isZodObject(schema: z.ZodType): schema is z.ZodObject<z.ZodRawShape> {
+	return schema._zod?.def?.type === 'object';
+}
+
+/**
+ * Check if a Zod schema is a record schema
+ */
+function isZodRecord(schema: z.ZodType): schema is z.ZodRecord {
+	return schema._zod?.def?.type === 'record';
+}
+
+/**
+ * Get the shape (field schemas) from a Zod object schema
+ */
+function getObjectShape(schema: z.ZodObject<z.ZodRawShape>): Record<string, z.ZodType> {
+	// Access shape from v4 internal structure or fallback to direct property
+	// Cast through unknown to handle Zod v4's readonly shape type
+	const schemaAny = schema as unknown as {
+		_zod?: { def?: { shape?: Record<string, z.ZodType> } };
+		shape?: Record<string, z.ZodType>;
+	};
+	const shape = schemaAny._zod?.def?.shape ?? schemaAny.shape ?? {};
+	return shape;
+}
+
+/**
+ * Get the value schema from a Zod record schema
+ */
+function getRecordValueSchema(schema: z.ZodRecord): z.ZodType {
+	// Access valueType from v4 internal structure
+	const valueType =
+		schema._zod?.def?.valueType ??
+		(schema as unknown as { _def?: { valueType?: z.ZodType } })._def?.valueType;
+	return valueType as z.ZodType;
+}
+
+/**
+ * Validate data field-by-field against a Zod object schema.
+ * Returns only the fields that pass validation.
+ *
+ * @param schema - Zod object schema
+ * @param data - Data to validate
+ * @param basePath - Base path for error reporting (used in recursion)
+ */
+export function validateFieldsGracefully<T extends Record<string, unknown>>(
+	schema: z.ZodObject<z.ZodRawShape>,
+	data: unknown,
+	basePath: (string | number)[] = []
+): FieldValidationResult<T> {
+	const valid: Record<string, unknown> = {};
+	const issues: FieldValidationIssue[] = [];
+
+	// Handle non-object data
+	if (typeof data !== 'object' || data === null) {
+		return { valid: valid as Partial<T>, issues, hasIssues: false };
+	}
+
+	const shape = getObjectShape(schema);
+	const dataObj = data as Record<string, unknown>;
+
+	for (const [key, fieldSchema] of Object.entries(shape)) {
+		if (!(key in dataObj)) {
+			continue; // Field not present, skip (defaults will fill in later)
+		}
+
+		const fieldValue = dataObj[key];
+		const fieldPath = [...basePath, key];
+
+		// Try to validate this field
+		const result = fieldSchema.safeParse(fieldValue);
+
+		if (result.success) {
+			valid[key] = result.data;
+		} else if (isZodObject(fieldSchema) && typeof fieldValue === 'object' && fieldValue !== null) {
+			// Recurse into nested object
+			const nestedResult = validateFieldsGracefully(fieldSchema, fieldValue, fieldPath);
+			if (Object.keys(nestedResult.valid).length > 0) {
+				valid[key] = nestedResult.valid;
+			}
+			issues.push(...nestedResult.issues);
+		} else {
+			// Record the issue
+			const issue = result.error.issues[0];
+			// In Zod v4, enum errors use 'invalid_value' code
+			const isEnumError = issue?.code === 'invalid_value' && 'options' in (issue ?? {});
+			issues.push({
+				path: fieldPath,
+				message: issue?.message ?? 'Invalid value',
+				invalidValue: fieldValue,
+				expected: isEnumError
+					? `one of: ${(issue as { options?: unknown[] }).options?.join(', ')}`
+					: undefined
+			});
+		}
+	}
+
+	return {
+		valid: valid as Partial<T>,
+		issues,
+		hasIssues: issues.length > 0
+	};
+}
+
+/**
+ * Validate a record (Record<string, T>) schema field-by-field per record.
+ * Each record is validated independently, and invalid fields within
+ * each record are discarded while keeping valid ones.
+ *
+ * @param schema - Zod record schema
+ * @param data - Data to validate
+ */
+export function validateRecordsGracefully<T extends Record<string, unknown>>(
+	schema: z.ZodRecord,
+	data: unknown
+): RecordValidationResult<T> {
+	const valid: Record<string, Partial<T>> = {};
+	const issues = new Map<string, FieldValidationIssue[]>();
+
+	// Handle non-object data
+	if (typeof data !== 'object' || data === null) {
+		return { valid, issues, hasIssues: false };
+	}
+
+	const valueSchema = getRecordValueSchema(schema);
+	const dataObj = data as Record<string, unknown>;
+
+	for (const [recordId, recordData] of Object.entries(dataObj)) {
+		if (isZodObject(valueSchema)) {
+			// Validate each record field-by-field
+			const recordResult = validateFieldsGracefully<T>(valueSchema, recordData, [recordId]);
+
+			// Include record if it has any valid fields
+			if (Object.keys(recordResult.valid).length > 0) {
+				valid[recordId] = recordResult.valid;
+			}
+
+			if (recordResult.hasIssues) {
+				issues.set(recordId, recordResult.issues);
+			}
+		} else {
+			// Non-object value schema - validate whole record
+			const result = valueSchema.safeParse(recordData);
+			if (result.success) {
+				valid[recordId] = result.data as Partial<T>;
+			} else {
+				issues.set(
+					recordId,
+					result.error.issues.map((i) => ({
+						path: [recordId, ...i.path.filter((p): p is string | number => typeof p !== 'symbol')],
+						message: i.message,
+						invalidValue: recordData
+					}))
+				);
+			}
+		}
+	}
+
+	return {
+		valid,
+		issues,
+		hasIssues: issues.size > 0
+	};
+}
+
+/**
+ * Validate data gracefully based on schema type.
+ * Automatically detects object vs record schemas.
+ *
+ * @param schema - Zod schema (object or record)
+ * @param data - Data to validate
+ */
+export function validateGracefully<T>(
+	schema: z.ZodType<T>,
+	data: unknown
+): { valid: Partial<T>; issues: FieldValidationIssue[]; hasIssues: boolean } {
+	if (isZodRecord(schema)) {
+		const result = validateRecordsGracefully(schema, data);
+		// Flatten issues from Map to array
+		const flatIssues: FieldValidationIssue[] = [];
+		for (const recordIssues of result.issues.values()) {
+			flatIssues.push(...recordIssues);
+		}
+		return {
+			valid: result.valid as Partial<T>,
+			issues: flatIssues,
+			hasIssues: result.hasIssues
+		};
+	}
+
+	if (isZodObject(schema)) {
+		const result = validateFieldsGracefully<T & Record<string, unknown>>(schema, data);
+		return {
+			valid: result.valid as Partial<T>,
+			issues: result.issues,
+			hasIssues: result.hasIssues
+		};
+	}
+
+	// For non-object schemas, just do standard validation
+	const result = schema.safeParse(data);
+	if (result.success) {
+		return { valid: result.data as Partial<T>, issues: [], hasIssues: false };
+	}
+
+	return {
+		valid: {} as Partial<T>,
+		issues: result.error.issues.map((i) => ({
+			path: i.path.filter((p): p is string | number => typeof p !== 'symbol'),
+			message: i.message,
+			invalidValue: data
+		})),
+		hasIssues: true
+	};
+}
+
+/**
+ * Format validation issues for logging/display
+ */
+export function formatValidationIssues(issues: FieldValidationIssue[], source?: string): string {
+	if (issues.length === 0) return '';
+
+	const lines = issues.map((issue) => {
+		const path = issue.path.join('.');
+		const expected = issue.expected ? ` (expected ${issue.expected})` : '';
+		return `  - ${path}: ${issue.message}${expected}`;
+	});
+
+	const header = source ? `Validation issues in ${source}:` : 'Validation issues:';
+	return [header, ...lines].join('\n');
+}

package/src/manifest/builder.ts

@@ -0,0 +1,452 @@
+/**
+ * Configuration Manifest Builder
+ *
+ * Factory functions for creating configuration manifests with type safety.
+ */
+
+import type { z } from 'zod/v4';
+import type {
+	ConfigManifest,
+	ConfigFieldMeta,
+	ConfigFieldGroup,
+	ConfigTier,
+	ManifestStorage,
+	ManifestContext,
+	ManifestNavigation,
+	ConfigContext,
+	FieldUI,
+	FieldOption,
+	FieldDefaults,
+	FieldRules,
+	HardwareContext,
+	EnvironmentContext,
+	ConfigSurface
+} from './types.ts';
+import type { CreateManifestOptions } from './schemas/builder.schema.ts';
+
+// Manifest Builder
+
+export type { CreateManifestOptions };
+
+/**
+ * Create a configuration manifest
+ *
+ * @example
+ * ```typescript
+ * const aiConfigManifest = createConfigManifest({
+ *   id: 'ai',
+ *   name: 'AI Settings',
+ *   tier: 'user',
+ *   schema: aiConfigSchema,
+ *   storage: {
+ *     adapter: 'json',
+ *     scope: 'global',
+ *     namespace: 'ai'
+ *   }
+ * })
+ *   .group({ id: 'connection', label: 'Connection Settings', order: 1 })
+ *   .field('connectionMode', {
+ *     ui: { label: 'Connection Mode', component: 'radio-group', group: 'connection' },
+ *     options: [
+ *       { value: 'local-first', label: 'Local First', icon: '🔄' },
+ *       { value: 'local-only', label: 'Local Only', icon: '💻' },
+ *       { value: 'cloud', label: 'Cloud', icon: '☁️' }
+ *     ]
+ *   })
+ *   .build();
+ * ```
+ */
+export function createConfigManifest<T extends z.ZodTypeAny>(
+	options: CreateManifestOptions<T>
+): ManifestBuilder<T> {
+	return new ManifestBuilder(options);
+}
+
+/**
+ * Builder class for fluent manifest construction
+ */
+export class ManifestBuilder<T extends z.ZodTypeAny> {
+	private readonly options: CreateManifestOptions<T>;
+	private readonly _fields: Map<string, ConfigFieldMeta> = new Map();
+	private readonly _groups: ConfigFieldGroup[] = [];
+
+	constructor(options: CreateManifestOptions<T>) {
+		this.options = options;
+	}
+
+	/**
+	 * Add a field group
+	 */
+	group(group: ConfigFieldGroup): this {
+		this._groups.push(group);
+		return this;
+	}
+
+	/**
+	 * Add multiple field groups
+	 */
+	groups(groups: ConfigFieldGroup[]): this {
+		this._groups.push(...groups);
+		return this;
+	}
+
+	/**
+	 * Add a field with metadata
+	 */
+	field(path: string, meta: ConfigFieldMeta): this {
+		this._fields.set(path, meta);
+		return this;
+	}
+
+	/**
+	 * Add multiple fields
+	 */
+	fields(fields: Record<string, ConfigFieldMeta>): this {
+		for (const [path, meta] of Object.entries(fields)) {
+			this._fields.set(path, meta);
+		}
+		return this;
+	}
+
+	/**
+	 * Build the final manifest
+	 */
+	build(): ConfigManifest<T> {
+		const fields: Record<string, ConfigFieldMeta> = {};
+		for (const [path, meta] of this._fields) {
+			fields[path] = meta;
+		}
+
+		return {
+			id: this.options.id,
+			name: this.options.name,
+			description: this.options.description,
+			icon: this.options.icon,
+			version: this.options.version,
+			tier: this.options.tier,
+			category: this.options.category,
+			schema: this.options.schema,
+			fields,
+			groups: this._groups.length > 0 ? this._groups : undefined,
+			storage: this.options.storage,
+			context: this.options.context,
+			navigation: this.options.navigation,
+			onLoad: this.options.onLoad,
+			onSave: this.options.onSave,
+			onFieldChange: this.options.onFieldChange
+		};
+	}
+}
+
+// Field Builder Helpers
+
+/**
+ * Create field metadata for a simple input field
+ */
+export function inputField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta {
+	const { ui: uiOptions, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: 'input',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+/**
+ * Create field metadata for a textarea field
+ */
+export function textareaField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta {
+	const { ui: uiOptions, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: 'textarea',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+/**
+ * Create field metadata for a number field
+ */
+export function numberField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta {
+	const { ui: uiOptions, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: 'number',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+/**
+ * Create field metadata for a boolean switch/checkbox field
+ */
+export function booleanField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & {
+		ui?: Partial<FieldUI>;
+		asCheckbox?: boolean;
+	}
+): ConfigFieldMeta {
+	const { ui: uiOptions, asCheckbox, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: asCheckbox ? 'checkbox' : 'switch',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+/**
+ * Create field metadata for a select field
+ * Supports two signatures:
+ * 1. selectField(label, optionsArray, config?) - options as array
+ * 2. selectField(label, configWithOptions) - options nested in config
+ */
+export function selectField<T extends string>(
+	label: string,
+	fieldOptionsOrConfig:
+		| FieldOption<T>[]
+		| (Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI>; options: FieldOption<T>[] }),
+	options?: Partial<Omit<ConfigFieldMeta, 'ui' | 'options'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta<T> {
+	// Handle both signatures
+	if (Array.isArray(fieldOptionsOrConfig)) {
+		// Signature 1: selectField(label, optionsArray, config?)
+		const { ui: uiOptions, ...rest } = options ?? {};
+		return {
+			ui: {
+				label,
+				component: 'select',
+				...uiOptions
+			},
+			options: fieldOptionsOrConfig as FieldOption<T>[],
+			...rest
+		} as ConfigFieldMeta<T>;
+	} else {
+		// Signature 2: selectField(label, configWithOptions)
+		const { ui: uiOptions, options: fieldOptions, ...rest } = fieldOptionsOrConfig;
+		return {
+			ui: {
+				label,
+				component: 'select',
+				...uiOptions
+			},
+			options: fieldOptions as FieldOption<T>[],
+			...rest
+		} as ConfigFieldMeta<T>;
+	}
+}
+
+/**
+ * Create field metadata for a radio group field
+ * Supports two signatures:
+ * 1. radioField(label, optionsArray, config?) - options as array
+ * 2. radioField(label, configWithOptions) - options nested in config
+ */
+export function radioField<T extends string>(
+	label: string,
+	fieldOptionsOrConfig:
+		| FieldOption<T>[]
+		| (Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI>; options: FieldOption<T>[] }),
+	options?: Partial<Omit<ConfigFieldMeta, 'ui' | 'options'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta<T> {
+	// Handle both signatures
+	if (Array.isArray(fieldOptionsOrConfig)) {
+		// Signature 1: radioField(label, optionsArray, config?)
+		const { ui: uiOptions, ...rest } = options ?? {};
+		return {
+			ui: {
+				label,
+				component: 'radio-group',
+				...uiOptions
+			},
+			options: fieldOptionsOrConfig as FieldOption<T>[],
+			...rest
+		} as ConfigFieldMeta<T>;
+	} else {
+		// Signature 2: radioField(label, configWithOptions)
+		const { ui: uiOptions, options: fieldOptions, ...rest } = fieldOptionsOrConfig;
+		return {
+			ui: {
+				label,
+				component: 'radio-group',
+				...uiOptions
+			},
+			options: fieldOptions as FieldOption<T>[],
+			...rest
+		} as ConfigFieldMeta<T>;
+	}
+}
+
+/**
+ * Create field metadata for a slider field
+ */
+export function sliderField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta {
+	const { ui: uiOptions, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: 'slider',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+/**
+ * Create field metadata for a secret/password field
+ */
+export function secretField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta {
+	const { ui: uiOptions, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: 'secret',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+/**
+ * Create field metadata for a JSON editor field
+ */
+export function jsonField(
+	label: string,
+	options?: Partial<Omit<ConfigFieldMeta, 'ui'>> & { ui?: Partial<FieldUI> }
+): ConfigFieldMeta {
+	const { ui: uiOptions, ...rest } = options ?? {};
+	return {
+		ui: {
+			label,
+			component: 'json',
+			...uiOptions
+		},
+		...rest
+	};
+}
+
+// Options Builder Helpers
+
+/**
+ * Create an option for enum/select fields
+ */
+export function option<T extends string>(
+	value: T,
+	label: string,
+	extras?: Omit<FieldOption<T>, 'value' | 'label'>
+): FieldOption<T> {
+	return {
+		value,
+		label,
+		...extras
+	};
+}
+
+/**
+ * Create options from an enum-like object
+ */
+export function optionsFromEnum<T extends string>(
+	enumObj: Record<T, string>,
+	metadata?: Partial<Record<T, Omit<FieldOption<T>, 'value' | 'label'>>>
+): FieldOption<T>[] {
+	return Object.entries(enumObj).map(([value, label]) => ({
+		value: value as T,
+		label: label as string,
+		...metadata?.[value as T]
+	}));
+}
+
+// Defaults Builder Helpers
+
+/**
+ * Create context-aware defaults
+ */
+export function defaults<T>(
+	base: T,
+	overrides?: {
+		byHardware?: Partial<Record<HardwareContext, T>>;
+		byEnvironment?: Partial<Record<EnvironmentContext, T>>;
+		bySurface?: Partial<Record<ConfigSurface, T>>;
+		resolver?: (ctx: ConfigContext) => T;
+	}
+): FieldDefaults<T> {
+	return {
+		base,
+		...overrides
+	};
+}
+
+// Rules Builder Helpers
+
+/**
+ * Create a field-based rule
+ */
+export function whenField(
+	field: string,
+	operator: 'equals' | 'notEquals' | 'in' | 'notIn' | 'exists' | 'isEmpty',
+	value?: unknown
+): FieldRules['visibleWhen'] {
+	return { field, operator, value };
+}
+
+/**
+ * Create a context-based rule
+ */
+export function whenContext(
+	context: keyof Omit<ConfigContext, 'get' | 'custom'> | `custom.${string}`,
+	operator: 'equals' | 'notEquals' | 'in' | 'notIn' | 'exists',
+	value?: unknown
+): FieldRules['visibleWhen'] {
+	return { context, operator, value };
+}
+
+/**
+ * Combine rules with AND
+ */
+export function allOf(
+	...rules: NonNullable<FieldRules['visibleWhen']>[]
+): FieldRules['visibleWhen'] {
+	return { and: rules };
+}
+
+/**
+ * Combine rules with OR
+ */
+export function anyOf(
+	...rules: NonNullable<FieldRules['visibleWhen']>[]
+): FieldRules['visibleWhen'] {
+	return { or: rules };
+}
+
+/**
+ * Negate a rule
+ */
+export function not(rule: NonNullable<FieldRules['visibleWhen']>): FieldRules['visibleWhen'] {
+	return { not: rule };
+}