Merge pull request #680 from devforth/next

Next

Author: yaroslav8765

adminforth/basePlugin.ts

@@ -20,6 +20,7 @@ export default class AdminForthPlugin implements IAdminForthPlugin {
   resourceConfig: AdminForthResource;
   className: string;
   activationOrder: number = 0;
+  pluginsScope: 'resource' | 'global' = 'resource';
   shouldHaveSingleInstancePerWholeApp?: () => boolean;
 
   constructor(pluginOptions: any, metaUrl: string) {
@@ -41,14 +42,27 @@ export default class AdminForthPlugin implements IAdminForthPlugin {
   }
 
 
+  initializePluginInstanceId = (resourceConfig?: AdminForthResource) => {
+    const uniqueness = this.instanceUniqueRepresentation(this.pluginOptions);
+    let seed = '';
+    if (resourceConfig) {
+      seed = `af_pl_${this.constructor.name}_${resourceConfig?.resourceId || '_'}_${uniqueness}`;
+    } else {
+      seed = `af_pl_${this.constructor.name}_global_${uniqueness}`;
+    }
+    this.pluginInstanceId = md5hash(seed);
+    afLogger.trace({seed, pluginInstanceId: this.pluginInstanceId}, `🪲 AdminForthPlugin.initializePluginInstanceId`);
+  }
+
   modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource, allPluginInstances?: {pi: AdminForthPlugin, resource: AdminForthResource}[]) {
     this.resourceConfig = resourceConfig;
-    const uniqueness = this.instanceUniqueRepresentation(this.pluginOptions);
+    this.initializePluginInstanceId(resourceConfig);
+    this.adminforth = adminforth;
+  }
 
-    const seed = `af_pl_${this.constructor.name}_${resourceConfig.resourceId}_${uniqueness}`;
-    this.pluginInstanceId = md5hash(seed);
-    afLogger.trace({seed, pluginInstanceId: this.pluginInstanceId}, `🪲 AdminForthPlugin.modifyResourceConfig`);
+  modifyGlobalConfig(adminforth: IAdminForth) {
     this.adminforth = adminforth;
+    this.initializePluginInstanceId();
   }
 
   /** 

adminforth/commands/createApp/templates/globalPlugins.ts.hbs

@@ -0,0 +1 @@
+export const globalPlugins = []

adminforth/commands/createApp/templates/index.ts.hbs

@@ -6,6 +6,7 @@ import path from 'path';
 import { Filters } from 'adminforth';
 import { initApi } from './api.js';
 import { logger } from 'adminforth';
+import { globalPlugins } from './globalPlugins.js';
 
 const ADMIN_BASE_URL = '';
 
@@ -66,6 +67,7 @@ export const admin = new AdminForth({
       resourceId: 'adminuser'
     },
   ],
+  globalPlugins: globalPlugins,
 });
 
 if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {

adminforth/commands/createApp/utils.js

@@ -428,6 +428,11 @@ async function writeTemplateFiles(dirname, cwd, useNpm, includePrismaMigrations,
       src: 'custom/package.json.hbs',
       dest: 'custom/package.json',
       data: {}
+    },
+    {
+      src: 'globalPlugins.ts.hbs',
+      dest: 'globalPlugins.ts',
+      data: {},
     }
   ];
 

adminforth/documentation/docs/tutorial/10-Advanced/01-plugin-development.md

@@ -510,6 +510,42 @@ Default value of activationOrder for most plugins is `0`. Plugins with higher ac
 
 To ensure that plugin activates before some other plugins set `activationOrder` to negative value.
 
+## Making plugin global
+
+Each plugin should define a scope: resource-level or global level. 
+* Resource-level plugins should be used when plugin instance works only with one resource config or it's fields. Instances of resource-scope plugins should be installed into "plugins' field of resource config. 
+* All other plugins should be global-scoped. Such plugins are installed to `globalPlugins` of root adminforth config. They might modify configs of many resources like default AuditLog plugin or use several database resources to store data like default Agent plugin.
+
+To make your plugin global, you need to use `pluginsScope: 'global'` and `modifyGlobalConfig` instead of `modifyResourceConfig`
+
+
+```ts title="./your-global-plugin/index.ts"
+
+  ...
+
+  export default class YourPugin extends AdminForthPlugin {
+    options: PluginOptions;
+    //diff-add
+    pluginsScope: 'global'
+
+  ...
+
+  //diff-remove
+  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
+    //diff-remove
+    super.modifyResourceConfig(adminforth, resourceConfig);
+  //diff-add
+  modifyGlobalConfig(adminforth: IAdminForth) {
+    //diff-add
+    super.modifyGlobalConfig(adminforth);
+
+  }
+
+  ...
+  
+```
+
+
 ## Splitting frontend logic into multiple files
 
 In case your plugin `.vue` files getting too big, you can split them into multiple files (components).

adminforth/index.ts

@@ -3,7 +3,7 @@ import CodeInjector from './modules/codeInjector.js';
 import ExpressServer from './servers/express.js';
 import OpenApiRegistry from './servers/openapi.js';
 // import FastifyServer from './servers/fastify.js';
-import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, getClientIp, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError, md5hash, applyRegexValidation } from './modules/utils.js';
+import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, getClientIp, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError, md5hash, applyRegexValidation, formatHugePluginError } from './modules/utils.js';
 import { 
   type AdminForthConfig, 
   type IAdminForth, 
@@ -290,13 +290,21 @@ class AdminForth implements IAdminForth {
   activatePlugins() {
     afLogger.trace('🔌🔌🔌 Activating plugins');
     const allPluginInstances = [];
+    const globalPlugins = this.config.globalPlugins || [];
     for (let resource of this.config.resources) {
       afLogger.trace(`🔌 Checking plugins for resource: ${resource.resourceId}`);
       for (let pluginInstance of resource.plugins || []) {
         afLogger.trace(`🔌 Found plugin: ${pluginInstance.constructor.name} for resource ${resource.resourceId}`);
+        if (pluginInstance.pluginsScope === 'global') {
+          throw new Error(formatHugePluginError(`Please move plugin ${pluginInstance.constructor.name} instance to index.ts config.globalPlugins array.
+            Details: Previously adminforth had only resource-level plugins. To keep project structure clean, in recent version of adminforth we introduced globalPlugins. 
+            Global plugins are installed on whole application and not only one resource (like agent, audit logs etc)
+          `));
+        }
         allPluginInstances.push({pi: pluginInstance, resource});
       }
     }
+    allPluginInstances.push(...globalPlugins.map((pluginInstance) => ({pi: pluginInstance, resource: null})));
     afLogger.trace(`🔌 Total plugins to activate: ${allPluginInstances.length}`);
 
     let activationLoopCounter = 0;
@@ -325,8 +333,12 @@ class AdminForth implements IAdminForth {
       unactivatedPlugins.forEach(
         ({pi: pluginInstance, resource}, index) => {
           afLogger.trace(`Activating plugin: ${pluginInstance.constructor.name}`);
-          afLogger.trace(`🔌 Activating plugin ${index + 1}/${unactivatedPlugins.length}: ${pluginInstance.constructor.name} for resource ${resource.resourceId}`);
-          pluginInstance.modifyResourceConfig(this, resource, allPluginInstances);
+          afLogger.trace(`🔌 Activating plugin ${index + 1}/${unactivatedPlugins.length}: ${pluginInstance.constructor.name} for resource ${resource ? resource.resourceId : 'global'}`);
+          if (pluginInstance.pluginsScope === 'global'){
+            pluginInstance.modifyGlobalConfig(this);
+          } else {
+            pluginInstance.modifyResourceConfig(this, resource, allPluginInstances);
+          }
           afLogger.trace(`🔌 Plugin ${pluginInstance.constructor.name} modifyResourceConfig completed`);
 
           const plugin = this.activatedPlugins.find((p) => p.pluginInstanceId === pluginInstance.pluginInstanceId);

adminforth/modules/utils.ts

@@ -572,18 +572,18 @@ export async function cascadeChildrenDelete(resource: AdminForthResource, primar
   return { error: null };
 }
 
-export function hookResponseError(hookResponse: {ok: boolean, error?: string | null}) {
-  if (!hookResponse || typeof hookResponse.ok !== 'boolean') {
-    throw new Error(`Hook beforeSave must return { ok: boolean, error?: string | null }`);
-  }
-  if (hookResponse.ok === false && !hookResponse.error) {
-    return { error: hookResponse.error ?? 'Operation aborted by hook' };
-  }
-  if (hookResponse.error) {
-    return { error: hookResponse.error };
+  export function hookResponseError(hookResponse: {ok: boolean, error?: string | null}) {
+    if (!hookResponse || typeof hookResponse.ok !== 'boolean') {
+      throw new Error(`Hook beforeSave must return { ok: boolean, error?: string | null }`);
+    }
+    if (hookResponse.ok === false && !hookResponse.error) {
+      return { error: hookResponse.error ?? 'Operation aborted by hook' };
+    }
+    if (hookResponse.error) {
+      return { error: hookResponse.error };
+    }
+    return null;
   }
-  return null;
-}
 
 export function checkIfFieldIsInsideResourceColumns(fieldName: string, resource: AdminForthResource): boolean {
   for (const column of resource.columns) {
@@ -622,4 +622,26 @@ export function applyRegexValidation(value, validation) {
       }
     }
   }
-}
+}
+
+ export function formatHugePluginError(message: string) {
+    const RED = '\x1b[31m';
+    const BG = '\x1b[41m';
+    const WHITE = '\x1b[97m';
+    const BOLD = '\x1b[1m';
+    const RESET = '\x1b[0m';
+
+    const horizontal = '═'.repeat(100);
+
+    return `
+  ${BG}${WHITE}${BOLD}
+  ╔${horizontal}╗
+  ║${' '.repeat(100)}║
+  ║  🚨 PLUGIN CONFIGURATION ERROR${' '.repeat(69)}║
+  ║${' '.repeat(100)}║
+  ║  ${message.padEnd(98)}║
+  ║${' '.repeat(100)}║
+  ╚${horizontal}╝
+  ${RESET}
+`;
+  }

adminforth/types/Back.ts

@@ -636,6 +636,7 @@ export interface IAdminForthPlugin {
   pluginOptions: any;
   resourceConfig: AdminForthResource;
   className: string;
+  pluginsScope: 'resource' | 'global';
 
   /**
    * Before activating all plugins are sorted by this number and then activated in order.
@@ -653,7 +654,15 @@ export interface IAdminForthPlugin {
    * @param adminforth Instance of IAdminForth
    * @param resourceConfig Resource configuration object which will be modified by plugin
    */
-  modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource, allPluginInstances?: {pi: IAdminForthPlugin, resource: AdminForthResource}[]): void;
+  modifyResourceConfig?(adminforth: IAdminForth, resourceConfig: AdminForthResource, allPluginInstances?: {pi: IAdminForthPlugin, resource: AdminForthResource}[]): void;
+  
+
+  /**
+   * This method is used for plugins, applied in global scope (pluginsScope = 'global')
+   * @param adminforth Instance of IAdminForth
+   */
+  modifyGlobalConfig?(adminforth: IAdminForth): void;
+
   componentPath(componentFile: string): string;
 
   /**
@@ -1831,6 +1840,10 @@ export interface AdminForthInputConfig {
      */
     componentsToExplicitRegister?: AdminForthComponentDeclarationFull[]
 
+    /**
+     * List of plugins that should be applied in global scope.
+     */
+    globalPlugins?: Array<IAdminForthPlugin>,
 }
 
 

dev-demo/globalPlugins.ts

@@ -0,0 +1,69 @@
+import CompletionAdapterOpenAIResponses from '../adapters/adminforth-completion-adapter-openai-responses/index.js';
+import AdminForthAgent from '../plugins/adminforth-agent/index.js';
+import AdminForthPlugin from '../adminforth/basePlugin.js';
+
+const OVH_AI_ENDPOINTS_BASE_URL = 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1';
+const ovhAiEndpointsAccessToken = process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN;
+const openAiResponsesApiKey = ovhAiEndpointsAccessToken || process.env.OPENAI_API_KEY;
+const usesOvhAiEndpoints = Boolean(ovhAiEndpointsAccessToken);
+
+function createAgentCompletionAdapter(
+  model: string,
+  effort: 'low' | 'medium' | 'xhigh',
+) {
+  return new CompletionAdapterOpenAIResponses({
+    openAiApiKey: openAiResponsesApiKey as string,
+    baseUrl: usesOvhAiEndpoints ? OVH_AI_ENDPOINTS_BASE_URL : undefined,
+    model: usesOvhAiEndpoints ? 'gpt-oss-120b' : model,
+    extraRequestBodyParameters: {
+      ...(usesOvhAiEndpoints ? { store: false } : {}),
+      reasoning: {
+        effort,
+      },
+    },
+  });
+}
+
+export const globalPlugins = [
+  new AdminForthAgent({
+    placeholderMessages: async ({ adminUser, httpExtra }) => {
+      return [
+        "What is a cars count in SQLite",
+        "Build average car price by days chart in SQLite",
+      ]
+    },
+    modes: [
+      {
+        name: 'Balanced',
+        completionAdapter: createAgentCompletionAdapter('gpt-5.4-mini', 'medium'),
+      },
+      {
+        name: 'Fast',
+        completionAdapter: createAgentCompletionAdapter('gpt-5.4-mini', 'low'),
+      },
+      {
+        name: 'Smart Thinking',
+        completionAdapter: createAgentCompletionAdapter('gpt-5.4', 'xhigh'),
+      },
+    ],
+    maxTokens: 10000,
+    reasoning: 'none',
+    sessionResource: {
+      resourceId: 'sessions',
+      idField: 'id',
+      titleField: 'title',
+      turnsField: 'turns',
+      askerIdField: 'asker_id',
+      createdAtField: 'created_at',
+    },
+    turnResource: {
+      resourceId: 'turns',
+      idField: 'id',
+      sessionIdField: 'session_id',
+      createdAtField: 'created_at',
+      promptField: 'prompt',
+      responseField: 'response',
+      debugField: 'dubbug',
+    },
+  }),
+];

dev-demo/index.ts

@@ -34,6 +34,8 @@ import adminExternalIdentitiesResource from './resources/adminUserExternalIdenti
 
 import { logger } from '../adminforth/modules/logger.js';
 
+import { globalPlugins } from './globalPlugins.js';
+
 const ADMIN_BASE_URL = '';
 
 export const admin = new AdminForth({
@@ -241,6 +243,7 @@ export const admin = new AdminForth({
       resourceId: 'turns',
     }
   ],
+  globalPlugins: globalPlugins,
 });
 
 let lastJobId: string | null = null;