@vibesdotdev/config 0.0.1

package/src/docs/environment.docs.descriptor.ts

@@ -0,0 +1,385 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'config.environment',
+	title: 'Environment Configuration',
+	summary: 'Environment variables, secrets management, and resolution',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Environment Configuration
+summary: Environment variables, secrets management, and resolution
+tags: [config, environment, variables, secrets, resolution]
+parent: config
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Environment Configuration
+
+Environment configuration manages environment variables, secrets, and runtime environment selection. The config system provides type-safe environment resolution with environment-specific overrides.
+
+## Environment Types
+
+### Defined Environments
+
+\`\`\`ts
+type Environment = 'development' | 'staging' | 'production' | 'test';
+\`\`\`
+
+### Environment Context
+
+\`\`\`ts
+interface EnvironmentContext {
+  name: Environment;
+  origin: string;
+  apiBaseUrl: string;
+  authOrigin: string;
+  features: {
+    analytics: boolean;
+    debugging: boolean;
+    experimental: boolean;
+  };
+}
+\`\`\`
+
+## Loading Environment
+
+### Current Environment
+
+\`\`\`ts
+import { loadCurrentEnvironmentSelection } from '@vibesdotdev/config';
+
+const env = await loadCurrentEnvironmentSelection();
+
+console.log(env.name);  // 'development' | 'staging' | 'production'
+console.log(env.origin);  // 'http://localhost:3000'
+\`\`\`
+
+### Environment Catalog
+
+\`\`\`ts
+import { loadEnvironmentCatalog } from '@vibesdotdev/config';
+
+const catalog = await loadEnvironmentCatalog();
+
+console.log(catalog);
+// {
+//   development: { origin: 'http://localhost:3000', ... },
+//   staging: { origin: 'https://staging.vibes.dev', ... },
+//   production: { origin: 'https://vibes.dev', ... }
+// }
+\`\`\`
+
+## Environment Variables
+
+### Accessing Variables
+
+\`\`\`ts
+import { env } from '@vibesdotdev/config';
+
+const apiKey = env.get('ANTHROPIC_API_KEY');
+const debug = env.get('DEBUG_MODE', 'false') === 'true';
+const port = env.get('PORT', '3000');
+\`\`\`
+
+### Typed Environment Variables
+
+\`\`\`ts
+import { z } from 'zod';
+import { env } from '@vibesdotdev/config';
+
+const config = env.parse(
+  z.object({
+    ANTHROPIC_API_KEY: z.string().min(1),
+    DEBUG_MODE: z.boolean().default(false),
+    PORT: z.number().default(3000),
+    DATABASE_URL: z.string().url()
+  })
+);
+
+console.log(config.ANTHROPIC_API_KEY);  // string
+console.log(config.DEBUG_MODE);         // boolean
+console.log(config.PORT);               // number
+\`\`\`
+
+## Secrets Management
+
+### Secret Resolution
+
+\`\`\`ts
+import { resolveAuthApiBaseUrl } from '@vibesdotdev/auth';
+
+const authUrl = await resolveAuthApiBaseUrl({
+  environment: 'production'
+});
+
+console.log(authUrl);  // 'https://auth.vibes.dev'
+\`\`\`
+
+### Secret Sources
+
+Secrets can come from multiple sources:
+
+\`\`\`ts
+interface SecretResolution {
+  source: 'env' | 'vault' | 'wrangler' | 'encrypted-local';
+  key: string;
+  resolved: string;
+}
+\`\`\`
+
+**Priority order:**
+1. Environment variable (process.env)
+2. Vault secret (if configured)
+3. Wrangler secret (Cloudflare)
+4. Encrypted local file (~/.config/vibes/secrets)
+
+### Credential References
+
+Use credential references in config files:
+
+\`\`\`jsonc
+{
+  "configuration": {
+    // ✅ Secret store reference
+    "apiKey": { "source": "secret", "key": "ANTHROPIC_API_KEY" },
+    
+    // ✅ Environment variable reference
+    "apiKey": { "source": "env", "key": "ANTHROPIC_API_KEY" },
+    
+    // ❌ NEVER — bare credential strings
+    "apiKey": "<raw-api-key>"
+  }
+}
+\`\`\`
+
+## Environment Resolution
+
+### Resolution Order
+
+1. **Explicit override** — \`--environment production\`
+2. **Saved selection** — ~/.config/vibes/environment.json
+3. **Environment detection** — Vercel, Cloudflare, etc.
+4. **Default** — 'development'
+
+### Programmatic Selection
+
+\`\`\`ts
+import { saveCurrentEnvironmentSelection } from '@vibesdotdev/config';
+
+await saveCurrentEnvironmentSelection({
+  name: 'production',
+  origin: 'https://vibes.dev'
+});
+
+// Future loads will use production
+const env = await loadCurrentEnvironmentSelection();
+console.log(env.name);  // 'production'
+\`\`\`
+
+### CLI Selection
+
+\`\`\`bash
+# Set environment
+vibes config environment set production
+
+# View current
+vibes config environment get
+
+# List available
+vibes config environment list
+\`\`\`
+
+## Environment-Specific Configuration
+
+### Config Overrides
+
+\`\`\`ts
+const aiConfigManifest = createConfigManifest({
+  id: 'ai',
+  schema: z.object({
+    baseUrl: z.string(),
+    timeout: z.number()
+  }),
+  fields: [
+    {
+      path: 'baseUrl',
+      label: 'API Base URL',
+      defaults: {
+        type: 'context',
+        rules: [
+          {
+            when: { environment: 'development' },
+            value: 'http://localhost:3000'
+          },
+          {
+            when: { environment: 'production' },
+            value: 'https://api.vibes.dev'
+          }
+        ]
+      }
+    },
+    {
+      path: 'timeout',
+      label: 'Timeout',
+      defaults: {
+        type: 'context',
+        rules: [
+          {
+            when: { environment: 'development' },
+            value: 60000  // 60s for debugging
+          },
+          {
+            when: { environment: 'production' },
+            value: 10000  // 10s for performance
+          }
+        ]
+      }
+    }
+  ]
+});
+\`\`\`
+
+### Feature Flags
+
+\`\`\`ts
+import { loadCurrentEnvironmentSelection } from '@vibesdotdev/config';
+
+const env = await loadCurrentEnvironmentSelection();
+
+if (env.features.experimental) {
+  // Enable experimental features
+  await enableExperimentalFeature('new-ui');
+}
+
+if (env.features.debugging) {
+  // Enable debug logging
+  logger.setLevel('debug');
+}
+\`\`\`
+
+## Platform Detection
+
+### Vercel
+
+\`\`\`ts
+// Auto-detected from VERCEL_ENV
+if (process.env.VERCEL_ENV === 'production') {
+  environment = 'production';
+} else if (process.env.VERCEL_ENV === 'preview') {
+  environment = 'staging';
+}
+\`\`\`
+
+### Cloudflare Workers
+
+\`\`\`ts
+// Auto-detected from worker environment
+if (env.CF_ENV === 'production') {
+  environment = 'production';
+}
+\`\`\`
+
+### Local Development
+
+\`\`\`ts
+// Default when no platform detected
+if (!process.env.VERCEL_ENV && !process.env.CF_ENV) {
+  environment = 'development';
+}
+\`\`\`
+
+## E2E Environment Configuration
+
+### E2E Origins
+
+\`\`\`ts
+import {
+  AUTH_E2E_LOCAL_ORIGIN,
+  AUTH_E2E_DEV_SERVER_ORIGIN,
+  resolveAuthE2EOrigin
+} from '@vibesdotdev/auth';
+
+const e2eOrigin = resolveAuthE2EOrigin({
+  mode: 'local'  // or 'dev-server'
+});
+
+console.log(e2eOrigin);  // 'http://localhost:3000' or dev server
+\`\`\`
+
+### E2E Base URL Resolution
+
+\`\`\`ts
+const authBaseUrl = await resolveAuthE2EBaseUrl({
+  e2eMode: 'local',
+  customOrigin: 'http://localhost:5173'
+});
+\`\`\`
+
+## Environment Validation
+
+### Schema Validation
+
+\`\`\`ts
+import { z } from 'zod';
+import { env } from '@vibesdotdev/config';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  DATABASE_URL: z.string().url(),
+  API_KEY: z.string().min(1)
+});
+
+try {
+  const config = env.parse(envSchema);
+} catch (error) {
+  console.error('Invalid environment configuration:', error);
+  process.exit(1);
+}
+\`\`\`
+
+### Required Variables
+
+\`\`\`ts
+const requiredVars = [
+  'DATABASE_URL',
+  'API_KEY',
+  'AUTH_SECRET'
+];
+
+for (const variable of requiredVars) {
+  if (!process.env[variable]) {
+    throw new Error(\`Missing required environment variable: \${variable}\`);
+  }
+}
+\`\`\`
+
+## Best Practices
+
+1. **Use typed environment variables** — Zod schemas for validation
+2. **Never commit secrets** — Use credential references
+3. **Provide sensible defaults** — Especially for local development
+4. **Validate on startup** — Fail fast on missing required vars
+5. **Document required variables** — In README or .env.example
+6. **Use environment-specific configs** — Different settings per environment
+
+:::card{title="See also"}
+- [\`config.manifests\`](config.manifests) — Configuration manifests
+- [\`config.validation\`](config.validation) — Schema validation
+- [\`auth.providers\`](auth.providers) — Auth provider configuration
+:::
+`
+	},
+	parent: 'config',
+	order: 2,
+	tags: ['config', 'environment', 'variables', 'secrets', 'resolution'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;