@vibesdotdev/config 0.0.1

package/src/docs/manifests.docs.descriptor.ts

@@ -0,0 +1,505 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'config.manifests',
+	title: 'Configuration Manifests',
+	summary: 'Config manifests, schemas, and validation',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Configuration Manifests
+summary: Config manifests, schemas, and validation
+tags: [config, manifests, schemas, validation]
+parent: config
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Configuration Manifests
+
+Configuration manifests define user-editable settings with form metadata, validation schemas, and context-aware defaults. The \`config/manifest\` runtime kind extends storage manifests with UI-specific features.
+
+## Manifest Structure
+
+\`\`\`ts
+interface ConfigManifestDescriptor {
+  kind: 'config/manifest';
+  id: string;
+  namespace: string;
+  tier: 'system' | 'user' | 'internal';
+  schema: ZodSchema;
+  fields: ConfigFieldMeta[];
+  groups: ConfigFieldGroup[];
+  storage: {
+    adapter: string;
+    scope: 'local' | 'cloud' | 'sync';
+  };
+  context?: {
+    hardware?: ('consumer' | 'cloud')[];
+    environment?: string[];
+  };
+  navigation?: {
+    section: string;
+    order: number;
+    icon: string;
+  };
+}
+\`\`\`
+
+## Defining a Config Manifest
+
+### Basic Manifest
+
+\`\`\`ts
+import { z } from 'zod';
+import { createConfigManifest } from '@vibesdotdev/config';
+
+const aiConfigManifest = createConfigManifest({
+  id: 'ai',
+  namespace: 'app',
+  tier: 'user',
+  schema: z.object({
+    provider: z.enum(['anthropic', 'openai', 'gemini']),
+    model: z.string(),
+    temperature: z.number().min(0).max(2),
+    maxTokens: z.number().min(100).max(8192)
+  }),
+  fields: [
+    {
+      path: 'provider',
+      label: 'AI Provider',
+      component: 'select',
+      options: [
+        { value: 'anthropic', label: 'Anthropic Claude' },
+        { value: 'openai', label: 'OpenAI GPT' },
+        { value: 'gemini', label: 'Google Gemini' }
+      ]
+    },
+    {
+      path: 'model',
+      label: 'Model',
+      component: 'input',
+      placeholder: 'claude-sonnet-4-20250514'
+    },
+    {
+      path: 'temperature',
+      label: 'Temperature',
+      component: 'slider',
+      min: 0,
+      max: 2,
+      step: 0.1
+    },
+    {
+      path: 'maxTokens',
+      label: 'Max Tokens',
+      component: 'number',
+      min: 100,
+      max: 8192
+    }
+  ],
+  groups: [
+    {
+      id: 'provider',
+      label: 'Provider Settings',
+      fields: ['provider', 'model']
+    },
+    {
+      id: 'generation',
+      label: 'Generation',
+      fields: ['temperature', 'maxTokens']
+    }
+  ],
+  storage: {
+    adapter: 'storage.adapter.libsql',
+    scope: 'local'
+  }
+});
+\`\`\`
+
+### Manifest with Conditional Fields
+
+\`\`\`ts
+const aiConfigManifest = createConfigManifest({
+  id: 'ai',
+  schema: z.object({
+    provider: z.enum(['anthropic', 'openai']),
+    apiKey: z.string(),
+    baseUrl: z.string().optional()
+  }),
+  fields: [
+    {
+      path: 'provider',
+      label: 'Provider',
+      component: 'radio',
+      options: [
+        { value: 'anthropic', label: 'Anthropic' },
+        { value: 'openai', label: 'OpenAI' }
+      ]
+    },
+    {
+      path: 'apiKey',
+      label: 'API Key',
+      component: 'secret',
+      rules: {
+        required: true,
+        visible: {
+          type: 'whenContext',
+          hardware: ['consumer', 'cloud']
+        }
+      }
+    },
+    {
+      path: 'baseUrl',
+      label: 'Custom Base URL',
+      component: 'input',
+      rules: {
+        visible: {
+          type: 'whenField',
+          field: 'provider',
+          equals: 'openai',
+          value: true
+        },
+        description: 'Optional custom OpenAI-compatible endpoint'
+      }
+    }
+  ]
+});
+\`\`\`
+
+### Manifest with Validation Rules
+
+\`\`\`ts
+const aiConfigManifest = createConfigManifest({
+  id: 'ai',
+  schema: z.object({
+    apiKey: z.string().min(1),
+    model: z.string(),
+    timeout: z.number().positive()
+  }),
+  fields: [
+    {
+      path: 'apiKey',
+      label: 'API Key',
+      component: 'secret',
+      rules: {
+        required: true,
+        validate: {
+          type: 'function',
+          fn: (value) => {
+            if (!value.startsWith('sk-')) {
+              return 'API key must start with sk-';
+            }
+            return null;  // null = valid
+          }
+        }
+      }
+    },
+    {
+      path: 'timeout',
+      label: 'Timeout (ms)',
+      component: 'number',
+      rules: {
+        required: true,
+        min: 1000,
+        max: 60000,
+        validate: {
+          type: 'function',
+          fn: (value) => {
+            if (value % 1000 !== 0) {
+              return 'Timeout must be multiple of 1000';
+            }
+            return null;
+          }
+        }
+      }
+    }
+  ]
+});
+\`\`\`
+
+## Using Config Manifests
+
+### Loading Configuration
+
+\`\`\`ts
+import { ConfigManifest } from '@vibesdotdev/config';
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+
+const runtime = getVibesRuntime();
+const config = new ConfigManifest('ai');
+
+const aiConfig = await config.loadWithDefaults({
+  hardware: 'consumer',
+  environment: 'development'
+});
+
+console.log(aiConfig.provider);  // 'anthropic' (default)
+console.log(aiConfig.model);     // 'claude-sonnet-4-20250514'
+\`\`\`
+
+### Saving Configuration
+
+\`\`\`ts
+await config.save({
+  provider: 'openai',
+  model: 'gpt-4o',
+  temperature: 0.7
+});
+
+// Configuration persisted to storage
+\`\`\`
+
+### Subscribing to Changes
+
+\`\`\`ts
+const unsubscribe = config.subscribe((newConfig) => {
+  console.log('Config changed:', newConfig);
+});
+
+// Later...
+unsubscribe();  // Stop listening
+\`\`\`
+
+## Config Tiers
+
+### System Tier
+
+System-wide configuration (admin-only):
+
+\`\`\`ts
+{
+  id: 'system/security',
+  tier: 'system',
+  context: {
+    hardware: ['cloud'],
+    environment: ['production']
+  }
+}
+\`\`\`
+
+### User Tier
+
+User-specific preferences:
+
+\`\`\`ts
+{
+  id: 'user/preferences',
+  tier: 'user',
+  storage: {
+    adapter: 'storage.adapter.libsql',
+    scope: 'local'
+  }
+}
+\`\`\`
+
+### Internal Tier
+
+Application internal settings (not user-editable):
+
+\`\`\`ts
+{
+  id: 'app/internal',
+  tier: 'internal',
+  navigation: null  // Hidden from settings UI
+}
+\`\`\`
+
+## Config Collections
+
+Group related manifests:
+
+\`\`\`ts
+import { ConfigCollection } from '@vibesdotdev/config';
+
+const settingsCollection = new ConfigCollection({
+  id: 'app.settings',
+  manifests: ['ai', 'theme', 'notifications', 'privacy']
+});
+
+// Load all manifests at once
+const allSettings = await settingsCollection.load();
+
+// Subscribe to all changes
+settingsCollection.subscribe((settings) => {
+  console.log('All settings:', settings);
+});
+\`\`\`
+
+## Field Components
+
+### Input Field
+
+\`\`\`ts
+{
+  path: 'name',
+  label: 'Name',
+  component: 'input',
+  placeholder: 'Enter name',
+  rules: {
+    required: true,
+    maxLength: 100
+  }
+}
+\`\`\`
+
+### Textarea Field
+
+\`\`\`ts
+{
+  path: 'description',
+  label: 'Description',
+  component: 'textarea',
+  placeholder: 'Enter description',
+  rules: {
+    maxLength: 1000
+  }
+}
+\`\`\`
+
+### Select Field
+
+\`\`\`ts
+{
+  path: 'theme',
+  label: 'Theme',
+  component: 'select',
+  options: [
+    { value: 'light', label: 'Light' },
+    { value: 'dark', label: 'Dark' },
+    { value: 'system', label: 'System' }
+  ]
+}
+\`\`\`
+
+### Boolean Field
+
+\`\`\`ts
+{
+  path: 'notifications',
+  label: 'Enable Notifications',
+  component: 'boolean'
+}
+\`\`\`
+
+### Secret Field
+
+\`\`\`ts
+{
+  path: 'apiKey',
+  label: 'API Key',
+  component: 'secret',
+  rules: {
+    required: true,
+    encrypted: true  // Encrypt at rest
+  }
+}
+\`\`\`
+
+## Context-Aware Defaults
+
+\`\`\`ts
+const aiConfigManifest = createConfigManifest({
+  id: 'ai',
+  schema: z.object({
+    baseUrl: z.string()
+  }),
+  fields: [
+    {
+      path: 'baseUrl',
+      label: 'API Base URL',
+      defaults: {
+        type: 'context',
+        rules: [
+          {
+            when: { environment: 'development' },
+            value: 'http://localhost:3000'
+          },
+          {
+            when: { environment: 'staging' },
+            value: 'https://staging-api.vibes.dev'
+          },
+          {
+            when: { environment: 'production' },
+            value: 'https://api.vibes.dev'
+          }
+        ]
+      }
+    }
+  ]
+});
+\`\`\`
+
+## Config Validation
+
+### Schema Validation
+
+\`\`\`ts
+try {
+  await config.save({ provider: 'invalid' });
+} catch (error) {
+  console.error(error);  // ZodError with validation details
+}
+\`\`\`
+
+### Custom Validation
+
+\`\`\`ts
+const manifest = createConfigManifest({
+  id: 'ai',
+  schema: z.object({
+    apiKey: z.string()
+  }),
+  fields: [
+    {
+      path: 'apiKey',
+      label: 'API Key',
+      component: 'secret',
+      rules: {
+        validate: {
+          type: 'async',
+          fn: async (value) => {
+            // Test API key validity
+            const response = await fetch('https://api.provider.com/validate', {
+              headers: { Authorization: \`Bearer \${value}\` }
+            });
+            
+            if (!response.ok) {
+              return 'Invalid API key';
+            }
+            return null;
+          }
+        }
+      }
+    }
+  ]
+});
+\`\`\`
+
+## Best Practices
+
+1. **Use appropriate tiers** — System for admin, user for preferences
+2. **Define clear field labels** — Help users understand settings
+3. **Provide sensible defaults** — Context-aware when possible
+4. **Validate thoroughly** — Both schema and custom rules
+5. **Group related fields** — Logical sections for navigation
+6. **Document field purposes** — Help text for complex settings
+
+:::card{title="See also"}
+- [\`config.environment\`](config.environment) — Environment variables
+- [\`config.validation\`](config.validation) — Schema validation
+- [\`storage.manifests\`](storage.manifests) — Storage manifests
+:::
+`
+	},
+	parent: 'config',
+	order: 1,
+	tags: ['config', 'manifests', 'schemas', 'validation'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;