@nocobase/cli 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/commands/init.js

@@ -15,15 +15,18 @@ 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 { resolveDefaultApiHost, resolveDefaultUiHost } from '../lib/cli-config.js';
+import { resolveConfiguredEnvPath, resolveDefaultConfigScope, resolveEnvRelativePath } from '../lib/cli-home.js';
+import { getCliConfigValue, resolveDefaultApiHost, resolveDefaultUiHost } from '../lib/cli-config.js';
+import { resolveOfficialDockerRegistry } from '../lib/docker-image.js';
 import { areConfiguredPathsEquivalent, deriveConfiguredSourcePath, deriveConfiguredStoragePath, inferConfiguredAppPathFromLegacyConfig, } from '../lib/env-paths.js';
 import { formatMissingManagedAppEnvMessage } from '../lib/app-runtime.js';
 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";
@@ -246,16 +249,12 @@ function formatBrowserOpenError(error) {
     return String(error);
 }
 export default class Init extends Command {
-    static summary = 'Set up NocoBase so coding agents can connect and work with it';
-    static description = `Set up NocoBase for coding agents in the current workspace.
+    static summary = 'Set up or connect a NocoBase environment in the current workspace';
+    static description = `Set up NocoBase in the current workspace.
 
-\`nb init\` prepares a NocoBase environment that coding agents can use. It supports three setup paths:
+\`nb init\` helps you install a new NocoBase app, take over managing one that already exists on this machine, or connect a remote NocoBase app and save it as a CLI env.
 
-- Install a new NocoBase app, then save it as a CLI env.
-- Take over managing an app that already exists on this machine by reusing its database.
-- Connect a remote NocoBase app and save it as a CLI env.
-
-It can also install NocoBase AI coding skills (\`nocobase/skills\`) so agents get the project-specific workflow guidance.
+You can use the saved environment directly, or let a coding agent access it later. It can also install NocoBase AI coding skills (\`nocobase/skills\`) when you want agent-specific workflow guidance.
 
 If setup was interrupted earlier, use \`--resume\` with an existing env name to continue from the saved workspace config.
 
@@ -475,7 +474,7 @@ Prompt modes:
             default: false,
         }),
         'ui-host': Flags.string({
-            description: 'Host for the local --ui setup server (default: 127.0.0.1)',
+            description: 'Browser-accessible host for the --ui setup page URL (default: 127.0.0.1)',
         }),
         'ui-port': Flags.integer({
             description: 'Port for the local --ui setup server; 0 lets the OS choose an available port',
@@ -699,6 +698,12 @@ Prompt modes:
         if (flags.yes && !Object.prototype.hasOwnProperty.call(downloadSeed, 'source')) {
             downloadSeed.source = 'docker';
         }
+        const builtinDbImageRegistry = String(presetValues.dockerRegistry ?? '').trim() ||
+            resolveOfficialDockerRegistry(await getCliConfigValue('nb-image-registry'));
+        if (!Object.prototype.hasOwnProperty.call(presetValues, 'dockerRegistry')) {
+            out.dockerRegistry = builtinDbImageRegistry;
+        }
+        out.builtinDbImageRegistry = builtinDbImageRegistry;
         const dbInitial = await Install.buildDbPromptInitialValues({
             flags,
             downloadResults: downloadSeed,
@@ -706,6 +711,9 @@ Prompt modes:
             warnOnPortFallback: false,
         });
         for (const [key, value] of Object.entries(dbInitial)) {
+            if (key === 'builtinDbImage') {
+                continue;
+            }
             if (!Object.prototype.hasOwnProperty.call(presetValues, key)) {
                 out[key] = value;
             }
@@ -1032,6 +1040,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
@@ -1040,6 +1056,7 @@ Prompt modes:
         results.appKey = appKey;
         results.timeZone = timeZone;
         await upsertEnv(envName, {
+            schemaVersion: ENV_CONFIG_SCHEMA_VERSION,
             ...(source === 'docker'
                 ? { kind: 'docker' }
                 : source || appPath || appRootPath
@@ -1057,6 +1074,7 @@ Prompt modes:
             ...(dockerPlatform ? { dockerPlatform } : {}),
             ...(gitUrl ? { gitUrl } : {}),
             ...(npmRegistry ? { npmRegistry } : {}),
+            ...(hookScript ? { hookScript } : {}),
             ...(appPath ? { appPath } : {}),
             ...(appRootPath && !areConfiguredPathsEquivalent(appRootPath, derivedAppRootPath) ? { appRootPath } : {}),
             ...(storagePath && !areConfiguredPathsEquivalent(storagePath, derivedStoragePath) ? { storagePath } : {}),
@@ -1132,6 +1150,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

@@ -13,11 +13,11 @@ import path from 'node:path';
 import { exit } from 'node:process';
 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 { applyCliLocale, localeText, 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 { resolveDefaultApiHost, resolveDockerContainerPrefix, resolveDockerNetworkName } from '../lib/cli-config.js';
-import { DEFAULT_DOCKER_VERSION, resolveDockerImageRef } from "../lib/docker-image.js";
+import { defaultDockerContainerPrefix, defaultDockerNetworkName, managedAppLifecycleEnvVars, } from '../lib/app-runtime.js';
+import { getCliConfigValue, resolveDefaultApiHost, resolveDockerContainerPrefix, resolveDockerNetworkName, } from '../lib/cli-config.js';
+import { DEFAULT_DOCKER_VERSION, DEFAULT_NB_IMAGE_VARIANT, inferNbImageRegistryFromRepository, normalizeNbImageVariant, resolveBuiltinDbImage, resolveDockerImageContainerPort, resolveDockerImageRef, resolveOfficialDockerRegistry, } from "../lib/docker-image.js";
 import { findAvailableTcpPort, validateAppPublicPath, validateAvailableTcpPort, validateTcpPort, validateEnvKey, } from "../lib/prompt-validators.js";
 import { validateExternalDbConfig, validateMysqlLowerCaseTableNamesCompatibility } from "../lib/db-connection-check.js";
 import { formatMissingManagedAppEnvMessage } from '../lib/app-runtime.js';
@@ -29,8 +29,9 @@ 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 Download from './download.js';
 import EnvAdd from "./env/add.js";
 import { resolveAppUrlFromApiBaseUrl } from "./env/shared.js";
 const DEFAULT_INSTALL_ENV_NAME = 'local';
@@ -44,18 +45,6 @@ const DEFAULT_INSTALL_DB_PORTS = {
     mariadb: '3306',
     kingbase: '54321',
 };
-const DEFAULT_INSTALL_BUILTIN_DB_IMAGES = {
-    postgres: 'postgres:16',
-    mysql: 'mysql:8',
-    mariadb: 'mariadb:11',
-    kingbase: 'registry.cn-shanghai.aliyuncs.com/nocobase/kingbase:v009r001c001b0030_single_x86',
-};
-const DEFAULT_INSTALL_BUILTIN_DB_IMAGES_ZH_CN = {
-    postgres: 'registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16',
-    mysql: 'registry.cn-shanghai.aliyuncs.com/nocobase/mysql:8',
-    mariadb: 'registry.cn-shanghai.aliyuncs.com/nocobase/mariadb:11',
-    kingbase: 'registry.cn-shanghai.aliyuncs.com/nocobase/kingbase:v009r001c001b0030_single_x86',
-};
 const DEFAULT_INSTALL_DB_DATABASE = 'nocobase';
 const DEFAULT_INSTALL_DB_USER = 'nocobase';
 const DEFAULT_INSTALL_DB_PASSWORD = 'nocobase';
@@ -178,22 +167,23 @@ function downloadVersionPromptValue(version) {
 }
 function supportsBuiltinDbDialect(value) {
     const dialect = String(value ?? '').trim();
-    return Object.prototype.hasOwnProperty.call(DEFAULT_INSTALL_BUILTIN_DB_IMAGES, dialect);
+    return INSTALL_DB_DIALECTS.includes(dialect);
 }
 export function defaultDbPortForDialect(value) {
     const dialect = String(value ?? 'postgres').trim();
     return DEFAULT_INSTALL_DB_PORTS[isInstallDbDialect(dialect) ? dialect : 'postgres'];
 }
-function defaultBuiltinDbImageForDialect(value) {
+function defaultBuiltinDbImageForDialect(value, options) {
     const dialect = String(value ?? 'postgres').trim();
-    const defaults = resolveCliLocale(process.env.NB_LOCALE) === 'zh-CN'
-        ? DEFAULT_INSTALL_BUILTIN_DB_IMAGES_ZH_CN
-        : DEFAULT_INSTALL_BUILTIN_DB_IMAGES;
-    return supportsBuiltinDbDialect(dialect) ? defaults[dialect] : defaults.postgres;
+    return resolveBuiltinDbImage(dialect, { registry: options?.registry });
 }
 function defaultDbDatabaseForDialect(value) {
     return String(value ?? '').trim() === 'kingbase' ? 'kingbase' : DEFAULT_INSTALL_DB_DATABASE;
 }
+function supportsDbSchemaPrompt(value) {
+    const dialect = String(value ?? '').trim();
+    return dialect === 'postgres' || dialect === 'kingbase';
+}
 function defaultDbHostForBuiltinDb(values) {
     return values.builtinDb ? DEFAULT_INSTALL_BUILTIN_DB_HOST : DEFAULT_INSTALL_DB_HOST;
 }
@@ -472,7 +462,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 = {
@@ -547,7 +540,9 @@ export default class Install extends Command {
             type: 'text',
             message: installText('prompts.builtinDbImage.message'),
             placeholder: installText('prompts.builtinDbImage.placeholder'),
-            initialValue: (values) => defaultBuiltinDbImageForDialect(values.dbDialect),
+            initialValue: (values) => defaultBuiltinDbImageForDialect(values.dbDialect, {
+                registry: String(values.builtinDbImageRegistry ?? '').trim() || undefined,
+            }),
             hidden: (values) => !values.builtinDb || !supportsBuiltinDbDialect(values.dbDialect),
             required: true,
         },
@@ -597,7 +592,7 @@ export default class Install extends Command {
             type: 'text',
             message: installText('prompts.dbSchema.message'),
             placeholder: installText('prompts.dbSchema.placeholder'),
-            hidden: (values) => String(values.dbDialect ?? '').trim() !== 'postgres',
+            hidden: (values) => !supportsDbSchemaPrompt(values.dbDialect),
         },
         dbTablePrefix: {
             type: 'text',
@@ -1095,6 +1090,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 +1121,7 @@ export default class Install extends Command {
             ...(appPort ? { appPort } : {}),
             ...(storagePath ? { storagePath } : {}),
             ...(appPublicPath ? { appPublicPath } : {}),
+            ...(hookScript ? { hookScript } : {}),
         };
         const downloadPreset = {
             ...(source ? { source } : {}),
@@ -1273,19 +1270,25 @@ export default class Install extends Command {
         return builtinDb && Install.shouldPublishBuiltinDbPort(values.source);
     }
     static async buildDbPromptInitialValues(params) {
-        if (params.flags['db-port'] !== undefined) {
-            return {};
-        }
+        const configuredRegistry = await getCliConfigValue('nb-image-registry');
         const values = {
             ...params.downloadResults,
             ...params.dbPreset,
         };
+        const dockerRegistry = String(values.dockerRegistry ?? '').trim() || resolveOfficialDockerRegistry(configuredRegistry);
+        const dialect = String(values.dbDialect ?? 'postgres').trim() || 'postgres';
+        const initialValues = values.builtinDb !== false && params.dbPreset.builtinDbImage === undefined
+            ? { builtinDbImage: defaultBuiltinDbImageForDialect(dialect, { registry: dockerRegistry }) }
+            : {};
+        if (params.flags['db-port'] !== undefined) {
+            return initialValues;
+        }
         if (!Install.shouldPublishBuiltinDbPortForValues(values)) {
-            return {};
+            return initialValues;
         }
-        const dialect = String(values.dbDialect ?? 'postgres').trim() || 'postgres';
         const defaultPort = defaultDbPortForDialect(dialect);
         return {
+            ...initialValues,
             dbPort: await Install.resolveAvailableDefaultPort(defaultPort, {
                 label: `Default ${dialect} port`,
                 warn: params.warnOnPortFallback ?? true,
@@ -1296,12 +1299,13 @@ export default class Install extends Command {
      * When install runs {@link Download.prompts} after app prompts, align the download
      * output directory with app settings, while Docker registry defaults follow the CLI locale.
      */
-    static buildDownloadPromptOptionsForInstall(appResults, envName) {
+    static async buildDownloadPromptOptionsForInstall(appResults, envName) {
         const appRoot = resolveConfiguredSourcePathValue(appResults, envName);
         const lang = String(appResults.lang ?? DEFAULT_INSTALL_LANG).trim() || DEFAULT_INSTALL_LANG;
+        const dockerRegistry = resolveOfficialDockerRegistry(await getCliConfigValue('nb-image-registry'));
         const initialValues = {
             lang,
-            dockerRegistry: defaultDockerRegistryForLang(process.env.NB_LOCALE),
+            dockerRegistry,
             outputDir: appRoot,
         };
         const values = {
@@ -1462,8 +1466,6 @@ export default class Install extends Command {
                 '-d',
                 '--name',
                 containerName,
-                '--restart',
-                'always',
                 '--network',
                 networkName,
                 '-e',
@@ -1506,8 +1508,6 @@ export default class Install extends Command {
                 '-d',
                 '--name',
                 containerName,
-                '--restart',
-                'always',
                 '--network',
                 networkName,
                 '-e',
@@ -1552,8 +1552,6 @@ export default class Install extends Command {
                 '-d',
                 '--name',
                 containerName,
-                '--restart',
-                'always',
                 '--network',
                 networkName,
                 '-e',
@@ -1598,8 +1596,6 @@ export default class Install extends Command {
                 '-d',
                 '--name',
                 containerName,
-                '--restart',
-                'always',
                 '--network',
                 networkName,
                 '--platform',
@@ -1762,12 +1758,15 @@ export default class Install extends Command {
         return plan;
     }
     static async buildDockerAppPlan(params) {
+        const configuredRegistry = await getCliConfigValue('nb-image-registry');
+        const configuredVariant = normalizeNbImageVariant(await getCliConfigValue('nb-image-variant')) ?? DEFAULT_NB_IMAGE_VARIANT;
         const dockerRegistry = String(downloadResultsValue(params.downloadResults, 'dockerRegistry') ?? '').trim() ||
-            defaultDockerRegistryForLang(process.env.NB_LOCALE);
+            resolveOfficialDockerRegistry(configuredRegistry);
         const version = String(downloadResultsValue(params.downloadResults, 'version') ?? '').trim() || DEFAULT_DOCKER_VERSION;
         const imageRef = resolveDockerImageRef(dockerRegistry, version, {
-            defaultRegistry: defaultDockerRegistryForLang(process.env.NB_LOCALE),
+            defaultRegistry: resolveOfficialDockerRegistry(configuredRegistry),
             defaultVersion: DEFAULT_DOCKER_VERSION,
+            variant: inferNbImageRegistryFromRepository(dockerRegistry) ? configuredVariant : undefined,
         });
         const appPort = String(params.appResults.appPort ?? DEFAULT_INSTALL_APP_PORT).trim() || DEFAULT_INSTALL_APP_PORT;
         const configuredStoragePath = resolveConfiguredStoragePathValue(params.appResults, params.envName);
@@ -1794,17 +1793,16 @@ export default class Install extends Command {
             appResults: params.appResults,
             rootResults: params.rootResults,
         });
+        const containerPort = resolveDockerImageContainerPort(imageRef);
         const args = [
             'run',
             '-d',
             '--name',
             containerName,
-            '--restart',
-            'always',
             '--network',
             params.networkName,
             '-p',
-            `${appPort}:80`,
+            `${appPort}:${containerPort}`,
         ];
         if (envFile) {
             args.push('--env-file', envFile);
@@ -1916,6 +1914,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 +1946,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';
     }
@@ -1954,12 +1992,15 @@ export default class Install extends Command {
     }
     async ensureSkippedDownloadInputsReady(params) {
         if (params.source === 'docker') {
+            const configuredRegistry = await getCliConfigValue('nb-image-registry');
+            const configuredVariant = normalizeNbImageVariant(await getCliConfigValue('nb-image-variant')) ?? DEFAULT_NB_IMAGE_VARIANT;
             const dockerRegistry = String(downloadResultsValue(params.downloadResults, 'dockerRegistry') ?? '').trim() ||
-                defaultDockerRegistryForLang(process.env.NB_LOCALE);
+                resolveOfficialDockerRegistry(configuredRegistry);
             const version = String(downloadResultsValue(params.downloadResults, 'version') ?? '').trim() || DEFAULT_DOCKER_VERSION;
             const imageRef = resolveDockerImageRef(dockerRegistry, version, {
-                defaultRegistry: defaultDockerRegistryForLang(process.env.NB_LOCALE),
+                defaultRegistry: resolveOfficialDockerRegistry(configuredRegistry),
                 defaultVersion: DEFAULT_DOCKER_VERSION,
+                variant: inferNbImageRegistryFromRepository(dockerRegistry) ? configuredVariant : undefined,
             });
             const imageExists = await commandSucceeds('docker', ['image', 'inspect', imageRef]);
             if (!imageExists) {
@@ -2011,7 +2052,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 +2259,51 @@ export default class Install extends Command {
         }
         await this.config.runCommand('env:update', [params.envName]);
     }
+    buildAppStartArgv(params) {
+        const argv = ['--env', params.envName, '--yes', '--no-sync-licensed-plugins', '--hook-command', 'init'];
+        if (params.verbose) {
+            argv.push('--verbose');
+        }
+        return argv;
+    }
+    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 +2335,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,7 +2400,10 @@ export default class Install extends Command {
             yesInitialValues: { resume: parsed.resume },
             yes,
         });
-        const downloadOpts = Install.buildDownloadPromptOptionsForInstall(appResults, envName);
+        if (resumePreset?.appPreset?.hookScript !== undefined && appResults.hookScript === undefined) {
+            appResults.hookScript = resumePreset.appPreset.hookScript;
+        }
+        const downloadOpts = await Install.buildDownloadPromptOptionsForInstall(appResults, envName);
         downloadOpts.values = {
             ...(resumePreset?.downloadPreset ?? {}),
             ...downloadOpts.values,
@@ -2418,7 +2510,6 @@ export default class Install extends Command {
         const parsed = {
             ...flags,
         };
-        const defaultApiHost = await resolveDefaultApiHost();
         if (parsed['skip-auth'] && (parsed['access-token'] !== undefined || parsed.token !== undefined)) {
             this.error('--skip-auth cannot be used with --access-token or --token.');
         }
@@ -2440,6 +2531,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
@@ -2492,8 +2589,7 @@ export default class Install extends Command {
             dbResults.dbUser = builtinDbPlan.dbUser;
             dbResults.dbPassword = builtinDbPlan.dbPassword;
         }
-        let dockerAppPlan;
-        let localAppPlan;
+        let shouldStartApp = false;
         if (source === 'docker' || source === 'npm' || source === 'git') {
             this.logStage('Preparing application');
             if (source === 'docker') {
@@ -2505,76 +2601,28 @@ export default class Install extends Command {
                     printInfo('Application image ready.');
                 }
                 if (!parsed['prepare-only']) {
-                    dockerAppPlan = await this.installDockerApp({
-                        envName,
-                        dockerNetworkName,
-                        dockerContainerPrefix,
-                        appResults,
-                        downloadResults,
-                        dbResults,
-                        rootResults,
-                        builtinDbPlan,
-                        force: parsed.force,
-                        commandStdio,
-                    });
-                    appResults.appKey = dockerAppPlan.appKey;
-                    appResults.timeZone = dockerAppPlan.timeZone;
+                    shouldStartApp = true;
                 }
             }
             else if (source === 'npm' || source === 'git') {
-                const localSource = source === 'npm' ? 'npm' : 'git';
-                const projectRoot = parsed['skip-download']
-                    ? Install.resolveLocalProjectRoot({
-                        envName,
-                        appResults,
-                        downloadResults,
-                    })
-                    : await this.downloadLocalApp({
+                if (!parsed['skip-download'] && !parsed['prepare-only']) {
+                    await this.downloadLocalApp({
                         envName,
                         appResults,
                         downloadResults,
                         verbose: parsed.verbose,
                     });
-                if (!parsed['skip-download']) {
                     printInfo('Application files ready.');
                 }
                 if (!parsed['prepare-only']) {
-                    localAppPlan = await this.startLocalApp({
-                        envName,
-                        source: localSource,
-                        projectRoot,
-                        appResults,
-                        dbResults,
-                        rootResults,
-                        commandStdio,
-                    });
-                    appResults.appKey = localAppPlan.appKey;
-                    appResults.timeZone = localAppPlan.timeZone;
+                    shouldStartApp = true;
                 }
             }
         }
         else {
             this.logDetail('Skipped app download and install.');
         }
-        if (dockerAppPlan || localAppPlan) {
-            this.logStage('Starting NocoBase');
-            await this.waitForAppHealthCheck(Install.resolveApiBaseUrl({
-                appResults,
-                envAddResults,
-                defaultApiHost,
-            }), {
-                containerName: dockerAppPlan?.containerName,
-                verbose: parsed.verbose,
-            });
-            const displayApiBaseUrl = Install.resolveApiBaseUrl({
-                appResults,
-                envAddResults,
-                defaultApiHost,
-            });
-            printInfo(`NocoBase is ready at ${formatInstallDisplayUrl(displayApiBaseUrl)}`);
-            appResults.setupState = 'installed';
-        }
-        if (dockerAppPlan || localAppPlan || builtinDbPlan) {
+        if (shouldStartApp || builtinDbPlan) {
             await this.saveInstalledEnv({
                 envName,
                 appResults,
@@ -2584,10 +2632,14 @@ export default class Install extends Command {
                 envAddResults,
             });
         }
+        if (shouldStartApp) {
+            this.logStage('Starting NocoBase');
+            await this.config.runCommand('app:start', this.buildAppStartArgv({ envName, verbose: parsed.verbose }));
+        }
         await this.syncInstalledEnvConnection({
             envName,
             envAddResults,
-            appReady: Boolean(dockerAppPlan || localAppPlan),
+            appReady: shouldStartApp,
             skipAuth: Boolean(parsed['skip-auth']),
         });
         if (!parsed['prepare-only']) {
@@ -2596,7 +2648,7 @@ export default class Install extends Command {
         if (parsed['prepare-only']) {
             printInfo(`Preparation complete for "${envName}". Activate the license, then run \`nb app start --env ${envName}\`.`);
         }
-        else if (!dockerAppPlan && !localAppPlan) {
+        else if (!shouldStartApp) {
             printInfo(`Install config for "${envName}" has been saved.`);
         }
     }

package/dist/commands/license/activate.js

@@ -143,11 +143,14 @@ export default class LicenseActivate extends Command {
         const validation = await validateLicenseKey(runtime, resolvedKey);
         const ok = !validation.keyStatus && validation.envMatch && validation.domainMatch && validation.licenseStatus === 'active';
         const licenseKeyPath = ok ? await saveLicenseKey(runtime, resolvedKey) : resolveLicenseKeyFile(runtime);
+        const shouldResolveInstanceId = Boolean(interactiveKeyFlowInstanceId || ok || (flags.json && !validation.keyStatus));
         const payload = {
             ok,
             env: runtime.envName,
             kind: runtime.kind,
-            instanceId: interactiveKeyFlowInstanceId ?? (await ensureInstanceId(runtime)),
+            instanceId: shouldResolveInstanceId
+                ? interactiveKeyFlowInstanceId ?? (await ensureInstanceId(runtime))
+                : undefined,
             mode: 'key',
             key: redactLicenseKey(resolvedKey),
             keyFile: keyFile || undefined,