profclaw 0.0.1-beta.1

package/dist/utils/circuit-breaker.js

@@ -0,0 +1,281 @@
+/**
+ * Circuit Breaker Implementation
+ *
+ * Protects against cascading failures by "opening" the circuit
+ * when error rates exceed thresholds, preventing further requests
+ * until the service has time to recover.
+ */
+import { AppError, ErrorCategory, ErrorSeverity } from '../types/errors.js';
+/**
+ * Circuit breaker states
+ */
+export var CircuitState;
+(function (CircuitState) {
+    /** Circuit is closed, requests flow normally */
+    CircuitState["CLOSED"] = "CLOSED";
+    /** Circuit is open, requests are blocked */
+    CircuitState["OPEN"] = "OPEN";
+    /** Circuit is testing if service recovered */
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+/**
+ * Circuit breaker error
+ */
+export class CircuitBreakerError extends AppError {
+    constructor(name, state) {
+        super(`Circuit breaker '${name}' is ${state}`, {
+            category: ErrorCategory.EXTERNAL_API,
+            severity: ErrorSeverity.MEDIUM,
+            retryable: state === CircuitState.HALF_OPEN,
+            statusCode: 503,
+            metadata: { circuitName: name, circuitState: state },
+        });
+    }
+}
+/**
+ * Circuit Breaker implementation
+ */
+export class CircuitBreaker {
+    config;
+    state = CircuitState.CLOSED;
+    failureCount = 0;
+    successCount = 0;
+    totalRequests = 0;
+    lastFailureTime;
+    lastSuccessTime;
+    stateChangedAt = new Date();
+    failures = [];
+    resetTimer;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Execute a function through the circuit breaker
+     */
+    async execute(fn) {
+        this.totalRequests++;
+        // Check circuit state
+        if (this.state === CircuitState.OPEN) {
+            // Check if we should attempt recovery
+            const timeSinceOpen = Date.now() - this.stateChangedAt.getTime();
+            if (timeSinceOpen >= this.config.resetTimeout) {
+                this.transitionTo(CircuitState.HALF_OPEN);
+            }
+            else {
+                throw new CircuitBreakerError(this.config.name, this.state);
+            }
+        }
+        try {
+            // Apply timeout if configured
+            const result = this.config.timeout
+                ? await this.withTimeout(fn, this.config.timeout)
+                : await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure(error);
+            throw error;
+        }
+    }
+    /**
+     * Execute function with timeout
+     */
+    async withTimeout(fn, timeoutMs) {
+        return Promise.race([
+            fn(),
+            new Promise((_, reject) => setTimeout(() => reject(new AppError(`Operation timed out after ${timeoutMs}ms`, {
+                category: ErrorCategory.TIMEOUT,
+                retryable: true,
+                statusCode: 504,
+            })), timeoutMs)),
+        ]);
+    }
+    /**
+     * Handle successful execution
+     */
+    onSuccess() {
+        this.lastSuccessTime = new Date();
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            if (this.successCount >= this.config.successThreshold) {
+                this.transitionTo(CircuitState.CLOSED);
+            }
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // Reset failure count on success in closed state
+            this.failureCount = 0;
+            this.failures = [];
+        }
+    }
+    /**
+     * Handle failed execution
+     */
+    onFailure(error) {
+        this.lastFailureTime = new Date();
+        this.failureCount++;
+        this.failures.push(new Date());
+        // Clean up old failures outside the window
+        const cutoff = Date.now() - this.config.failureWindow;
+        this.failures = this.failures.filter((f) => f.getTime() > cutoff);
+        // Check if we should open the circuit
+        if (this.state === CircuitState.HALF_OPEN) {
+            // Any failure in half-open state reopens the circuit
+            this.transitionTo(CircuitState.OPEN);
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // Check if failures exceed threshold within window
+            if (this.failures.length >= this.config.failureThreshold) {
+                this.transitionTo(CircuitState.OPEN);
+            }
+        }
+        console.error(`[CircuitBreaker:${this.config.name}] Failure recorded. ` +
+            `Count: ${this.failures.length}/${this.config.failureThreshold} ` +
+            `State: ${this.state}`, error);
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.stateChangedAt = new Date();
+        if (newState === CircuitState.CLOSED) {
+            // Reset counters when closing
+            this.failureCount = 0;
+            this.successCount = 0;
+            this.failures = [];
+        }
+        else if (newState === CircuitState.HALF_OPEN) {
+            // Reset success counter when entering half-open
+            this.successCount = 0;
+        }
+        else if (newState === CircuitState.OPEN) {
+            // Schedule automatic transition to half-open
+            if (this.resetTimer) {
+                clearTimeout(this.resetTimer);
+            }
+            this.resetTimer = setTimeout(() => {
+                if (this.state === CircuitState.OPEN) {
+                    this.transitionTo(CircuitState.HALF_OPEN);
+                }
+            }, this.config.resetTimeout);
+        }
+        console.log(`[CircuitBreaker:${this.config.name}] State changed: ${oldState} → ${newState}`);
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            successCount: this.successCount,
+            totalRequests: this.totalRequests,
+            lastFailureTime: this.lastFailureTime,
+            lastSuccessTime: this.lastSuccessTime,
+            stateChangedAt: this.stateChangedAt,
+        };
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+        }
+        this.state = CircuitState.CLOSED;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.failures = [];
+        this.stateChangedAt = new Date();
+        console.log(`[CircuitBreaker:${this.config.name}] Manually reset`);
+    }
+    /**
+     * Manually open the circuit breaker
+     */
+    open() {
+        this.transitionTo(CircuitState.OPEN);
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return this.state;
+    }
+}
+/**
+ * Circuit breaker registry for managing multiple breakers
+ */
+class CircuitBreakerRegistry {
+    breakers = new Map();
+    /**
+     * Get or create a circuit breaker
+     */
+    getOrCreate(name, config) {
+        let breaker = this.breakers.get(name);
+        if (!breaker) {
+            const defaultConfig = {
+                name,
+                failureThreshold: 5,
+                failureWindow: 60000, // 1 minute
+                resetTimeout: 30000, // 30 seconds
+                successThreshold: 2,
+                timeout: 10000, // 10 seconds
+                ...config,
+            };
+            breaker = new CircuitBreaker(defaultConfig);
+            this.breakers.set(name, breaker);
+        }
+        return breaker;
+    }
+    /**
+     * Get all circuit breakers
+     */
+    getAll() {
+        return new Map(this.breakers);
+    }
+    /**
+     * Get stats for all breakers
+     */
+    getAllStats() {
+        const stats = {};
+        for (const [name, breaker] of this.breakers) {
+            stats[name] = breaker.getStats();
+        }
+        return stats;
+    }
+    /**
+     * Reset a specific breaker
+     */
+    reset(name) {
+        this.breakers.get(name)?.reset();
+    }
+    /**
+     * Reset all breakers
+     */
+    resetAll() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+    }
+}
+// Singleton registry
+export const circuitBreakers = new CircuitBreakerRegistry();
+/**
+ * Decorator to wrap a function with a circuit breaker
+ */
+export function withCircuitBreaker(name, config) {
+    return function (_target, _propertyKey, descriptor) {
+        const original = descriptor.value;
+        if (!original) {
+            return descriptor;
+        }
+        descriptor.value = async function (...args) {
+            const breaker = circuitBreakers.getOrCreate(name, config);
+            return breaker.execute(() => original.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/utils/config-loader.d.ts

@@ -0,0 +1,12 @@
+import fs from 'fs';
+/**
+ * Loads and parses a YAML configuration file
+ * @param fileName Name of the file in the config/ directory
+ * @returns Parsed configuration object
+ */
+export declare function loadConfig<T>(fileName: string): T;
+/**
+ * Watch a config file for changes and reload (optional)
+ */
+export declare function watchConfig<T>(fileName: string, onUpdate: (config: T) => void): fs.FSWatcher;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/utils/config-loader.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { logger } from './logger.js';
+/**
+ * Loads and parses a YAML configuration file
+ * @param fileName Name of the file in the config/ directory
+ * @returns Parsed configuration object
+ */
+export function loadConfig(fileName) {
+    try {
+        const configPath = path.resolve(process.cwd(), 'config', fileName);
+        if (!fs.existsSync(configPath)) {
+            logger.warn(`Config file not found: ${configPath}, using defaults`);
+            return {};
+        }
+        const fileContents = fs.readFileSync(configPath, 'utf8');
+        // Interpolate environment variables: ${VAR_NAME} or ${VAR_NAME:-default}
+        const interpolated = fileContents.replace(/\${(\w+)(?::-([^}]*))?}/g, (_, name, defaultValue) => {
+            return process.env[name] || defaultValue || '';
+        });
+        const config = yaml.load(interpolated);
+        logger.debug(`Loaded configuration from ${fileName}`);
+        return config;
+    }
+    catch (error) {
+        logger.error(`Error loading config file ${fileName}:`, error);
+        return {};
+    }
+}
+/**
+ * Watch a config file for changes and reload (optional)
+ */
+export function watchConfig(fileName, onUpdate) {
+    const configPath = path.resolve(process.cwd(), 'config', fileName);
+    return fs.watch(configPath, (eventType) => {
+        if (eventType === 'change') {
+            logger.info(`Config file changed: ${fileName}, reloading...`);
+            const newConfig = loadConfig(fileName);
+            onUpdate(newConfig);
+        }
+    });
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/utils/crypto.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encrypt sensitive data
+ * @returns Base64 string containing [iv]:[authTag]:[encryptedData]
+ */
+export declare function encrypt(text: string): string;
+/**
+ * Decrypt sensitive data
+ */
+export declare function decrypt(encryptedText: string): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/utils/crypto.js

@@ -0,0 +1,59 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+import { logger } from './logger.js';
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12; // Recommended for GCM
+/**
+ * Get the encryption key from environment variable
+ */
+function getEncryptionKey() {
+    const key = process.env.ENCRYPTION_KEY;
+    if (!key) {
+        if (process.env.NODE_ENV === 'production') {
+            throw new Error('ENCRYPTION_KEY environment variable is required in production');
+        }
+        // Fallback for development/testing
+        return Buffer.from('default_development_key_32_bytes_long_12345678');
+    }
+    // Key must be 32 bytes for aes-256-gcm
+    const bufferedKey = Buffer.from(key, 'hex');
+    if (bufferedKey.length !== 32) {
+        throw new Error('ENCRYPTION_KEY must be a 32-byte hex string');
+    }
+    return bufferedKey;
+}
+/**
+ * Encrypt sensitive data
+ * @returns Base64 string containing [iv]:[authTag]:[encryptedData]
+ */
+export function encrypt(text) {
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, getEncryptionKey(), iv);
+    const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return `${iv.toString('base64')}:${authTag.toString('base64')}:${encrypted.toString('base64')}`;
+}
+/**
+ * Decrypt sensitive data
+ */
+export function decrypt(encryptedText) {
+    try {
+        const [ivBase64, authTagBase64, dataBase64] = encryptedText.split(':');
+        if (!ivBase64 || !authTagBase64 || !dataBase64) {
+            throw new Error('Invalid encrypted text format');
+        }
+        const iv = Buffer.from(ivBase64, 'base64');
+        const authTag = Buffer.from(authTagBase64, 'base64');
+        const encrypted = Buffer.from(dataBase64, 'base64');
+        const decipher = createDecipheriv(ALGORITHM, getEncryptionKey(), iv);
+        decipher.setAuthTag(authTag);
+        return decipher.update(encrypted) + decipher.final('utf8');
+    }
+    catch (error) {
+        logger.error('[Crypto] Decryption failed:', error);
+        // If decryption fails, it might be due to a key mismatch or corrupted data.
+        // In some cases, we might want to return the original text if it's not encrypted (migration path),
+        // but for security it's better to throw.
+        throw new Error('Failed to decrypt data');
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/utils/env-validator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Environment Variable Validator
+ *
+ * Validates required and optional environment variables at startup.
+ * Fails fast with clear error messages if required variables are missing.
+ */
+export interface EnvVarSpec {
+    name: string;
+    required: boolean;
+    default?: string;
+    description: string;
+    secret?: boolean;
+    validate?: (value: string) => boolean | string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    loaded: Record<string, string>;
+}
+/**
+ * All environment variables used by the application
+ */
+export declare const ENV_SPEC: EnvVarSpec[];
+/**
+ * Validate all environment variables
+ */
+export declare function validateEnvironment(options?: {
+    exitOnError?: boolean;
+    logResults?: boolean;
+}): ValidationResult;
+/**
+ * Get a summary of configured integrations
+ */
+export declare function getConfiguredIntegrations(): string[];
+/**
+ * Get a summary of configured AI providers
+ */
+export declare function getConfiguredAIProviders(): string[];
+/**
+ * Generate .env.example content
+ */
+export declare function generateEnvExample(): string;
+//# sourceMappingURL=env-validator.d.ts.map

package/dist/utils/env-validator.js

@@ -0,0 +1,236 @@
+/**
+ * Environment Variable Validator
+ *
+ * Validates required and optional environment variables at startup.
+ * Fails fast with clear error messages if required variables are missing.
+ */
+import { createContextualLogger } from './logger.js';
+const log = createContextualLogger('EnvValidator');
+/**
+ * All environment variables used by the application
+ */
+export const ENV_SPEC = [
+    // Server
+    { name: 'PORT', required: false, default: '3000', description: 'HTTP server port' },
+    { name: 'NODE_ENV', required: false, default: 'development', description: 'Node environment (development/production/test)' },
+    // Storage
+    { name: 'STORAGE_TIER', required: false, default: 'local', description: 'Storage backend: memory, local (file), libsql' },
+    { name: 'LIBSQL_URL', required: false, description: 'LibSQL database URL (required if STORAGE_TIER=libsql)' },
+    { name: 'LIBSQL_AUTH_TOKEN', required: false, secret: true, description: 'LibSQL auth token for Turso cloud' },
+    { name: 'DATA_PATH', required: false, default: './data', description: 'Path for file-based storage' },
+    // Redis/Queue
+    { name: 'REDIS_URL', required: false, description: 'Redis URL for task queue (optional, enables background jobs)' },
+    // Cron
+    { name: 'ENABLE_CRON', required: false, default: 'true', description: 'Enable scheduled job execution' },
+    // CORS
+    { name: 'CORS_ORIGIN', required: false, description: 'Allowed CORS origin (comma-separated for multiple)' },
+    // AI Providers
+    { name: 'ANTHROPIC_API_KEY', required: false, secret: true, description: 'Anthropic API key for Claude models' },
+    { name: 'OPENAI_API_KEY', required: false, secret: true, description: 'OpenAI API key for GPT models' },
+    { name: 'GOOGLE_AI_API_KEY', required: false, secret: true, description: 'Google AI API key for Gemini models' },
+    { name: 'AZURE_OPENAI_API_KEY', required: false, secret: true, description: 'Azure OpenAI API key' },
+    { name: 'AZURE_OPENAI_ENDPOINT', required: false, description: 'Azure OpenAI endpoint URL' },
+    { name: 'OLLAMA_URL', required: false, default: 'http://localhost:11434', description: 'Ollama server URL for local models' },
+    // Integrations - GitHub
+    { name: 'GITHUB_CLIENT_ID', required: false, description: 'GitHub OAuth app client ID' },
+    { name: 'GITHUB_CLIENT_SECRET', required: false, secret: true, description: 'GitHub OAuth app client secret' },
+    { name: 'GITHUB_TOKEN', required: false, secret: true, description: 'GitHub personal access token' },
+    { name: 'GITHUB_WEBHOOK_SECRET', required: false, secret: true, description: 'GitHub webhook signature secret' },
+    // Integrations - JIRA
+    { name: 'JIRA_CLIENT_ID', required: false, description: 'JIRA OAuth client ID' },
+    { name: 'JIRA_CLIENT_SECRET', required: false, secret: true, description: 'JIRA OAuth client secret' },
+    { name: 'JIRA_CLOUD_ID', required: false, description: 'JIRA Cloud instance ID' },
+    // Integrations - Linear
+    { name: 'LINEAR_API_KEY', required: false, secret: true, description: 'Linear API key' },
+    { name: 'LINEAR_WEBHOOK_SECRET', required: false, secret: true, description: 'Linear webhook signature secret' },
+    // Integrations - Slack
+    { name: 'SLACK_BOT_TOKEN', required: false, secret: true, description: 'Slack bot OAuth token' },
+    { name: 'SLACK_SIGNING_SECRET', required: false, secret: true, description: 'Slack request signing secret' },
+    { name: 'SLACK_APP_TOKEN', required: false, secret: true, description: 'Slack app-level token (for Socket Mode)' },
+    // Integrations - Discord
+    { name: 'DISCORD_BOT_TOKEN', required: false, secret: true, description: 'Discord bot token' },
+    { name: 'DISCORD_APPLICATION_ID', required: false, description: 'Discord application ID' },
+    { name: 'DISCORD_PUBLIC_KEY', required: false, description: 'Discord public key for verification' },
+    { name: 'DISCORD_CLIENT_SECRET', required: false, secret: true, description: 'Discord client secret for OAuth' },
+    // Integrations - Telegram
+    { name: 'TELEGRAM_BOT_TOKEN', required: false, secret: true, description: 'Telegram bot token from BotFather' },
+    // Integrations - WhatsApp
+    { name: 'WHATSAPP_ACCESS_TOKEN', required: false, secret: true, description: 'WhatsApp Business API access token' },
+    { name: 'WHATSAPP_PHONE_NUMBER_ID', required: false, description: 'WhatsApp Business phone number ID' },
+    { name: 'WHATSAPP_VERIFY_TOKEN', required: false, secret: true, description: 'WhatsApp webhook verify token' },
+    // Search
+    { name: 'SEARXNG_URL', required: false, default: 'https://searx.tiekoetter.com', description: 'SearXNG instance for web search' },
+    // Embeddings
+    { name: 'EMBEDDING_PROVIDER', required: false, default: 'local', description: 'Embedding provider: local, openai, voyage' },
+    { name: 'VOYAGE_API_KEY', required: false, secret: true, description: 'Voyage AI API key for embeddings' },
+];
+/**
+ * Validate all environment variables
+ */
+export function validateEnvironment(options = {}) {
+    const { exitOnError = false, logResults = true } = options;
+    const result = {
+        valid: true,
+        errors: [],
+        warnings: [],
+        loaded: {},
+    };
+    for (const spec of ENV_SPEC) {
+        const value = process.env[spec.name];
+        if (!value && spec.required) {
+            result.valid = false;
+            result.errors.push(`Missing required environment variable: ${spec.name} - ${spec.description}`);
+        }
+        else if (!value && spec.default) {
+            // Apply default
+            process.env[spec.name] = spec.default;
+            result.loaded[spec.name] = spec.default;
+            if (logResults) {
+                log.debug(`Using default for ${spec.name}: ${spec.secret ? '[HIDDEN]' : spec.default}`);
+            }
+        }
+        else if (value) {
+            result.loaded[spec.name] = value;
+            // Run custom validation if provided
+            if (spec.validate) {
+                const validateResult = spec.validate(value);
+                if (validateResult !== true) {
+                    result.valid = false;
+                    result.errors.push(`Invalid value for ${spec.name}: ${validateResult}`);
+                }
+            }
+        }
+    }
+    // Cross-validation checks
+    if (process.env.STORAGE_TIER === 'libsql' && !process.env.LIBSQL_URL) {
+        result.valid = false;
+        result.errors.push('STORAGE_TIER=libsql requires LIBSQL_URL to be set');
+    }
+    // Warnings for missing optional but recommended vars
+    const hasAnyAIKey = process.env.ANTHROPIC_API_KEY ||
+        process.env.OPENAI_API_KEY ||
+        process.env.GOOGLE_AI_API_KEY;
+    if (!hasAnyAIKey) {
+        result.warnings.push('No AI provider configured. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_AI_API_KEY for AI features.');
+    }
+    // Log results
+    if (logResults) {
+        if (result.errors.length > 0) {
+            log.error('Environment validation failed:');
+            result.errors.forEach(err => log.error(`  ❌ ${err}`));
+        }
+        if (result.warnings.length > 0) {
+            result.warnings.forEach(warn => log.warn(`  ⚠️  ${warn}`));
+        }
+        if (result.valid && result.errors.length === 0) {
+            log.info('Environment validation passed ✓');
+        }
+    }
+    // Exit if configured to do so
+    if (!result.valid && exitOnError) {
+        log.error('Server startup aborted due to environment errors. Fix the issues above and restart.');
+        process.exit(1);
+    }
+    return result;
+}
+/**
+ * Get a summary of configured integrations
+ */
+export function getConfiguredIntegrations() {
+    const integrations = [];
+    if (process.env.GITHUB_TOKEN || process.env.GITHUB_CLIENT_ID)
+        integrations.push('GitHub');
+    if (process.env.JIRA_CLIENT_ID)
+        integrations.push('JIRA');
+    if (process.env.LINEAR_API_KEY)
+        integrations.push('Linear');
+    if (process.env.SLACK_BOT_TOKEN)
+        integrations.push('Slack');
+    if (process.env.DISCORD_BOT_TOKEN)
+        integrations.push('Discord');
+    if (process.env.TELEGRAM_BOT_TOKEN)
+        integrations.push('Telegram');
+    if (process.env.WHATSAPP_ACCESS_TOKEN)
+        integrations.push('WhatsApp');
+    return integrations;
+}
+/**
+ * Get a summary of configured AI providers
+ */
+export function getConfiguredAIProviders() {
+    const providers = [];
+    if (process.env.ANTHROPIC_API_KEY)
+        providers.push('Anthropic (Claude)');
+    if (process.env.OPENAI_API_KEY)
+        providers.push('OpenAI (GPT)');
+    if (process.env.GOOGLE_AI_API_KEY)
+        providers.push('Google (Gemini)');
+    if (process.env.AZURE_OPENAI_API_KEY)
+        providers.push('Azure OpenAI');
+    if (process.env.OLLAMA_URL)
+        providers.push('Ollama (local)');
+    return providers;
+}
+/**
+ * Generate .env.example content
+ */
+export function generateEnvExample() {
+    const lines = [
+        '# profClaw Environment Configuration',
+        '# Generated from ENV_SPEC in src/utils/env-validator.ts',
+        '# Copy this file to .env and fill in your values',
+        '',
+    ];
+    let currentCategory = '';
+    for (const spec of ENV_SPEC) {
+        // Add category headers based on name patterns
+        const category = spec.name.split('_')[0];
+        if (category !== currentCategory) {
+            currentCategory = category;
+            lines.push('');
+            lines.push(`# ─── ${getCategory(spec.name)} ───`);
+        }
+        // Add description and example
+        lines.push(`# ${spec.description}`);
+        if (spec.default) {
+            lines.push(`${spec.name}=${spec.default}`);
+        }
+        else if (spec.secret) {
+            lines.push(`# ${spec.name}=your_secret_here`);
+        }
+        else {
+            lines.push(`# ${spec.name}=`);
+        }
+    }
+    return lines.join('\n');
+}
+function getCategory(name) {
+    const prefix = name.split('_')[0];
+    const categories = {
+        PORT: 'Server',
+        NODE: 'Server',
+        STORAGE: 'Storage',
+        LIBSQL: 'Storage',
+        DATA: 'Storage',
+        REDIS: 'Queue',
+        ENABLE: 'Features',
+        CORS: 'Security',
+        ANTHROPIC: 'AI Providers',
+        OPENAI: 'AI Providers',
+        GOOGLE: 'AI Providers',
+        AZURE: 'AI Providers',
+        OLLAMA: 'AI Providers',
+        GITHUB: 'GitHub Integration',
+        JIRA: 'JIRA Integration',
+        LINEAR: 'Linear Integration',
+        SLACK: 'Slack Integration',
+        DISCORD: 'Discord Integration',
+        TELEGRAM: 'Telegram Integration',
+        WHATSAPP: 'WhatsApp Integration',
+        SEARXNG: 'Search',
+        EMBEDDING: 'Embeddings',
+        VOYAGE: 'Embeddings',
+    };
+    return categories[prefix] || 'Other';
+}
+//# sourceMappingURL=env-validator.js.map