@vibesdotdev/config 0.0.1

package/dist/docs/validation.docs.descriptor.js

@@ -0,0 +1,441 @@
+const descriptor = {
+    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;
+//# sourceMappingURL=validation.docs.descriptor.js.map

package/dist/docs/validation.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/validation.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,mBAAmB;IACvB,KAAK,EAAE,0BAA0B;IACjC,OAAO,EAAE,iDAAiD;IAC1D,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsaT;KACC;IACD,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/doctor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Config Doctor
+ *
+ * Generic diagnostic functions for validating configuration state.
+ */
+import type { ConfigManifest } from './manifest/types';
+import type { ConfigCollection } from './collection/collection';
+import type { 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 declare function diagnoseConfig<T extends ConfigManifest>(manifest: T, values: Record<string, unknown>, options?: DiagnoseConfigOptions): DetailedDiagnostic;
+/**
+ * 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 declare function diagnoseCollection(collection: ConfigCollection): Promise<Record<string, DetailedDiagnostic>>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAmB,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAE7G,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEjI;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,EACtD,QAAQ,EAAE,CAAC,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAE,qBAA0B,GACjC,kBAAkB,CA0DpB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,UAAU,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAc7C"}

package/dist/doctor.js

@@ -0,0 +1,119 @@
+/**
+ * Config Doctor
+ *
+ * Generic diagnostic functions for validating configuration state.
+ */
+/**
+ * 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(manifest, values, options = {}) {
+    const issues = [];
+    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) {
+    const results = {};
+    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, path) {
+    if (path in obj) {
+        return obj[path];
+    }
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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").
+ */
+/** Read an env var (or the `PUBLIC_`-prefixed variant) with a fallback. */
+export declare function getEnv(key: string, defaultValue?: string): string;
+/** Read an env var as a number, falling back when missing or unparseable. */
+export declare function getEnvNumber(key: string, defaultValue: number): number;
+/** Read an env var as a boolean (`"true"` is true; anything else is the default). */
+export declare function getEnvBoolean(key: string, defaultValue: boolean): boolean;
+/**
+ * Assert that the given env vars are set. No-op in browser runtimes.
+ * Throws with a formatted message listing every missing key.
+ */
+export declare function validateRequiredEnv(required: Array<{
+    key: string;
+    description: string;
+}>): void;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkCH,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAItE;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAIzE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAqB/F"}