@vibesdotdev/config 0.0.1

package/src/loader/merge.ts

@@ -0,0 +1,366 @@
+/**
+ * Config Merge Utilities
+ *
+ * Deep merge configs with priority handling.
+ * Higher priority sources override lower priority ones.
+ *
+ * Supports graceful validation where invalid fields are discarded
+ * per-source, allowing valid fields from lower-priority sources
+ * to fill in gaps.
+ */
+
+import type { z } from 'zod/v4';
+import { type LoadedConfigSource, CONFIG_PRIORITIES } from './types.ts';
+import {
+	validateGracefully,
+	formatValidationIssues,
+	type FieldValidationIssue
+} from './validation.ts';
+
+/**
+ * Check if value is a plain object (not array, null, Date, etc.)
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== 'object' || value === null) return false;
+	if (Array.isArray(value)) return false;
+	if (value instanceof Date) return false;
+	if (value instanceof RegExp) return false;
+	if (value instanceof Map || value instanceof Set) return false;
+	return Object.getPrototypeOf(value) === Object.prototype;
+}
+
+/**
+ * Deep merge two objects
+ * Source values override target values.
+ * Both plain objects are merged recursively.
+ * Arrays are replaced, not merged.
+ */
+export function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+	const result = { ...target };
+
+	for (const key in source) {
+		const sourceValue = source[key];
+		const targetValue = result[key];
+
+		if (sourceValue === undefined) {
+			continue;
+		}
+
+		// Both are plain objects - merge recursively
+		if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+			result[key] = deepMerge(
+				targetValue as Record<string, unknown>,
+				sourceValue as Record<string, unknown>
+			) as T[Extract<keyof T, string>];
+		} else {
+			// Override with source value
+			result[key] = sourceValue as T[Extract<keyof T, string>];
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Merge multiple config sources in priority order
+ *
+ * Sources with lower priority are merged first, so higher priority
+ * sources override them.
+ *
+ * @param sources - Array of loaded config sources
+ * @returns Merged config object
+ */
+export function mergeConfigSources<T extends Record<string, unknown>>(
+	sources: LoadedConfigSource<T>[]
+): T {
+	// Sort by priority (lowest first)
+	const sorted = [...sources]
+		.filter((s) => s.loaded && s.data !== null && s.data !== undefined)
+		.sort((a, b) => a.priority - b.priority);
+
+	if (sorted.length === 0) {
+		return {} as T;
+	}
+
+	// Start with empty object and merge each source
+	let result = {} as T;
+	for (const source of sorted) {
+		if (isPlainObject(source.data)) {
+			result = deepMerge(result, source.data as Partial<T>);
+		} else {
+			// Non-object data - just use it directly
+			result = source.data;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Merge configs for record-type manifests
+ *
+ * For record manifests, we merge by record ID.
+ * Later sources can override or add records.
+ */
+export function mergeRecordConfigs<T extends { id: string }>(
+	sources: LoadedConfigSource<Record<string, T> | T[]>[]
+): Record<string, T> {
+	const sorted = [...sources]
+		.filter((s) => s.loaded && s.data !== null && s.data !== undefined)
+		.sort((a, b) => a.priority - b.priority);
+
+	const result: Record<string, T> = {};
+
+	for (const source of sorted) {
+		const data = source.data;
+
+		if (Array.isArray(data)) {
+			// Array of records - merge by ID
+			for (const record of data) {
+				if (record && typeof record === 'object' && 'id' in record) {
+					const existing = result[record.id];
+					if (existing && isPlainObject(existing) && isPlainObject(record)) {
+						result[record.id] = deepMerge(existing, record) as T;
+					} else {
+						result[record.id] = record;
+					}
+				}
+			}
+		} else if (isPlainObject(data)) {
+			// Object keyed by ID
+			for (const [id, record] of Object.entries(data)) {
+				if (record && typeof record === 'object') {
+					const existing = result[id];
+					if (existing && isPlainObject(existing) && isPlainObject(record)) {
+						result[id] = deepMerge(existing, record as Partial<T>) as T;
+					} else {
+						result[id] = { ...record, id } as T;
+					}
+				}
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Create a defaults source from schema defaults or provided defaults
+ * Accepts Partial<T> since defaults don't need to be complete
+ */
+export function createDefaultsSource<T>(defaults: Partial<T>): LoadedConfigSource<T> {
+	return {
+		source: 'defaults',
+		scope: 'defaults',
+		priority: CONFIG_PRIORITIES.DEFAULTS,
+		data: defaults as T, // Defaults are merged with other sources
+		loaded: true
+	};
+}
+
+/**
+ * Create a storage source from adapter data
+ */
+export function createStorageSource<T>(data: T | null): LoadedConfigSource<T> | null {
+	if (data === null || data === undefined) {
+		return null;
+	}
+
+	return {
+		source: 'storage',
+		scope: 'storage',
+		priority: CONFIG_PRIORITIES.STORAGE,
+		data,
+		loaded: true
+	};
+}
+
+// Validated Merge Functions
+
+import type { ValidatedMergeResult } from './schemas/merge.schema.ts';
+
+export type { ValidatedMergeResult } from './schemas/merge.schema.ts';
+
+/**
+ * Merge config sources with per-field validation.
+ *
+ * Each source's data is validated field-by-field against the schema.
+ * Invalid fields are discarded, allowing valid fields from lower-priority
+ * sources to be used instead.
+ *
+ * @example
+ * ```ts
+ * // Project config has invalid toolApprovalMode
+ * const projectSource = { data: { name: 'Dev', toolApprovalMode: 'invalid' }, priority: 3 };
+ * // User config has valid toolApprovalMode
+ * const userSource = { data: { toolApprovalMode: 'auto-approve-safe' }, priority: 1 };
+ *
+ * const result = mergeConfigSourcesWithValidation([projectSource, userSource], schema);
+ * // result.data = { name: 'Dev', toolApprovalMode: 'auto-approve-safe' }
+ * // result.issues = Map { 'project' => [{ path: ['toolApprovalMode'], ... }] }
+ * ```
+ */
+export function mergeConfigSourcesWithValidation<T extends Record<string, unknown>>(
+	sources: LoadedConfigSource<T>[],
+	schema: z.ZodType<T>,
+	options?: {
+		/** Whether to log validation issues */
+		logIssues?: boolean;
+		/** Custom logger */
+		logger?: (message: string) => void;
+	}
+): ValidatedMergeResult<T> {
+	const { logIssues = false, logger = console.warn } = options ?? {};
+
+	// Sort by priority (lowest first - will be overridden by higher)
+	const sorted = [...sources]
+		.filter((s) => s.loaded && s.data !== null && s.data !== undefined)
+		.sort((a, b) => a.priority - b.priority);
+
+	if (sorted.length === 0) {
+		return {
+			data: {} as T,
+			issues: new Map(),
+			hasIssues: false,
+			contributingSources: []
+		};
+	}
+
+	const allIssues = new Map<string, FieldValidationIssue[]>();
+	const contributingSources: string[] = [];
+
+	// Validate and merge each source
+	let result = {} as T;
+	for (const source of sorted) {
+		if (!isPlainObject(source.data)) {
+			// Non-object data - validate whole thing
+			const validation = validateGracefully(schema, source.data);
+			if (validation.hasIssues) {
+				allIssues.set(source.source, validation.issues);
+				if (logIssues) {
+					logger(formatValidationIssues(validation.issues, source.source));
+				}
+			}
+			if (Object.keys(validation.valid).length > 0) {
+				result = validation.valid as T;
+				contributingSources.push(source.source);
+			}
+			continue;
+		}
+
+		// Validate per-field
+		const validation = validateGracefully(schema, source.data);
+
+		if (validation.hasIssues) {
+			allIssues.set(source.source, validation.issues);
+			if (logIssues) {
+				logger(formatValidationIssues(validation.issues, source.source));
+			}
+		}
+
+		// Merge valid fields (higher priority overrides lower)
+		if (Object.keys(validation.valid).length > 0) {
+			result = deepMerge(result, validation.valid as Partial<T>);
+			contributingSources.push(source.source);
+		}
+	}
+
+	return {
+		data: result,
+		issues: allIssues,
+		hasIssues: allIssues.size > 0,
+		contributingSources
+	};
+}
+
+/**
+ * Merge record configs with per-record, per-field validation.
+ *
+ * Each record in each source is validated field-by-field.
+ * Invalid fields are discarded, allowing valid fields from
+ * lower-priority sources to fill in.
+ */
+export function mergeRecordConfigsWithValidation<T extends { id: string }>(
+	sources: LoadedConfigSource<Record<string, T> | T[]>[],
+	recordSchema: z.ZodType<T>,
+	options?: {
+		logIssues?: boolean;
+		logger?: (message: string) => void;
+	}
+): ValidatedMergeResult<Record<string, T>> {
+	const { logIssues = false, logger = console.warn } = options ?? {};
+
+	const sorted = [...sources]
+		.filter((s) => s.loaded && s.data !== null && s.data !== undefined)
+		.sort((a, b) => a.priority - b.priority);
+
+	const result: Record<string, Partial<T>> = {};
+	const allIssues = new Map<string, FieldValidationIssue[]>();
+	const contributingSources: string[] = [];
+
+	for (const source of sorted) {
+		const data = source.data;
+		const sourceIssues: FieldValidationIssue[] = [];
+		let contributed = false;
+
+		// Normalize to record format
+		let records: Record<string, unknown>;
+		if (Array.isArray(data)) {
+			records = {};
+			for (const item of data) {
+				if (item && typeof item === 'object' && 'id' in item) {
+					records[(item as { id: string }).id] = item;
+				}
+			}
+		} else if (isPlainObject(data)) {
+			records = data;
+		} else {
+			continue;
+		}
+
+		// Validate and merge each record
+		for (const [id, record] of Object.entries(records)) {
+			if (!record || typeof record !== 'object') continue;
+
+			const validation = validateGracefully(recordSchema, record);
+
+			if (validation.hasIssues) {
+				// Prefix issues with record ID
+				sourceIssues.push(
+					...validation.issues.map((issue) => ({
+						...issue,
+						path: [id, ...issue.path]
+					}))
+				);
+			}
+
+			// Merge valid fields into this record
+			if (Object.keys(validation.valid).length > 0) {
+				const existing = result[id] ?? {};
+				result[id] = deepMerge(
+					existing as Record<string, unknown>,
+					{ ...validation.valid, id } as Record<string, unknown>
+				) as Partial<T>;
+				contributed = true;
+			}
+		}
+
+		if (sourceIssues.length > 0) {
+			allIssues.set(source.source, sourceIssues);
+			if (logIssues) {
+				logger(formatValidationIssues(sourceIssues, source.source));
+			}
+		}
+
+		if (contributed) {
+			contributingSources.push(source.source);
+		}
+	}
+
+	return {
+		data: result as Record<string, T>,
+		issues: allIssues,
+		hasIssues: allIssues.size > 0,
+		contributingSources
+	};
+}

package/src/loader/schemas/merge.schema.ts

@@ -0,0 +1,8 @@
+import type { FieldValidationIssue } from './validation.schema.ts';
+
+export interface ValidatedMergeResult<T> {
+	data: T;
+	issues: Map<string, FieldValidationIssue[]>;
+	hasIssues: boolean;
+	contributingSources: string[];
+}

package/src/loader/schemas/validation.schema.ts

@@ -0,0 +1,18 @@
+export interface FieldValidationIssue {
+	path: (string | number)[];
+	message: string;
+	invalidValue?: unknown;
+	expected?: string;
+}
+
+export interface FieldValidationResult<T> {
+	valid: Partial<T>;
+	issues: FieldValidationIssue[];
+	hasIssues: boolean;
+}
+
+export interface RecordValidationResult<T> {
+	valid: Record<string, Partial<T>>;
+	issues: Map<string, FieldValidationIssue[]>;
+	hasIssues: boolean;
+}

package/src/loader/server.ts

@@ -0,0 +1,15 @@
+export type {
+	ConfigLoadResult as ServerConfigLoadResult,
+	DiscoveredConfigFile,
+	DiscoveryOptions,
+	LoadOptions as ServerLoadOptions,
+	LoadedConfigSource as ServerLoadedConfigSource
+} from './index.server.ts';
+export {
+	loadConfigFromManifest as serverLoadConfigFromManifest,
+	loadRecordConfigFromManifest as serverLoadRecordConfigFromManifest,
+	hasConfigFiles,
+	getConfigLoadDebugInfo,
+	discoverConfigFiles,
+	loadConfigFromPath
+} from './index.server.ts';

package/src/loader/types.ts

@@ -0,0 +1,142 @@
+/**
+ * Config File Loader Types
+ *
+ * Types for the multi-source config file loading system.
+ */
+
+import type { ConfigManifest } from '../manifest/types.ts';
+
+/**
+ * Supported config file formats
+ */
+export type ConfigFileFormat = 'ts' | 'js' | 'json' | 'jsonc' | 'yaml';
+
+/**
+ * Config file scope (determines search paths)
+ */
+export type ConfigFileScope = 'global' | 'local' | 'project';
+
+/**
+ * Priority levels for config sources
+ * Higher number = higher priority (wins in merge)
+ */
+export const CONFIG_PRIORITIES = {
+	/** Schema defaults */
+	DEFAULTS: 0,
+	/** Global: ~/.vibes/{namespace}.* */
+	GLOBAL: 1,
+	/** Local: ./.vibes/{namespace}.* */
+	LOCAL: 2,
+	/** Project: ./vibes.{namespace}.* */
+	PROJECT: 3,
+	/** Storage adapter (localdb/json) - user edits */
+	STORAGE: 4,
+	/** CLI overrides */
+	CLI: 5
+} as const;
+
+export type ConfigPriority = (typeof CONFIG_PRIORITIES)[keyof typeof CONFIG_PRIORITIES];
+
+/**
+ * A discovered config file
+ */
+export interface DiscoveredConfigFile {
+	/** Absolute path to the file */
+	path: string;
+	/** File format */
+	format: ConfigFileFormat;
+	/** Scope this file belongs to */
+	scope: ConfigFileScope;
+	/** Priority for merging */
+	priority: ConfigPriority;
+	/** Whether the file exists */
+	exists: boolean;
+}
+
+/**
+ * A loaded config source
+ */
+export interface LoadedConfigSource<T = unknown> {
+	/** Source identifier (file path or 'storage' or 'defaults') */
+	source: string;
+	/** Scope */
+	scope: ConfigFileScope | 'storage' | 'defaults';
+	/** Priority used for merging */
+	priority: ConfigPriority;
+	/** The loaded data */
+	data: T;
+	/** Format that was loaded */
+	format?: ConfigFileFormat;
+	/** Whether this source was successfully loaded */
+	loaded: boolean;
+	/** Error if loading failed */
+	error?: string;
+}
+
+/**
+ * Result of loading config from all sources
+ */
+export interface ConfigLoadResult<T = unknown> {
+	/** Merged configuration data */
+	data: T;
+	/** All sources that were checked/loaded */
+	sources: LoadedConfigSource<T>[];
+	/** Sources that were successfully loaded and merged */
+	mergedSources: LoadedConfigSource<T>[];
+	/** Whether any file sources were found */
+	hasFileSources: boolean;
+	/** Whether storage had data */
+	hasStorageData: boolean;
+	/** Validation issues found when using graceful validation (by source) */
+	validationIssues?: Map<string, { path: (string | number)[]; message: string }[]>;
+}
+
+/**
+ * Options for discovering config files
+ */
+export interface DiscoveryOptions {
+	/** Namespace for the config (e.g., 'autoloop', 'ai', 'pm') */
+	namespace: string;
+	/** Scopes to search */
+	scopes?: ConfigFileScope[];
+	/** Custom patterns to search (in addition to defaults) */
+	patterns?: string[];
+	/** Fallback patterns if primary not found */
+	fallbackPatterns?: string[];
+	/** Working directory (defaults to process.cwd()) */
+	cwd?: string;
+}
+
+/**
+ * Options for loading config
+ */
+export interface LoadOptions<T = unknown> {
+	/** The manifest to load config for */
+	manifest: ConfigManifest;
+	/** Working directory */
+	cwd?: string;
+	/** Whether to include storage adapter data */
+	includeStorage?: boolean;
+	/** Whether to include defaults */
+	includeDefaults?: boolean;
+	/** Custom default values */
+	defaults?: Partial<T>;
+	/** Storage adapter to use (if not using manifest's storage config) */
+	storageAdapter?: {
+		load(): Promise<T | null>;
+	};
+	/**
+	 * Enable graceful per-field validation.
+	 * Invalid fields are discarded instead of failing the entire load.
+	 * This allows valid fields from lower-priority sources to fill in.
+	 */
+	validateGracefully?: boolean;
+	/**
+	 * Callback when validation issues are found.
+	 * Called with the source name and list of issues.
+	 */
+	onValidationIssues?: (
+		source: string,
+		issues: { path: (string | number)[]; message: string }[]
+	) => void;
+}