Merge branch 'main' of github.com:devforth/adminforth

Author: NoOne7135

AGENTS.md

@@ -183,7 +183,7 @@ For impossible states, prefer failing loudly in development rather than hiding t
 
 ---
 
-## Code review rules for agents
+## Code rules for agents
 
 Before writing extra guards, ask:
 

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/03-Customization/12-security.md

@@ -53,6 +53,7 @@ new AdminForth({
 
 The format is `requests/period`, where period can use `s`, `m`, `h`, or `d`.
 Because rate limits are keyed by client IP, configure `auth.clientIpHeader` when AdminForth runs behind a trusted CDN or reverse proxy. See [Trusting client IP addresses](#trusting-client-ip-addresses).
+> It is important to provide '`auth.clientIpHeader`, because otherwise adminforth will automatically detect client IP in headers and if you don't use proxy, hacker can change IP like `x-forwarded-for: 1.1.1.1` in request headers and skip rate limit 
 
 
 ## Password strength

adminforth/documentation/docs/tutorial/03-Customization/13-standardPagesTuning.md

@@ -542,6 +542,26 @@ And `edit` action will be available as quick action:
      
 
 
+## Show
+
+### Next record button
+
+By default, when a user opens a record from the list view, a **Next** button appears on the show page. It allows navigating through records one by one, respecting the current filters and sorting applied in the list. When the user reaches the last record on the current page, AdminForth automatically fetches the next page and continues navigation seamlessly.
+
+To disable the Next button for a resource, set `showNextButton` to `false`:
+
+```typescript title="./resources/apartments.ts"
+export default {
+  resourceId: 'aparts',
+  options: {
+//diff-add
+    showNextButton: false,
+  }
+}
+```
+
+> ☝️ The Next button is only shown when the user navigates to the show page from the list view. Opening a record directly via URL will not display the button.
+
 ## Creating
 
 ### Fill with default values

adminforth/documentation/docs/tutorial/05-deploy.md

@@ -19,6 +19,7 @@ You can use it to build your AdminForth application in Docker container.
 > at build time. If you will remove it, your AdminForth application will still work, but will cause some downtime during app restart/redeploy because bundling will happen at runtime after you start the `index.ts` file. When `npx adminforth bundle` command is executed at build time, the call do `bundleNow()` inside of `index.ts` file will actually do nothing.
 
 
+
 ## Building the image
 
 Now you can build your image:
@@ -41,6 +42,33 @@ docker run -p 3500:3500 \
 
 Now open your browser and go to `http://localhost:3500` to see your AdminForth application running in Docker container.
 
+
+## Reducing docker image build time
+
+By default `Dockerfile` created by adminforth CLI is configured in a way to rebuild adminforth SPA from scratch on every build:
+
+```
+RUN pnpm/npm adminforth bundle
+```
+
+If you want to speed up your build, you can use Docker cache for /tmp folder and change this line to:
+
+```
+RUN --mount=type=cache,target=/tmp pnpm/npm adminforth bundle
+```
+
+This will cache all /tmp folder between builds and speed up the build process significantly. However you need to ensure that your build daemon persists cache from `--mount=type=cache` mounts. Most of vendor CI build daemons like Github actions Default runner will not persist cache between builds so adding `--mount=type=cache` will not help in such case and you need to use dedicated caching solutions.
+
+To verify build performance locally you can do next:
+1) Modify any custom vue file
+2) Run `docker build -t myadminapp .`. This populates docker cache with bundled SPA
+3) Modify same cusom vue file again
+4) Run `time docker build -t myadminapp .` and check resulting time.
+
+First we recommend repeat steps 1-4 without `--mount=type=cache` on your docker daemon to see how much time it takes to build without cache and then add `--mount=type=cache` and repeat steps 1-4 again to see the difference in build times. Then experiment with your CI caching solution to achieve similar build times.
+
+
+
 ## Automating deployments with CI
 
 If you are looking for a professional way to deploy your AdminForth application, you can follow our blog post [how to deploy your AdminForth application with Terraform From GitHub actions](https://adminforth.dev/blog/compose-aws-ec2-ecr-terraform-github-actions/)

adminforth/documentation/docs/tutorial/06-Adapters/02-oauth2-adapters.md

@@ -59,7 +59,7 @@ Adds support for Twitch authentication, useful for streaming or creator-oriented
 ## Clerk OAuth Adapter
 
 ```bash
-pnpm i @adminforth/clerk-oauth-adapter
+pnpm i @adminforth/oauth-adapter-clerk
 ```
 
 Enables sign-in via [Clerk](https://clerk.com/) — a hosted authentication platform with built-in user management, MFA, and social logins.

adminforth/documentation/docs/tutorial/09-Plugins/01-agent.md

@@ -17,8 +17,8 @@ It stores session history in your own resources and generates responses using on
 ## Installation
 
 ```bash
-pnpm i @adminforth/agent --save
-pnpm i @adminforth/completion-adapter-openai-responses --save
+pnpm add @adminforth/agent --save
+pnpm add @adminforth/completion-adapter-openai-responses --save
 ```
 
 Add your LLM credentials to `.env`:
@@ -197,17 +197,17 @@ export const admin = new AdminForth({
 });
 ```
 
-Then attach the plugin once, usually to your `adminuser` resource:
+Then attach the plugin once in `index.ts` as global plugin:
 
 Configure the plugin with `modes`. The legacy top-level `completionAdapter` setup is no longer used.
 
-```ts title="./resources/adminuser.ts"
+```ts title="./index.ts"
 import AdminForthAgent from '@adminforth/agent';
 import CompletionAdapterOpenAIResponses from '@adminforth/completion-adapter-openai-responses';
 
 ...
 
-plugins: [
+globalPlugins: [
   ...
   new AdminForthAgent({
     // optional, can be used to suggest example prompts in the UI
@@ -462,7 +462,7 @@ pnpm makemigration --name add-adminforth-agent-turn-debug ; pnpm migrate:local
 
 Tell the plugin where to store debug data:
 
-```ts title="./resources/adminuser.ts"
+```ts title="index.ts"
 new AdminForthAgent({
   modes: [
     ...
@@ -604,7 +604,7 @@ pnpm add @adminforth/audio-adapter-openai
 
 2) Import it in your users resource and add to the plugin config
 
-```ts title="./resources/adminuser.ts"
+```ts title="index.ts"
   //diff-add
   import OpenAIAudioAdapter from '@adminforth/audio-adapter-openai'
 
@@ -1010,7 +1010,7 @@ export const admin = new AdminForth({
 
 Then connect it to the plugin:
 
-```ts title="./resources/adminuser.ts"
+```ts title="index.ts"
 new AdminForthAgent({
   modes: [
     ...