feat: implement global settings initialization and define GitHub OAuth and SMTP configuration modules

Author: JasonKrik

services/backend/GLOBAL_SETTINGS.md

@@ -7,11 +7,22 @@ This document describes the global key-value store system for managing applicati
 The global settings system provides secure storage for application-wide configuration values such as:
 
 - **SMTP Server Credentials**: Host, port, username, password for email functionality
+- **OAuth Credentials**: GitHub OAuth client ID and secret for authentication
 - **API Keys**: External service credentials (OpenAI, AWS, etc.)
 - **System Configuration**: Application-wide settings and feature flags
 - **Integration Credentials**: Third-party service authentication tokens
 - **Environment Variables**: Dynamic configuration that can be changed without code deployment
 
+### Auto-Initialization System
+
+The system includes an **auto-initialization feature** that automatically creates missing global settings when the server starts. Settings are defined in modular files within the `src/global-settings/` directory, and the system will:
+
+- Scan for setting definition files on startup
+- Check which settings exist in the database
+- Create missing settings with default values (non-destructive)
+- Preserve existing settings and their values
+- Log initialization results for transparency
+
 ## Key Features
 
 - **Hierarchical Keys**: Dot notation organization (e.g., `smtp.host`, `api.openai.key`)
@@ -487,6 +498,231 @@ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <toke
   -d '{"pattern":"smtp"}' http://localhost:3000/api/settings/search
 ```
 
+## Auto-Initialization System
+
+### Overview
+
+The auto-initialization system automatically creates missing global settings when the server starts. This ensures that all required settings are available without manual configuration, while preserving existing values.
+
+### File-Based Setting Definitions
+
+Settings are defined in TypeScript files within the `src/global-settings/` directory:
+
+```text
+src/global-settings/
+├── types.ts              # Type definitions
+├── index.ts              # Auto-discovery service
+├── smtp.ts               # SMTP configuration
+├── github-oauth.ts       # GitHub OAuth settings
+└── [custom].ts           # Your custom settings
+```
+
+### Setting Definition Format
+
+Each setting file exports a `GlobalSettingsModule`:
+
+```typescript
+// src/global-settings/smtp.ts
+import type { GlobalSettingsModule } from './types';
+
+export const smtpSettings: GlobalSettingsModule = {
+  category: 'smtp',
+  settings: [
+    {
+      key: 'smtp.host',
+      defaultValue: '',
+      description: 'SMTP server hostname (e.g., smtp.gmail.com)',
+      encrypted: false,
+      required: true
+    },
+    {
+      key: 'smtp.password',
+      defaultValue: '',
+      description: 'SMTP authentication password',
+      encrypted: true,
+      required: true
+    }
+    // ... more settings
+  ]
+};
+```
+
+### Startup Behavior
+
+When the server starts:
+
+1. **Discovery**: Scans `src/global-settings/` for `.ts` files
+2. **Loading**: Dynamically imports each settings module
+3. **Validation**: Ensures each module has the correct structure
+4. **Database Check**: Checks which settings exist in the database
+5. **Creation**: Creates missing settings with default values
+6. **Preservation**: Skips existing settings (non-destructive)
+7. **Logging**: Reports initialization results
+
+### Example Startup Output
+
+```text
+🔄 Loading global settings definitions...
+📁 Found 2 setting files: smtp, github-oauth
+✅ Loaded settings module: smtp (7 settings)
+✅ Loaded settings module: github-oauth (5 settings)
+🎉 Loaded 2 settings modules with 12 total settings
+🔄 Initializing 12 global settings...
+✅ Created setting: smtp.host
+✅ Created setting: smtp.port
+✅ Created setting: smtp.username
+✅ Created setting: smtp.password
+⏭️  Skipped existing setting: smtp.secure
+✅ Created setting: github.oauth.client_id
+✅ Created setting: github.oauth.client_secret
+🎉 Global settings initialization complete: 6 created, 1 skipped
+⚠️  Missing required settings: smtp.host, smtp.username, smtp.password
+```
+
+### Built-in Setting Categories
+
+#### SMTP Settings
+
+| Key | Default | Required | Encrypted | Description |
+|-----|---------|----------|-----------|-------------|
+| `smtp.host` | `''` | ✅ | ❌ | SMTP server hostname |
+| `smtp.port` | `'587'` | ✅ | ❌ | SMTP server port |
+| `smtp.username` | `''` | ✅ | ❌ | SMTP authentication username |
+| `smtp.password` | `''` | ✅ | ✅ | SMTP authentication password |
+| `smtp.secure` | `'true'` | ❌ | ❌ | Use SSL/TLS connection |
+| `smtp.from_name` | `'DeployStack'` | ❌ | ❌ | Default sender name |
+| `smtp.from_email` | `''` | ❌ | ❌ | Default sender email |
+
+#### GitHub OAuth Settings
+
+| Key | Default | Required | Encrypted | Description |
+|-----|---------|----------|-----------|-------------|
+| `github.oauth.client_id` | `''` | ❌ | ❌ | GitHub OAuth client ID |
+| `github.oauth.client_secret` | `''` | ❌ | ✅ | GitHub OAuth client secret |
+| `github.oauth.enabled` | `'false'` | ❌ | ❌ | Enable GitHub OAuth |
+| `github.oauth.callback_url` | `'http://localhost:3000/api/auth/github/callback'` | ❌ | ❌ | OAuth callback URL |
+| `github.oauth.scope` | `'user:email'` | ❌ | ❌ | OAuth requested scopes |
+
+### Helper Methods
+
+The system provides helper methods for retrieving complete configurations:
+
+```typescript
+import { GlobalSettingsInitService } from '../global-settings';
+
+// Get complete SMTP configuration
+const smtpConfig = await GlobalSettingsInitService.getSmtpConfiguration();
+if (smtpConfig) {
+  // Use smtpConfig.host, smtpConfig.port, etc.
+}
+
+// Get complete GitHub OAuth configuration
+const githubConfig = await GlobalSettingsInitService.getGitHubOAuthConfiguration();
+if (githubConfig && githubConfig.enabled) {
+  // Use githubConfig.clientId, githubConfig.clientSecret, etc.
+}
+
+// Check if services are configured
+const isSmtpReady = await GlobalSettingsInitService.isSmtpConfigured();
+const isGitHubReady = await GlobalSettingsInitService.isGitHubOAuthConfigured();
+```
+
+### Adding New Setting Categories
+
+To add a new setting category:
+
+1. **Create Setting File**: Add a new `.ts` file in `src/global-settings/`
+
+```typescript
+// src/global-settings/my-service.ts
+import type { GlobalSettingsModule } from './types';
+
+export const myServiceSettings: GlobalSettingsModule = {
+  category: 'my-service',
+  settings: [
+    {
+      key: 'my-service.api_key',
+      defaultValue: '',
+      description: 'API key for My Service',
+      encrypted: true,
+      required: true
+    },
+    {
+      key: 'my-service.enabled',
+      defaultValue: 'false',
+      description: 'Enable My Service integration',
+      encrypted: false,
+      required: false
+    }
+  ]
+};
+```
+
+2. **Restart Server**: The new settings will be automatically discovered and initialized
+
+3. **Add Helper Method** (optional): Add a helper method to `GlobalSettingsInitService`
+
+```typescript
+// In src/global-settings/index.ts
+static async getMyServiceConfiguration(): Promise<MyServiceConfig | null> {
+  const settings = await Promise.all([
+    GlobalSettingsService.get('my-service.api_key'),
+    GlobalSettingsService.get('my-service.enabled')
+  ]);
+  
+  const [apiKey, enabled] = settings;
+  
+  if (enabled?.value !== 'true' || !apiKey?.value) {
+    return null;
+  }
+  
+  return {
+    apiKey: apiKey.value,
+    enabled: enabled.value === 'true'
+  };
+}
+```
+
+### Validation and Health Checks
+
+The system provides validation for required settings:
+
+```typescript
+// Check all required settings
+const validation = await GlobalSettingsInitService.validateRequiredSettings();
+
+if (!validation.valid) {
+  console.log('Missing required settings:', validation.missing);
+  
+  // Check by category
+  for (const [category, info] of Object.entries(validation.categories)) {
+    if (info.missing > 0) {
+      console.log(`${category}: ${info.missing}/${info.total} missing`);
+      console.log('Missing keys:', info.missingKeys);
+    }
+  }
+}
+```
+
+### Best Practices for Setting Definitions
+
+- **Use Clear Keys**: Follow the `category.subcategory.setting` pattern
+- **Provide Descriptions**: Include helpful descriptions for administrators
+- **Mark Sensitive Data**: Set `encrypted: true` for passwords, API keys, secrets
+- **Set Appropriate Defaults**: Use sensible default values when possible
+- **Mark Required Settings**: Set `required: true` for essential settings
+- **Group Related Settings**: Use consistent category names
+
+### Non-Destructive Behavior
+
+The auto-initialization system is **completely non-destructive**:
+
+- ✅ **Preserves existing settings**: Never overwrites existing values
+- ✅ **Only creates missing settings**: Skips settings that already exist
+- ✅ **Maintains user configurations**: Respects administrator changes
+- ✅ **Safe to run repeatedly**: Can be run multiple times without issues
+- ✅ **Logs all actions**: Transparent about what was created vs. skipped
+
 ## Future Enhancements
 
 ### Planned Features

services/backend/src/global-settings/github-oauth.ts

@@ -0,0 +1,42 @@
+import type { GlobalSettingsModule } from './types';
+
+export const githubOAuthSettings: GlobalSettingsModule = {
+  category: 'github-oauth',
+  settings: [
+    {
+      key: 'github.oauth.client_id',
+      defaultValue: '',
+      description: 'GitHub OAuth application client ID',
+      encrypted: false,
+      required: false
+    },
+    {
+      key: 'github.oauth.client_secret',
+      defaultValue: '',
+      description: 'GitHub OAuth application client secret',
+      encrypted: true,
+      required: false
+    },
+    {
+      key: 'github.oauth.enabled',
+      defaultValue: 'false',
+      description: 'Enable GitHub OAuth authentication (true/false)',
+      encrypted: false,
+      required: false
+    },
+    {
+      key: 'github.oauth.callback_url',
+      defaultValue: 'http://localhost:3000/api/auth/github/callback',
+      description: 'GitHub OAuth callback URL',
+      encrypted: false,
+      required: false
+    },
+    {
+      key: 'github.oauth.scope',
+      defaultValue: 'user:email',
+      description: 'GitHub OAuth requested scopes',
+      encrypted: false,
+      required: false
+    }
+  ]
+};