@vibesdotdev/config 0.0.1

package/src/docs/validation.docs.descriptor.ts

@@ -0,0 +1,443 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'config.validation',
+	title: 'Configuration Validation',
+	summary: 'Schema validation, error handling, and defaults',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Configuration Validation
+summary: Schema validation, error handling, and defaults
+tags: [config, validation, schema, errors, defaults]
+parent: config
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Configuration Validation
+
+Configuration validation ensures config data meets schema requirements, provides helpful error messages, and applies sensible defaults. The config system uses Zod schemas for type-safe validation.
+
+## Schema Validation
+
+### Zod Schema Basics
+
+\`\`\`ts
+import { z } from 'zod';
+
+const configSchema = z.object({
+  // Required string
+  apiKey: z.string().min(1),
+  
+  // Number with range
+  port: z.number().min(1).max(65535),
+  
+  // Enum type
+  environment: z.enum(['development', 'production']),
+  
+  // Optional with default
+  timeout: z.number().default(5000),
+  
+  // Array of strings
+  allowedOrigins: z.array(z.string().url()),
+  
+  // Nested object
+  database: z.object({
+    host: z.string(),
+    port: z.number(),
+    name: z.string()
+  })
+});
+\`\`\`
+
+### Parsing Configuration
+
+\`\`\`ts
+import { z } from 'zod';
+
+const configSchema = z.object({
+  apiKey: z.string().min(1),
+  port: z.number().default(3000)
+});
+
+const rawConfig = {
+  apiKey: '<api-key>',
+  port: '3000'  // string, will be coerced
+};
+
+try {
+  const config = configSchema.parse(rawConfig);
+  console.log(config);  // { apiKey: '<api-key>', port: 3000 }
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    console.error(error.errors);
+    // [
+    //   {
+    //     path: ['apiKey'],
+    //     message: 'Required',
+    //     code: 'invalid_type'
+    //   }
+    // ]
+  }
+}
+\`\`\`
+
+### Type Coercion
+
+\`\`\`ts
+const configSchema = z.object({
+  // Coerce string to number
+  port: z.coerce.number().default(3000),
+  
+  // Coerce string to boolean
+  debug: z.coerce.boolean().default(false),
+  
+  // Coerce string to date
+  createdAt: z.coerce.date()
+});
+
+const rawConfig = {
+  port: '3000',
+  debug: 'true',
+  createdAt: '2024-01-01'
+};
+
+const config = configSchema.parse(rawConfig);
+// { port: 3000, debug: true, createdAt: Date }
+\`\`\`
+
+## Validation Errors
+
+### Error Format
+
+\`\`\`ts
+interface ValidationError {
+  code: string;           // 'invalid_type', 'too_small', etc.
+  path: string[];         // ['database', 'host']
+  message: string;        // 'Required'
+  expected?: string;      // 'string'
+  received?: string;      // 'undefined'
+}
+\`\`\`
+
+### Error Handling
+
+\`\`\`ts
+import { validateConfig } from '@vibesdotdev/config';
+
+const result = validateConfig(configSchema, rawData);
+
+if (!result.success) {
+  console.error('Validation failed:');
+  for (const error of result.errors) {
+    console.error(\`  \${error.path.join('.')}: \${error.message}\`);
+  }
+} else {
+  console.log('Config valid:', result.data);
+}
+\`\`\`
+
+### Custom Error Messages
+
+\`\`\`ts
+const configSchema = z.object({
+  email: z.string().email('Must be a valid email address'),
+  password: z
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain uppercase letter')
+    .regex(/[0-9]/, 'Password must contain number'),
+  age: z.number().min(18, 'Must be 18 or older')
+});
+\`\`\`
+
+### Error Formatting
+
+\`\`\`ts
+import { formatValidationErrors } from '@vibesdotdev/config';
+
+try {
+  configSchema.parse(rawData);
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    const formatted = formatValidationErrors(error);
+    console.log(formatted);
+    // {
+    //   fieldErrors: {
+    //     email: ['Must be a valid email address'],
+    //     password: ['Password must be at least 8 characters']
+    //   },
+    //   rootErrors: []
+    // }
+  }
+}
+\`\`\`
+
+## Default Values
+
+### Schema Defaults
+
+\`\`\`ts
+const configSchema = z.object({
+  // Simple default
+  debug: z.boolean().default(false),
+  
+  // Default with transform
+  tags: z.string().transform((s) => s.split(',')).default(''),
+  
+  // Default object
+  settings: z.object({
+    theme: z.enum(['light', 'dark']).default('system'),
+    notifications: z.boolean().default(true)
+  }).default({})
+});
+\`\`\`
+
+### Context-Aware Defaults
+
+\`\`\`ts
+import { applyDefaults } from '@vibesdotdev/config';
+
+const configSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number()
+});
+
+const defaults = {
+  apiUrl: {
+    type: 'context',
+    rules: [
+      {
+        when: { environment: 'development' },
+        value: 'http://localhost:3000'
+      },
+      {
+        when: { environment: 'production' },
+        value: 'https://api.vibes.dev'
+      }
+    ]
+  },
+  timeout: {
+    type: 'context',
+    rules: [
+      {
+        when: { hardware: 'consumer' },
+        value: 30000
+      },
+      {
+        when: { hardware: 'cloud' },
+        value: 10000
+      }
+    ]
+  }
+};
+
+const config = applyDefaults(configSchema, rawData, {
+  environment: 'production',
+  hardware: 'cloud'
+});
+\`\`\`
+
+### Lazy Defaults
+
+\`\`\`ts
+const configSchema = z.object({
+  // Default from environment variable
+  apiKey: z.string().default(() => process.env.API_KEY),
+  
+  // Default from function
+  timestamp: z.number().default(() => Date.now()),
+  
+  // Default from async function
+  version: z.string().default(async () => {
+    const pkg = await import('../package.json');
+    return pkg.version;
+  })
+});
+\`\`\`
+
+## Custom Validation
+
+### Refine Validation
+
+\`\`\`ts
+const configSchema = z.object({
+  password: z.string(),
+  confirmPassword: z.string()
+}).refine(
+  (data) => data.password === data.confirmPassword,
+  {
+    message: 'Passwords do not match',
+    path: ['confirmPassword']
+  }
+);
+\`\`\`
+
+### Async Validation
+
+\`\`\`ts
+const configSchema = z.object({
+  apiKey: z.string()
+}).refineAsync(
+  async (data) => {
+    // Validate API key with remote service
+    const response = await fetch('https://api.example.com/validate', {
+      headers: { Authorization: \`Bearer \${data.apiKey}\` }
+    });
+    return response.ok;
+  },
+  {
+    message: 'Invalid API key',
+    path: ['apiKey']
+  }
+);
+\`\`\`
+
+### Transform Validation
+
+\`\`\`ts
+const configSchema = z.object({
+  // Trim and lowercase email
+  email: z.string().transform((s) => s.trim().toLowerCase()),
+  
+  // Parse JSON string
+  metadata: z.string().transform((s) => JSON.parse(s)),
+  
+  // Validate and transform
+  port: z.string().transform((s) => {
+    const port = parseInt(s, 10);
+    if (port < 1 || port > 65535) {
+      throw new Error('Invalid port number');
+    }
+    return port;
+  })
+});
+\`\`\`
+
+## Validation Strategies
+
+### Strict Validation
+
+\`\`\`ts
+const configSchema = z.object({
+  apiKey: z.string()
+}).strict();  // Reject unknown keys
+
+try {
+  configSchema.parse({ apiKey: '<api-key>', unknown: 'value' });
+} catch (error) {
+  console.error(error);  // Unrecognized key 'unknown'
+}
+\`\`\`
+
+### Passthrough Validation
+
+\`\`\`ts
+const configSchema = z.object({
+  apiKey: z.string()
+}).passthrough();  // Allow unknown keys
+
+const config = configSchema.parse({
+  apiKey: '<api-key>',
+  unknown: 'value'  // preserved
+});
+\`\`\`
+
+### Partial Validation
+
+\`\`\`ts
+const configSchema = z.object({
+  apiKey: z.string(),
+  port: z.number()
+}).partial();  // All fields optional
+
+const config = configSchema.parse({});
+// {}
+\`\`\`
+
+## Validation Utilities
+
+### Deep Merge
+
+\`\`\`ts
+import { deepMerge } from '@vibesdotdev/config';
+
+const defaults = {
+  database: {
+    host: 'localhost',
+    port: 5432
+  }
+};
+
+const overrides = {
+  database: {
+    host: 'db.example.com'
+  }
+};
+
+const merged = deepMerge(defaults, overrides);
+// { database: { host: 'db.example.com', port: 5432 } }
+\`\`\`
+
+### Flatten Errors
+
+\`\`\`ts
+import { flattenErrors } from '@vibesdotdev/config';
+
+const zodError = new z.ZodError([...]);
+const flat = flattenErrors(zodError);
+
+console.log(flat);
+// {
+//   'database.host': ['Required'],
+//   'database.port': ['Must be a number']
+// }
+\`\`\`
+
+### Validate Against Schema
+
+\`\`\`ts
+import { validateAgainstSchema } from '@vibesdotdev/config';
+
+const result = validateAgainstSchema(configSchema, rawData, {
+  strict: true,
+  applyDefaults: true,
+  context: { environment: 'production' }
+});
+
+if (result.success) {
+  console.log(result.data);  // Validated config with defaults
+} else {
+  console.error(result.errors);
+}
+\`\`\`
+
+## Best Practices
+
+1. **Use specific schemas** — Avoid \`z.any()\` or \`z.unknown()\`
+2. **Provide helpful error messages** — Guide users to fix issues
+3. **Apply sensible defaults** — Reduce required configuration
+4. **Validate early** — Fail fast on invalid config
+5. **Use context-aware defaults** — Different values per environment
+6. **Document required fields** — Clear what must be provided
+
+:::card{title="See also"}
+- [\`config.manifests\`](config.manifests) — Configuration manifests
+- [\`config.environment\`](config.environment) — Environment variables
+- [\`storage.manifests\`](storage.manifests) — Storage manifests
+:::
+`
+	},
+	parent: 'config',
+	order: 3,
+	tags: ['config', 'validation', 'schema', 'errors', 'defaults'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;

package/src/doctor.ts

@@ -0,0 +1,143 @@
+/**
+ * Config Doctor
+ *
+ * Generic diagnostic functions for validating configuration state.
+ */
+
+import type { ConfigManifest } from './manifest/types';
+import type { ConfigCollection } from './collection/collection';
+
+import type { DiagnosticIssue, DetailedDiagnostic, DiagnoseConfigOptions } from './schemas/doctor.schema.ts';
+
+export type { DiagnosticSeverity, DiagnosticIssue, DetailedDiagnostic, DiagnoseConfigOptions } from './schemas/doctor.schema.ts';
+
+/**
+ * Generic diagnostic function for any ConfigManifest.
+ *
+ * Validates:
+ * - Required fields are present
+ * - Values match schema constraints
+ * - No deprecated settings (optional)
+ * - Custom validation rules
+ *
+ * @param manifest - The ConfigManifest to diagnose
+ * @param values - The current configuration values
+ * @param options - Diagnostic options
+ * @returns Detailed diagnostic result
+ *
+ * @example
+ * ```typescript
+ * const result = diagnoseConfig(myManifest, currentValues);
+ * if (!result.ready) {
+ *   console.error('Config errors:', result.issues.filter(i => i.severity === 'error'));
+ * }
+ * ```
+ */
+export function diagnoseConfig<T extends ConfigManifest>(
+	manifest: T,
+	values: Record<string, unknown>,
+	options: DiagnoseConfigOptions = {}
+): DetailedDiagnostic {
+	const issues: DiagnosticIssue[] = [];
+	const { checkDeprecated = false } = options;
+
+	// Check all fields from manifest
+	for (const [fieldKey, fieldMeta] of Object.entries(manifest.fields)) {
+		const value = getValueAtPath(values, fieldKey);
+
+		// Check required fields (fields without defaults)
+		// Empty string and null count as missing
+		const hasValue = value !== undefined && value !== null && value !== '';
+		if (fieldMeta.defaults?.base === undefined && !hasValue) {
+			issues.push({
+				path: fieldKey,
+				message: `Required field '${fieldMeta.ui.label || fieldKey}' is missing`,
+				severity: 'error',
+				code: 'required_field_missing'
+			});
+		}
+
+		// Check deprecated fields
+		if (checkDeprecated && fieldMeta.tags?.includes('deprecated')) {
+			if (value !== undefined && value !== null) {
+				issues.push({
+					path: fieldKey,
+					message: `Field '${fieldMeta.ui.label || fieldKey}' is deprecated and should be removed`,
+					severity: 'warning',
+					code: 'deprecated_field_used'
+				});
+			}
+		}
+	}
+
+	// Run custom validators
+	if (options.customValidators) {
+		for (const { path, fn } of options.customValidators) {
+			const value = getValueAtPath(values, path);
+			const error = fn(value);
+			if (error) {
+				issues.push({
+					path,
+					message: error,
+					severity: 'error',
+					code: 'custom_validation_failed'
+				});
+			}
+		}
+	}
+
+	const errors = issues.filter((i) => i.severity === 'error').length;
+	const warnings = issues.filter((i) => i.severity === 'warning').length;
+	const info = issues.filter((i) => i.severity === 'info').length;
+
+	return {
+		ready: errors === 0,
+		issues,
+		summary: { errors, warnings, info }
+	};
+}
+
+/**
+ * Diagnose a ConfigCollection (group of related configs).
+ *
+ * Validates that all manifests in the collection are properly configured.
+ *
+ * @param collection - The ConfigCollection to diagnose
+ * @returns Diagnostic results for each manifest in the collection
+ */
+export async function diagnoseCollection(
+	collection: ConfigCollection
+): Promise<Record<string, DetailedDiagnostic>> {
+	const results: Record<string, DetailedDiagnostic> = {};
+
+	for (const manifestId of collection.manifestIds) {
+		// Load current values for this manifest
+		// Note: This assumes manifests are registered and loadable
+		results[manifestId] = {
+			ready: true,
+			issues: [],
+			summary: { errors: 0, warnings: 0, info: 0 }
+		};
+	}
+
+	return results;
+}
+
+/**
+ * Helper: Get value at a dot-notation path from an object
+ */
+function getValueAtPath(obj: Record<string, unknown>, path: string): unknown {
+	if (path in obj) {
+		return obj[path];
+	}
+
+	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;
+}

package/src/env.runtime.ts

@@ -0,0 +1,49 @@
+/**
+ * Runtime environment access for storage policy and other runtime-dependent modules.
+ *
+ * Provides settable env overrides so tests can inject values without mutating process.env.
+ */
+
+declare const window: Record<string, unknown> | undefined;
+
+type WindowWithEnv = { __env?: Record<string, string | undefined>; [key: string]: unknown };
+
+/** Internal mutable env override map (used by tests) */
+const envOverrides = new Map<string, string>();
+
+/**
+ * Read an environment variable at runtime.
+ * Priority: envOverrides → process.env → browser window.__env
+ */
+export function readRuntimeEnv(key: string): string | undefined {
+	if (envOverrides.has(key)) return envOverrides.get(key);
+
+	const publicKey = `PUBLIC_${key}`;
+
+	if (typeof window !== 'undefined') {
+		return (window as WindowWithEnv).__env?.[publicKey];
+	}
+
+	if (typeof process !== 'undefined') {
+		return (
+			process.env?.[key] ??
+			process.env?.[publicKey]
+		);
+	}
+
+	return undefined;
+}
+
+/**
+ * Set an environment variable override (primarily for testing).
+ */
+export function setRuntimeEnv(key: string, value: string): void {
+	envOverrides.set(key, value);
+}
+
+/**
+ * Clear all environment overrides (primarily for testing).
+ */
+export function clearRuntimeEnvOverrides(): void {
+	envOverrides.clear();
+}

package/src/env.ts

@@ -0,0 +1,91 @@
+/**
+ * Generic environment-variable helpers.
+ *
+ * This module is the canonical home for *generic* env access: read a key,
+ * parse a number, parse a boolean, validate required keys at startup. It is
+ * isomorphic — works in Node/server and browser (`window.__env`).
+ *
+ * Domain-specific env (AI provider keys, OAuth callback URLs, SMTP, Linear
+ * status IDs, scheduler crons, …) lives with the owning module. Do not
+ * re-introduce a monorepo-wide `env` aggregate here.
+ *
+ * See `packages/config/SPEC.md` ("Does not own").
+ */
+
+// Declare browser globals for isomorphic compatibility (this file runs in both Node and browser)
+declare const window: Record<string, unknown> | undefined;
+
+type WindowWithEnv = { __env?: Record<string, string | undefined>; [key: string]: unknown };
+
+function readBrowserEnv(key: string): string | undefined {
+	if (typeof window === 'undefined') return undefined;
+	return (window as WindowWithEnv).__env?.[key];
+}
+
+function readProcessEnv(key: string): string | undefined {
+	if (typeof process === 'undefined') return undefined;
+	return process.env?.[key];
+}
+
+function readRuntimeEnv(key: string): string | undefined {
+	const publicKey = `PUBLIC_${key}`;
+	if (typeof window !== 'undefined') {
+		return readBrowserEnv(publicKey);
+	}
+	return (
+		readProcessEnv(key) ??
+		readProcessEnv(publicKey) ??
+		readBrowserEnv(key) ??
+		readBrowserEnv(publicKey)
+	);
+}
+
+function isServerRuntime(): boolean {
+	return typeof window === 'undefined' && typeof process !== 'undefined';
+}
+
+/** Read an env var (or the `PUBLIC_`-prefixed variant) with a fallback. */
+export function getEnv(key: string, defaultValue?: string): string {
+	return readRuntimeEnv(key) || defaultValue || '';
+}
+
+/** Read an env var as a number, falling back when missing or unparseable. */
+export function getEnvNumber(key: string, defaultValue: number): number {
+	const value = getEnv(key);
+	const parsed = parseInt(value, 10);
+	return isNaN(parsed) ? defaultValue : parsed;
+}
+
+/** Read an env var as a boolean (`"true"` is true; anything else is the default). */
+export function getEnvBoolean(key: string, defaultValue: boolean): boolean {
+	const value = getEnv(key);
+	if (!value) return defaultValue;
+	return value.toLowerCase() === 'true';
+}
+
+/**
+ * Assert that the given env vars are set. No-op in browser runtimes.
+ * Throws with a formatted message listing every missing key.
+ */
+export function validateRequiredEnv(required: Array<{ key: string; description: string }>): void {
+	if (!isServerRuntime()) {
+		return;
+	}
+
+	const missing: Array<{ key: string; description: string }> = [];
+
+	for (const { key, description } of required) {
+		if (!readRuntimeEnv(key)) {
+			missing.push({ key, description });
+		}
+	}
+
+	if (missing.length > 0) {
+		const errorList = missing
+			.map(({ key, description }) => `  - ${key}: ${description}`)
+			.join('\n');
+		throw new Error(
+			`Missing required environment variables:\n${errorList}\n\nPlease set these variables in your environment or .env file.`
+		);
+	}
+}