@nocobase/cli 2.1.0-alpha.20 → 2.1.0-alpha.21

package/dist/commands/install.js

@@ -8,696 +8,1718 @@
  */
 import { Command, Flags } from '@oclif/core';
 import * as p from '@clack/prompts';
-import pc from 'picocolors';
+import _ from 'lodash';
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
 import path from 'node:path';
-import { stdin as stdinStream, stdout as stdoutStream } from 'node:process';
-import { loadAuthConfig } from "../lib/auth-store.js";
+import { exit } from 'node:process';
+import { runPromptCatalog, } from "../lib/prompt-catalog.js";
+import { findAvailableTcpPort, validateAvailableTcpPort, validateTcpPort, validateEnvKey, } from "../lib/prompt-validators.js";
+import { formatMissingManagedAppEnvMessage } from '../lib/app-runtime.js';
+import { run, runNocoBaseCommand } from '../lib/run-npm.js';
+import { startTask, stopTask, updateTask } from '../lib/ui.js';
+import { ensureWorkspaceName, getEnv } from '../lib/auth-store.js';
+import Download, { defaultDockerRegistryForLang, } from './download.js';
+import EnvAdd from "./env/add.js";
 const DEFAULT_INSTALL_ENV_NAME = 'local';
-const DEFAULT_INSTALL_SOURCE = 'docker';
 const DEFAULT_INSTALL_LANG = 'en-US';
+const DEFAULT_INSTALL_APP_PORT = '13000';
+const DEFAULT_INSTALL_DB_HOST = '127.0.0.1';
+const DEFAULT_INSTALL_BUILTIN_DB_HOST = 'postgres';
+const DEFAULT_INSTALL_DB_PORTS = {
+    postgres: '5432',
+    mysql: '3306',
+    mariadb: '3306',
+    kingbase: '54321',
+};
+const DEFAULT_INSTALL_DB_DATABASE = 'nocobase';
+const DEFAULT_INSTALL_DB_USER = 'nocobase';
+const DEFAULT_INSTALL_DB_PASSWORD = 'nocobase';
+const DEFAULT_INSTALL_ROOT_USERNAME = 'nocobase';
+const DEFAULT_INSTALL_ROOT_EMAIL = 'admin@example.com';
+const DEFAULT_INSTALL_ROOT_PASSWORD = 'admin123';
+const DEFAULT_INSTALL_ROOT_NICKNAME = 'Super Admin';
+const CONFIG_SCOPE = 'project';
+const APP_HEALTH_CHECK_INTERVAL_MS = 2_000;
+const APP_HEALTH_CHECK_TIMEOUT_MS = 600_000;
+const APP_HEALTH_CHECK_REQUEST_TIMEOUT_MS = 5_000;
+const INSTALL_DB_DIALECTS = ['postgres', 'mysql', 'mariadb', 'kingbase'];
+const INSTALL_LANGUAGE_CODES = {
+    'ar-EG': { label: 'العربية' },
+    'az-AZ': { label: 'Azərbaycan dili' },
+    'bg-BG': { label: 'Български' },
+    'bn-BD': { label: 'Bengali' },
+    'by-BY': { label: 'Беларускі' },
+    'ca-ES': { label: 'Сatalà/Espanya' },
+    'cs-CZ': { label: 'Česky' },
+    'da-DK': { label: 'Dansk' },
+    'de-DE': { label: 'Deutsch' },
+    'el-GR': { label: 'Ελληνικά' },
+    'en-GB': { label: 'English(GB)' },
+    'en-US': { label: 'English' },
+    'es-ES': { label: 'Español' },
+    'et-EE': { label: 'Estonian (Eesti)' },
+    'fa-IR': { label: 'فارسی' },
+    'fi-FI': { label: 'Suomi' },
+    'fr-BE': { label: 'Français(BE)' },
+    'fr-CA': { label: 'Français(CA)' },
+    'fr-FR': { label: 'Français' },
+    'ga-IE': { label: 'Gaeilge' },
+    'gl-ES': { label: 'Galego' },
+    'he-IL': { label: 'עברית' },
+    'hi-IN': { label: 'हिन्दी' },
+    'hr-HR': { label: 'Hrvatski jezik' },
+    'hu-HU': { label: 'Magyar' },
+    'hy-AM': { label: 'Հայերեն' },
+    'id-ID': { label: 'Bahasa Indonesia' },
+    'is-IS': { label: 'Íslenska' },
+    'it-IT': { label: 'Italiano' },
+    'ja-JP': { label: '日本語' },
+    'ka-GE': { label: 'ქართული' },
+    'kk-KZ': { label: 'Қазақ тілі' },
+    'km-KH': { label: 'ភាសាខ្មែរ' },
+    'kn-IN': { label: 'ಕನ್ನಡ' },
+    'ko-KR': { label: '한국어' },
+    'ku-IQ': { label: 'کوردی' },
+    'lt-LT': { label: 'lietuvių' },
+    'lv-LV': { label: 'Latviešu valoda' },
+    'mk-MK': { label: 'македонски јазик' },
+    'ml-IN': { label: 'മലയാളം' },
+    'mn-MN': { label: 'Монгол хэл' },
+    'ms-MY': { label: 'بهاس ملايو' },
+    'nb-NO': { label: 'Norsk bokmål' },
+    'ne-NP': { label: 'नेपाली' },
+    'nl-BE': { label: 'Vlaams' },
+    'nl-NL': { label: 'Nederlands' },
+    'pl-PL': { label: 'Polski' },
+    'pt-BR': { label: 'Português brasileiro' },
+    'pt-PT': { label: 'Português' },
+    'ro-RO': { label: 'România' },
+    'ru-RU': { label: 'Русский' },
+    'si-LK': { label: 'සිංහල' },
+    'sk-SK': { label: 'Slovenčina' },
+    'sl-SI': { label: 'Slovenščina' },
+    'sr-RS': { label: 'српски језик' },
+    'sv-SE': { label: 'Svenska' },
+    'ta-IN': { label: 'Tamil' },
+    'th-TH': { label: 'ภาษาไทย' },
+    'tk-TK': { label: 'Turkmen' },
+    'tr-TR': { label: 'Türkçe' },
+    'uk-UA': { label: 'Українська' },
+    'ur-PK': { label: 'Oʻzbekcha' },
+    'vi-VN': { label: 'Tiếng Việt' },
+    'zh-CN': { label: '简体中文' },
+    'zh-HK': { label: '繁體中文（香港）' },
+    'zh-TW': { label: '繁體中文（台湾）' },
+};
+const INSTALL_LANGUAGE_OPTIONS = Object.entries(INSTALL_LANGUAGE_CODES).map(([value, { label }]) => ({
+    value,
+    label: `${label} (${value})`,
+}));
+function argvHasToken(argv, tokens) {
+    return tokens.some((t) => argv.includes(t));
+}
+function isInstallDbDialect(value) {
+    return INSTALL_DB_DIALECTS.includes(value);
+}
+export function defaultDbPortForDialect(value) {
+    const dialect = String(value ?? 'postgres').trim();
+    return DEFAULT_INSTALL_DB_PORTS[isInstallDbDialect(dialect) ? dialect : 'postgres'];
+}
+function defaultDbHostForBuiltinDb(values) {
+    return Boolean(values.builtinDb)
+        ? DEFAULT_INSTALL_BUILTIN_DB_HOST
+        : DEFAULT_INSTALL_DB_HOST;
+}
+function defaultInstallAppRootPath(envName) {
+    const name = String(envName ?? DEFAULT_INSTALL_ENV_NAME).trim() || DEFAULT_INSTALL_ENV_NAME;
+    return `./${name}/source/`;
+}
+function defaultInstallStoragePath(envName) {
+    const name = String(envName ?? DEFAULT_INSTALL_ENV_NAME).trim() || DEFAULT_INSTALL_ENV_NAME;
+    return `./${name}/storage/`;
+}
+function pickPresetKeys(source, keys) {
+    const out = {};
+    for (const k of keys) {
+        if (Object.prototype.hasOwnProperty.call(source, k)) {
+            out[k] = source[k];
+        }
+    }
+    return out;
+}
+async function commandSucceeds(command, args, options) {
+    return await new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: options?.cwd,
+            env: {
+                ...process.env,
+                ...options?.env,
+            },
+            stdio: 'ignore',
+        });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    });
+}
+async function commandOutput(command, args, options) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options?.cwd,
+            env: {
+                ...process.env,
+                ...options?.env,
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0) {
+                resolve(stdout);
+                return;
+            }
+            if (signal) {
+                reject(new Error(`${command} exited due to signal ${signal}`));
+                return;
+            }
+            reject(new Error(`${command} exited with code ${code}: ${stderr.trim()}`));
+        });
+    });
+}
 export default class Install extends Command {
-    static description = 'Run the legacy NocoBase install (forwards to `npm run install` in the repo root)';
+    static description = 'Install NocoBase: database, storage, admin user, and `nocobase-v1 install`. Optionally run `nb download` first; distribution and image details are configured on `nb download`, not here. Use `--resume` to continue an interrupted setup from the saved workspace env config.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> -f',
-        '<%= config.bin %> <%= command.id %> -l zh-CN',
-        '<%= config.bin %> <%= command.id %> -u nocobase -m admin@nocobase.com -p admin123',
-        '<%= config.bin %> <%= command.id %> -n "Super Admin"',
-        '<%= config.bin %> <%= command.id %> --app-root-path=./nocobase --storage-path=./storage/myenv -e myenv',
-        '<%= config.bin %> <%= command.id %> --source npm',
-        '<%= config.bin %> <%= command.id %> -y --env dev --app-root-path=./nocobase',
-        '<%= config.bin %> <%= command.id %> -y --source npm --fetch-source --app-root-path=./nocobase',
+        '<%= config.bin %> <%= command.id %> --env app1',
+        '<%= config.bin %> <%= command.id %> --env app1 --resume',
+        '<%= config.bin %> <%= command.id %> --env app1 -f',
+        '<%= config.bin %> <%= command.id %> --env app1 -l zh-CN',
+        '<%= config.bin %> <%= command.id %> --env app1 --root-username nocobase --root-email admin@nocobase.com --root-password admin123',
+        '<%= config.bin %> <%= command.id %> --env app1 --root-nickname "Super Admin"',
+        '<%= config.bin %> <%= command.id %> --env myenv --app-root-path=./myenv/source/ --storage-path=./myenv/storage/',
+        '<%= config.bin %> <%= command.id %> --env dev -y --app-root-path=./dev/source/',
+        '<%= config.bin %> <%= command.id %> --env dev -y --fetch-source --app-root-path=./dev/source/',
     ];
     static flags = {
-        source: Flags.string({
-            description: `Where to obtain the NocoBase package (default: ${DEFAULT_INSTALL_SOURCE})`,
-            options: ['git', 'npm', 'docker'],
-        }),
         yes: Flags.boolean({
             char: 'y',
             description: 'Skip interactive prompts; use flags and defaults only',
             default: false,
         }),
+        resume: Flags.boolean({
+            description: 'Resume a previous unfinished setup for this env using the saved workspace env config',
+            default: false,
+        }),
         env: Flags.string({
             char: 'e',
-            description: 'Application name (CLI env key). Required. Storage defaults to ./storage/<name> unless --storage-path is set',
+            description: 'App/env name to create or update. Defaults app paths to ./<envName>/source/ and ./<envName>/storage/.',
+        }),
+        lang: Flags.string({ description: 'Language for the installed NocoBase app', char: 'l', required: false }),
+        force: Flags.boolean({
+            description: 'Reconfigure an existing env and replace conflicting runtime resources when needed',
+            char: 'f',
+            required: false,
+        }),
+        'app-root-path': Flags.string({
+            description: 'Source directory for a local npm/git app (default: ./<envName>/source/)',
+        }),
+        'app-port': Flags.string({
+            description: 'HTTP port for the local app (default: 13000, or an available port with --yes)',
+        }),
+        'storage-path': Flags.string({
+            description: 'Storage directory for uploads and managed database data (default: ./<envName>/storage/)',
         }),
-        force: Flags.boolean({ description: 'Reinstall the application by clearing the database', char: 'f', required: false }),
-        lang: Flags.string({ description: 'Language during installation', char: 'l', required: false }),
         'root-username': Flags.string({
-            char: 'u',
-            description: 'Root username (sets INIT_ROOT_USERNAME for install; forwarded as --root-username)',
+            description: 'Initial admin username for the installed app',
             required: false,
         }),
         'root-email': Flags.string({
-            char: 'm',
-            description: 'Root user email (sets INIT_ROOT_EMAIL for install; forwarded as --root-email)',
+            description: 'Initial admin email for the installed app',
             required: false,
         }),
         'root-password': Flags.string({
-            char: 'p',
-            description: 'Root user password (forwarded as --root-password)',
+            description: 'Initial admin password for the installed app',
             required: false,
         }),
         'root-nickname': Flags.string({
-            char: 'n',
-            description: 'Root user nickname (forwarded as --root-nickname)',
+            description: 'Initial admin display name for the installed app',
             required: false,
         }),
-        'app-root-path': Flags.string({
-            description: 'Application root directory for install (relative to cwd; default: ./nocobase)',
-        }),
-        'storage-path': Flags.string({
-            description: 'Storage directory (relative to cwd; default: ./storage/<env> when --env is set, else ./storage/default)',
-        }),
-        'app-port': Flags.string({
-            description: 'Application HTTP port (APP_PORT; default: 13000)',
+        'builtin-db': Flags.boolean({
+            description: 'Create and connect a CLI-managed built-in database for the app',
+            default: false,
         }),
         'db-dialect': Flags.string({
-            description: 'Database dialect (e.g. postgres, mysql)',
+            description: 'Database dialect for the app',
             options: ['postgres', 'mysql', 'mariadb', 'kingbase'],
         }),
         'db-host': Flags.string({
-            description: 'Database host',
+            description: 'Database host for the app',
         }),
         'db-port': Flags.string({
-            description: 'Database port',
+            description: 'Database port for the app',
         }),
         'db-database': Flags.string({
-            description: 'Database name',
+            description: 'Database name for the app',
         }),
         'db-user': Flags.string({
-            description: 'Database user',
+            description: 'Database username for the app',
         }),
         'db-password': Flags.string({
-            description: 'Database password',
-        }),
-        'docker-registry': Flags.string({
-            description: 'Docker image without tag (e.g. nocobase/nocobase)',
-        }),
-        'docker-tag': Flags.string({
-            description: 'Docker image tag (e.g. latest)',
-        }),
-        'start-builtin-db': Flags.boolean({
-            description: 'Run `nb db start` before install (use with `-y` when you rely on the CLI-managed database)',
-            default: false,
+            description: 'Database password for the app',
         }),
         'fetch-source': Flags.boolean({
-            description: 'With --source npm|git, run `nb download` before install (non-interactive; in a TTY use the prompt unless you pass this to skip the question and force download)',
+            description: 'Download NocoBase app files or pull a Docker image before installing',
             default: false,
         }),
-        'download-version': Flags.string({
-            description: 'When using fetch-source or nb download: version / dist-tag (-v); default latest when non-interactive / -y',
-        }),
-        'download-git-url': Flags.string({
-            description: 'When using fetch-source with git: repository URL (nb download --git-url)',
-        }),
+        ..._.omit(Download.flags, ['yes']),
     };
-    defaultDbPort(dialect) {
-        if (dialect === 'mysql' || dialect === 'mariadb') {
-            return '3306';
-        }
-        return '5432';
+    /** Environment name only: run before {@link Install.prompts} (see `run`). */
+    static envPrompts = {
+        env: {
+            type: 'text',
+            message: 'What would you like to call this app?',
+            placeholder: DEFAULT_INSTALL_ENV_NAME,
+            required: true,
+            validate: validateEnvKey,
+        },
+    };
+    static appPrompts = {
+        lang: {
+            type: 'select',
+            message: 'Which language would you like to use?',
+            options: INSTALL_LANGUAGE_OPTIONS,
+            initialValue: DEFAULT_INSTALL_LANG,
+            yesInitialValue: DEFAULT_INSTALL_LANG,
+        },
+        // force: {
+        //   type: 'boolean',
+        //   message: 'Reinstall the application by clearing the database? (-f / --force)',
+        //   initialValue: false,
+        //   yesInitialValue: false,
+        // },
+        appRootPath: {
+            type: 'text',
+            message: 'Where should this app be stored?',
+            placeholder: './<env>/source/',
+            initialValue: (values) => defaultInstallAppRootPath(values.env ?? values.appName),
+        },
+        appPort: {
+            type: 'text',
+            message: 'Which port should this app use?',
+            placeholder: DEFAULT_INSTALL_APP_PORT,
+            validate: validateAvailableTcpPort,
+        },
+        storagePath: {
+            type: 'text',
+            message: 'Where should uploads and local files be stored?',
+            placeholder: './<env>/storage/',
+            initialValue: (values) => defaultInstallStoragePath(values.env ?? values.appName),
+        },
+        fetchSource: {
+            type: 'boolean',
+            message: 'Download NocoBase automatically if the app directory is empty?',
+            initialValue: true,
+            yesInitialValue: true,
+        },
+    };
+    static dbPrompts = {
+        builtinDb: {
+            type: 'boolean',
+            message: "Would you like to use the built-in database?",
+            initialValue: true,
+            yesInitialValue: true,
+        },
+        dbDialect: {
+            type: 'select',
+            message: 'Which database would you like to use?',
+            options: [
+                { value: 'postgres', label: 'PostgreSQL' },
+                { value: 'mysql', label: 'MySQL' },
+                { value: 'mariadb', label: 'MariaDB' },
+                { value: 'kingbase', label: 'KingbaseES' },
+            ],
+            initialValue: 'postgres',
+            yesInitialValue: 'postgres',
+            required: true,
+        },
+        dbHost: {
+            type: 'text',
+            message: 'What is the database host?',
+            placeholder: DEFAULT_INSTALL_DB_HOST,
+            initialValue: (values) => defaultDbHostForBuiltinDb(values),
+            yesInitialValue: DEFAULT_INSTALL_BUILTIN_DB_HOST,
+            required: true,
+            hidden: (values) => Boolean(values.builtinDb),
+        },
+        dbPort: {
+            type: 'text',
+            message: 'What is the database port?',
+            placeholder: DEFAULT_INSTALL_DB_PORTS.postgres,
+            initialValue: (values) => defaultDbPortForDialect(values.dbDialect),
+            required: true,
+            validate: validateTcpPort,
+            hidden: (values) => Boolean(values.builtinDb)
+                && String(values.source ?? '').trim() === 'docker',
+        },
+        dbDatabase: {
+            type: 'text',
+            message: 'What is the database name?',
+            initialValue: DEFAULT_INSTALL_DB_DATABASE,
+            yesInitialValue: DEFAULT_INSTALL_DB_DATABASE,
+            required: true,
+        },
+        dbUser: {
+            type: 'text',
+            message: 'What is the database username?',
+            initialValue: DEFAULT_INSTALL_DB_USER,
+            yesInitialValue: DEFAULT_INSTALL_DB_USER,
+            required: true,
+        },
+        dbPassword: {
+            type: 'password',
+            message: 'What is the database password?',
+            initialValue: DEFAULT_INSTALL_DB_PASSWORD,
+            yesInitialValue: DEFAULT_INSTALL_DB_PASSWORD,
+            required: true,
+        },
+    };
+    static rootUserPrompts = {
+        rootUsername: {
+            type: 'text',
+            message: 'Choose the initial admin username',
+            placeholder: DEFAULT_INSTALL_ROOT_USERNAME,
+            initialValue: DEFAULT_INSTALL_ROOT_USERNAME,
+            yesInitialValue: DEFAULT_INSTALL_ROOT_USERNAME,
+        },
+        rootEmail: {
+            type: 'text',
+            message: 'What is the initial admin email?',
+            placeholder: DEFAULT_INSTALL_ROOT_EMAIL,
+            initialValue: DEFAULT_INSTALL_ROOT_EMAIL,
+            yesInitialValue: DEFAULT_INSTALL_ROOT_EMAIL,
+        },
+        rootPassword: {
+            type: 'password',
+            message: 'Choose the initial admin password',
+            initialValue: DEFAULT_INSTALL_ROOT_PASSWORD,
+            yesInitialValue: DEFAULT_INSTALL_ROOT_PASSWORD,
+        },
+        rootNickname: {
+            type: 'text',
+            message: 'What display name should the initial admin use?',
+            placeholder: DEFAULT_INSTALL_ROOT_NICKNAME,
+            initialValue: DEFAULT_INSTALL_ROOT_NICKNAME,
+            yesInitialValue: DEFAULT_INSTALL_ROOT_NICKNAME,
+        },
+    };
+    /**
+     * App catalog with `env` seeded into `out` first so `storagePath`’s `initialValue(values)`
+     * sees `values.env` (same iteration order as {@link runPromptCatalog}).
+     */
+    static buildAppPromptsCatalog(seedEnv) {
+        return {
+            seedEnv: {
+                type: 'run',
+                run: (values) => {
+                    values.env = seedEnv;
+                },
+            },
+            ...Install.appPrompts,
+        };
     }
-    resolveAppRoot(flagPath, saved) {
-        if (flagPath) {
-            return path.resolve(process.cwd(), flagPath);
-        }
-        if (saved) {
-            return path.isAbsolute(saved) ? saved : path.resolve(process.cwd(), saved);
-        }
-        return path.resolve(process.cwd(), 'nocobase');
+    static buildDbPromptsCatalog(downloadResults) {
+        const source = String(downloadResults.source ?? '').trim();
+        return {
+            seedDownloadSource: {
+                type: 'run',
+                run: (values) => {
+                    if (source) {
+                        values.source = source;
+                    }
+                },
+            },
+            ...Install.dbPrompts,
+        };
     }
-    resolveStoragePath(flagPath, envName, saved) {
-        if (flagPath) {
-            return path.resolve(process.cwd(), flagPath);
+    /** Preset for {@link Install.envPrompts} only (`env` flag). */
+    static buildEnvPresetValuesFromFlags(flags) {
+        const preset = {};
+        if (flags.env !== undefined && String(flags.env).trim() !== '') {
+            preset.env = String(flags.env).trim();
         }
-        if (saved) {
-            return path.isAbsolute(saved) ? saved : path.resolve(process.cwd(), saved);
-        }
-        return path.resolve(process.cwd(), 'storage', envName);
+        return preset;
     }
     /**
-     * For npm/git: optionally run `nb download`, otherwise (interactive, no saved env) prompt for app root.
+     * Preset `values` for `runPromptCatalog`: keys here skip that prompt and fix the result.
+     * Booleans with defaults are only preset when the user passed the flag on argv (see `download`).
+     * Does not include `env` — use {@link buildEnvPresetValuesFromFlags} for {@link Install.envPrompts}.
      */
-    async resolveNpmGitAppRootWithDownload(options) {
-        const { source, interactive, hasSavedEnv, savedEnv, fetchSourceFlag, downloadGitUrl, } = options;
-        const downloadVersion = options.downloadVersion;
-        let appRootPathFlag = options.appRootPathFlag;
-        let runDownload;
-        if (!interactive) {
-            runDownload = fetchSourceFlag;
+    static buildPresetValuesFromFlags(flags) {
+        const preset = {};
+        const argv = process.argv.slice(2);
+        if (flags.lang !== undefined) {
+            const v = String(flags.lang).trim();
+            if (v) {
+                preset.lang = v;
+            }
         }
-        else if (hasSavedEnv) {
-            runDownload = fetchSourceFlag;
+        if (argvHasToken(argv, ['--force', '-f'])) {
+            preset.force = flags.force;
         }
-        else if (fetchSourceFlag) {
-            runDownload = true;
+        if (flags['app-root-path'] !== undefined) {
+            const v = flags['app-root-path']?.trim();
+            if (v) {
+                preset.appRootPath = v;
+            }
         }
-        else {
-            const fetchAns = await p.confirm({
-                message: 'Download or clone NocoBase source with nb download before install?',
-                initialValue: true,
-            });
-            if (p.isCancel(fetchAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        if (flags['app-port'] !== undefined) {
+            const v = String(flags['app-port'] ?? '').trim();
+            if (v) {
+                preset.appPort = v;
             }
-            runDownload = fetchAns;
-        }
-        if (!runDownload) {
-            if (interactive && !hasSavedEnv) {
-                const defaultRoot = appRootPathFlag ?? path.relative(process.cwd(), this.resolveAppRoot(undefined, savedEnv?.appRootPath));
-                const rootAns = await p.text({
-                    message: 'Application root directory (where nocobase-v1 runs; relative to cwd)',
-                    initialValue: defaultRoot || 'nocobase',
-                });
-                if (p.isCancel(rootAns)) {
-                    p.cancel('Install cancelled.');
-                    this.exit(0);
-                }
-                appRootPathFlag = rootAns.trim() || appRootPathFlag;
+        }
+        if (flags['storage-path'] !== undefined) {
+            const v = flags['storage-path']?.trim();
+            if (v) {
+                preset.storagePath = v;
             }
-            return appRootPathFlag;
-        }
-        const downloadArgv = [];
-        if (!interactive) {
-            downloadArgv.push('-y');
-        }
-        downloadArgv.push('--source', source);
-        if (!interactive) {
-            const version = downloadVersion?.trim() || 'latest';
-            downloadArgv.push('-v', version);
-            let outputDir = appRootPathFlag?.trim();
-            if (!outputDir) {
-                const safe = version.replace(/[/\\]/g, '-');
-                outputDir = `nocobase-${safe}`;
+        }
+        if (flags['root-username'] !== undefined) {
+            preset.rootUsername = String(flags['root-username'] ?? '').trim();
+        }
+        if (flags['root-email'] !== undefined) {
+            preset.rootEmail = String(flags['root-email'] ?? '').trim();
+        }
+        if (flags['root-password'] !== undefined) {
+            preset.rootPassword = String(flags['root-password'] ?? '');
+        }
+        if (flags['root-nickname'] !== undefined) {
+            preset.rootNickname = String(flags['root-nickname'] ?? '').trim();
+        }
+        if (argvHasToken(argv, ['--fetch-source'])) {
+            preset.fetchSource = flags['fetch-source'];
+        }
+        if (argvHasToken(argv, ['--builtin-db'])) {
+            preset.builtinDb = flags['builtin-db'];
+        }
+        if (flags['db-dialect'] !== undefined) {
+            const t = String(flags['db-dialect']).trim();
+            if (t && isInstallDbDialect(t)) {
+                preset.dbDialect = t;
+            }
+        }
+        if (flags['db-host'] !== undefined) {
+            const v = String(flags['db-host'] ?? '').trim();
+            if (v) {
+                preset.dbHost = v;
             }
-            downloadArgv.push('-o', outputDir);
-            if (source === 'git' && downloadGitUrl?.trim()) {
-                downloadArgv.push('--git-url', downloadGitUrl.trim());
+        }
+        if (flags['db-port'] !== undefined) {
+            const v = String(flags['db-port'] ?? '').trim();
+            if (v) {
+                preset.dbPort = v;
             }
         }
-        else {
-            const v = downloadVersion?.trim();
+        if (flags['db-database'] !== undefined) {
+            const v = String(flags['db-database'] ?? '').trim();
             if (v) {
-                downloadArgv.push('-v', v);
+                preset.dbDatabase = v;
             }
-            const out = appRootPathFlag?.trim();
-            if (out) {
-                downloadArgv.push('-o', out);
+        }
+        if (flags['db-user'] !== undefined) {
+            const v = String(flags['db-user'] ?? '').trim();
+            if (v) {
+                preset.dbUser = v;
             }
-            if (source === 'git' && downloadGitUrl?.trim()) {
-                downloadArgv.push('--git-url', downloadGitUrl.trim());
+        }
+        if (flags['db-password'] !== undefined) {
+            preset.dbPassword = String(flags['db-password'] ?? '');
+        }
+        return preset;
+    }
+    static buildAppPresetValuesFromFlags(flags) {
+        return pickPresetKeys(Install.buildPresetValuesFromFlags(flags), [
+            'lang',
+            'force',
+            'appRootPath',
+            'appPort',
+            'storagePath',
+            'fetchSource',
+        ]);
+    }
+    static buildDbPresetValuesFromFlags(flags) {
+        return pickPresetKeys(Install.buildPresetValuesFromFlags(flags), [
+            'builtinDb',
+            'dbDialect',
+            'dbHost',
+            'dbPort',
+            'dbDatabase',
+            'dbUser',
+            'dbPassword',
+        ]);
+    }
+    static buildRootPresetValuesFromFlags(flags) {
+        return pickPresetKeys(Install.buildPresetValuesFromFlags(flags), [
+            'rootUsername',
+            'rootEmail',
+            'rootPassword',
+            'rootNickname',
+        ]);
+    }
+    static toOptionalPromptString(value) {
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+        const text = String(value).trim();
+        return text || undefined;
+    }
+    static buildResumePresetValues(env) {
+        const envName = String(env.name ?? '').trim();
+        const config = env.config ?? {};
+        const source = Install.toOptionalPromptString(config.source);
+        const appRootPath = Install.toOptionalPromptString(config.appRootPath);
+        const appPort = Install.toOptionalPromptString(config.appPort);
+        const storagePath = Install.toOptionalPromptString(config.storagePath);
+        const downloadVersion = Install.toOptionalPromptString(config.downloadVersion);
+        const dockerRegistry = Install.toOptionalPromptString(config.dockerRegistry);
+        const dockerPlatform = Install.toOptionalPromptString(config.dockerPlatform);
+        const gitUrl = Install.toOptionalPromptString(config.gitUrl);
+        const npmRegistry = Install.toOptionalPromptString(config.npmRegistry);
+        const dbDialect = Install.toOptionalPromptString(config.dbDialect);
+        const dbHost = Install.toOptionalPromptString(config.dbHost);
+        const dbPort = Install.toOptionalPromptString(config.dbPort);
+        const dbDatabase = Install.toOptionalPromptString(config.dbDatabase);
+        const dbUser = Install.toOptionalPromptString(config.dbUser);
+        const dbPassword = Install.toOptionalPromptString(config.dbPassword);
+        const auth = config.auth;
+        const appPreset = {
+            ...(appRootPath ? { appRootPath } : {}),
+            ...(appPort ? { appPort } : {}),
+            ...(storagePath ? { storagePath } : {}),
+            ...(source
+                ? { fetchSource: true }
+                : appRootPath
+                    ? { fetchSource: false }
+                    : {}),
+        };
+        const downloadPreset = {
+            ...(source ? { source } : {}),
+            ...(downloadVersion ? { version: downloadVersion } : {}),
+            ...(dockerRegistry ? { dockerRegistry } : {}),
+            ...(dockerPlatform ? { dockerPlatform } : {}),
+            ...(gitUrl ? { gitUrl } : {}),
+            ...(npmRegistry ? { npmRegistry } : {}),
+            ...(typeof config.devDependencies === 'boolean'
+                ? { devDependencies: config.devDependencies }
+                : {}),
+            ...(typeof config.build === 'boolean' ? { build: config.build } : {}),
+            ...(typeof config.buildDts === 'boolean' ? { buildDts: config.buildDts } : {}),
+        };
+        const dbPreset = {
+            ...(typeof config.builtinDb === 'boolean' ? { builtinDb: config.builtinDb } : {}),
+            ...(dbDialect ? { dbDialect } : {}),
+            ...(dbHost ? { dbHost } : {}),
+            ...(dbPort ? { dbPort } : {}),
+            ...(dbDatabase ? { dbDatabase } : {}),
+            ...(dbUser ? { dbUser } : {}),
+            ...(dbPassword ? { dbPassword } : {}),
+        };
+        const envAddPreset = {};
+        if (auth?.type === 'token') {
+            envAddPreset.authType = 'token';
+            if (Install.toOptionalPromptString(auth.accessToken)) {
+                envAddPreset.accessToken = String(auth.accessToken);
             }
         }
-        if (interactive) {
-            p.log.step('Running nb download');
+        else if (auth?.type === 'oauth') {
+            envAddPreset.authType = 'oauth';
         }
-        else {
-            this.log('Running nb download');
+        return {
+            envPreset: {
+                ...(envName ? { env: envName } : {}),
+            },
+            appPreset,
+            downloadPreset,
+            dbPreset,
+            envAddPreset,
+        };
+    }
+    static buildResumeMissingYesFlags(flags) {
+        const missing = [];
+        if (!Install.toOptionalPromptString(flags.lang)) {
+            missing.push('--lang');
+        }
+        if (!Install.toOptionalPromptString(flags['root-username'])) {
+            missing.push('--root-username');
+        }
+        if (!Install.toOptionalPromptString(flags['root-email'])) {
+            missing.push('--root-email');
         }
-        const dl = await this.config.runCommand('download', downloadArgv);
-        if (dl.projectRoot) {
-            return dl.projectRoot;
+        if (!Install.toOptionalPromptString(flags['root-password'])) {
+            missing.push('--root-password');
         }
-        if (!interactive) {
-            const version = downloadVersion?.trim() || 'latest';
-            const safe = version.replace(/[/\\]/g, '-');
-            const outputDir = appRootPathFlag?.trim() || `nocobase-${safe}`;
-            return path.resolve(process.cwd(), outputDir);
+        if (!Install.toOptionalPromptString(flags['root-nickname'])) {
+            missing.push('--root-nickname');
         }
-        this.error('Could not determine the project directory after nb download.');
+        return missing;
     }
-    async run() {
-        const { flags } = await this.parse(Install);
-        const interactive = Boolean(stdinStream.isTTY && stdoutStream.isTTY && !flags.yes);
-        let installLang = flags.lang?.trim() || undefined;
-        let envName = flags.env?.trim();
-        if (envName === '') {
-            envName = undefined;
-        }
-        if (interactive) {
-            p.intro('nb install');
-            if (installLang === undefined) {
-                const langAns = await p.text({
-                    message: 'Install language (--lang, e.g. en-US or zh-CN)',
-                    placeholder: DEFAULT_INSTALL_LANG,
-                    initialValue: DEFAULT_INSTALL_LANG,
-                });
-                if (p.isCancel(langAns)) {
-                    p.cancel('Install cancelled.');
-                    this.exit(0);
-                }
-                const t = langAns.trim();
-                installLang = t || DEFAULT_INSTALL_LANG;
-            }
-            if (!envName) {
-                const envAnswer = await p.text({
-                    message: 'Application name',
-                    placeholder: DEFAULT_INSTALL_ENV_NAME,
-                    validate: (value) => (value.trim() ? undefined : 'Application name is required'),
-                });
-                if (p.isCancel(envAnswer)) {
-                    p.cancel('Install cancelled.');
-                    this.exit(0);
-                }
-                envName = envAnswer.trim();
-            }
+    async resolveResumePresetValues(parsed, yes) {
+        if (!parsed.resume) {
+            return undefined;
         }
-        else if (!envName) {
-            this.error('Application name is required (pass -e or --env).');
-        }
-        const auth = await loadAuthConfig();
-        const savedEnv = auth.envs[envName];
-        const hasSavedEnv = savedEnv !== undefined;
-        if (interactive && hasSavedEnv) {
-            p.log.info(`Using saved CLI env ${pc.cyan(`"${envName}"`)} (from ${pc.dim('nb env add')}). Override any field with flags if needed.`);
-        }
-        // Default: built-in DB (non-interactive / -y skips the prompt and keeps this).
-        let hasExistingDb = false;
-        if (interactive && !hasSavedEnv) {
-            const dbMode = await p.select({
-                message: 'Use the built-in database, or connect to one you already have?',
-                options: [
-                    { value: 'builtin', label: 'Use built-in database' },
-                    { value: 'own', label: 'I already have a database' },
-                ],
-                initialValue: 'builtin',
-            });
-            if (p.isCancel(dbMode)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
-            }
-            hasExistingDb = dbMode === 'own';
-        }
-        let dbDialect = flags['db-dialect'] ?? savedEnv?.dbDialect ?? 'postgres';
-        let dbHost = flags['db-host'] ?? savedEnv?.dbHost ?? 'localhost';
-        let dbPort = flags['db-port'] ?? (savedEnv?.dbPort !== undefined ? String(savedEnv.dbPort) : undefined);
-        let dbDatabase = flags['db-database'] ?? savedEnv?.dbDatabase ?? 'nocobase';
-        let dbUser = flags['db-user'] ?? savedEnv?.dbUser ?? 'nocobase';
-        let dbPassword = flags['db-password'] ?? savedEnv?.dbPassword ?? 'nocobase';
-        if (!hasExistingDb && !flags['db-port'] && savedEnv?.dbPort === undefined) {
-            dbPort = dbPort ?? '5432';
-        }
-        else if (!dbPort) {
-            dbPort = this.defaultDbPort(dbDialect);
-        }
-        if (interactive && !hasSavedEnv) {
-            const dialectAns = await p.select({
-                message: 'Database dialect',
-                options: [
-                    { value: 'postgres', label: 'PostgreSQL' },
-                    { value: 'mysql', label: 'MySQL' },
-                    { value: 'mariadb', label: 'MariaDB' },
-                    { value: 'kingbase', label: 'Kingbase' },
-                ],
-                initialValue: dbDialect,
-            });
-            if (p.isCancel(dialectAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
-            }
-            dbDialect = dialectAns;
-            const hostAns = await p.text({
-                message: 'Database host',
-                initialValue: dbHost,
-            });
-            if (p.isCancel(hostAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        const env = await getEnv(parsed.env, { scope: CONFIG_SCOPE });
+        if (!env) {
+            throw new Error(formatMissingManagedAppEnvMessage(parsed.env));
+        }
+        if (yes) {
+            const missingFlags = Install.buildResumeMissingYesFlags(parsed);
+            if (missingFlags.length > 0) {
+                throw new Error([
+                    `Cannot continue setup for "${env.name}" in non-interactive resume mode yet.`,
+                    `These setup-only flags are not saved in the env config: ${missingFlags.join(', ')}`,
+                    `Run \`nb install --env ${env.name} --resume\` without \`--yes\`, or pass those flags again.`,
+                ].join('\n'));
             }
-            dbHost = hostAns.trim() || dbHost;
-            const portAns = await p.text({
-                message: 'Database port',
-                initialValue: dbPort,
+        }
+        return Install.buildResumePresetValues(env);
+    }
+    static async resolveAvailableDefaultPort(defaultPort, options) {
+        const normalized = String(defaultPort).trim();
+        const portError = await validateAvailableTcpPort(normalized);
+        if (!portError) {
+            return normalized;
+        }
+        const nextPort = await findAvailableTcpPort();
+        if (options?.warn) {
+            p.log.warn(`${options.label ?? 'Default port'} ${normalized} is already in use. Using available port ${nextPort} for this setup.`);
+        }
+        return nextPort;
+    }
+    static async buildAppPromptInitialValues(params) {
+        const initialValues = {};
+        const envName = params.envName ?? DEFAULT_INSTALL_ENV_NAME;
+        if (params.flags['app-root-path'] === undefined) {
+            initialValues.appRootPath = defaultInstallAppRootPath(envName);
+        }
+        if (params.flags['storage-path'] === undefined) {
+            initialValues.storagePath = defaultInstallStoragePath(envName);
+        }
+        if (params.flags['app-port'] === undefined) {
+            initialValues.appPort = await Install.resolveAvailableDefaultPort(DEFAULT_INSTALL_APP_PORT, {
+                label: 'Default app port',
+                warn: true,
             });
-            if (p.isCancel(portAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        }
+        return initialValues;
+    }
+    static shouldPublishBuiltinDbPortForValues(values) {
+        const builtinDb = values.builtinDb === undefined ? true : Boolean(values.builtinDb);
+        return builtinDb
+            && Install.shouldPublishBuiltinDbPort(values.source);
+    }
+    static async buildDbPromptInitialValues(params) {
+        if (params.flags['db-port'] !== undefined) {
+            return {};
+        }
+        const values = {
+            ...params.downloadResults,
+            ...params.dbPreset,
+        };
+        if (!Install.shouldPublishBuiltinDbPortForValues(values)) {
+            return {};
+        }
+        const dialect = String(values.dbDialect ?? 'postgres').trim() || 'postgres';
+        const defaultPort = defaultDbPortForDialect(dialect);
+        return {
+            dbPort: await Install.resolveAvailableDefaultPort(defaultPort, {
+                label: `Default ${dialect} port`,
+                warn: true,
+            }),
+        };
+    }
+    /**
+     * When install runs {@link Download.prompts} after app prompts, align language and
+     * output directory defaults with the app settings collected earlier in the flow.
+     */
+    static buildDownloadPromptOptionsForInstall(appResults, envName) {
+        const appRoot = String(appResults.appRootPath ?? '').trim() || defaultInstallAppRootPath(envName);
+        const lang = String(appResults.lang ?? DEFAULT_INSTALL_LANG).trim() || DEFAULT_INSTALL_LANG;
+        const initialValues = {
+            lang,
+            dockerRegistry: defaultDockerRegistryForLang(lang),
+            outputDir: appRoot,
+        };
+        const values = {
+            lang,
+        };
+        return {
+            initialValues,
+            values,
+            yes: false,
+            hooks: {
+                onCancel: () => {
+                    p.cancel('Download cancelled.');
+                    exit(0);
+                },
+                onMissingNonInteractive: (message) => {
+                    console.error(message);
+                    exit(1);
+                },
+            },
+        };
+    }
+    /**
+     * Resolve the effective preset `values` for the embedded download step.
+     * Explicit download flags win; otherwise `-y` falls back to the docker + alpha quickstart path.
+     */
+    static buildDownloadPresetValuesForInstall(flags, appResults, envName, yes) {
+        const preset = {};
+        const argv = process.argv.slice(2);
+        const appRoot = String(appResults.appRootPath ?? '').trim() || defaultInstallAppRootPath(envName);
+        const lang = String(appResults.lang ?? DEFAULT_INSTALL_LANG).trim() || DEFAULT_INSTALL_LANG;
+        preset.lang = lang;
+        if (flags.source !== undefined && String(flags.source).trim() !== '') {
+            preset.source = String(flags.source).trim();
+        }
+        if (flags.version !== undefined) {
+            preset.version = String(flags.version).trim() || 'latest';
+        }
+        if (flags['docker-registry'] !== undefined) {
+            const value = String(flags['docker-registry'] ?? '').trim();
+            if (value) {
+                preset.dockerRegistry = value;
             }
-            dbPort = portAns.trim() || dbPort;
-            const dbNameAns = await p.text({
-                message: 'Database name',
-                initialValue: dbDatabase,
-            });
-            if (p.isCancel(dbNameAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        }
+        if (flags['docker-platform'] !== undefined) {
+            const value = String(flags['docker-platform'] ?? '').trim();
+            if (value) {
+                preset.dockerPlatform = value;
             }
-            dbDatabase = dbNameAns.trim() || dbDatabase;
-            const userAns = await p.text({
-                message: 'Database user',
-                initialValue: dbUser,
-            });
-            if (p.isCancel(userAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        }
+        if (flags['output-dir'] !== undefined) {
+            const value = String(flags['output-dir'] ?? '').trim();
+            if (value) {
+                preset.outputDir = value;
             }
-            dbUser = userAns.trim() || dbUser;
-            const passAns = await p.password({
-                message: 'Database password',
-            });
-            if (p.isCancel(passAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        }
+        if (flags['git-url'] !== undefined) {
+            const value = String(flags['git-url'] ?? '').trim();
+            if (value) {
+                preset.gitUrl = value;
             }
-            dbPassword =
-                typeof passAns === 'string' && passAns.length > 0 ? passAns : dbPassword;
-        }
-        const runDbStart = (!hasSavedEnv && !hasExistingDb) || Boolean(flags['start-builtin-db']);
-        if (runDbStart) {
-            try {
-                if (interactive) {
-                    p.log.step('Running nb db start');
-                }
-                else {
-                    this.log('Running nb db start');
-                }
-                // oclif explicit registry: `db:start` → user types `nb db start`
-                await this.config.runCommand('db:start', []);
+        }
+        if (flags['npm-registry'] !== undefined) {
+            preset.npmRegistry =
+                typeof flags['npm-registry'] === 'string' ? flags['npm-registry'] : '';
+        }
+        if (argvHasToken(argv, ['--replace', '-r'])) {
+            preset.replace = flags.replace;
+        }
+        if (argvHasToken(argv, ['--dev-dependencies', '--no-dev-dependencies', '-D'])) {
+            preset.devDependencies = flags['dev-dependencies'];
+        }
+        if (argvHasToken(argv, ['--docker-save', '--no-docker-save'])) {
+            preset.dockerSave = flags['docker-save'];
+        }
+        if (argvHasToken(argv, ['--build', '--no-build'])) {
+            preset.build = flags.build;
+        }
+        if (argvHasToken(argv, ['--build-dts', '--no-build-dts'])) {
+            preset.buildDts = flags['build-dts'];
+        }
+        if (yes) {
+            preset.source ??= 'docker';
+            preset.version ??= 'alpha';
+            preset.outputDir ??= appRoot;
+        }
+        return preset;
+    }
+    static sanitizeDockerResourceName(value) {
+        const normalized = value
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9_.-]+/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-+|-+$/g, '');
+        return normalized || 'nocobase';
+    }
+    static defaultWorkspaceName() {
+        return Install.sanitizeDockerResourceName(`nb-${path.basename(process.cwd())}`);
+    }
+    static buildBuiltinDbResourcePrefix(envName, workspaceName) {
+        void envName;
+        const storedName = String(workspaceName ?? '').trim();
+        return storedName
+            ? Install.sanitizeDockerResourceName(storedName)
+            : Install.defaultWorkspaceName();
+    }
+    static async ensureWorkspaceName() {
+        return await ensureWorkspaceName(Install.defaultWorkspaceName(), { scope: CONFIG_SCOPE });
+    }
+    static buildBuiltinDbNetworkName(envName, workspaceName) {
+        return Install.buildBuiltinDbResourcePrefix(envName, workspaceName);
+    }
+    static buildBuiltinDbContainerName(envName, dbDialect, workspaceName) {
+        return Install.sanitizeDockerResourceName(`${Install.buildBuiltinDbResourcePrefix(envName, workspaceName)}-${envName}-${dbDialect}`);
+    }
+    static buildDockerAppContainerName(envName, workspaceName) {
+        return Install.sanitizeDockerResourceName(`${Install.buildBuiltinDbResourcePrefix(envName, workspaceName)}-${envName}-app`);
+    }
+    static buildInitAppEnvVars(params) {
+        const out = {};
+        const put = (key, value) => {
+            const text = String(value ?? '').trim();
+            if (!text) {
+                return;
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                if (interactive) {
-                    p.outro(pc.red(message));
-                }
-                this.error(message);
+            out[key] = text;
+        };
+        put('INIT_APP_LANG', params.appResults.lang);
+        put('INIT_ROOT_USERNAME', params.rootResults.rootUsername);
+        put('INIT_ROOT_EMAIL', params.rootResults.rootEmail);
+        put('INIT_ROOT_PASSWORD', params.rootResults.rootPassword);
+        put('INIT_ROOT_NICKNAME', params.rootResults.rootNickname);
+        return out;
+    }
+    static shouldPublishBuiltinDbPort(source) {
+        return String(source ?? '').trim() !== 'docker';
+    }
+    static buildBuiltinDbPlan(params) {
+        const dbDialect = String(params.dbDialect ?? 'postgres').trim() || 'postgres';
+        const dbPort = String(params.dbPort ?? defaultDbPortForDialect(dbDialect)).trim()
+            || defaultDbPortForDialect(dbDialect);
+        const networkName = Install.buildBuiltinDbNetworkName(params.envName, params.workspaceName);
+        const containerName = Install.buildBuiltinDbContainerName(params.envName, dbDialect, params.workspaceName);
+        const dbHostInput = String(params.dbHost ?? '').trim();
+        const dbHost = Install.shouldPublishBuiltinDbPort(params.source)
+            ? (dbHostInput
+                && dbHostInput !== DEFAULT_INSTALL_BUILTIN_DB_HOST
+                && dbHostInput !== containerName
+                ? dbHostInput
+                : DEFAULT_INSTALL_DB_HOST)
+            : (dbHostInput
+                && dbHostInput !== DEFAULT_INSTALL_DB_HOST
+                && dbHostInput !== 'localhost'
+                ? dbHostInput
+                : containerName);
+        if (dbDialect === 'postgres') {
+            const dataDir = path.resolve(params.storagePath, 'db', 'postgres');
+            const args = [
+                'run',
+                '-d',
+                '--name',
+                containerName,
+                '--restart',
+                'always',
+                '--network',
+                networkName,
+                '-e',
+                `POSTGRES_USER=${String(params.dbUser ?? DEFAULT_INSTALL_DB_USER).trim() || DEFAULT_INSTALL_DB_USER}`,
+                '-e',
+                `POSTGRES_DB=${String(params.dbDatabase ?? DEFAULT_INSTALL_DB_DATABASE).trim() || DEFAULT_INSTALL_DB_DATABASE}`,
+                '-e',
+                `POSTGRES_PASSWORD=${String(params.dbPassword ?? DEFAULT_INSTALL_DB_PASSWORD) || DEFAULT_INSTALL_DB_PASSWORD}`,
+                '-v',
+                `${dataDir}:/var/lib/postgresql/data`,
+            ];
+            if (Install.shouldPublishBuiltinDbPort(params.source)) {
+                args.push('-p', `${dbPort}:5432`);
             }
+            args.push('postgres:16', 'postgres', '-c', 'wal_level=logical');
+            return {
+                source: String(params.source ?? '').trim() || undefined,
+                dbDialect,
+                dbHost,
+                dbPort,
+                dbDatabase: String(params.dbDatabase ?? DEFAULT_INSTALL_DB_DATABASE).trim()
+                    || DEFAULT_INSTALL_DB_DATABASE,
+                dbUser: String(params.dbUser ?? DEFAULT_INSTALL_DB_USER).trim()
+                    || DEFAULT_INSTALL_DB_USER,
+                dbPassword: String(params.dbPassword ?? DEFAULT_INSTALL_DB_PASSWORD)
+                    || DEFAULT_INSTALL_DB_PASSWORD,
+                networkName,
+                containerName,
+                dataDir,
+                image: 'postgres:16',
+                args,
+            };
         }
-        let resolvedStorage = this.resolveStoragePath(flags['storage-path'], envName, savedEnv?.storagePath);
-        let appPort = flags['app-port'] ?? '13000';
-        if (interactive && !hasSavedEnv) {
-            const relInitial = path.relative(process.cwd(), resolvedStorage) || path.join('storage', envName);
-            const sp = await p.text({
-                message: 'Storage directory (relative to cwd)',
-                initialValue: relInitial,
-            });
-            if (p.isCancel(sp)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        if (dbDialect === 'mysql') {
+            const dataDir = path.resolve(params.storagePath, 'db', 'mysql');
+            const dbUser = String(params.dbUser ?? DEFAULT_INSTALL_DB_USER).trim() || DEFAULT_INSTALL_DB_USER;
+            const dbDatabase = String(params.dbDatabase ?? DEFAULT_INSTALL_DB_DATABASE).trim() || DEFAULT_INSTALL_DB_DATABASE;
+            const dbPassword = String(params.dbPassword ?? DEFAULT_INSTALL_DB_PASSWORD) || DEFAULT_INSTALL_DB_PASSWORD;
+            const args = [
+                'run',
+                '-d',
+                '--name',
+                containerName,
+                '--restart',
+                'always',
+                '--network',
+                networkName,
+                '-e',
+                `MYSQL_USER=${dbUser}`,
+                '-e',
+                `MYSQL_DATABASE=${dbDatabase}`,
+                '-e',
+                `MYSQL_PASSWORD=${dbPassword}`,
+                '-e',
+                `MYSQL_ROOT_PASSWORD=${dbPassword}`,
+                '-v',
+                `${dataDir}:/var/lib/mysql`,
+            ];
+            if (Install.shouldPublishBuiltinDbPort(params.source)) {
+                args.push('-p', `${dbPort}:3306`);
             }
-            resolvedStorage = path.resolve(process.cwd(), sp.trim() || relInitial);
+            args.push('mysql:8');
+            return {
+                source: String(params.source ?? '').trim() || undefined,
+                dbDialect,
+                dbHost,
+                dbPort,
+                dbDatabase,
+                dbUser,
+                dbPassword,
+                networkName,
+                containerName,
+                dataDir,
+                image: 'mysql:8',
+                args,
+            };
         }
-        if (interactive && !hasSavedEnv) {
-            const portAns = await p.text({
-                message: 'Application port (APP_PORT)',
-                initialValue: appPort,
-            });
-            if (p.isCancel(portAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
-            }
-            appPort = portAns.trim() || appPort;
-        }
-        let source = flags.source ?? DEFAULT_INSTALL_SOURCE;
-        if (interactive && !hasSavedEnv) {
-            const src = await p.select({
-                message: 'Install source for this project',
-                options: [
-                    { value: 'docker', label: 'Docker image' },
-                    { value: 'npm', label: 'npm (create-nocobase-app style / published package)' },
-                    { value: 'git', label: 'Git clone / monorepo checkout' },
-                ],
-                initialValue: source,
-            });
-            if (p.isCancel(src)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        if (dbDialect === 'mariadb') {
+            const dataDir = path.resolve(params.storagePath, 'db', 'mariadb');
+            const dbUser = String(params.dbUser ?? DEFAULT_INSTALL_DB_USER).trim() || DEFAULT_INSTALL_DB_USER;
+            const dbDatabase = String(params.dbDatabase ?? DEFAULT_INSTALL_DB_DATABASE).trim() || DEFAULT_INSTALL_DB_DATABASE;
+            const dbPassword = String(params.dbPassword ?? DEFAULT_INSTALL_DB_PASSWORD) || DEFAULT_INSTALL_DB_PASSWORD;
+            const args = [
+                'run',
+                '-d',
+                '--name',
+                containerName,
+                '--restart',
+                'always',
+                '--network',
+                networkName,
+                '-e',
+                `MARIADB_USER=${dbUser}`,
+                '-e',
+                `MARIADB_DATABASE=${dbDatabase}`,
+                '-e',
+                `MARIADB_PASSWORD=${dbPassword}`,
+                '-e',
+                `MARIADB_ROOT_PASSWORD=${dbPassword}`,
+                '-v',
+                `${dataDir}:/var/lib/mysql`,
+            ];
+            if (Install.shouldPublishBuiltinDbPort(params.source)) {
+                args.push('-p', `${dbPort}:3306`);
             }
-            source = src;
+            args.push('mariadb:11');
+            return {
+                source: String(params.source ?? '').trim() || undefined,
+                dbDialect,
+                dbHost,
+                dbPort,
+                dbDatabase,
+                dbUser,
+                dbPassword,
+                networkName,
+                containerName,
+                dataDir,
+                image: 'mariadb:11',
+                args,
+            };
         }
-        let appRootPathFlag = flags['app-root-path'];
-        let dockerRegistry = flags['docker-registry'];
-        let dockerTag = flags['docker-tag'];
-        if (interactive && !hasSavedEnv) {
-            if (source === 'docker') {
-                const reg = await p.text({
-                    message: 'Docker image (without tag, e.g. nocobase/nocobase)',
-                    initialValue: dockerRegistry ?? 'nocobase/nocobase',
-                });
-                if (p.isCancel(reg)) {
-                    p.cancel('Install cancelled.');
-                    this.exit(0);
-                }
-                dockerRegistry = reg.trim() || dockerRegistry;
-                const tag = await p.text({
-                    message: 'Docker tag',
-                    initialValue: dockerTag ?? 'latest',
-                });
-                if (p.isCancel(tag)) {
-                    p.cancel('Install cancelled.');
-                    this.exit(0);
-                }
-                dockerTag = tag.trim() || dockerTag;
-            }
+        throw new Error(`Built-in database does not support "${dbDialect}" yet. Please choose PostgreSQL, MySQL, or MariaDB.`);
+    }
+    async ensureDockerNetwork(name) {
+        p.log.step(`Checking Docker network: ${name}`);
+        const exists = await commandSucceeds('docker', ['network', 'inspect', name]);
+        if (exists) {
+            p.log.info(`Docker network already exists: ${name}`);
+            return;
         }
-        if (source === 'npm' || source === 'git') {
-            appRootPathFlag = await this.resolveNpmGitAppRootWithDownload({
-                source,
-                interactive,
-                hasSavedEnv,
-                appRootPathFlag,
-                savedEnv,
-                fetchSourceFlag: Boolean(flags['fetch-source']),
-                downloadVersion: flags['download-version']?.trim() || undefined,
-                downloadGitUrl: flags['download-git-url'],
+        p.log.step(`Creating Docker network: ${name}`);
+        try {
+            await run('docker', ['network', 'create', name], {
+                errorName: 'docker network create',
             });
+            p.log.info(`Docker network is ready: ${name}`);
         }
-        const appRoot = this.resolveAppRoot(appRootPathFlag, savedEnv?.appRootPath);
-        const procEnv = {
-            STORAGE_PATH: resolvedStorage,
-            APP_PORT: appPort,
-            DB_DIALECT: dbDialect,
-            DB_HOST: dbHost,
-            DB_PORT: dbPort,
-            DB_DATABASE: dbDatabase,
-            DB_USER: dbUser,
-            DB_PASSWORD: dbPassword,
-            NOCOBASE_INSTALL_SOURCE: source,
-        };
-        if (source === 'docker' && (dockerRegistry || dockerTag)) {
-            if (dockerRegistry) {
-                procEnv.NOCOBASE_DOCKER_REGISTRY = dockerRegistry;
-            }
-            if (dockerTag) {
-                procEnv.NOCOBASE_DOCKER_TAG = dockerTag;
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/address pools have been fully subnetted/i.test(message)) {
+                throw new Error([
+                    `Docker could not create network "${name}" because its address pools are exhausted.`,
+                    'Remove unused Docker networks and try again, for example: docker network prune',
+                    `Original error: ${message}`,
+                ].join('\n'));
             }
+            throw error;
         }
-        const installOpts = await this.promptNocoBaseInstallOptions(interactive, {
-            force: flags.force,
-            lang: installLang,
-            rootUserName: flags['root-username'],
-            rootEmail: flags['root-email'],
-            rootPassword: flags['root-password'],
-            rootNickname: flags['root-nickname'],
+    }
+    async dockerContainerExists(name) {
+        return await commandSucceeds('docker', [
+            'container',
+            'inspect',
+            name,
+        ]);
+    }
+    async removeDockerContainer(name) {
+        await run('docker', ['rm', '-f', name], {
+            errorName: 'docker rm',
         });
-        const argvFlags = {
-            source,
-            ...installOpts,
-        };
-        if (argvFlags.rootUserName) {
-            procEnv.INIT_ROOT_USERNAME = argvFlags.rootUserName;
+    }
+    async removeDockerContainerIfForced(params) {
+        const exists = await this.dockerContainerExists(params.containerName);
+        if (!exists) {
+            return false;
         }
-        if (argvFlags.rootEmail) {
-            procEnv.INIT_ROOT_EMAIL = argvFlags.rootEmail;
+        if (!params.force) {
+            return true;
         }
-        try {
-            await this.runNocoBaseInstall(appRoot, procEnv, argvFlags, interactive);
+        p.log.info(`Removing existing ${params.displayName}: ${params.containerName}`);
+        await this.removeDockerContainer(params.containerName);
+        return false;
+    }
+    async inspectDockerContainerEnv(name) {
+        const output = await commandOutput('docker', [
+            'inspect',
+            '--format',
+            '{{range .Config.Env}}{{println .}}{{end}}',
+            name,
+        ]);
+        const env = {};
+        for (const line of output.split(/\r?\n/)) {
+            const index = line.indexOf('=');
+            if (index <= 0) {
+                continue;
+            }
+            env[line.slice(0, index)] = line.slice(index + 1);
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (interactive) {
-                p.outro(pc.red(message));
+        return env;
+    }
+    async ensureBuiltinDbContainer(plan) {
+        const exists = await this.dockerContainerExists(plan.containerName);
+        if (exists) {
+            p.log.info(`Built-in ${plan.dbDialect} container already exists: ${plan.containerName}`);
+            return;
+        }
+        await mkdir(plan.dataDir, { recursive: true });
+        await run('docker', plan.args, {
+            errorName: 'docker run',
+        });
+    }
+    async startBuiltinDb(params) {
+        const storagePath = String(params.appResults.storagePath ?? '').trim()
+            || defaultInstallStoragePath(params.envName);
+        const plan = Install.buildBuiltinDbPlan({
+            envName: params.envName,
+            workspaceName: params.workspaceName,
+            storagePath,
+            source: params.downloadResults.source,
+            dbDialect: params.dbResults.dbDialect,
+            dbHost: params.dbResults.dbHost,
+            dbPort: params.dbResults.dbPort,
+            dbDatabase: params.dbResults.dbDatabase,
+            dbUser: params.dbResults.dbUser,
+            dbPassword: params.dbResults.dbPassword,
+        });
+        p.log.step(`Preparing built-in ${plan.dbDialect} database`);
+        await this.ensureDockerNetwork(plan.networkName);
+        await this.removeDockerContainerIfForced({
+            containerName: plan.containerName,
+            displayName: `built-in ${plan.dbDialect} container`,
+            force: params.force,
+        });
+        if (Install.shouldPublishBuiltinDbPort(params.downloadResults.source)) {
+            const portError = await validateAvailableTcpPort(plan.dbPort);
+            if (portError) {
+                throw new Error(`Built-in ${plan.dbDialect} needs host port ${plan.dbPort}, but ${portError}`);
             }
-            this.error(message);
         }
-        const envPostInstall = await this.runPostInstallEnvCommand({
-            hasSavedEnv,
-            envName,
+        await this.ensureBuiltinDbContainer(plan);
+        p.log.info(`Built-in ${plan.dbDialect} database is ready at ${plan.dbHost}:${plan.dbPort}`);
+        return plan;
+    }
+    static buildDockerAppPlan(params) {
+        const dockerRegistry = String(downloadResultsValue(params.downloadResults, 'dockerRegistry') ?? '').trim()
+            || defaultDockerRegistryForLang(params.appResults.lang);
+        const version = String(downloadResultsValue(params.downloadResults, 'version') ?? '').trim() || 'latest';
+        const appPort = String(params.appResults.appPort ?? DEFAULT_INSTALL_APP_PORT).trim() || DEFAULT_INSTALL_APP_PORT;
+        const storagePath = path.resolve(String(params.appResults.storagePath ?? '').trim()
+            || defaultInstallStoragePath(params.envName));
+        const dbDialect = String(params.dbResults.dbDialect ?? 'postgres').trim() || 'postgres';
+        const dbHost = String(params.dbResults.dbHost ?? DEFAULT_INSTALL_DB_HOST).trim() || DEFAULT_INSTALL_DB_HOST;
+        const dbPort = String(params.dbResults.dbPort ?? defaultDbPortForDialect(dbDialect)).trim()
+            || defaultDbPortForDialect(dbDialect);
+        const dbDatabase = String(params.dbResults.dbDatabase ?? DEFAULT_INSTALL_DB_DATABASE).trim()
+            || DEFAULT_INSTALL_DB_DATABASE;
+        const dbUser = String(params.dbResults.dbUser ?? DEFAULT_INSTALL_DB_USER).trim() || DEFAULT_INSTALL_DB_USER;
+        const dbPassword = String(params.dbResults.dbPassword ?? DEFAULT_INSTALL_DB_PASSWORD) || DEFAULT_INSTALL_DB_PASSWORD;
+        const appKey = crypto.randomBytes(32).toString('hex');
+        const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+        const containerName = Install.buildDockerAppContainerName(params.envName, params.workspaceName);
+        const initEnvVars = Install.buildInitAppEnvVars({
+            appResults: params.appResults,
+            rootResults: params.rootResults,
+        });
+        const args = [
+            'run',
+            '-d',
+            '--name',
+            containerName,
+            '--restart',
+            'always',
+            '--network',
+            params.networkName,
+            '-p',
+            `${appPort}:80`,
+        ];
+        for (const [key, value] of Object.entries(initEnvVars)) {
+            args.push('-e', `${key}=${value}`);
+        }
+        args.push('-e', `APP_KEY=${appKey}`, '-e', `DB_DIALECT=${dbDialect}`, '-e', `DB_HOST=${dbHost}`, '-e', `DB_PORT=${dbPort}`, '-e', `DB_DATABASE=${dbDatabase}`, '-e', `DB_USER=${dbUser}`, '-e', `DB_PASSWORD=${dbPassword}`, '-e', `TZ=${timeZone}`, '-v', `${storagePath}:/app/nocobase/storage`, `${dockerRegistry}:${version}`);
+        return {
+            source: 'docker',
+            networkName: params.networkName,
+            containerName,
+            imageRef: `${dockerRegistry}:${version}`,
             appPort,
-            interactive,
+            storagePath,
+            appKey,
+            timeZone,
+            args,
+        };
+    }
+    async ensureDockerAppContainer(plan) {
+        const exists = await this.dockerContainerExists(plan.containerName);
+        if (exists) {
+            p.log.info(`App container already exists: ${plan.containerName}`);
+            return 'existing';
+        }
+        await mkdir(plan.storagePath, { recursive: true });
+        await run('docker', plan.args, {
+            errorName: 'docker run',
         });
-        if (envPostInstall === 'failed') {
-            return;
+        return 'created';
+    }
+    async installDockerApp(params) {
+        const networkName = params.builtinDbPlan?.networkName
+            ?? Install.buildBuiltinDbNetworkName(params.envName, params.workspaceName);
+        await this.ensureDockerNetwork(networkName);
+        const plan = Install.buildDockerAppPlan({
+            envName: params.envName,
+            workspaceName: params.workspaceName,
+            appResults: params.appResults,
+            downloadResults: params.downloadResults,
+            dbResults: params.dbResults,
+            rootResults: params.rootResults,
+            networkName,
+        });
+        p.log.step(`Starting Docker app ${plan.imageRef}`);
+        await this.removeDockerContainerIfForced({
+            containerName: plan.containerName,
+            displayName: 'app container',
+            force: params.force,
+        });
+        const containerState = await this.ensureDockerAppContainer(plan);
+        if (containerState === 'existing') {
+            const env = await this.inspectDockerContainerEnv(plan.containerName);
+            plan.appKey = env.APP_KEY || plan.appKey;
+            plan.timeZone = env.TZ || plan.timeZone;
         }
-        if (interactive) {
-            p.outro('Install finished.');
+        p.log.info(`App container is ready at http://127.0.0.1:${plan.appPort}`);
+        return plan;
+    }
+    static pushDownloadArgIfValue(argv, flag, value) {
+        const text = String(value ?? '').trim();
+        if (text) {
+            argv.push(flag, text);
         }
-        else {
-            this.log('Install finished.');
+    }
+    static buildDownloadArgvFromResults(results) {
+        const argv = ['-y', '--no-intro'];
+        Install.pushDownloadArgIfValue(argv, '--source', results.source);
+        Install.pushDownloadArgIfValue(argv, '--version', results.version);
+        Install.pushDownloadArgIfValue(argv, '--output-dir', results.outputDir);
+        Install.pushDownloadArgIfValue(argv, '--git-url', results.gitUrl);
+        Install.pushDownloadArgIfValue(argv, '--docker-registry', results.dockerRegistry);
+        Install.pushDownloadArgIfValue(argv, '--docker-platform', results.dockerPlatform);
+        Install.pushDownloadArgIfValue(argv, '--npm-registry', results.npmRegistry);
+        if (Boolean(results.replace)) {
+            argv.push('--replace');
+        }
+        if (Boolean(results.devDependencies)) {
+            argv.push('--dev-dependencies');
+        }
+        if (Boolean(results.dockerSave)) {
+            argv.push('--docker-save');
+        }
+        if (results.build !== undefined && !Boolean(results.build)) {
+            argv.push('--no-build');
         }
+        if (Boolean(results.buildDts)) {
+            argv.push('--build-dts');
+        }
+        return argv;
     }
-    /**
-     * After a successful `nocobase-v1 install`, refresh or create the CLI env via oclif (`nb env update` / `nb env add`).
-     * Failures are logged but do not fail the overall install (artifacts are already on disk).
-     */
-    async runPostInstallEnvCommand(options) {
-        const { hasSavedEnv, envName, appPort, interactive } = options;
+    static resolveLocalProjectRoot(params) {
+        const projectRoot = params.downloadCommandResult?.projectRoot;
+        if (projectRoot) {
+            return projectRoot;
+        }
+        const outputDir = String(params.downloadResults.outputDir ?? '').trim()
+            || String(params.appResults.appRootPath ?? '').trim()
+            || defaultInstallAppRootPath(params.envName);
+        return path.resolve(process.cwd(), outputDir);
+    }
+    async downloadLocalApp(params) {
+        const argv = Install.buildDownloadArgvFromResults(params.downloadResults);
+        p.log.step('Downloading local NocoBase app files');
+        const result = await this.config.runCommand('download', argv);
+        const projectRoot = Install.resolveLocalProjectRoot({
+            envName: params.envName,
+            appResults: params.appResults,
+            downloadResults: params.downloadResults,
+            downloadCommandResult: result,
+        });
+        params.appResults.appRootPath = projectRoot;
+        return projectRoot;
+    }
+    static buildLocalAppEnvVars(params) {
+        const storagePath = path.resolve(String(params.appResults.storagePath ?? '').trim()
+            || defaultInstallStoragePath(params.envName));
+        const dbDialect = String(params.dbResults.dbDialect ?? 'postgres').trim()
+            || 'postgres';
+        const appKey = crypto.randomBytes(32).toString('hex');
+        const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+        const env = {
+            STORAGE_PATH: storagePath,
+            APP_PORT: String(params.appResults.appPort ?? DEFAULT_INSTALL_APP_PORT).trim()
+                || DEFAULT_INSTALL_APP_PORT,
+            APP_KEY: appKey,
+            TZ: timeZone,
+            DB_DIALECT: dbDialect,
+            DB_HOST: String(params.dbResults.dbHost ?? DEFAULT_INSTALL_DB_HOST).trim()
+                || DEFAULT_INSTALL_DB_HOST,
+            DB_PORT: String(params.dbResults.dbPort ?? defaultDbPortForDialect(dbDialect)).trim()
+                || defaultDbPortForDialect(dbDialect),
+            DB_DATABASE: String(params.dbResults.dbDatabase ?? DEFAULT_INSTALL_DB_DATABASE).trim()
+                || DEFAULT_INSTALL_DB_DATABASE,
+            DB_USER: String(params.dbResults.dbUser ?? DEFAULT_INSTALL_DB_USER).trim()
+                || DEFAULT_INSTALL_DB_USER,
+            DB_PASSWORD: String(params.dbResults.dbPassword ?? DEFAULT_INSTALL_DB_PASSWORD)
+                || DEFAULT_INSTALL_DB_PASSWORD,
+            ...Install.buildInitAppEnvVars({
+                appResults: params.appResults,
+                rootResults: params.rootResults,
+            }),
+        };
+        return env;
+    }
+    async startLocalApp(params) {
+        const env = Install.buildLocalAppEnvVars({
+            envName: params.envName,
+            appResults: params.appResults,
+            dbResults: params.dbResults,
+            rootResults: params.rootResults,
+        });
+        const args = ['start', '--quickstart', '--daemon'];
+        p.log.step(`Stopping any existing local NocoBase process in ${params.projectRoot}`);
         try {
-            if (hasSavedEnv) {
-                if (interactive) {
-                    p.log.step('Running nb env update');
-                }
-                else {
-                    this.log('Running nb env update');
-                }
-                await this.config.runCommand('env:update', [envName, '--scope', 'project']);
-            }
-            else {
-                if (interactive) {
-                    p.log.step('Running nb env add');
-                }
-                else {
-                    this.log('Running nb env add');
-                }
-                const addArgv = interactive
-                    ? [envName, '--scope', 'project']
-                    : [
-                        envName,
-                        '--scope',
-                        'project',
-                        '--api-base-url',
-                        `http://127.0.0.1:${appPort}/api`,
-                        '--auth-type',
-                        'oauth',
-                    ];
-                await this.config.runCommand('env:add', addArgv);
-            }
-            return 'ok';
+            await runNocoBaseCommand(['pm2', 'kill'], {
+                cwd: params.projectRoot,
+                env,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            if (interactive) {
-                p.log.warn(`Post-install env command failed: ${message}`);
-                p.outro('Install finished.');
-            }
-            else {
-                this.warn(`Post-install env command failed: ${message}`);
-                this.log('Install finished.');
-            }
-            return 'failed';
+            p.log.info(`Skipped local process cleanup before start: ${message}`);
         }
+        p.log.step(`Starting local NocoBase app from ${params.projectRoot}`);
+        await runNocoBaseCommand(args, {
+            cwd: params.projectRoot,
+            env,
+        });
+        p.log.info(`Local app is starting at http://127.0.0.1:${env.APP_PORT}`);
+        return {
+            source: params.source,
+            projectRoot: params.projectRoot,
+            appPort: env.APP_PORT,
+            storagePath: env.STORAGE_PATH,
+            appKey: env.APP_KEY,
+            timeZone: env.TZ,
+            env,
+            args,
+        };
     }
-    /**
-     * Interactive prompts for `nocobase-v1 install` options; CLI flags win when already set.
-     */
-    async promptNocoBaseInstallOptions(interactive, flags) {
-        let force = flags.force;
-        let lang = flags.lang;
-        let rootUserName = flags.rootUserName;
-        let rootEmail = flags.rootEmail;
-        let rootPassword = flags.rootPassword;
-        let rootNickname = flags.rootNickname;
-        if (!interactive) {
-            return { force, lang, rootUserName, rootEmail, rootPassword, rootNickname };
-        }
-        if (!flags.force) {
-            const reinstall = await p.confirm({
-                message: 'Reinstall and clear the database? (--force)',
-                initialValue: false,
-            });
-            if (p.isCancel(reinstall)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
-            }
-            force = reinstall;
+    static resolveApiBaseUrl(params) {
+        const appPort = String(params.appResults.appPort ?? DEFAULT_INSTALL_APP_PORT).trim()
+            || DEFAULT_INSTALL_APP_PORT;
+        return (String(params.envAddResults.apiBaseUrl ?? '').trim()
+            || `http://127.0.0.1:${appPort}/api`);
+    }
+    static buildHealthCheckUrl(apiBaseUrl) {
+        return `${apiBaseUrl.replace(/\/+$/, '')}/__health_check`;
+    }
+    static async sleep(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    static formatHealthCheckMessage(message, maxLength = 120) {
+        const text = message.replace(/\s+/g, ' ').trim();
+        if (!text) {
+            return 'No response yet';
         }
-        if (rootUserName === undefined) {
-            const userAns = await p.text({
-                message: 'Root username (--root-username)',
-                placeholder: 'nocobase',
-                initialValue: 'nocobase',
-            });
-            if (p.isCancel(userAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
-            }
-            const t = userAns.trim();
-            rootUserName = t || undefined;
-        }
-        if (rootEmail === undefined) {
-            const emailAns = await p.text({
-                message: 'Root user email (--root-email)',
-                placeholder: 'admin@nocobase.com',
-                initialValue: 'admin@nocobase.com',
+        return text.length > maxLength ? `${text.slice(0, maxLength - 3)}...` : text;
+    }
+    static async requestAppHealthCheck(params) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, params.requestTimeoutMs);
+        try {
+            const response = await params.fetchImpl(params.healthCheckUrl, {
+                method: 'GET',
+                signal: controller.signal,
             });
-            if (p.isCancel(emailAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+            const text = await response.text().catch(() => '');
+            const body = Install.formatHealthCheckMessage(text);
+            return {
+                ok: response.ok && text.trim().toLowerCase() === 'ok',
+                message: response.ok
+                    ? `HTTP ${response.status}: ${body}`
+                    : `HTTP ${response.status}: ${body}`,
+            };
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                return {
+                    ok: false,
+                    message: `No response within ${Math.ceil(params.requestTimeoutMs / 1000)}s`,
+                };
             }
-            const t = emailAns.trim();
-            rootEmail = t || undefined;
+            return {
+                ok: false,
+                message: error instanceof Error ? error.message : String(error),
+            };
         }
-        if (rootPassword === undefined) {
-            const passAns = await p.password({
-                message: 'Root user password (--root-password)',
-            });
-            if (p.isCancel(passAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async waitForAppHealthCheck(apiBaseUrl, options) {
+        const healthCheckUrl = Install.buildHealthCheckUrl(apiBaseUrl);
+        const timeoutMs = options?.timeoutMs ?? APP_HEALTH_CHECK_TIMEOUT_MS;
+        const intervalMs = options?.intervalMs ?? APP_HEALTH_CHECK_INTERVAL_MS;
+        const requestTimeoutMs = options?.requestTimeoutMs ?? APP_HEALTH_CHECK_REQUEST_TIMEOUT_MS;
+        const fetchImpl = options?.fetchImpl ?? fetch;
+        const startedAt = Date.now();
+        let lastMessage = 'No response yet';
+        let taskActive = true;
+        startTask(`Waiting for application health check: ${healthCheckUrl}. NocoBase has started and is still booting...`);
+        try {
+            while (Date.now() - startedAt < timeoutMs) {
+                const result = await Install.requestAppHealthCheck({
+                    healthCheckUrl,
+                    fetchImpl,
+                    requestTimeoutMs,
+                });
+                if (result.ok) {
+                    stopTask();
+                    taskActive = false;
+                    p.log.info(`Application health check passed: ${healthCheckUrl}`);
+                    return;
+                }
+                lastMessage = result.message;
+                const elapsedSeconds = Math.max(1, Math.floor((Date.now() - startedAt) / 1000));
+                updateTask(`Waiting for application health check: ${healthCheckUrl}. Still starting... (${elapsedSeconds}s elapsed, last status: ${Install.formatHealthCheckMessage(lastMessage)})`);
+                const remainingMs = timeoutMs - (Date.now() - startedAt);
+                if (remainingMs <= 0) {
+                    break;
+                }
+                await Install.sleep(Math.min(intervalMs, remainingMs));
             }
-            rootPassword = typeof passAns === 'string' && passAns.length > 0 ? passAns : undefined;
         }
-        if (rootNickname === undefined) {
-            const nickAns = await p.text({
-                message: 'Root user nickname (--root-nickname)',
-                placeholder: 'Super Admin',
-            });
-            if (p.isCancel(nickAns)) {
-                p.cancel('Install cancelled.');
-                this.exit(0);
+        finally {
+            if (taskActive) {
+                stopTask();
             }
-            const t = nickAns.trim();
-            rootNickname = t || undefined;
         }
-        return { force, lang, rootUserName, rootEmail, rootPassword, rootNickname };
+        const logHint = options?.containerName
+            ? ` You can inspect startup logs with: docker logs ${options.containerName}`
+            : '';
+        throw new Error(`The application did not become ready in time. Expected \`${healthCheckUrl}\` to respond with \`ok\`, but the last status was: ${Install.formatHealthCheckMessage(lastMessage)}.${logHint}`);
     }
-    /**
-     * Build argv for `nocobase-v1 install` from CLI flags.
-     */
-    buildNocoBaseInstallArgs(flags) {
-        const npmArgs = ['install'];
-        if (flags.force) {
-            npmArgs.push('--force');
+    async saveInstalledEnv(params) {
+        await this.config.runCommand('env:add', Install.buildEnvAddArgv(params));
+    }
+    static pushArgIfValue(argv, flag, value) {
+        const text = String(value ?? '').trim();
+        if (text) {
+            argv.push(flag, text);
         }
-        if (flags.lang !== undefined) {
-            npmArgs.push('--lang', flags.lang);
+    }
+    static pushBooleanArgIfSet(argv, flag, value) {
+        if (value === undefined) {
+            return;
         }
-        if (flags.rootUserName !== undefined) {
-            npmArgs.push('--root-username', flags.rootUserName);
+        argv.push(Boolean(value) ? flag : `--no-${flag.replace(/^--/, '')}`);
+    }
+    static buildEnvAddArgv(params) {
+        const appPort = String(params.appResults.appPort ?? DEFAULT_INSTALL_APP_PORT).trim()
+            || DEFAULT_INSTALL_APP_PORT;
+        const storagePath = String(params.appResults.storagePath ?? '').trim()
+            || defaultInstallStoragePath(params.envName);
+        const apiBaseUrl = Install.resolveApiBaseUrl({
+            appResults: params.appResults,
+            envAddResults: params.envAddResults,
+        });
+        const authType = String(params.envAddResults.authType ?? 'oauth').trim()
+            || 'oauth';
+        const argv = [
+            params.envName,
+            '--no-intro',
+            '--scope',
+            CONFIG_SCOPE,
+            '--api-base-url',
+            apiBaseUrl,
+            '--auth-type',
+            authType,
+            '--app-port',
+            appPort,
+            '--storage-path',
+            storagePath,
+        ];
+        Install.pushArgIfValue(argv, '--source', downloadResultsValue(params.downloadResults, 'source'));
+        Install.pushArgIfValue(argv, '--download-version', downloadResultsValue(params.downloadResults, 'version'));
+        Install.pushArgIfValue(argv, '--docker-registry', downloadResultsValue(params.downloadResults, 'dockerRegistry'));
+        Install.pushArgIfValue(argv, '--docker-platform', downloadResultsValue(params.downloadResults, 'dockerPlatform'));
+        Install.pushArgIfValue(argv, '--git-url', downloadResultsValue(params.downloadResults, 'gitUrl'));
+        Install.pushArgIfValue(argv, '--npm-registry', downloadResultsValue(params.downloadResults, 'npmRegistry'));
+        Install.pushBooleanArgIfSet(argv, '--dev-dependencies', downloadResultsValue(params.downloadResults, 'devDependencies'));
+        Install.pushBooleanArgIfSet(argv, '--build', downloadResultsValue(params.downloadResults, 'build'));
+        Install.pushBooleanArgIfSet(argv, '--build-dts', downloadResultsValue(params.downloadResults, 'buildDts'));
+        Install.pushArgIfValue(argv, '--app-root-path', params.appResults.appRootPath);
+        Install.pushArgIfValue(argv, '--app-key', params.appResults.appKey);
+        Install.pushArgIfValue(argv, '--timezone', params.appResults.timeZone);
+        Install.pushBooleanArgIfSet(argv, '--builtin-db', params.dbResults.builtinDb);
+        Install.pushArgIfValue(argv, '--db-dialect', params.dbResults.dbDialect);
+        Install.pushArgIfValue(argv, '--db-host', params.dbResults.dbHost);
+        Install.pushArgIfValue(argv, '--db-port', params.dbResults.dbPort);
+        Install.pushArgIfValue(argv, '--db-database', params.dbResults.dbDatabase);
+        Install.pushArgIfValue(argv, '--db-user', params.dbResults.dbUser);
+        Install.pushArgIfValue(argv, '--db-password', params.dbResults.dbPassword);
+        if (authType === 'token') {
+            argv.push('--access-token', String(params.envAddResults.accessToken ?? ''));
+        }
+        return argv;
+    }
+    async collectPromptResults(parsed, yes) {
+        const resumePreset = await this.resolveResumePresetValues(parsed, yes);
+        const envPreset = {
+            ...(resumePreset?.envPreset ?? {}),
+            ...Install.buildEnvPresetValuesFromFlags(parsed),
+        };
+        const envResults = await runPromptCatalog(Install.envPrompts, {
+            initialValues: {
+                env: DEFAULT_INSTALL_ENV_NAME,
+            },
+            values: envPreset,
+            yes,
+        });
+        const envName = String(envResults.env ?? '').trim() || DEFAULT_INSTALL_ENV_NAME;
+        const appPreset = {
+            ...(resumePreset?.appPreset ?? {}),
+            ...Install.buildAppPresetValuesFromFlags(parsed),
+        };
+        const appCatalog = Install.buildAppPromptsCatalog(envName);
+        const appResults = await runPromptCatalog(appCatalog, {
+            initialValues: await Install.buildAppPromptInitialValues({
+                envName,
+                flags: {
+                    ...parsed,
+                    'app-root-path': parsed['app-root-path']
+                        ?? Install.toOptionalPromptString(appPreset.appRootPath),
+                    'app-port': parsed['app-port']
+                        ?? Install.toOptionalPromptString(appPreset.appPort),
+                    'storage-path': parsed['storage-path']
+                        ?? Install.toOptionalPromptString(appPreset.storagePath),
+                },
+            }),
+            values: appPreset,
+            yes,
+        });
+        let downloadResults = {};
+        if (Boolean(appResults.fetchSource)) {
+            const downloadOpts = Install.buildDownloadPromptOptionsForInstall(appResults, envName);
+            downloadOpts.values = {
+                ...(resumePreset?.downloadPreset ?? {}),
+                ...downloadOpts.values,
+                ...Install.buildDownloadPresetValuesForInstall(parsed, appResults, envName, yes),
+            };
+            downloadOpts.yes = yes;
+            downloadResults = await runPromptCatalog(Download.prompts, downloadOpts);
         }
-        if (flags.rootEmail !== undefined) {
-            npmArgs.push('--root-email', flags.rootEmail);
+        const dbPreset = {
+            ...(resumePreset?.dbPreset ?? {}),
+            ...Install.buildDbPresetValuesFromFlags(parsed),
+        };
+        const dbResults = await runPromptCatalog(Install.buildDbPromptsCatalog(downloadResults), {
+            initialValues: {
+                ...downloadResults,
+                ...await Install.buildDbPromptInitialValues({
+                    flags: {
+                        ...parsed,
+                        'db-port': parsed['db-port']
+                            ?? Install.toOptionalPromptString(dbPreset.dbPort),
+                    },
+                    downloadResults,
+                    dbPreset,
+                }),
+            },
+            values: dbPreset,
+            yes,
+        });
+        const rootPreset = Install.buildRootPresetValuesFromFlags(parsed);
+        const rootResults = await runPromptCatalog(Install.rootUserPrompts, {
+            initialValues: {},
+            values: rootPreset,
+            yes,
+        });
+        const envAddResults = await runPromptCatalog(EnvAdd.prompts, {
+            initialValues: {
+                apiBaseUrl: `http://127.0.0.1:${appResults.appPort ?? DEFAULT_INSTALL_APP_PORT}/api`,
+            },
+            values: {
+                name: envName,
+                scope: 'project',
+                ...(resumePreset?.envAddPreset ?? {}),
+            },
+            yes,
+        });
+        return {
+            envName,
+            envResults,
+            appResults,
+            downloadResults,
+            dbResults,
+            rootResults,
+            envAddResults,
+        };
+    }
+    async run() {
+        const parsedResult = await this.parse(Install);
+        const flags = parsedResult.flags;
+        const parsed = {
+            ...flags,
+        };
+        if (!parsed['no-intro']) {
+            p.intro('Set Up NocoBase');
         }
-        if (flags.rootPassword !== undefined) {
-            npmArgs.push('--root-password', flags.rootPassword);
+        if (parsed.resume) {
+            const envLabel = Install.toOptionalPromptString(parsed.env);
+            p.log.step(envLabel
+                ? `Resuming setup for env "${envLabel}" from the saved workspace config`
+                : 'Resuming setup from the saved workspace config');
         }
-        if (flags.rootNickname !== undefined) {
-            npmArgs.push('--root-nickname', flags.rootNickname);
+        const promptResults = await this.collectPromptResults(parsed, flags.yes);
+        const { envName, appResults, downloadResults, dbResults, rootResults, envAddResults, } = promptResults;
+        const source = String(downloadResultsValue(downloadResults, 'source') ?? '').trim();
+        const usesDockerResources = Boolean(dbResults.builtinDb)
+            || (Boolean(appResults.fetchSource) && source === 'docker');
+        const workspaceName = usesDockerResources
+            ? await Install.ensureWorkspaceName()
+            : undefined;
+        let builtinDbPlan;
+        if (Boolean(dbResults.builtinDb)) {
+            builtinDbPlan = await this.startBuiltinDb({
+                envName,
+                workspaceName,
+                appResults,
+                downloadResults,
+                dbResults,
+                force: parsed.force,
+            });
+            dbResults.dbHost = builtinDbPlan.dbHost;
+            dbResults.dbPort = builtinDbPlan.dbPort;
+            dbResults.dbDialect = builtinDbPlan.dbDialect;
+            dbResults.dbDatabase = builtinDbPlan.dbDatabase;
+            dbResults.dbUser = builtinDbPlan.dbUser;
+            dbResults.dbPassword = builtinDbPlan.dbPassword;
         }
-        return npmArgs;
-    }
-    /**
-     * Execute `nocobase-v1` in the application root. Add pre/post steps or source-specific behavior here.
-     */
-    async runNocoBaseInstall(appRoot, procEnv, flags, interactive) {
-        const rel = path.relative(process.cwd(), appRoot);
-        const where = rel === '' || rel === '.'
-            ? 'this folder'
-            : rel.startsWith('..')
-                ? appRoot
-                : `./${rel.split(path.sep).join('/')}`;
-        const label = `Installing NocoBase — this may take a few minutes.`;
-        if (interactive) {
-            p.log.step(label);
+        let dockerAppPlan;
+        let localAppPlan;
+        if (Boolean(appResults.fetchSource)) {
+            if (source === 'docker') {
+                dockerAppPlan = await this.installDockerApp({
+                    envName,
+                    workspaceName,
+                    appResults,
+                    downloadResults,
+                    dbResults,
+                    rootResults,
+                    builtinDbPlan,
+                    force: parsed.force,
+                });
+                appResults.appKey = dockerAppPlan.appKey;
+                appResults.timeZone = dockerAppPlan.timeZone;
+            }
+            else if (source === 'npm' || source === 'git') {
+                const projectRoot = await this.downloadLocalApp({
+                    envName,
+                    appResults,
+                    downloadResults,
+                });
+                localAppPlan = await this.startLocalApp({
+                    envName,
+                    source,
+                    projectRoot,
+                    appResults,
+                    dbResults,
+                    rootResults,
+                });
+                appResults.appKey = localAppPlan.appKey;
+                appResults.timeZone = localAppPlan.timeZone;
+            }
         }
         else {
-            this.log(label);
+            p.log.info('Skipped app download and install.');
         }
-        const npmArgs = this.buildNocoBaseInstallArgs(flags);
-        // TODO: Re-enable when the app root has a runnable `nocobase-v1 install` (or swap to the supported entrypoint).
-        // await runNocoBaseCommand(npmArgs, { cwd: appRoot, env: procEnv });
-        void npmArgs;
+        if (dockerAppPlan || localAppPlan) {
+            await this.waitForAppHealthCheck(Install.resolveApiBaseUrl({
+                appResults,
+                envAddResults,
+            }), {
+                containerName: dockerAppPlan?.containerName,
+            });
+        }
+        await this.saveInstalledEnv({
+            envName,
+            appResults,
+            downloadResults,
+            dbResults,
+            envAddResults,
+        });
+        p.outro(dockerAppPlan || localAppPlan
+            ? `NocoBase is ready at http://127.0.0.1:${dockerAppPlan?.appPort ?? localAppPlan?.appPort}`
+            : `Install config for "${envName}" has been saved.`);
     }
 }
+function downloadResultsValue(downloadResults, key) {
+    return downloadResults[key];
+}