feat: implement plugin support for global settings, allowing plugins to define and manage their own settings and groups

Author: Lasim

services/backend/GLOBAL_SETTINGS.md

@@ -501,9 +501,9 @@ const isSmtpReady = await GlobalSettingsInitService.isSmtpConfigured();
 const isGitHubReady = await GlobalSettingsInitService.isGitHubOAuthConfigured();
 ```
 
-### Adding New Setting Groups
+### Adding New Setting Groups (Core)
 
-To add a new setting group:
+To add a new core setting group (managed directly by the application):
 
 1. **Create Setting File**: Add a new `.ts` file in `src/global-settings/`
 
@@ -691,6 +691,17 @@ The new group-based system replaces the old category-based approach. The migrati
 2. **Auto-Initialization**: Groups are created automatically from setting definitions
 3. **Setting Linking**: Existing settings are linked to appropriate groups
 
+## Plugin-Contributed Global Settings
+
+In addition to core global settings, plugins can also define and register their own global settings and setting groups. These are managed through the same system and are subject to the same access controls (i.e., editable by `global_admin`).
+
+Key points for plugin-contributed settings:
+
+- **Declaration**: Plugins declare global settings via a `globalSettingsExtension` property in their main class.
+- **Initialization**: The `PluginManager` processes these definitions at startup, creating new groups and settings if they don't already exist.
+- **Precedence**: Core global settings always take precedence. If a plugin tries to define a setting with a key that already exists (either from core or another plugin), the plugin's definition for that specific key is ignored.
+- **Documentation**: For details on how plugins can define global settings, refer to the [PLUGINS.MD](PLUGINS.MD) document.
+
 ## API Reference Summary
 
 | Endpoint | Method | Permission | Description |

services/backend/PLUGINS.md

@@ -210,6 +210,7 @@ Plugins receive access to:
 - **Fastify instance** (`app`) - For registering routes, hooks, and decorations
 - **Database instance** (`db`) - For database operations
 - **Configuration** - Through the plugin manager (if provided)
+- **Global Settings** - Plugins can define their own global settings
 
 ## Plugin Lifecycle
 
@@ -308,6 +309,112 @@ See the `plugins/example-plugin` directory for a working example.
 
 The complete Plugin interface is defined in `src/plugin-system/types.ts`.
 
+## Defining Global Settings via Plugins
+
+Plugins can contribute their own global settings to the DeployStack system. These settings will be managed alongside core global settings and will be editable by users with the `global_admin` role.
+
+### How it Works
+
+1. **Define `globalSettingsExtension`**: In your plugin class, add an optional property `globalSettingsExtension`.
+2. **Structure**: This property should be an object implementing the `GlobalSettingsExtension` interface (defined in `src/plugin-system/types.ts`). It can contain:
+
+- `groups`: An optional array of `GlobalSettingGroupForPlugin` objects to define new setting groups.
+- `settings`: A mandatory array of `GlobalSettingDefinitionForPlugin` objects to define individual settings.
+
+3. **Initialization**: During server startup, the `PluginManager` will:
+
+- Collect all group and setting definitions from active plugins.
+- Create any new groups defined by plugins if they don't already exist. If a group ID already exists, the plugin's group definition is ignored for that specific group, and the existing group is used.
+- Initialize the plugin's global settings with their default values, but only if a setting with the same key doesn't already exist (either from core settings or another plugin). Core settings always take precedence.
+
+4. **Access Control**: All plugin-defined global settings are subject to the same access control as core settings (i.e., manageable by `global_admin`).
+
+5. **Security**:
+
+- **Core Precedence**: Core global settings (defined in `services/backend/src/global-settings/`) cannot be overridden by plugins.
+- **Duplicate Keys**: If a plugin attempts to register a setting with a key that already exists (from core or another plugin), the plugin's setting will be ignored, and a warning will be logged.
+
+### Example: Defining Global Settings in a Plugin
+
+```typescript
+// In your plugin's index.ts
+
+import { 
+  type Plugin, 
+  type GlobalSettingsExtension,
+  // ... other imports
+} from '../../plugin-system/types';
+
+class MyAwesomePlugin implements Plugin {
+  meta = {
+    id: 'my-awesome-plugin',
+    name: 'My Awesome Plugin',
+    version: '1.0.0',
+    // ... other metadata
+  };
+
+  globalSettingsExtension: GlobalSettingsExtension = {
+    groups: [
+      {
+        id: 'my_awesome_plugin_group', // Unique ID for the group
+        name: 'My Awesome Plugin Config',
+        description: 'Settings specific to My Awesome Plugin.',
+        icon: 'settings-2', // Example: Lucide icon name
+        sort_order: 150,    // Controls tab order in UI
+      }
+    ],
+    settings: [
+      {
+        key: 'myAwesomePlugin.features.enableSuperFeature',
+        defaultValue: 'true',
+        description: 'Enables the super feature of this plugin.',
+        encrypted: false,
+        required: false,
+        groupId: 'my_awesome_plugin_group', // Link to the group defined above
+      },
+      {
+        key: 'myAwesomePlugin.credentials.externalApiKey',
+        defaultValue: '',
+        description: 'API key for an external service used by this plugin.',
+        encrypted: true, // Sensitive value, will be encrypted
+        required: true,
+        groupId: 'my_awesome_plugin_group',
+      },
+      {
+        // Example of a setting not belonging to a new custom group
+        // It might appear in a default group or ungrouped in the UI,
+        // or you can assign it to an existing core group ID if appropriate.
+        key: 'myAwesomePlugin.performance.cacheDurationSeconds',
+        defaultValue: '3600',
+        description: 'Cache duration in seconds for plugin data.',
+        encrypted: false,
+        required: false,
+        // groupId: 'system', // Example: if you want to add to an existing core group
+      }
+    ]
+  };
+
+  // ... rest of your plugin implementation (databaseExtension, initialize, etc.)
+  async initialize(app: FastifyInstance, db: AnyDatabase | null) {
+    console.log(`[${this.meta.id}] Initializing...`);
+    
+    // You can try to access your plugin's settings here if needed during init,
+    // using GlobalSettingsService.get('myAwesomePlugin.features.enableSuperFeature')
+    // Note: Ensure GlobalSettingsService is available or handle potential errors.
+  }
+}
+
+export default MyAwesomePlugin;
+```
+
+### Important Considerations
+
+- **Key Uniqueness**: Ensure your setting keys are unique, preferably prefixed with your plugin ID (e.g., `yourPluginId.category.settingName`) to avoid conflicts.
+- **Group IDs**: If defining new groups, ensure their IDs are unique.
+- **Default Values**: Provide sensible default values.
+- **Encryption**: Mark sensitive settings (API keys, passwords) with `encrypted: true`.
+- **Documentation**: Document any global settings your plugin introduces in its own README or documentation.
+
 ---
 
 For additional questions or support, please contact the DeployStack team or open an issue on GitHub.

services/backend/src/plugin-system/plugin-manager.ts

@@ -9,7 +9,10 @@ import {
   type Plugin, 
   type PluginPackage, 
   type PluginConfiguration,
-  type PluginOptions 
+  type PluginOptions,
+  type GlobalSettingsExtension,
+  type GlobalSettingDefinitionForPlugin,
+  type GlobalSettingGroupForPlugin
 } from './types';
 import { 
   PluginLoadError, 
@@ -18,6 +21,7 @@ import {
   PluginDuplicateError,
   PluginNotFoundError 
 } from './errors';
+import { GlobalSettingsService } from '../services/globalSettingsService';
 
 /**
  * Plugin manager class responsible for loading and managing plugins
@@ -262,6 +266,106 @@ export class PluginManager {
     return this.getAllPlugins().filter(plugin => plugin.databaseExtension);
   }
 
+  /**
+   * Get all global setting groups defined by plugins
+   */
+  getPluginGlobalSettingGroups(): GlobalSettingGroupForPlugin[] {
+    const allGroups: GlobalSettingGroupForPlugin[] = [];
+    const groupIds = new Set<string>();
+
+    for (const plugin of this.plugins.values()) {
+      if (plugin.globalSettingsExtension?.groups) {
+        for (const group of plugin.globalSettingsExtension.groups) {
+          if (!groupIds.has(group.id)) {
+            allGroups.push(group);
+            groupIds.add(group.id);
+          } else {
+            console.warn(`[PluginManager] Duplicate group ID '${group.id}' defined by plugin '${plugin.meta.id}'. Ignoring subsequent definition.`);
+          }
+        }
+      }
+    }
+    return allGroups;
+  }
+
+  /**
+   * Get all global setting definitions from plugins
+   */
+  getPluginGlobalSettingDefinitions(): { pluginId: string, definition: GlobalSettingDefinitionForPlugin }[] {
+    const allDefinitions: { pluginId: string, definition: GlobalSettingDefinitionForPlugin }[] = [];
+    for (const plugin of this.plugins.values()) {
+      if (plugin.globalSettingsExtension?.settings) {
+        plugin.globalSettingsExtension.settings.forEach(definition => {
+          allDefinitions.push({ pluginId: plugin.meta.id, definition });
+        });
+      }
+    }
+    return allDefinitions;
+  }
+  
+  /**
+   * Initialize global settings defined by plugins.
+   * This should be called after core settings are initialized.
+   */
+  async initializePluginGlobalSettings(): Promise<void> {
+    console.log('[PluginManager] Initializing global settings from plugins...');
+    const pluginGroups = this.getPluginGlobalSettingGroups();
+    const pluginSettings = this.getPluginGlobalSettingDefinitions();
+
+    // Initialize groups first
+    for (const group of pluginGroups) {
+      try {
+        // Check if group exists (this logic might need to be in GlobalSettingsService or InitService)
+        // For now, we assume GlobalSettingsService.set will handle linking to existing group or we manage group creation here.
+        // Let's try to create/ensure group exists. This is a simplified version.
+        // A more robust solution would use a method like GlobalSettingsInitService.createGroup
+        const existingGroup = await GlobalSettingsService.getGroup(group.id); // Assuming getGroup exists
+        if (!existingGroup) {
+          // Attempt to create the group if it doesn't exist.
+          await GlobalSettingsService.createGroup(group); 
+          console.log(`[PluginManager] Created global setting group ID '${group.id}' (Name: "${group.name}") as defined by a plugin.`);
+        } else {
+          // Group ID already exists. Log that the plugin's definition for this group ID (name, description, etc.) is ignored.
+          console.warn(`[PluginManager] Global setting group ID '${group.id}' already exists (Existing Name: "${existingGroup.name}"). Plugin's attempt to define a group with this ID (Plugin's proposed Name: "${group.name}") will use the existing group. Plugin-specific metadata for this group ID (name, description, icon, sort_order) is ignored.`);
+        }
+      } catch (error) {
+        console.error(`[PluginManager] Error processing plugin-defined group '${group.id}' (Plugin's proposed Name: "${group.name}"):`, error);
+      }
+    }
+
+    // Initialize settings
+    const initializedKeys = new Set<string>();
+    // First, get all existing core setting keys to ensure precedence
+    try {
+      const coreSettings = await GlobalSettingsService.getAll();
+      coreSettings.forEach(cs => initializedKeys.add(cs.key));
+    } catch (error) {
+      console.error('[PluginManager] Failed to get all core settings for precedence check:', error);
+      // If this fails, we might risk overwriting, but proceed with caution.
+    }
+
+
+    for (const { pluginId, definition } of pluginSettings) {
+      if (initializedKeys.has(definition.key)) {
+        console.warn(`[PluginManager] Global setting key '${definition.key}' from plugin '${pluginId}' already exists (core or another plugin). Skipping.`);
+        continue;
+      }
+
+      try {
+        await GlobalSettingsService.set(definition.key, definition.defaultValue, {
+          description: definition.description,
+          encrypted: definition.encrypted,
+          group_id: definition.groupId,
+        });
+        initializedKeys.add(definition.key); // Add to set after successful initialization
+        console.log(`[PluginManager] Initialized global setting '${definition.key}' from plugin '${pluginId}'.`);
+      } catch (error) {
+        console.error(`[PluginManager] Failed to initialize global setting '${definition.key}' from plugin '${pluginId}':`, error);
+      }
+    }
+    console.log('[PluginManager] Plugin global settings initialization complete.');
+  }
+
   /**
    * Initialize all loaded plugins
    */

services/backend/src/plugin-system/types.ts

@@ -3,6 +3,40 @@ import { type FastifyInstance } from 'fastify';
 // import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'; // Replaced by AnyDatabase
 import { type AnyDatabase } from '../db'; // Import AnyDatabase
 
+/**
+ * Definition for a global setting that can be provided by a plugin.
+ * Mirrors parts of GlobalSettingDefinition from global-settings/types.ts
+ * but is defined here to avoid circular dependencies.
+ */
+export interface GlobalSettingDefinitionForPlugin {
+  key: string;
+  defaultValue: string;
+  description: string;
+  encrypted: boolean;
+  required?: boolean; // Optional: if the setting must have a value
+  groupId?: string; // Optional: if this setting belongs to a specific group
+}
+
+/**
+ * Definition for a global setting group that can be provided by a plugin.
+ * Mirrors GlobalSettingGroup from global-settings/types.ts
+ */
+export interface GlobalSettingGroupForPlugin {
+  id: string;
+  name: string;
+  description?: string;
+  icon?: string;
+  sort_order?: number;
+}
+
+/**
+ * Interface for plugins to declare global settings and groups.
+ */
+export interface GlobalSettingsExtension {
+  groups?: GlobalSettingGroupForPlugin[];
+  settings: GlobalSettingDefinitionForPlugin[];
+}
+
 /**
  * Plugin metadata interface
  */
@@ -49,6 +83,11 @@ export interface Plugin {
    * Optional database extension
    */
   databaseExtension?: DatabaseExtension;
+
+  /**
+   * Optional global settings extension
+   */
+  globalSettingsExtension?: GlobalSettingsExtension;
 
   /**
    * Initialize the plugin

services/backend/src/plugins/example-plugin/index.ts

@@ -1,5 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Plugin, type DatabaseExtension } from '../../plugin-system/types';
+import { 
+  type Plugin, 
+  type DatabaseExtension,
+  type GlobalSettingsExtension,
+  type GlobalSettingDefinitionForPlugin,
+  type GlobalSettingGroupForPlugin
+} from '../../plugin-system/types';
 import { type FastifyInstance } from 'fastify';
 import { type AnyDatabase, getSchema } from '../../db'; // Import getSchema
 import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'; // For type guard
@@ -35,6 +41,44 @@ class ExamplePlugin implements Plugin {
     description: 'An example plugin for DeployStack',
     author: 'DeployStack Team',
   };
+
+  // Define global settings provided by this plugin
+  globalSettingsExtension: GlobalSettingsExtension = {
+    groups: [
+      {
+        id: 'example_plugin_settings',
+        name: 'Example Plugin Settings',
+        description: 'Configuration for the Example Plugin.',
+        icon: 'puzzle', // Example icon (Lucide icon name)
+        sort_order: 100, // Example sort order
+      },
+    ],
+    settings: [
+      {
+        key: 'examplePlugin.config.featureEnabled',
+        defaultValue: 'false',
+        description: 'Enable or disable a specific feature in the example plugin.',
+        encrypted: false,
+        required: false,
+        groupId: 'example_plugin_settings',
+      },
+      {
+        key: 'examplePlugin.secret.apiKey',
+        defaultValue: '',
+        description: 'API Key for an external service used by the example plugin.',
+        encrypted: true,
+        required: false,
+        groupId: 'example_plugin_settings',
+      },
+      { // Example of a setting not in a custom group (will go to default or no group)
+        key: 'examplePlugin.general.logLevel',
+        defaultValue: 'info',
+        description: 'Logging level for the example plugin.',
+        encrypted: false,
+        required: false,
+      }
+    ],
+  };
 
   // Database extension
   databaseExtension: DatabaseExtension = {
@@ -43,7 +87,7 @@ class ExamplePlugin implements Plugin {
     // Optional initialization function
     // Use arrow function to correctly capture 'this' for access to this.meta.id
     onDatabaseInit: async (db: AnyDatabase) => {
-      console.log('Initializing example plugin database...');
+      console.log(`[${this.meta.id}] Initializing example plugin database...`);
 
       const currentSchema = getSchema();
       // 'this' here refers to the ExamplePlugin instance because of the arrow function