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

AdminForth/1774/find-a-way-to-run-dev-demo-in-

Author: yaroslav8765

adminforth/commands/cli.js

@@ -42,6 +42,61 @@ export function getVersion() {
   return ADMINFORTH_VERSION;
 }
 
+/**
+ * Resolves the adminforth version range to write into a scaffolded package.json.
+ *
+ * Returns a caret range pinned to the latest published release of the dist-tag
+ * matching the running CLI, e.g. "^3.6.12" (installs the latest 3.x.x, never a
+ * major upgrade). For "next" builds the moving "next" tag is kept, since
+ * prerelease versions do not caret cleanly. Falls back to a major-only range
+ * (e.g. "^3.0.0"), and finally to "latest", when the registry is unreachable.
+ */
+export async function resolveAdminforthVersionRange() {
+  // Determine which dist-tag matches the CLI currently running, and derive an
+  // offline fallback range from the CLI's own major version.
+  let tag = 'latest';
+  let offlineFallback = 'latest';
+  try {
+    const version = getVersion();
+    if (typeof version === 'string') {
+      if (version.includes('next')) {
+        tag = 'next';
+      }
+      const major = version.split('.')[0];
+      if (/^\d+$/.test(major)) {
+        offlineFallback = `^${major}.0.0`;
+      }
+    }
+  } catch {
+    // Ignore; fall back to "latest" below.
+  }
+
+  // "next" builds keep the moving tag — prerelease versions don't caret cleanly.
+  if (tag === 'next') {
+    return 'next';
+  }
+
+  try {
+    const res = await fetch('https://registry.npmjs.org/-/package/adminforth/dist-tags', {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) {
+      throw new Error(`registry responded with ${res.status}`);
+    }
+    const distTags = await res.json();
+    const latest = distTags[tag];
+    if (typeof latest !== 'string' || !/^\d+\.\d+\.\d+/.test(latest)) {
+      throw new Error('invalid version received from registry');
+    }
+    return `^${latest}`;
+  } catch (err) {
+    console.warn(
+      `⚠️ Could not resolve AdminForth version from npm registry (${err.message}); defaulting to "${offlineFallback}".`
+    );
+    return offlineFallback;
+  }
+}
+
 function showVersion() {
   const ADMINFORTH_VERSION = getVersion();
 

adminforth/commands/createApp/utils.js

@@ -11,33 +11,14 @@ import { exec } from 'child_process';
 
 import Handlebars from 'handlebars';
 import { promisify } from 'util';
-import { getVersion } from '../cli.js';
+import { resolveAdminforthVersionRange } from '../cli.js';
 
 import { URL } from 'url'
 import net from 'net'
 
 const execAsync = promisify(exec);
 
-function detectAdminforthVersion() {
-  try {
-    const version =  getVersion();
-
-    if (typeof version !== 'string') {
-      throw new Error('Invalid version format');
-    }
-
-    if (version.includes('next')) {
-      return 'next';
-    }
-    return 'latest';
-  } catch (err) {
-    console.warn('⚠️ Could not detect AdminForth version, defaulting to "latest".');
-    return 'latest';
-  }
-}
-
-const adminforthVersion = detectAdminforthVersion();
-const SUPPORTED_DB_URL_SCHEMES = ['sqlite://', 'postgresql://', 'mongodb://', 'mysql://', 'clickhouse://'];
+const SUPPORTED_DB_URL_SCHEMES =['sqlite://', 'postgresql://', 'mongodb://', 'mysql://', 'clickhouse://'];
 const PRISMA_MIGRATION_DB_PROTOCOLS = ['sqlite', 'postgres', 'postgresql', 'mysql'];
 
 
@@ -314,6 +295,7 @@ async function writeTemplateFiles(dirname, cwd, useNpm, includePrismaMigrations,
     dbUrlProd, prismaDbUrlProd, sqliteFile
    } = options;
   const packageManagerTemplateData = getPackageManagerTemplateData(useNpm, nodeMajor);
+  const adminforthVersion = await resolveAdminforthVersionRange();
   const resolvedPrismaDbUrl = includePrismaMigrations ? prismaDbUrl : null;
   const resolvedPrismaDbUrlProd = includePrismaMigrations ? prismaDbUrlProd : null;
   const connectorProvider = provider === 'postgresql' ? 'postgres' : 

adminforth/commands/createPlugin/templates/package.json.hbs

@@ -16,6 +16,6 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "adminforth": "latest"
+    "adminforth": "{{adminforthVersion}}"
   }
 }

adminforth/commands/createPlugin/utils.js

@@ -8,6 +8,7 @@ import { Listr } from 'listr2';
 import { fileURLToPath } from 'url';
 import { execa } from 'execa';
 import Handlebars from 'handlebars';
+import { resolveAdminforthVersionRange } from '../cli.js';
 
 export function parseArgumentsIntoOptions(rawArgs) {
   const args = arg(
@@ -102,6 +103,7 @@ async function scaffoldProject(ctx, options, cwd) {
 
 async function writeTemplateFiles(dirname, cwd, options) {
   const { pluginName } = options;
+  const adminforthVersion = await resolveAdminforthVersionRange();
 
   // Build a list of files to generate
   const templateTasks = [
@@ -113,7 +115,7 @@ async function writeTemplateFiles(dirname, cwd, options) {
     {
       src: "package.json.hbs",
       dest: "package.json",
-      data: { pluginName },
+      data: { pluginName, adminforthVersion },
     },
     {
       src: "index.ts.hbs",

adminforth/documentation/docs/tutorial/03-Customization/04-hooks.md

@@ -42,9 +42,9 @@ When user opens edit page, AdminForth makes a request to the backend to get the
 
 ![Initial data for edit page flow](get_resource_data.png)
 
-Practically you can use `show.afterDatasourceResponse` to modify or add some data before it is displayed on the edit page. 
+Practically you can use `show.afterDatasourceResponse` to modify or add some data before it is displayed on the edit page. In other words, at this stage you can enrich the data with some additional metadata which might be handy on edit page for custom Vue fields.
 
-For example [upload plugin](/docs/tutorial/Plugins/upload/) uses this hook to generate signed preview URL so user can see existing uploaded file preview  in form, and at the same time database stores only original file path which might be not accessible without presigned URL.
+For example [upload plugin](/docs/tutorial/Plugins/upload/) uses this hook to generate signed preview URL so user can see existing uploaded file preview in form, and at the same time database stores only original file path which might be not accessible without presigned URL.
 
 ## Saving data on edit page
 
@@ -177,6 +177,28 @@ For example, you can change the way columns value is displayed by changing the v
 }
 ```
 
+Also you can use this hook to enrich the returned records list with some additional data fields which might be handy for custom Vue components defined in `components.list` or `components.show` for this resource. For example you can use [key-value adapter](/docs/tutorial/Adapters/key-value-adapters/) to get some global configuration values and add them to each record in the list:
+
+```ts title='./resources/apartments.ts'
+
+{
+  ...
+  hooks: {
+    list: {
+//diff-add
+      afterDatasourceResponse: async ({ response }: { response: any }) => {
+//diff-add
+        response.forEach((r: any) => {  
+          const taxRate = await kvAdapter.getValue('taxRate');
+          r.priceWithTax = r.price * (1 + taxRate);
+        });
+        return { ok: true, error: "" };
+      },
+    },
+  },
+}
+```
+
 ### Dropdown list of foreignResource
 
 By default if there is `foreignResource` like we use for demo on `realtor_id` column, the filter will suggest a

adminforth/documentation/docs/tutorial/06-Adapters/07-key-value-adapters.md

@@ -1,5 +1,5 @@
 ---
-description: "Reference page for AdminForth key-value adapters, including RAM, Redis, and LevelDB backends for temporary state, caching, and plugin storage."
+description: "Reference page for prebuilt key-value adapters created by AdminForth team, including simplest RAM Adapter (in-memory, no dependencies but ephemeral), Redis-based adapter, LevelDB - based (requires a mounted volume DevOps), Resource-based (Works on top of a resource persistable with your native SQL/NoSQL database)"
 ---
 
 # Key-value Adapters

adminforth/documentation/docs/tutorial/09-Plugins/11-oauth.md

@@ -106,6 +106,26 @@ export default {
 } satisfies AdminForthResourceInput;
 ```
 
+Then register the resource in `index.ts`:
+
+```ts title="./index.ts"
+//diff-add
+import adminUserExternalIdentitiesResource from "./resources/adminUserExternalIdentities";
+
+
+... new AdminForth({
+  dataSources: [...],
+    ...
+  resources: [
+    apartmentsResource,
+    usersResource,
+//diff-add
+    adminUserExternalIdentitiesResource,
+  ],
+    ...
+})
+```
+
 ## Configuration
 
 This example configures Google OAuth. See [OAuth2 Providers](#oauth2-providers) for provider setup details.

adminforth/package.json

@@ -89,7 +89,6 @@
     "@inquirer/prompts": "^7.4.1",
     "@scalar/express-api-reference": "^0.9.7",
     "@types/express": "^4.17.21",
-    "adminforth": "link:.",
     "ajv": "^8.18.0",
     "arg": "^5.0.2",
     "ast-types": "^0.14.2",