@nocobase/cli 2.2.0-beta.3 → 2.2.0-beta.6

package/dist/commands/app/restart.js

@@ -14,6 +14,7 @@ import { recreateSavedDockerApp } from '../../lib/app-managed-resources.js';
 import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
 import { run } from '../../lib/run-npm.js';
 import { announceTargetEnv, failTask, startTask, succeedTask } from '../../lib/ui.js';
+import { buildHookContext, resolveHookScriptPath, runHookScriptHook } from '../../lib/hook-script.js';
 function argvHasToken(argv, tokens) {
     return tokens.some((token) => argv.includes(token));
 }
@@ -62,6 +63,39 @@ function resolveDisplayAppUrl(apiBaseUrl, port, appPublicPath) {
     }
     return formatAppUrl(port, appPublicPath);
 }
+async function runDockerAfterAppStartHookIfNeeded(runtime) {
+    const hookScript = runtime.env.config?.hookScript;
+    if (!hookScript) {
+        return;
+    }
+    const hookScriptPath = resolveHookScriptPath({
+        appPath: runtime.env.appPath,
+        hookScript,
+    });
+    if (!hookScriptPath) {
+        return;
+    }
+    const context = buildHookContext({
+        phase: 'app-start',
+        command: 'app:restart',
+        envName: runtime.envName,
+        source: runtime.source,
+        version: runtime.env.config?.downloadVersion,
+        appPath: runtime.env.appPath,
+        sourcePath: runtime.env.sourcePath,
+        storagePath: runtime.env.storagePath,
+        hookScript: String(hookScript).trim(),
+        envConfig: runtime.env.config,
+    });
+    if (!context) {
+        return;
+    }
+    await runHookScriptHook({
+        hookScriptPath,
+        hookName: 'afterAppStart',
+        context,
+    });
+}
 export default class AppRestart extends Command {
     static hidden = false;
     static description = 'Restart NocoBase for the selected env. When applicable, the CLI synchronizes licensed commercial plugins first, then restarts the local app or recreates the saved Docker container.';
@@ -199,6 +233,7 @@ export default class AppRestart extends Command {
                 logHint: `You can inspect startup logs with \`nb app logs --env ${runtime.envName}\`.`,
                 ...(flags.verbose ? { verbose: true } : {}),
             });
+            await runDockerAfterAppStartHookIfNeeded(runtime);
             succeedTask(`NocoBase is running for "${runtime.envName}"${appUrl ? ` at ${appUrl}` : ''}.`);
             return;
         }
@@ -222,6 +257,9 @@ export default class AppRestart extends Command {
         if (daemonFlagWasProvided) {
             startArgv.push(flags.daemon === false ? '--no-daemon' : '--daemon');
         }
+        if (runtime.env.config?.hookScript) {
+            startArgv.push('--hook-command', 'app:restart');
+        }
         await runWithSuppressedTargetEnvLog(async () => {
             await runCommand('app:start', startArgv);
         });

package/dist/commands/app/start.js

@@ -18,6 +18,7 @@ import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
 import { readManagedRuntimeEnvValues } from '../../lib/managed-env-file.js';
 import { run } from '../../lib/run-npm.js';
 import { announceTargetEnv, failTask, printInfo, printWarning, startTask, succeedTask } from '../../lib/ui.js';
+import { buildHookContext, resolveHookScriptPath, runHookScriptHook, } from '../../lib/hook-script.js';
 function shouldPrintStartSuccess() {
     return process.env.NB_SKIP_APP_START_SUCCESS_LOG !== '1';
 }
@@ -34,6 +35,57 @@ function buildLicenseSyncArgv(envName, options) {
     }
     return argv;
 }
+function resolveHookCommand(value) {
+    const text = String(value ?? '').trim();
+    if (text === 'app:restart' || text === 'app:upgrade') {
+        return text;
+    }
+    return 'app:start';
+}
+function resolveAppStartHookPhase(options) {
+    if (options.isPreparedEnv) {
+        return 'init';
+    }
+    if (options.command === 'app:upgrade') {
+        return 'upgrade';
+    }
+    return 'app-start';
+}
+async function runRuntimeHookIfNeeded(params) {
+    const hookScript = params.runtime.env.config?.hookScript;
+    if (!hookScript) {
+        return;
+    }
+    const hookScriptPath = resolveHookScriptPath({
+        appPath: params.runtime.env.appPath,
+        hookScript,
+    });
+    if (!hookScriptPath) {
+        return;
+    }
+    const context = buildHookContext({
+        phase: params.phase,
+        command: params.command,
+        envName: params.runtime.envName,
+        source: params.runtime.source,
+        version: params.runtime.env.config?.downloadVersion,
+        appPath: params.runtime.env.appPath,
+        sourcePath: params.runtime.env.sourcePath,
+        storagePath: params.runtime.env.storagePath,
+        hookScript: String(hookScript).trim(),
+        envConfig: params.hookName === 'afterAppStart' && params.phase === 'init'
+            ? { ...params.runtime.env.config, setupState: 'installed' }
+            : params.runtime.env.config,
+    });
+    if (!context) {
+        return;
+    }
+    await runHookScriptHook({
+        hookScriptPath,
+        hookName: params.hookName,
+        context,
+    });
+}
 async function runWithSuppressedTargetEnvLog(task) {
     const previousTargetEnv = process.env.NB_SKIP_TARGET_ENV_LOG;
     process.env.NB_SKIP_TARGET_ENV_LOG = '1';
@@ -171,6 +223,10 @@ export default class AppStart extends Command {
             description: 'Show raw startup output from the underlying local or Docker command',
             default: false,
         }),
+        'hook-command': Flags.string({
+            hidden: true,
+            options: ['app:start', 'app:restart', 'app:upgrade'],
+        }),
     };
     async run() {
         const { flags } = await this.parse(AppStart);
@@ -192,6 +248,12 @@ export default class AppStart extends Command {
         const runtime = await resolveManagedAppRuntime(requestedEnv);
         const preparedInitEnvVars = buildInitAppEnvVarsFromConfig(runtime?.env.config);
         const isPreparedEnv = isPreparedSetupState(runtime?.env.config?.setupState);
+        const hookCommand = resolveHookCommand(flags['hook-command']);
+        const hookPhase = resolveAppStartHookPhase({
+            isPreparedEnv,
+            command: hookCommand,
+        });
+        const shouldRunBeforeAppInstall = isPreparedEnv || hookCommand === 'app:upgrade';
         const runCommand = this.config.runCommand.bind(this.config);
         const commandStdio = flags.verbose ? 'inherit' : 'ignore';
         if (!runtime) {
@@ -249,6 +311,14 @@ export default class AppStart extends Command {
                     errorName: 'docker rm',
                     stdio: commandStdio,
                 }).catch(() => undefined);
+                if (shouldRunBeforeAppInstall) {
+                    await runRuntimeHookIfNeeded({
+                        hookName: 'beforeAppInstall',
+                        runtime,
+                        phase: hookPhase,
+                        command: hookCommand,
+                    });
+                }
                 await recreateSavedDockerApp(runtime, {
                     initEnvVars: isPreparedEnv ? preparedInitEnvVars : undefined,
                     verbose: flags.verbose,
@@ -270,6 +340,12 @@ export default class AppStart extends Command {
             if (isPreparedEnv) {
                 await finalizePreparedEnv(runtime.envName);
             }
+            await runRuntimeHookIfNeeded({
+                hookName: 'afterAppStart',
+                runtime,
+                phase: hookPhase,
+                command: hookCommand,
+            });
             if (shouldPrintStartSuccess()) {
                 succeedTask(`NocoBase is running for "${runtime.envName}"${appUrl ? ` at ${appUrl}` : ''}.`);
             }
@@ -285,6 +361,8 @@ export default class AppStart extends Command {
             const downloadableRuntime = runtime;
             await ensureSavedLocalSource(downloadableRuntime, runCommand, {
                 verbose: flags.verbose,
+                hookPhase: isPreparedEnv ? 'init' : 'restore',
+                hookCommand,
                 onStartTask: startTask,
                 onSucceedTask: succeedTask,
                 onFailTask: failTask,
@@ -381,6 +459,14 @@ export default class AppStart extends Command {
                     ...managedAppLifecycleEnvVars(),
                     ...(isPreparedEnv ? preparedInitEnvVars : {}),
                 };
+            if (shouldRunBeforeAppInstall) {
+                await runRuntimeHookIfNeeded({
+                    hookName: 'beforeAppInstall',
+                    runtime,
+                    phase: hookPhase,
+                    command: hookCommand,
+                });
+            }
             await runLocalNocoBaseCommand(runtime, npmArgs, {
                 env: startEnv,
                 stdio: commandStdio,
@@ -394,6 +480,12 @@ export default class AppStart extends Command {
                 if (isPreparedEnv) {
                     await finalizePreparedEnv(runtime.envName);
                 }
+                await runRuntimeHookIfNeeded({
+                    hookName: 'afterAppStart',
+                    runtime,
+                    phase: hookPhase,
+                    command: hookCommand,
+                });
                 if (shouldPrintStartSuccess()) {
                     succeedTask(`NocoBase is running for "${runtime.envName}"${appUrl ? ` at ${appUrl}` : ''}.`);
                 }

package/dist/commands/app/upgrade.js

@@ -12,6 +12,7 @@ import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, } from '..
 import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
 import { DEFAULT_DOCKER_REGISTRY } from "../../lib/docker-image.js";
 import { confirm } from "../../lib/inquirer.js";
+import { resolveHookScriptPath } from '../../lib/hook-script.js';
 import { announceTargetEnv, isInteractiveTerminal, printInfo, printWarning, succeedTask } from '../../lib/ui.js';
 import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
 function trimValue(value) {
@@ -345,6 +346,13 @@ export default class AppUpgrade extends Command {
         if (runtime.env.config.buildDts === true) {
             argv.push('--build-dts');
         }
+        const hookScriptPath = resolveHookScriptPath({
+            appPath: runtime.env.appPath,
+            hookScript: runtime.env.config.hookScript,
+        });
+        if (hookScriptPath) {
+            argv.push('--hook-script', hookScriptPath, '--hook-phase', 'upgrade', '--hook-command', 'app:upgrade', '--hook-env-name', runtime.envName, '--hook-app-path', runtime.env.appPath, '--hook-storage-path', runtime.env.storagePath);
+        }
         return argv;
     }
     static buildDockerDownloadArgv(runtime, downloadVersion, options) {
@@ -497,6 +505,9 @@ export default class AppUpgrade extends Command {
             await runWithSuppressedTargetEnvLog(async () => {
                 const startArgv = buildManagedActionArgv(runtime.envName, parsed, { quickstart: true });
                 startArgv.push('--no-sync-licensed-plugins');
+                if (runtime.env.config.hookScript) {
+                    startArgv.push('--hook-command', 'app:upgrade');
+                }
                 await runWithSuppressedStartSuccessLog(async () => {
                     await runCommand('app:start', startArgv);
                 });

package/dist/commands/init.js

@@ -15,7 +15,7 @@ import { stdin as stdinStream, stdout as stdoutStream } from 'node:process';
 import { getEnv, upsertEnv } from "../lib/auth-store.js";
 import { runPromptCatalog, } from "../lib/prompt-catalog.js";
 import { applyCliLocale, localeText, translateCli } from "../lib/cli-locale.js";
-import { resolveDefaultConfigScope } from '../lib/cli-home.js';
+import { resolveConfiguredEnvPath, resolveDefaultConfigScope, resolveEnvRelativePath } from '../lib/cli-home.js';
 import { resolveDefaultApiHost, resolveDefaultUiHost } from '../lib/cli-config.js';
 import { areConfiguredPathsEquivalent, deriveConfiguredSourcePath, deriveConfiguredStoragePath, inferConfiguredAppPathFromLegacyConfig, } from '../lib/env-paths.js';
 import { formatMissingManagedAppEnvMessage } from '../lib/app-runtime.js';
@@ -23,7 +23,9 @@ import { runPromptCatalogWebUI } from "../lib/prompt-web-ui.js";
 import { validateApiBaseUrl, validateEnvKey } from "../lib/prompt-validators.js";
 import { installNocoBaseSkills, isNpmRegistryUnavailable } from '../lib/skills-manager.js';
 import { omitKeys, pickKeys } from "../lib/object-utils.js";
+import { ENV_CONFIG_SCHEMA_VERSION } from '../lib/env-config.js';
 import { printInfo, printStage, printVerbose, printWarning } from '../lib/ui.js';
+import { persistHookScript } from '../lib/hook-script.js';
 import Download from "./download.js";
 import EnvAdd from "./env/add.js";
 import Install, { defaultDbPortForDialect } from "./install.js";
@@ -1028,6 +1030,14 @@ Prompt modes:
         const skipDownload = results.skipDownload === true;
         const appKey = resolveManagedAppKey(results.appKey ?? existingEnv?.config.appKey);
         const timeZone = resolveManagedTimeZone(results.timeZone ?? existingEnv?.config.timezone);
+        const hookScriptInput = String(flags['hook-script'] ?? '').trim();
+        const hookAppPath = appPath || `./${envName}/`;
+        const hookScript = hookScriptInput
+            ? await persistHookScript({
+                sourcePath: hookScriptInput,
+                appPath: resolveConfiguredEnvPath(hookAppPath) ?? resolveEnvRelativePath(hookAppPath),
+            })
+            : String(results.hookScript ?? '').trim();
         const builtinDb = explicitDbHostFlag(flags)
             ? false
             : results.builtinDb === undefined
@@ -1036,6 +1046,7 @@ Prompt modes:
         results.appKey = appKey;
         results.timeZone = timeZone;
         await upsertEnv(envName, {
+            schemaVersion: ENV_CONFIG_SCHEMA_VERSION,
             ...(source === 'docker'
                 ? { kind: 'docker' }
                 : source || appPath || appRootPath
@@ -1053,6 +1064,7 @@ Prompt modes:
             ...(dockerPlatform ? { dockerPlatform } : {}),
             ...(gitUrl ? { gitUrl } : {}),
             ...(npmRegistry ? { npmRegistry } : {}),
+            ...(hookScript ? { hookScript } : {}),
             ...(appPath ? { appPath } : {}),
             ...(appRootPath && !areConfiguredPathsEquivalent(appRootPath, derivedAppRootPath) ? { appRootPath } : {}),
             ...(storagePath && !areConfiguredPathsEquivalent(storagePath, derivedStoragePath) ? { storagePath } : {}),
@@ -1128,6 +1140,10 @@ Prompt modes:
         if (flags['prepare-only']) {
             argv.push('--prepare-only');
         }
+        const hookScript = String(results.hookScript ?? flags['hook-script'] ?? '').trim();
+        if (hookScript) {
+            argv.push('--hook-script', hookScript);
+        }
         if (flags.verbose) {
             argv.push('--verbose');
         }

package/dist/commands/install.js

@@ -29,6 +29,7 @@ import { buildStoredEnvConfig } from '../lib/env-config.js';
 import { resolveDockerEnvFileArg } from "../lib/docker-env-file.js";
 import { startDockerLogFollower } from '../lib/docker-log-stream.js';
 import { buildInitAppEnvVarsFromConfig } from '../lib/managed-init-env.js';
+import { buildHookContext, persistHookScript, resolveHookScriptPath, runHookScriptHook, } from '../lib/hook-script.js';
 import { areConfiguredPathsEquivalent, deriveConfiguredSourcePath, deriveConfiguredStoragePath, inferConfiguredAppPathFromLegacyConfig, } from '../lib/env-paths.js';
 import Download, { defaultDockerRegistryForLang } from './download.js';
 import EnvAdd from "./env/add.js";
@@ -472,7 +473,10 @@ export default class Install extends Command {
             description: 'Skip the download step and reuse an existing local app directory or Docker image',
             default: false,
         }),
-        ...omitKeys(Download.flags, ['yes']),
+        'hook-script': Flags.string({
+            description: 'Hook module copied to <appPath>/.nb/hooks.mjs and run before npm/git dependency installation.',
+        }),
+        ...omitKeys(Download.flags, ['yes', 'hook-script']),
     };
     /** Environment name only: run before {@link Install.prompts} (see `run`). */
     static envPrompts = {
@@ -1095,6 +1099,7 @@ export default class Install extends Command {
         const appPort = Install.toOptionalPromptString(config.appPort);
         const storagePath = Install.toOptionalPromptString(config.storagePath);
         const appPublicPath = Install.toOptionalPromptString(config.appPublicPath);
+        const hookScript = Install.toOptionalPromptString(config.hookScript);
         const apiBaseUrl = Install.toOptionalPromptString(config.apiBaseUrl);
         const downloadVersion = Install.toOptionalPromptString(config.downloadVersion);
         const dockerRegistry = Install.toOptionalPromptString(config.dockerRegistry);
@@ -1125,6 +1130,7 @@ export default class Install extends Command {
             ...(appPort ? { appPort } : {}),
             ...(storagePath ? { storagePath } : {}),
             ...(appPublicPath ? { appPublicPath } : {}),
+            ...(hookScript ? { hookScript } : {}),
         };
         const downloadPreset = {
             ...(source ? { source } : {}),
@@ -1916,6 +1922,12 @@ export default class Install extends Command {
         if (results.buildDts) {
             argv.push('--build-dts');
         }
+        Install.pushDownloadArgIfValue(argv, '--hook-script', results.hookScript);
+        Install.pushDownloadArgIfValue(argv, '--hook-phase', results.hookPhase);
+        Install.pushDownloadArgIfValue(argv, '--hook-command', results.hookCommand);
+        Install.pushDownloadArgIfValue(argv, '--hook-env-name', results.hookEnvName);
+        Install.pushDownloadArgIfValue(argv, '--hook-app-path', results.hookAppPath);
+        Install.pushDownloadArgIfValue(argv, '--hook-storage-path', results.hookStoragePath);
         return argv;
     }
     static resolveLocalProjectRoot(params) {
@@ -1942,6 +1954,40 @@ export default class Install extends Command {
             buildDts: false,
         };
     }
+    static resolveAbsoluteAppPath(envName, appResults) {
+        const configuredAppPath = resolveConfiguredAppPathValue(appResults) ?? defaultInstallAppPath(envName);
+        return resolveConfiguredEnvPath(configuredAppPath) ?? resolveEnvRelativePath(defaultInstallAppPath(envName));
+    }
+    static resolveAbsoluteStoragePath(envName, appResults) {
+        const configuredStoragePath = resolveConfiguredStoragePathValue(appResults, envName);
+        return resolveConfiguredEnvPath(configuredStoragePath) ?? resolveEnvRelativePath(defaultInstallStoragePath(envName));
+    }
+    async prepareHookScriptForInstall(params) {
+        const appPath = Install.resolveAbsoluteAppPath(params.envName, params.appResults);
+        const storagePath = Install.resolveAbsoluteStoragePath(params.envName, params.appResults);
+        const inputHookScript = Install.toOptionalPromptString(params.hookScript);
+        if (inputHookScript) {
+            params.appResults.hookScript = await persistHookScript({
+                sourcePath: inputHookScript,
+                appPath,
+            });
+            printInfo(`Saved hook script to ${path.join(appPath, String(params.appResults.hookScript))}.`);
+        }
+        const savedHookScript = Install.toOptionalPromptString(params.appResults.hookScript);
+        const hookScriptPath = resolveHookScriptPath({
+            appPath,
+            hookScript: savedHookScript,
+        });
+        if (!hookScriptPath) {
+            return;
+        }
+        params.downloadResults.hookScript = hookScriptPath;
+        params.downloadResults.hookPhase = 'init';
+        params.downloadResults.hookCommand = 'init';
+        params.downloadResults.hookEnvName = params.envName;
+        params.downloadResults.hookAppPath = appPath;
+        params.downloadResults.hookStoragePath = storagePath;
+    }
     commandStdio(verbose) {
         return verbose ? 'inherit' : 'ignore';
     }
@@ -2216,6 +2262,44 @@ export default class Install extends Command {
         }
         await this.config.runCommand('env:update', [params.envName]);
     }
+    async runInstallHookIfNeeded(params) {
+        const appPath = Install.resolveAbsoluteAppPath(params.envName, params.appResults);
+        const savedHookScript = Install.toOptionalPromptString(params.appResults.hookScript);
+        const hookScriptPath = resolveHookScriptPath({
+            appPath,
+            hookScript: savedHookScript,
+        });
+        if (!hookScriptPath) {
+            return;
+        }
+        const storagePath = Install.resolveAbsoluteStoragePath(params.envName, params.appResults);
+        const sourcePath = params.projectRoot ??
+            resolveConfiguredEnvPath(resolveConfiguredSourcePathValue(params.appResults, params.envName)) ??
+            path.join(appPath, 'source');
+        const context = buildHookContext({
+            phase: 'init',
+            command: 'init',
+            envName: params.envName,
+            source: params.source,
+            version: downloadResultsValue(params.downloadResults, 'version'),
+            appPath,
+            sourcePath,
+            storagePath,
+            hookScript: savedHookScript,
+            envConfig: Install.buildSavedEnvConfig(params, {
+                defaultApiHost: params.defaultApiHost,
+            }),
+        });
+        if (!context) {
+            return;
+        }
+        this.log(`Running hook ${params.hookName}: ${hookScriptPath}`);
+        await runHookScriptHook({
+            hookScriptPath,
+            hookName: params.hookName,
+            context,
+        });
+    }
     static buildSavedEnvConfig(params, options = {}) {
         const appPath = resolveConfiguredAppPathValue(params.appResults);
         const appRootPath = Install.toOptionalPromptString(params.appResults.appRootPath);
@@ -2247,6 +2331,7 @@ export default class Install extends Command {
             devDependencies: downloadResultsValue(params.downloadResults, 'devDependencies'),
             build: downloadResultsValue(params.downloadResults, 'build'),
             buildDts: downloadResultsValue(params.downloadResults, 'buildDts'),
+            hookScript: params.appResults.hookScript,
             ...(appPath ? { appPath } : {}),
             ...(appRootPath && !areConfiguredPathsEquivalent(appRootPath, derivedAppRootPath) ? { appRootPath } : {}),
             appPort,
@@ -2311,6 +2396,9 @@ export default class Install extends Command {
             yesInitialValues: { resume: parsed.resume },
             yes,
         });
+        if (resumePreset?.appPreset?.hookScript !== undefined && appResults.hookScript === undefined) {
+            appResults.hookScript = resumePreset.appPreset.hookScript;
+        }
         const downloadOpts = Install.buildDownloadPromptOptionsForInstall(appResults, envName);
         downloadOpts.values = {
             ...(resumePreset?.downloadPreset ?? {}),
@@ -2440,6 +2528,12 @@ export default class Install extends Command {
             appResults,
         });
         appResults.setupState = 'prepared';
+        await this.prepareHookScriptForInstall({
+            envName,
+            appResults,
+            downloadResults,
+            hookScript: parsed['hook-script'],
+        });
         const source = String(downloadResultsValue(downloadResults, 'source') ?? '').trim();
         const usesDockerResources = Boolean(dbResults.builtinDb) || source === 'docker';
         const dockerNetworkName = usesDockerResources
@@ -2505,6 +2599,17 @@ export default class Install extends Command {
                     printInfo('Application image ready.');
                 }
                 if (!parsed['prepare-only']) {
+                    await this.runInstallHookIfNeeded({
+                        hookName: 'beforeAppInstall',
+                        envName,
+                        source,
+                        appResults,
+                        downloadResults,
+                        dbResults,
+                        rootResults,
+                        envAddResults,
+                        defaultApiHost,
+                    });
                     dockerAppPlan = await this.installDockerApp({
                         envName,
                         dockerNetworkName,
@@ -2523,7 +2628,7 @@ export default class Install extends Command {
             }
             else if (source === 'npm' || source === 'git') {
                 const localSource = source === 'npm' ? 'npm' : 'git';
-                const projectRoot = parsed['skip-download']
+                const projectRoot = parsed['skip-download'] || parsed['prepare-only']
                     ? Install.resolveLocalProjectRoot({
                         envName,
                         appResults,
@@ -2535,10 +2640,22 @@ export default class Install extends Command {
                         downloadResults,
                         verbose: parsed.verbose,
                     });
-                if (!parsed['skip-download']) {
+                if (!parsed['skip-download'] && !parsed['prepare-only']) {
                     printInfo('Application files ready.');
                 }
                 if (!parsed['prepare-only']) {
+                    await this.runInstallHookIfNeeded({
+                        hookName: 'beforeAppInstall',
+                        envName,
+                        source,
+                        appResults,
+                        downloadResults,
+                        dbResults,
+                        rootResults,
+                        envAddResults,
+                        projectRoot,
+                        defaultApiHost,
+                    });
                     localAppPlan = await this.startLocalApp({
                         envName,
                         source: localSource,
@@ -2573,6 +2690,18 @@ export default class Install extends Command {
             });
             printInfo(`NocoBase is ready at ${formatInstallDisplayUrl(displayApiBaseUrl)}`);
             appResults.setupState = 'installed';
+            await this.runInstallHookIfNeeded({
+                hookName: 'afterAppStart',
+                envName,
+                source,
+                appResults,
+                downloadResults,
+                dbResults,
+                rootResults,
+                envAddResults,
+                projectRoot: localAppPlan?.projectRoot,
+                defaultApiHost,
+            });
         }
         if (dockerAppPlan || localAppPlan || builtinDbPlan) {
             await this.saveInstalledEnv({

package/dist/commands/source/download.js

@@ -13,6 +13,9 @@ import { stdin as stdinStream, stdout as stdoutStream } from 'node:process';
 import { runPromptCatalog, } from "../../lib/prompt-catalog.js";
 import { applyCliLocale, CLI_LOCALE_FLAG_DESCRIPTION, CLI_LOCALE_FLAG_OPTIONS, localeText, resolveCliLocale, translateCli, } from "../../lib/cli-locale.js";
 import { DEFAULT_DOCKER_REGISTRY, DEFAULT_DOCKER_REGISTRY_ZH_CN, resolveDockerImageRef, } from "../../lib/docker-image.js";
+import { getEnv } from '../../lib/auth-store.js';
+import { resolveDefaultConfigScope } from '../../lib/cli-home.js';
+import { buildBeforeDependencyInstallHookContext, runBeforeDependencyInstallHook, } from '../../lib/hook-script.js';
 import { run } from "../../lib/run-npm.js";
 import { printVerbose, setVerboseMode, startTask, stopTask, updateTask } from '../../lib/ui.js';
 const DEFAULT_DOCKER_PLATFORM = 'auto';
@@ -231,6 +234,26 @@ export default class SourceDownload extends Command {
         'npm-registry': Flags.string({
             description: 'npm registry for npm/git downloads and dependency installation.',
         }),
+        'hook-script': Flags.string({
+            description: 'Hook module to run after npm scaffold or git clone and before dependency installation.',
+        }),
+        'hook-phase': Flags.string({
+            hidden: true,
+            options: ['init', 'upgrade', 'restore', 'source-download', 'app-start'],
+        }),
+        'hook-command': Flags.string({
+            hidden: true,
+            options: ['init', 'source:download', 'app:start', 'app:restart', 'app:upgrade'],
+        }),
+        'hook-env-name': Flags.string({
+            hidden: true,
+        }),
+        'hook-app-path': Flags.string({
+            hidden: true,
+        }),
+        'hook-storage-path': Flags.string({
+            hidden: true,
+        }),
         build: Flags.boolean({
             allowNo: true,
             description: 'Build npm/git source after dependencies are installed.',
@@ -573,6 +596,9 @@ export default class SourceDownload extends Command {
         const npmRegistryRaw = results.npmRegistry !== undefined ? String(results.npmRegistry) : flags['npm-registry'] ?? '';
         const npmRegistry = npmRegistryRaw.trim() || undefined;
         const npmDevDependencies = devDependencies ?? false;
+        const hookScript = flags['hook-script']?.trim()
+            ? path.resolve(process.cwd(), flags['hook-script'].trim())
+            : undefined;
         return {
             source,
             version,
@@ -586,6 +612,14 @@ export default class SourceDownload extends Command {
             ...(source === 'docker' ? { 'docker-platform': dockerPlatform } : {}),
             ...(source === 'docker' ? { 'docker-save': dockerSave } : {}),
             ...(npmRegistry ? { 'npm-registry': npmRegistry } : {}),
+            ...(hookScript ? { 'hook-script': hookScript } : {}),
+            ...(flags['hook-phase'] ? { 'hook-phase': flags['hook-phase'] } : {}),
+            ...(flags['hook-command'] ? { 'hook-command': flags['hook-command'] } : {}),
+            ...(flags['hook-env-name'] ? { 'hook-env-name': flags['hook-env-name'].trim() } : {}),
+            ...(flags['hook-app-path'] ? { 'hook-app-path': path.resolve(process.cwd(), flags['hook-app-path']) } : {}),
+            ...(flags['hook-storage-path']
+                ? { 'hook-storage-path': path.resolve(process.cwd(), flags['hook-storage-path']) }
+                : {}),
         };
     }
     async resolveDownloadFlags(flags) {
@@ -718,6 +752,36 @@ export default class SourceDownload extends Command {
         }
         return argv;
     }
+    async runBeforeDependencyInstallHookIfNeeded(flags, projectRoot) {
+        const hookScript = flags['hook-script']?.trim();
+        if (!hookScript || (flags.source !== 'npm' && flags.source !== 'git')) {
+            return;
+        }
+        const envName = flags['hook-env-name']?.trim() || '';
+        const env = envName ? await getEnv(envName, { scope: resolveDefaultConfigScope() }) : undefined;
+        const appPath = flags['hook-app-path']?.trim() || projectRoot;
+        const storagePath = flags['hook-storage-path']?.trim() || path.join(appPath, 'storage');
+        const context = buildBeforeDependencyInstallHookContext({
+            phase: flags['hook-phase'] ?? 'source-download',
+            command: flags['hook-command'] ?? 'source:download',
+            envName,
+            source: flags.source,
+            version: flags.version,
+            appPath,
+            sourcePath: projectRoot,
+            storagePath,
+            hookScript,
+            envConfig: env?.config ?? {},
+        });
+        if (!context) {
+            return;
+        }
+        this.log(`Running hook before dependency install: ${hookScript}`);
+        await runBeforeDependencyInstallHook({
+            hookScriptPath: hookScript,
+            context,
+        });
+    }
     async downloadFromDocker(flags) {
         const imageRef = resolveDockerImageRef(flags['docker-registry'], flags.version, {
             defaultRegistry: defaultDockerRegistryForLang(process.env.NB_LOCALE),
@@ -777,6 +841,7 @@ export default class SourceDownload extends Command {
             errorName: 'npx create-nocobase-app',
             loadingMessage: 'Creating the app scaffold',
         });
+        await this.runBeforeDependencyInstallHookIfNeeded(flags, projectRoot);
         const installArgs = ['install'];
         if (!flags['dev-dependencies']) {
             installArgs.push('--production');
@@ -820,6 +885,7 @@ export default class SourceDownload extends Command {
         });
         const projectRoot = path.resolve(process.cwd(), outputDir);
         const registryEnv = this.npmRegistryEnv(flags);
+        await this.runBeforeDependencyInstallHookIfNeeded(flags, projectRoot);
         this.log(`Installing dependencies in ${projectRoot}`);
         await this.runExternalCommand('yarn', ['install'], {
             ...this.runOptionsWithCwd(projectRoot, registryEnv),

package/dist/lib/app-managed-resources.js

@@ -13,6 +13,7 @@ import { deriveBuiltinDbConnection, resolveBuiltinDbConnection } from './builtin
 import { resolveConfiguredStoragePath } from './env-paths.js';
 import { resolveDockerEnvFileArg } from "./docker-env-file.js";
 import { DEFAULT_DOCKER_REGISTRY, DEFAULT_DOCKER_VERSION, resolveDockerImageRef, } from "./docker-image.js";
+import { resolveHookScriptPath } from './hook-script.js';
 import { commandSucceeds, ensureDockerDaemonRunning, run } from './run-npm.js';
 import Install from '../commands/install.js';
 const DOCKER_APP_STORAGE_DESTINATION = '/app/nocobase/storage';
@@ -302,6 +303,13 @@ export function buildSavedLocalDownloadArgv(runtime, options) {
     if (config.buildDts === true) {
         argv.push('--build-dts');
     }
+    const hookScriptPath = resolveHookScriptPath({
+        appPath: runtime.env.appPath,
+        hookScript: config.hookScript,
+    });
+    if (hookScriptPath) {
+        argv.push('--hook-script', hookScriptPath, '--hook-phase', options?.hookPhase ?? 'restore', '--hook-command', options?.hookCommand ?? 'app:start', '--hook-env-name', runtime.envName, '--hook-app-path', runtime.env.appPath, '--hook-storage-path', runtime.env.storagePath);
+    }
     return argv;
 }
 export async function ensureSavedLocalSource(runtime, runCommand, options) {
@@ -313,6 +321,8 @@ export async function ensureSavedLocalSource(runtime, runCommand, options) {
     try {
         await runCommand('source:download', buildSavedLocalDownloadArgv(runtime, {
             verbose: options?.verbose,
+            hookPhase: options?.hookPhase,
+            hookCommand: options?.hookCommand,
         }));
         options?.onSucceedTask?.(`NocoBase files are ready for "${runtime.envName}".`);
     }

package/dist/lib/auth-store.js

@@ -12,6 +12,7 @@ import { resolveAppPublicPath } from './app-public-path.js';
 import { resolveCliHomeDir, resolveConfiguredEnvPath, resolveEnvRelativePath } from './cli-home.js';
 import { normalizeCliLocale } from './cli-locale.js';
 import { inferConfiguredAppPathFromLegacyConfig, resolveConfiguredAppPath, resolveConfiguredSourcePath, resolveConfiguredStoragePath, } from './env-paths.js';
+import { ENV_CONFIG_SCHEMA_VERSION, normalizeEnvConfigSchemaVersion } from './env-config.js';
 import { cleanupCurrentSessionAfterEnvRemoval, resolveEffectiveCurrentEnv, setSessionCurrentEnv, } from './session-store.js';
 function normalizeStoredEnvKind(value) {
     const kind = String(value ?? '').trim();
@@ -76,11 +77,13 @@ function normalizeEnvConfigEntry(entry) {
     if (!entry) {
         return entry;
     }
-    const { kind: _kind, apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, ...rest } = entry;
+    const { kind: _kind, apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, schemaVersion: _schemaVersion, ...rest } = entry;
     const normalizedKind = resolveEnvKind(entry);
     const apiBaseUrl = readEnvApiBaseUrl(entry);
+    const schemaVersion = normalizeEnvConfigSchemaVersion(entry.schemaVersion);
     return {
         ...rest,
+        ...(schemaVersion ? { schemaVersion } : {}),
         ...(normalizedKind ? { kind: normalizedKind } : {}),
         ...(apiBaseUrl !== undefined ? { apiBaseUrl } : {}),
         ...(normalizeOptionalString(entry.appPublicPath) ? { appPublicPath: resolveAppPublicPath(entry.appPublicPath) } : {}),
@@ -366,7 +369,13 @@ function areAuthConfigsEquivalent(left, right) {
 async function writeEnv(envName, updater, options = {}) {
     const config = await loadExactAuthConfig(options);
     const previous = config.envs[envName];
-    config.envs[envName] = updater(previous);
+    const next = updater(previous);
+    config.envs[envName] = {
+        ...next,
+        schemaVersion: normalizeEnvConfigSchemaVersion(next.schemaVersion) ??
+            normalizeEnvConfigSchemaVersion(previous?.schemaVersion) ??
+            ENV_CONFIG_SCHEMA_VERSION,
+    };
     await saveAuthConfig(config, options);
 }
 function normalizeConfiguredAuthType(value) {
@@ -377,18 +386,19 @@ export function resolveConfiguredAuthType(config) {
 }
 export async function upsertEnv(envName, config, options = {}) {
     await writeEnv(envName, (previous) => {
-        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, ...rest } = config;
+        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, schemaVersion, ...rest } = config;
         const nextApiBaseUrl = readEnvApiBaseUrl(config);
         const previousApiBaseUrl = readEnvApiBaseUrl(previous);
         const baseUrlChanged = previousApiBaseUrl !== nextApiBaseUrl;
         const previousAuthType = resolveConfiguredAuthType(previous);
         const requestedAuthType = normalizeConfiguredAuthType(authType);
-        const nextAuthType = requestedAuthType ?? (accessToken ? 'token' : previousAuthType);
+        const nextAccessToken = normalizeOptionalString(accessToken);
+        const nextAuthType = requestedAuthType ?? (nextAccessToken ? 'token' : previousAuthType);
         const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(authUsername) ?? previous?.authUsername : undefined;
-        const nextAuth = accessToken
+        const nextAuth = nextAccessToken
             ? {
                 type: 'token',
-                accessToken,
+                accessToken: nextAccessToken,
             }
             : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
                 ? previous.auth
@@ -396,6 +406,9 @@ export async function upsertEnv(envName, config, options = {}) {
         const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
         const authTypeChanged = previousAuthType !== nextAuthType;
         const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
+        const nextSchemaVersion = normalizeEnvConfigSchemaVersion(schemaVersion) ??
+            normalizeEnvConfigSchemaVersion(previous?.schemaVersion) ??
+            ENV_CONFIG_SCHEMA_VERSION;
         return {
             ...previous,
             apiBaseUrl: nextApiBaseUrl,
@@ -403,6 +416,7 @@ export async function upsertEnv(envName, config, options = {}) {
             authUsername: nextAuthUsername,
             auth: nextAuth,
             ...rest,
+            schemaVersion: nextSchemaVersion,
             runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
         };
     }, options);

package/dist/lib/env-config.js

@@ -14,6 +14,7 @@ const STRING_ENV_CONFIG_KEYS = [
     'dockerPlatform',
     'gitUrl',
     'npmRegistry',
+    'hookScript',
     'appPath',
     'appRootPath',
     'storagePath',
@@ -46,6 +47,7 @@ const BOOLEAN_ENV_CONFIG_KEYS = [
     'buildDts',
     'dbUnderscored',
 ];
+export const ENV_CONFIG_SCHEMA_VERSION = 1;
 function trimConfigValue(value) {
     const text = String(value ?? '').trim();
     return text || undefined;
@@ -53,6 +55,9 @@ function trimConfigValue(value) {
 function resolveSetupState(value) {
     return value === 'prepared' || value === 'installed' ? value : undefined;
 }
+export function normalizeEnvConfigSchemaVersion(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
 function resolveEnvKind(input) {
     const source = trimConfigValue(input.source);
     const appPath = trimConfigValue(input.appPath);
@@ -67,6 +72,7 @@ function resolveEnvKind(input) {
 }
 export function buildStoredEnvConfig(input) {
     const envConfig = {
+        schemaVersion: normalizeEnvConfigSchemaVersion(input.schemaVersion) ?? ENV_CONFIG_SCHEMA_VERSION,
         kind: resolveEnvKind(input),
         apiBaseUrl: trimConfigValue(input.apiBaseUrl) ?? '',
     };

package/dist/lib/hook-script.js

@@ -0,0 +1,160 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { copyFile, mkdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+export const ENV_HOOK_SCRIPT_CONFIG_PATH = '.nb/hooks.mjs';
+const require = createRequire(import.meta.url);
+const { spawn } = require('node:child_process');
+function trimValue(value) {
+    return String(value ?? '').trim();
+}
+function normalizeHookPhase(value) {
+    const text = trimValue(value);
+    if (text === 'init' || text === 'upgrade' || text === 'restore' || text === 'source-download' || text === 'app-start') {
+        return text;
+    }
+    return 'init';
+}
+function normalizeHookCommand(value) {
+    const text = trimValue(value);
+    if (text === 'source:download' || text === 'app:start' || text === 'app:restart' || text === 'app:upgrade') {
+        return text;
+    }
+    return 'init';
+}
+function normalizeHookSource(value) {
+    const text = trimValue(value);
+    if (text === 'npm' || text === 'git' || text === 'docker') {
+        return text;
+    }
+    return undefined;
+}
+function isDependencyHookSource(source) {
+    return source === 'npm' || source === 'git';
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function resolveHookScriptPath(params) {
+    const hookScript = trimValue(params.hookScript);
+    if (!hookScript) {
+        return undefined;
+    }
+    if (path.isAbsolute(hookScript)) {
+        return hookScript;
+    }
+    const appPath = trimValue(params.appPath);
+    if (!appPath) {
+        return hookScript;
+    }
+    const usesWindowsSeparators = appPath.includes('\\') || /^[a-zA-Z]:([\\/]|$)/.test(appPath) || appPath.startsWith('\\\\');
+    return usesWindowsSeparators ? path.win32.join(appPath, hookScript) : path.posix.join(appPath, hookScript);
+}
+export async function persistHookScript(params) {
+    const sourcePath = path.resolve(params.sourcePath);
+    const targetPath = path.join(params.appPath, ENV_HOOK_SCRIPT_CONFIG_PATH);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    if (path.resolve(sourcePath) !== path.resolve(targetPath)) {
+        await copyFile(sourcePath, targetPath);
+    }
+    return ENV_HOOK_SCRIPT_CONFIG_PATH;
+}
+const hookRunnerScript = `
+import { pathToFileURL } from 'node:url';
+
+const knownHookNames = ['beforeDependencyInstall', 'beforeAppInstall', 'afterAppStart'];
+const [, hookScriptPath, hookName, contextJson] = process.argv;
+const url = pathToFileURL(hookScriptPath);
+url.searchParams.set('t', String(Date.now()));
+
+const imported = await import(url.href);
+const hooks = imported.default ?? imported;
+
+if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) {
+  throw new Error('Hook script must export an object.');
+}
+
+for (const knownHookName of knownHookNames) {
+  if (Object.prototype.hasOwnProperty.call(hooks, knownHookName) && typeof hooks[knownHookName] !== 'function') {
+    throw new Error(\`Hook "\${knownHookName}" must be a function.\`);
+  }
+}
+
+const hook = hooks[hookName];
+if (typeof hook === 'function') {
+  await hook(JSON.parse(contextJson));
+}
+`;
+async function runHookInSubprocess(params) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, ['--input-type=module', '--eval', hookRunnerScript, params.hookScriptPath, params.hookName, JSON.stringify(params.context)], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on?.('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on?.('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.once('error', reject);
+        child.once('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const output = stderr.trim() || stdout.trim();
+            reject(new Error(output || `Hook process exited with code ${code ?? 'unknown'}.`));
+        });
+    });
+}
+export function buildHookContext(params) {
+    const source = normalizeHookSource(params.source);
+    if (!source) {
+        return undefined;
+    }
+    const version = trimValue(params.version);
+    return {
+        phase: normalizeHookPhase(params.phase),
+        command: normalizeHookCommand(params.command),
+        envName: trimValue(params.envName),
+        source,
+        ...(version ? { version } : {}),
+        appPath: params.appPath,
+        sourcePath: params.sourcePath,
+        storagePath: params.storagePath,
+        hookScript: params.hookScript,
+        envConfig: { ...(params.envConfig ?? {}) },
+    };
+}
+export function buildBeforeDependencyInstallHookContext(params) {
+    const context = buildHookContext(params);
+    if (!context || !isDependencyHookSource(context.source)) {
+        return undefined;
+    }
+    return context;
+}
+export async function runHookScriptHook(params) {
+    try {
+        await runHookInSubprocess(params);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error([`Hook script failed: ${params.hookScriptPath}`, `Hook stage: ${params.hookName}`, `Details: ${message}`].join('\n'));
+    }
+}
+export async function runBeforeDependencyInstallHook(params) {
+    await runHookScriptHook({
+        hookScriptPath: params.hookScriptPath,
+        hookName: 'beforeDependencyInstall',
+        context: params.context,
+    });
+}

package/dist/lib/source-publish.js

@@ -232,7 +232,7 @@ export async function publishSourceSnapshot(params) {
             version,
             stdio,
         });
-        await run('yarn', ['lerna', 'publish', 'from-package', '--registry', npmRegistry, '--dist-tag', 'local', '--yes', '--no-verify-access', '--git-head', gitSha], {
+        await run('yarn', ['lerna', 'publish', 'from-package', '--registry', npmRegistry, '--dist-tag', 'local', '--yes', '--no-verify-access', '--no-git-reset', '--git-head', gitSha], {
             cwd: projectRoot,
             errorName: 'lerna publish',
             stdio,
@@ -319,7 +319,7 @@ export function buildSuggestedInitCommand(result) {
     const normalizedRegistry = result.npmRegistry || `http://${host}:${port || DEFAULT_SOURCE_REGISTRY_PORT}`;
     const suggestedEnv = ['snapshot', sanitizeEnvSegment(result.gitSha)].filter(Boolean).join('');
     return [
-        `nb init --ui --env ${suggestedEnv} --yes --source npm`,
+        `nb init --env ${suggestedEnv} --yes --source npm`,
         `--version ${result.version}`,
         `--npm-registry=${normalizedRegistry}`,
     ].join(' ');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/cli",
-  "version": "2.2.0-beta.3",
+  "version": "2.2.0-beta.6",
   "description": "NocoBase Command Line Tool",
   "type": "module",
   "main": "dist/generated/command-registry.js",
@@ -143,5 +143,5 @@
     "type": "git",
     "url": "git+https://github.com/nocobase/nocobase.git"
   },
-  "gitHead": "7b16bb2cfd427c110c6671252138cd85155723c5"
+  "gitHead": "dc9246516f8a3efd6056f22fe7b3bc947bd4575b"
 }