adminforth 2.25.1 → 2.26.0-next.10

package/dist/modules/codeInjector.js

@@ -5,9 +5,11 @@ import fsExtra from 'fs-extra';
 import os from 'os';
 import path from 'path';
 import { promisify } from 'util';
+import yaml from 'yaml';
 import { ADMIN_FORTH_ABSOLUTE_PATH, getComponentNameFromPath, md5hash } from './utils.js';
 import { StylesGenerator } from './styleGenerator.js';
 import { afLogger } from '../modules/logger.js';
+import { pathToFileURL } from 'url';
 let TMP_DIR;
 try {
     TMP_DIR = os.tmpdir();
@@ -60,9 +62,9 @@ function isFulfilled(result) {
     return result.status === 'fulfilled';
 }
 function notifyWatcherIssue(limit) {
-    afLogger.info('Ran out of file handles after watching %s files.', limit);
-    afLogger.info('Falling back to polling which uses more CPU.');
-    afLogger.info('Run ulimit -n 10000 to increase the limit for open files.');
+    console.log('Ran out of file handles after watching %s files.', limit);
+    console.log('Falling back to polling which uses more CPU.');
+    console.log('Run ulimit -n 10000 to increase the limit for open files.');
 }
 class CodeInjector {
     spaTmpPath() {
@@ -76,7 +78,7 @@ class CodeInjector {
         const uniqueIcons = Array.from(new Set(icons));
         const collections = new Set(icons.map((icon) => icon.split(':')[0]));
         const iconPackageNames = Array.from(collections).map((collection) => `@iconify-prerendered/vue-${collection}`);
-        const iconPackages = (await Promise.allSettled(iconPackageNames.map(async (pkg) => ({ pkg: await import(this.spaTmpPath() + '/node_modules/' + pkg), name: pkg }))));
+        const iconPackages = (await Promise.allSettled(iconPackageNames.map(async (pkg) => ({ pkg: await import(pathToFileURL(path.join(this.spaTmpPath(), 'node_modules', pkg)).href), name: pkg }))));
         const loadedIconPackages = iconPackages.filter(isFulfilled).map((res) => res.value).reduce((acc, { pkg, name }) => {
             acc[name.slice(`@iconify-prerendered/vue-`.length)] = pkg;
             return acc;
@@ -99,7 +101,7 @@ class CodeInjector {
         this.allComponentNames[filePath] = componentName;
     }
     cleanup() {
-        afLogger.info('Cleaning up...');
+        console.log('Cleaning up...');
         this.allWatchers.forEach((watcher) => {
             watcher.removeAll();
         });
@@ -116,40 +118,68 @@ class CodeInjector {
             process.exit();
         }));
     }
-    async runNpmShell({ command, cwd, envOverrides = {} }) {
+    async doesUserHasPnpmLockFile(dir) {
+        const usersPackagePath = path.join(dir, 'package.json');
+        let packageContent = null;
+        try {
+            packageContent = JSON.parse(await fs.promises.readFile(usersPackagePath, 'utf-8'));
+        }
+        catch (e) {
+            // user package.json does not exist, user does not have custom components
+        }
+        if (packageContent) {
+            const lockPath = path.join(dir, 'pnpm-lock.yaml');
+            let lock = null;
+            try {
+                lock = yaml.parse(await fs.promises.readFile(lockPath, 'utf-8'));
+                return true;
+            }
+            catch (e) {
+                return false;
+            }
+        }
+        return false;
+    }
+    async runPackageManagerShell({ command, cwd, envOverrides = {} }) {
         const nodeBinary = process.execPath; // Path to the Node.js binary running this script
-        // On Windows, npm is npm.cmd, on Unix systems it's npm
-        const npmExecutable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-        const npmPath = path.join(path.dirname(nodeBinary), npmExecutable); // Path to the npm executable
+        const doesUserHavePnpmLock = await this.doesUserHasPnpmLockFile(this.adminforth.config.customization.customComponentsDir);
+        // On Windows, npm/pnpm is npm/pnpm.cmd, on Unix systems it's npm/pnpm
+        let packageExecutable;
+        if (doesUserHavePnpmLock) {
+            process.env.HEAVY_DEBUG && console.log(`User has pnpm-lock.yaml, using pnpm for installing custom components`);
+            packageExecutable = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+        }
+        else {
+            process.env.HEAVY_DEBUG && console.log(`User does not have pnpm-lock.yaml, falling back to npm for installing custom components`);
+            packageExecutable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        }
+        const packagePath = path.join(path.dirname(nodeBinary), packageExecutable); // Path to the package executable
         const env = Object.assign(Object.assign({ VITE_ADMINFORTH_PUBLIC_PATH: this.adminforth.config.baseUrl, FORCE_COLOR: '1' }, process.env), envOverrides);
-        afLogger.trace(`⚙️ exec: npm ${command}`);
-        afLogger.trace(`🪲 npm ${command} cwd: ${cwd}`);
-        afLogger.trace(`npm ${command} done in`);
-        // On Windows, execute npm.cmd directly; on Unix, use node + npm
+        process.env.HEAVY_DEBUG && console.log(`⚙️ exec: ${packageExecutable} ${command}`);
+        process.env.HEAVY_DEBUG && console.log(`🪲 ${packageExecutable} ${command} cwd: ${cwd}`);
         let execCommand;
         if (process.platform === 'win32') {
             // Quote path if it contains spaces
-            const quotedNpmPath = npmPath.includes(' ') ? `"${npmPath}"` : npmPath;
-            execCommand = `${quotedNpmPath} ${command}`;
+            const quotedPackagePath = packagePath.includes(' ') ? `"${packagePath}"` : packagePath;
+            execCommand = `${quotedPackagePath} ${command}`;
         }
         else {
             // Quote paths that contain spaces (for Unix systems)
             const quotedNodeBinary = nodeBinary.includes(' ') ? `"${nodeBinary}"` : nodeBinary;
-            const quotedNpmPath = npmPath.includes(' ') ? `"${npmPath}"` : npmPath;
-            execCommand = `${quotedNodeBinary} ${quotedNpmPath} ${command}`;
+            const quotedPackagePath = packagePath.includes(' ') ? `"${packagePath}"` : packagePath;
+            execCommand = `${quotedNodeBinary} ${quotedPackagePath} ${command}`;
         }
         const execOptions = {
             cwd,
             env,
         };
-        // On Windows, use shell to execute .cmd files
         if (process.platform === 'win32') {
             execOptions.shell = true;
         }
-        const { stdout: out, stderr: err } = await execAsync(execCommand, execOptions);
-        afLogger.trace(`npm ${command} done in`);
+        const { stderr: err } = await execAsync(execCommand, execOptions);
+        process.env.HEAVY_DEBUG && console.log(`${packageExecutable} ${command} done in`);
         if (err) {
-            afLogger.trace(`🪲npm ${command} errors/warnings: ${err}`);
+            process.env.HEAVY_DEBUG && console.log(`🪲${packageExecutable} ${command} errors/warnings: ${err}`);
         }
     }
     async rmTmpDir() {
@@ -164,7 +194,8 @@ class CodeInjector {
     getServeDir() {
         return path.join(this.getSpaDir(), 'dist');
     }
-    async packagesFromNpm(dir) {
+    async packagesFromPnpm(dir) {
+        var _a;
         const usersPackagePath = path.join(dir, 'package.json');
         let packageContent = null;
         let lockHash = '';
@@ -176,26 +207,55 @@ class CodeInjector {
             // user package.json does not exist, user does not have custom components
         }
         if (packageContent) {
-            const lockPath = path.join(dir, 'package-lock.json');
+            const lockPath = path.join(dir, 'pnpm-lock.yaml');
             let lock = null;
             try {
-                lock = JSON.parse(await fs.promises.readFile(lockPath, 'utf-8'));
+                lock = yaml.parse(await fs.promises.readFile(lockPath, 'utf-8'));
             }
             catch (e) {
-                throw new Error(`Custom package-lock.json does not exist in ${dir}, but package.json does. 
-          We can't determine version of packages without package-lock.json. Please run npm install in ${dir}`);
+                const npmLockPath = path.join(dir, 'package-lock.json');
+                let npmLock = null;
+                try {
+                    npmLock = JSON.parse(await fs.promises.readFile(npmLockPath, 'utf-8'));
+                }
+                catch (npmLockError) {
+                    throw new Error(`Custom pnpm-lock.yaml or package-lock.json does not exist in ${dir}, but package.json does.
+          We can't determine version of packages without pnpm-lock.yaml or package-lock.json. Please run pnpm install or npm install in ${dir}`);
+                }
+                lockHash = hashify(npmLock);
+                packages = [
+                    ...Object.keys(packageContent.dependencies || {}),
+                    ...Object.keys(packageContent.devDependencies || {})
+                ].reduce((acc, packageName) => {
+                    var _a;
+                    const pack = (_a = npmLock === null || npmLock === void 0 ? void 0 : npmLock.packages) === null || _a === void 0 ? void 0 : _a[`node_modules/${packageName}`];
+                    if (!(pack === null || pack === void 0 ? void 0 : pack.version)) {
+                        throw new Error(`Package ${packageName} is not in package-lock.json but is in package.json. Please run 'npm install' in ${dir}`);
+                    }
+                    acc.push(`${packageName}@${pack.version}`);
+                    return acc;
+                }, []);
+                return [lockHash, packages];
             }
             lockHash = hashify(lock);
+            const importer = (_a = lock === null || lock === void 0 ? void 0 : lock.importers) === null || _a === void 0 ? void 0 : _a['.'];
+            if (!importer) {
+                throw new Error(`pnpm-lock.yaml in ${dir} does not contain importer ".". Please run pnpm install in ${dir}`);
+            }
+            const importerDeps = Object.assign(Object.assign(Object.assign({}, (importer.dependencies || {})), (importer.devDependencies || {})), (importer.optionalDependencies || {}));
             packages = [
-                ...Object.keys(packageContent.dependencies || []),
-                ...Object.keys(packageContent.devDependencies || [])
+                ...Object.keys(packageContent.dependencies || {}),
+                ...Object.keys(packageContent.devDependencies || {})
             ].reduce((acc, packageName) => {
-                const pack = lock.packages[`node_modules/${packageName}`];
-                if (!pack) {
-                    throw new Error(`Package ${packageName} is not in package-lock.json but is in package.json. Please run 'npm install' in ${dir}`);
+                const depInfo = importerDeps[packageName];
+                const raw = typeof depInfo === 'string'
+                    ? depInfo
+                    : ((depInfo === null || depInfo === void 0 ? void 0 : depInfo.version) || (depInfo === null || depInfo === void 0 ? void 0 : depInfo.specifier));
+                if (!raw) {
+                    throw new Error(`Package ${packageName} is not in pnpm-lock.yaml but is in package.json. Please run 'pnpm install' in ${dir}`);
                 }
-                const version = pack.version;
-                acc.push(`${packageName}@${version}`);
+                const cleaned = raw.includes('(') ? raw.split('(')[0] : raw;
+                acc.push(`${packageName}@${cleaned}`);
                 return acc;
             }, []);
         }
@@ -219,7 +279,7 @@ class CodeInjector {
                 dereference: true, // needed to dereference types
                 // preserveTimestamps: true, // needed to not invalidate any caches
             });
-            afLogger.trace(`🪲⚙️ fsExtra.copy copy single file, ${src}, ${dest}`);
+            process.env.HEAVY_DEBUG && console.log(`🪲⚙️ fsExtra.copy copy single file, ${src}, ${dest}`);
         }));
     }
     async migrateLegacyCustomLayout(oldMeta) {
@@ -322,7 +382,7 @@ class CodeInjector {
         collectAssetsFromMenu(this.adminforth.config.menu);
         registerSettingPages(this.adminforth.config.auth.userMenuSettingsPages);
         const spaDir = this.getSpaDir();
-        afLogger.trace(`🪲⚙️ fsExtra.copy from ${spaDir} -> ${this.spaTmpPath()}`);
+        process.env.HEAVY_DEBUG && console.log(`🪲⚙️ fsExtra.copy from ${spaDir} -> ${this.spaTmpPath()}`);
         // try to rm <spa tmp path>/src/types directory 
         try {
             await fs.promises.rm(path.join(this.spaTmpPath(), 'src', 'types'), { recursive: true });
@@ -337,7 +397,7 @@ class CodeInjector {
                 const filterPasses = !src.includes(`${path.sep}adminforth${path.sep}spa${path.sep}node_modules`) && !src.includes(`${path.sep}adminforth${path.sep}spa${path.sep}dist`)
                     && !src.includes(`${path.sep}dist${path.sep}spa${path.sep}node_modules`) && !src.includes(`${path.sep}dist${path.sep}spa${path.sep}dist`);
                 if (!filterPasses) {
-                    afLogger.trace(`🪲⚙️ fsExtra.copy filtered out, ${src}`);
+                    process.env.HEAVY_DEBUG && console.log(`🪲⚙️ fsExtra.copy filtered out, ${src}`);
                 }
                 return filterPasses;
             },
@@ -360,7 +420,7 @@ class CodeInjector {
         }
         for (const [src, dest] of Object.entries(this.srcFoldersToSync)) {
             const to = path.join(this.spaTmpPath(), 'src', 'custom', dest);
-            afLogger.trace(`🪲⚙️ srcFoldersToSync: fsExtra.copy from ${src}, ${to}`);
+            process.env.HEAVY_DEBUG && console.log(`🪲⚙️ srcFoldersToSync: fsExtra.copy from ${src}, ${to}`);
             await fsExtra.copy(src, to, {
                 recursive: true,
                 dereference: true,
@@ -555,20 +615,28 @@ class CodeInjector {
         routerVueContent = routerVueContent.replace('/* IMPORTANT:ADMINFORTH ROUTES */', routes);
         await fs.promises.writeFile(routerVuePath, routerVueContent);
         /* hash checking */
-        const spaPackageLockPath = path.join(this.spaTmpPath(), 'package-lock.json');
-        const spaPackageLock = JSON.parse(await fs.promises.readFile(spaPackageLockPath, 'utf-8'));
-        const spaLockHash = hashify(spaPackageLock);
+        let spaLockHash = '';
+        if (await this.doesUserHasPnpmLockFile(this.adminforth.config.customization.customComponentsDir)) {
+            const spaPnpmLockPath = path.join(this.spaTmpPath(), 'pnpm-lock.yaml');
+            const spaPnpmLock = yaml.parse(await fs.promises.readFile(spaPnpmLockPath, 'utf-8'));
+            spaLockHash = hashify(spaPnpmLock);
+        }
+        else {
+            const spaNpmLockPath = path.join(this.spaTmpPath(), 'package-lock.json');
+            const spaNpmLock = JSON.parse(await fs.promises.readFile(spaNpmLockPath, 'utf-8'));
+            spaLockHash = hashify(spaNpmLock);
+        }
         /* customPackageLock */
         let usersLockHash = '';
         let usersPackages = [];
         if ((_q = this.adminforth.config.customization) === null || _q === void 0 ? void 0 : _q.customComponentsDir) {
-            [usersLockHash, usersPackages] = await this.packagesFromNpm(this.adminforth.config.customization.customComponentsDir);
+            [usersLockHash, usersPackages] = await this.packagesFromPnpm(this.adminforth.config.customization.customComponentsDir);
         }
         const pluginPackages = [];
         // for every installed plugin generate packages
         for (const plugin of this.adminforth.activatedPlugins) {
-            afLogger.trace(`🔧 Checking packages for plugin, ${plugin.constructor.name}, ${plugin.customFolderPath}`);
-            const [lockHash, packages] = await this.packagesFromNpm(plugin.customFolderPath);
+            process.env.HEAVY_DEBUG && console.log(`🔧 Checking packages for plugin, ${plugin.constructor.name}, ${plugin.customFolderPath}`);
+            const [lockHash, packages] = await this.packagesFromPnpm(plugin.customFolderPath);
             if (packages.length) {
                 pluginPackages.push({
                     pluginName: plugin.constructor.name,
@@ -586,19 +654,20 @@ class CodeInjector {
             const existingHash = await fs.promises.readFile(hashPath, 'utf-8');
             await this.checkIconNames(icons);
             if (existingHash === fullHash) {
-                afLogger.trace(`🪲Hashes match, skipping npm ci/install, from file: ${existingHash}, actual: ${fullHash}`);
+                process.env.HEAVY_DEBUG && console.log(`🪲Hashes match, skipping pnpm install, from file: ${existingHash}, actual: ${fullHash}`);
                 return;
             }
             else {
-                afLogger.trace(`🪲 Hashes do not match: from file: ${existingHash} actual: ${fullHash}, proceeding with npm ci/install`);
+                process.env.HEAVY_DEBUG && console.log(`🪲 Hashes do not match: from file: ${existingHash} actual: ${fullHash}, proceeding with pnpm install`);
             }
         }
         catch (e) {
             // ignore
-            afLogger.trace(`🪲Hash file does not exist, proceeding with npm ci/install, ${e}`);
+            process.env.HEAVY_DEBUG && console.log(`🪲Hash file does not exist, proceeding with pnpm install, ${e}`);
         }
-        await this.runNpmShell({ command: 'ci', cwd: this.spaTmpPath(), envOverrides: {
-                NODE_ENV: 'development' // othewrwise it will not install devDependencies which we still need, e.g for extract
+        // install --frozen-lockfile works for npm and pnpm
+        await this.runPackageManagerShell({ command: 'install --frozen-lockfile', cwd: this.spaTmpPath(), envOverrides: {
+                NODE_ENV: 'development' // otherwise it will not install devDependencies which we still need, e.g for extract
             } });
         const allPacks = [
             ...iconPackageNames,
@@ -614,11 +683,11 @@ class CodeInjector {
         });
         const allPacksUnique = Array.from(new Set(allPacksFiltered));
         if (allPacks.length) {
-            const npmInstallCommand = `install ${allPacksUnique.join(' ')}`;
-            await this.runNpmShell({
-                command: npmInstallCommand, cwd: this.spaTmpPath(),
+            const packageManagerInstallCommand = `install ${allPacksUnique.join(' ')}`;
+            await this.runPackageManagerShell({
+                command: packageManagerInstallCommand, cwd: this.spaTmpPath(),
                 envOverrides: {
-                    NODE_ENV: 'development' // othewrwise it will not install devDependencies which we still need, e.g for extract
+                    NODE_ENV: 'development' // otherwise it will not install devDependencies which we still need, e.g for extract
                 }
             });
         }
@@ -642,7 +711,7 @@ class CodeInjector {
             }
         };
         await collectDirectories(spaPath);
-        afLogger.trace(`🪲🔎 Watch for: ${directories.join(',')}`);
+        process.env.HEAVY_DEBUG && console.log(`🪲🔎 Watch for: ${directories.join(',')}`);
         const watcher = filewatcher({ debounce: 30 });
         directories.forEach((dir) => {
             // read directory files and add to watcher, only files not directories
@@ -650,13 +719,13 @@ class CodeInjector {
             files.forEach((file) => {
                 const fullPath = path.join(dir, file);
                 if (fs.lstatSync(fullPath).isFile()) {
-                    afLogger.trace(`🪲🔎 Watch for file ${fullPath}`);
+                    process.env.HEAVY_DEBUG && console.log(`🪲🔎 Watch for file ${fullPath}`);
                     watcher.add(fullPath);
                 }
             });
         });
         watcher.on('change', async (file) => {
-            afLogger.trace(`🐛 File ${file} changed (SPA), preparing sources...`);
+            process.env.HEAVY_DEBUG && console.log(`🐛 File ${file} changed (SPA), preparing sources...`);
             await this.updatePartials({ filesUpdated: [file.replace(spaPath + path.sep, '')] });
         });
         watcher.on('fallback', notifyWatcherIssue);
@@ -671,7 +740,7 @@ class CodeInjector {
             await fs.promises.access(customComponentsDir, fs.constants.F_OK);
         }
         catch (e) {
-            afLogger.trace(`🪲Custom components dir ${customComponentsDir} does not exist, skipping watching`);
+            process.env.HEAVY_DEBUG && console.log(`🪲Custom components dir ${customComponentsDir} does not exist, skipping watching`);
             return;
         }
         // get all subdirs
@@ -696,21 +765,21 @@ class CodeInjector {
         await collectDirectories(customComponentsDir);
         const watcher = filewatcher({ debounce: 30 });
         files.forEach((file) => {
-            afLogger.trace(`🪲🔎 Watch for file ${file}`);
+            process.env.HEAVY_DEBUG && console.log(`🪲🔎 Watch for file ${file}`);
             watcher.add(file);
         });
-        afLogger.trace(`🪲🔎 Watch for: ${directories.join(',')}`);
+        process.env.HEAVY_DEBUG && console.log(`🪲🔎 Watch for: ${directories.join(',')}`);
         watcher.on('change', async (fileOrDir) => {
             // copy one file
             const relativeFilename = fileOrDir.replace(customComponentsDir + path.sep, '');
-            afLogger.trace(`🔎 fileOrDir ${fileOrDir} changed`);
-            afLogger.trace(`🔎 relativeFilename ${relativeFilename}`);
-            afLogger.trace(`🔎 customComponentsDir ${customComponentsDir}`);
-            afLogger.trace(`🔎 destination ${destination}`);
+            process.env.HEAVY_DEBUG && console.log(`🔎 fileOrDir ${fileOrDir} changed`);
+            process.env.HEAVY_DEBUG && console.log(`🔎 relativeFilename ${relativeFilename}`);
+            process.env.HEAVY_DEBUG && console.log(`🔎 customComponentsDir ${customComponentsDir}`);
+            process.env.HEAVY_DEBUG && console.log(`🔎 destination ${destination}`);
             const isFile = fs.lstatSync(fileOrDir).isFile();
             if (isFile) {
                 const destPath = path.join(this.spaTmpPath(), 'src', 'custom', destination, relativeFilename);
-                afLogger.trace(`🔎 Copying file ${fileOrDir} to ${destPath}`);
+                process.env.HEAVY_DEBUG && console.log(`🔎 Copying file ${fileOrDir} to ${destPath}`);
                 await fsExtra.copy(fileOrDir, destPath);
                 return;
             }
@@ -728,7 +797,7 @@ class CodeInjector {
         }
         catch (e) {
             // file does not exist
-            afLogger.trace(`🪲File ${filePath} does not exist, returning null`);
+            process.env.HEAVY_DEBUG && console.log(`🪲File ${filePath} does not exist, returning null`);
             return null;
         }
     }
@@ -738,7 +807,9 @@ class CodeInjector {
             const filePath = path.join(folderPath, file.name);
             // 🚫 Skip big files or files which might be dynamic
             if (file.name === 'node_modules' || file.name === 'dist' ||
-                file.name === 'i18n-messages.json' || file.name === 'i18n-empty.json') {
+                file.name === 'i18n-messages.json' || file.name === 'i18n-empty.json' ||
+                file.name === 'hashes.json' || file.name === 'package.json' ||
+                file.name === 'pnpm-lock.yaml' || file.name === 'package-lock.json') {
                 return '';
             }
             allFiles.push(filePath);
@@ -752,8 +823,49 @@ class CodeInjector {
         }));
         return md5hash(hashes.join(''));
     }
+    // Compute a map of file relative paths -> md5 hash of file contents and return it.
+    // Skips directories/files that are ignored by computeSourcesHash (node_modules, dist, i18n files).
+    async computeSourcesHashMap(folderPath = this.spaTmpPath(), rootFolder = this.spaTmpPath(), map = {}) {
+        const files = await fs.promises.readdir(folderPath, { withFileTypes: true });
+        await Promise.all(files.map(async (file) => {
+            const filePath = path.join(folderPath, file.name);
+            // 🚫 Skip big/dynamic folders or files
+            if (file.name === 'node_modules' || file.name === 'dist' ||
+                file.name === 'i18n-messages.json' || file.name === 'i18n-empty.json' ||
+                file.name === 'hashes.json' || file.name === 'package.json' ||
+                file.name === 'pnpm-lock.yaml' || file.name === 'package-lock.json') {
+                return;
+            }
+            if (file.isDirectory()) {
+                return await this.computeSourcesHashMap(filePath, rootFolder, map);
+            }
+            else {
+                try {
+                    const content = await fs.promises.readFile(filePath, 'utf-8');
+                    const hash = md5hash(content);
+                    // store relative path using forward slashes for portability
+                    const rel = path.relative(rootFolder, filePath).split(path.sep).join('/');
+                    map[rel] = hash;
+                }
+                catch (e) {
+                    // If a file can't be read (binary or permission), log and continue
+                    process.env.HEAVY_DEBUG && console.log(`🪲File ${filePath} read error: ${e}`);
+                    return;
+                }
+            }
+        }));
+        return map;
+    }
+    // Convenience helper: compute per-file hashes and save them into hashes.json in the spa tmp dir
+    async saveSourcesHashesToFile(outputFileName = 'hashes.json', hashMap = {}) {
+        const root = this.spaTmpPath();
+        const outPath = path.join(root, outputFileName);
+        await fs.promises.writeFile(outPath, JSON.stringify(hashMap, null, 2), 'utf-8');
+        process.env.HEAVY_DEBUG && console.log(`🪲 Saved sources hashes to ${outPath}`);
+        return outPath;
+    }
     async bundleNow({ hotReload = false }) {
-        afLogger.info(`${this.adminforth.formatAdminForth()} Bundling ${hotReload ? 'and listening for changes (🔥 Hotreload)' : ' (no hot reload)'}`);
+        console.log(`${this.adminforth.formatAdminForth()} Bundling ${hotReload ? 'and listening for changes (🔥 Hotreload)' : ' (no hot reload)'}`);
         this.adminforth.runningHotReload = hotReload;
         await this.prepareSources();
         if (hotReload) {
@@ -771,14 +883,12 @@ class CodeInjector {
         const serveDir = this.getServeDir();
         const allFiles = [];
         const sourcesHash = await this.computeSourcesHash(this.spaTmpPath(), allFiles);
-        afLogger.trace(`🪲🪲 allFiles:, ${JSON.stringify(allFiles.sort((a, b) => a.localeCompare(b)), null, 1)}`);
+        process.env.HEAVY_DEBUG && console.log(`🪲🪲 allFiles:, ${JSON.stringify(allFiles.sort((a, b) => a.localeCompare(b)), null, 1)}`);
         const buildHash = await this.tryReadFile(path.join(serveDir, '.adminforth_build_hash'));
         const messagesHash = await this.tryReadFile(path.join(serveDir, '.adminforth_messages_hash'));
         const skipBuild = buildHash === sourcesHash;
         const skipExtract = messagesHash === sourcesHash;
-        afLogger.trace(`🪲 SPA build hash: ${buildHash}`);
-        afLogger.trace(`🪲 SPA messages hash: ${messagesHash}`);
-        afLogger.trace(`🪲 SPA sources hash: ${sourcesHash}`);
+        process.env.HEAVY_DEBUG && console.log(`🪲 SPA messages hash: ${messagesHash}`);
         if (!skipBuild) {
             // remove serveDir if exists
             try {
@@ -790,7 +900,7 @@ class CodeInjector {
             await fs.promises.mkdir(serveDir, { recursive: true });
         }
         if (!skipExtract) {
-            await this.runNpmShell({ command: 'run i18n:extract', cwd });
+            await this.runPackageManagerShell({ command: 'run i18n:extract', cwd });
             // create serveDir if not exists
             await fs.promises.mkdir(serveDir, { recursive: true });
             // copy i18n messages to serve dir
@@ -799,51 +909,98 @@ class CodeInjector {
             await fs.promises.writeFile(path.join(serveDir, '.adminforth_messages_hash'), sourcesHash);
         }
         else {
-            afLogger.info(`AdminForth i18n message extraction skipped — build already performed for the current sources.`);
+            console.log(`AdminForth i18n message extraction skipped — build already performed for the current sources.`);
         }
         if (!hotReload) {
             if (!skipBuild) {
+                console.log(`🪲 Build cache miss or outdated, building SPA...`);
+                let oldHashForFiles = null;
+                try {
+                    oldHashForFiles = await fs.promises.readFile(path.join(this.spaTmpPath(), 'hashes.json'), 'utf-8');
+                }
+                catch (e) {
+                    // ignore if file doesn't exist, it is only for debugging
+                    console.log(`Build cache not found, building now (downtime) please consider running npx adminforth bundle at build time to avoid downtimes at runtime`);
+                }
+                const root = this.spaTmpPath();
+                const hashMap = await this.computeSourcesHashMap(root, root, {});
+                if (oldHashForFiles) {
+                    const parsedOldHashForFiles = JSON.parse(oldHashForFiles);
+                    const logsToDisplay = [];
+                    logsToDisplay.push(`Build cache exists but is outdated:`);
+                    for (const [file, hash] of Object.entries(hashMap)) {
+                        if (!parsedOldHashForFiles[file]) {
+                            logsToDisplay.push(`   - file ${file} - does not exist in cache but exists in runtime`);
+                        }
+                        else if (parsedOldHashForFiles[file] !== hash) {
+                            logsToDisplay.push(`   - file ${file} - content in cache is different then in runtime`);
+                        }
+                    }
+                    /**
+                     * Currently we can't detect, if file was removed,
+                     * because we can only add files to the tpm folder but not remove them,
+                     * so if file existed before and now doesn't exist, we will not detect it
+                     */
+                    // for(const [file, hash] of Object.entries(parsedOldHashForFiles)) {
+                    //   console.log(`checking file ${file} in old hash: ${hash}`);
+                    //   console.log(`checking file ${file} in new hash: ${hashMap[file]}`);
+                    //   if (!hashMap[file]) {
+                    //     logsToDisplay.push(`   - file ${file} - exists in cache but does not exist in runtime`);
+                    //   }
+                    // }
+                    logsToDisplay.push(`If you are running in production now, then the cache loss is a downtime issue.`);
+                    logsToDisplay.push(`If you have npx adminforth bundle in build time, then this issue might be caused by conditional instantiation of plugins:`);
+                    logsToDisplay.push(`Please avoid constructions like (process.env.SOME_KEY ? new Plugin(...) ) because if you will miss SOME_KEY in build time build cache and functionality fails.`);
+                    if (logsToDisplay.length > 4) {
+                        for (const log of logsToDisplay) {
+                            console.log(log);
+                        }
+                    }
+                }
                 // TODO probably add option to build with tsh check (plain 'build')
-                await this.runNpmShell({ command: 'run build-only', cwd });
+                await this.runPackageManagerShell({ command: 'run build-only', cwd });
                 // coy dist to serveDir
                 await fsExtra.copy(path.join(cwd, 'dist'), serveDir, { recursive: true });
                 // save hash
                 await fs.promises.writeFile(path.join(serveDir, '.adminforth_build_hash'), sourcesHash);
+                // save sources hashes to file for later debugging if needed
+                await this.saveSourcesHashesToFile('hashes.json', hashMap);
             }
             else {
-                afLogger.info(`Skipping AdminForth SPA bundling - already completed for the current sources.`);
+                console.log(`Skipping AdminForth SPA bundling - already completed for the current sources.`);
             }
         }
         else {
             const command = 'run dev';
-            afLogger.info(`⚙️ spawn: npm ${command}...`);
+            const usersPackageManager = await this.doesUserHasPnpmLockFile(this.adminforth.config.customization.customComponentsDir) ? 'pnpm' : 'npm';
+            console.log(`⚙️ spawn: ${usersPackageManager} ${command}...`);
             if (process.env.VITE_ADMINFORTH_PUBLIC_PATH) {
-                afLogger.info(`⚠️ Your VITE_ADMINFORTH_PUBLIC_PATH: ${process.env.VITE_ADMINFORTH_PUBLIC_PATH} has no effect`);
+                console.log(`⚠️ Your VITE_ADMINFORTH_PUBLIC_PATH: ${process.env.VITE_ADMINFORTH_PUBLIC_PATH} has no effect`);
             }
             const env = Object.assign({ VITE_ADMINFORTH_PUBLIC_PATH: this.adminforth.config.baseUrl, FORCE_COLOR: '1' }, process.env);
             const nodeBinary = process.execPath;
-            const npmPath = path.join(path.dirname(nodeBinary), 'npm');
+            const packageManagerPath = path.join(path.dirname(nodeBinary), usersPackageManager);
             let devServer;
             if (process.platform === 'win32') {
-                devServer = spawn('npm', command.split(' '), { cwd, env, shell: true });
+                devServer = spawn(usersPackageManager, command.split(' '), { cwd, env, shell: true });
             }
             else {
-                devServer = spawn(`${nodeBinary}`, [`${npmPath}`, ...command.split(' ')], { cwd, env });
+                devServer = spawn(`${nodeBinary}`, [`${packageManagerPath}`, ...command.split(' ')], { cwd, env });
             }
             devServer.stdout.on('data', (data) => {
                 if (data.includes('➜')) {
                     // TODO: maybe better use our string "App port: 5174. HMR port: 5274", it is more reliable because vue might change their output
                     // parse port from message "  ➜  Local:   http://localhost:xyz/"
                     const s = stripAnsiCodes(data.toString());
-                    afLogger.trace(`🪲 devServer stdout ➜ (port detect): ${s}`);
+                    process.env.HEAVY_DEBUG && console.log(`🪲 devServer stdout ➜ (port detect): ${s}`);
                     const portMatch = s.match(/.+?http:\/\/.+?:(\d+).+?/m);
                     if (portMatch) {
                         this.devServerPort = parseInt(portMatch[1]);
                     }
                 }
                 else {
-                    afLogger.trace(`[AdminForth SPA]:`);
-                    afLogger.trace(data.toString());
+                    process.env.HEAVY_DEBUG && console.log(`[AdminForth SPA]:`);
+                    process.env.HEAVY_DEBUG && console.log(data.toString());
                 }
             });
             devServer.stderr.on('data', (data) => {