@nocobase/cli 2.1.9 → 2.1.11-test.1

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';
@@ -25,6 +25,7 @@ import { installNocoBaseSkills, isNpmRegistryUnavailable } from '../lib/skills-m
 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";
@@ -1029,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
@@ -1055,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 } : {}),
@@ -1130,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

@@ -15,7 +15,7 @@ import { appendAppPublicPath } from '../lib/app-public-path.js';
 import { runPromptCatalog, } from "../lib/prompt-catalog.js";
 import { applyCliLocale, localeText, resolveCliLocale, translateCli } from "../lib/cli-locale.js";
 import { resolveConfiguredEnvPath, resolveDefaultConfigScope, resolveEnvRoot, resolveEnvRelativePath, } from '../lib/cli-home.js';
-import { defaultDockerContainerPrefix, defaultDockerNetworkName } from '../lib/app-runtime.js';
+import { defaultDockerContainerPrefix, defaultDockerNetworkName, managedAppLifecycleEnvVars, } from '../lib/app-runtime.js';
 import { resolveDefaultApiHost, resolveDockerContainerPrefix, resolveDockerNetworkName } from '../lib/cli-config.js';
 import { DEFAULT_DOCKER_VERSION, resolveDockerImageRef } from "../lib/docker-image.js";
 import { findAvailableTcpPort, validateAppPublicPath, validateAvailableTcpPort, validateTcpPort, validateEnvKey, } from "../lib/prompt-validators.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';
     }
@@ -2011,7 +2057,9 @@ export default class Install extends Command {
         const dbDialect = String(params.dbResults.dbDialect ?? 'postgres').trim() || 'postgres';
         const appKey = Install.resolveManagedAppKey(params.appResults.appKey);
         const timeZone = Install.resolveManagedTimeZone(params.appResults.timeZone);
+        const lifecycleEnvVars = managedAppLifecycleEnvVars();
         const env = {
+            ...lifecycleEnvVars,
             STORAGE_PATH: storagePath,
             APP_PORT: String(params.appResults.appPort ?? DEFAULT_INSTALL_APP_PORT).trim() || DEFAULT_INSTALL_APP_PORT,
             APP_KEY: appKey,
@@ -2216,6 +2264,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 +2333,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 +2398,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 +2530,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 +2601,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 +2630,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 +2642,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 +2692,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/self/update.js

@@ -26,7 +26,7 @@ function formatSkillsUpdateMessage(result, verbose) {
 }
 export default class SelfUpdate extends Command {
     static summary = 'Update the globally installed NocoBase CLI';
-    static description = 'Update the current NocoBase CLI install when it is managed by a standard global npm install.';
+    static description = 'Update the current NocoBase CLI install when it is managed by a standard global npm, pnpm, or yarn install.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
         '<%= config.bin %> <%= command.id %> --yes',

package/dist/commands/source/dev.js

@@ -8,8 +8,9 @@
  */
 import { Command, Flags } from '@oclif/core';
 import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
-import { ensureLocalPostinstall } from '../../lib/app-managed-resources.js';
+import { ensureLocalPostinstall, ensureNpmSourceDevDependencies } from '../../lib/app-managed-resources.js';
 import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, runLocalNocoBaseCommand, } from '../../lib/app-runtime.js';
+import { findAvailableTcpPort } from '../../lib/prompt-validators.js';
 import { announceTargetEnv, failTask, printInfo, startTask, succeedTask } from '../../lib/ui.js';
 function formatUnsupportedRuntimeMessage(kind, envName) {
     if (kind === 'docker') {
@@ -129,10 +130,7 @@ export default class SourceDev extends Command {
             this.error(formatUnsupportedRuntimeMessage(runtime.kind, runtime.envName));
         }
         announceTargetEnv(runtime.envName);
-        const devPort = flags.port ||
-            (runtime.env.appPort !== undefined && runtime.env.appPort !== null
-                ? String(runtime.env.appPort).trim()
-                : undefined);
+        const devPort = flags.port?.trim() || (await findAvailableTcpPort());
         const appUrl = appUrlForPort(devPort);
         if (await isAppAlreadyRunning(appUrl)) {
             this.error([
@@ -160,6 +158,12 @@ export default class SourceDev extends Command {
         }
         printInfo(`Starting NocoBase dev mode for "${runtime.envName}" from ${runtime.projectRoot}. Press Ctrl+C to stop.`);
         try {
+            await ensureNpmSourceDevDependencies(runtime, {
+                onStartTask: startTask,
+                onSucceedTask: succeedTask,
+                onFailTask: failTask,
+                verbose: true,
+            });
             await ensureLocalPostinstall(runtime, {
                 onStartTask: startTask,
                 onSucceedTask: succeedTask,