@nocobase/cli 2.1.0-alpha.22 → 2.1.0-alpha.23

package/dist/commands/download.js

@@ -12,13 +12,15 @@ import * as p from '@clack/prompts';
 import path from 'node:path';
 import { stdin as stdinStream, stdout as stdoutStream } from 'node:process';
 import { runPromptCatalog, } from "../lib/prompt-catalog.js";
-import { applyCliLocale, CLI_LOCALE_FLAG_DESCRIPTION, CLI_LOCALE_FLAG_OPTIONS, localeText, } from "../lib/cli-locale.js";
+import { applyCliLocale, CLI_LOCALE_FLAG_DESCRIPTION, CLI_LOCALE_FLAG_OPTIONS, localeText, resolveCliLocale, translateCli, } from "../lib/cli-locale.js";
 import { run } from "../lib/run-npm.js";
 import { printVerbose, setVerboseMode, startTask, stopTask, updateTask } from '../lib/ui.js';
 const DEFAULT_DOCKER_REGISTRY = 'nocobase/nocobase';
 const DEFAULT_DOCKER_REGISTRY_ZH_CN = 'registry.cn-shanghai.aliyuncs.com/nocobase/nocobase';
 const DEFAULT_DOCKER_PLATFORM = 'auto';
+const DEFAULT_DOWNLOAD_VERSION = 'beta';
 const downloadText = (key, values) => localeText(`commands.download.${key}`, values);
+const downloadTranslatedText = (key, values, fallback) => translateCli(`commands.download.${key}`, values, { fallback });
 function defaultOutputDirForVersion(versionTag) {
     const safe = versionTag.replace(/[/\\]/g, '-');
     return `./nocobase-${safe}`;
@@ -33,10 +35,13 @@ async function pathExists(target) {
     }
 }
 export function defaultDockerRegistryForLang(lang) {
-    return String(lang ?? '').trim() === 'zh-CN'
+    return resolveCliLocale(String(lang ?? '').trim() || undefined) === 'zh-CN'
         ? DEFAULT_DOCKER_REGISTRY_ZH_CN
         : DEFAULT_DOCKER_REGISTRY;
 }
+function defaultDockerRegistryForPromptValues(_values) {
+    return defaultDockerRegistryForLang(process.env.NB_LOCALE);
+}
 function argvHasToken(argv, tokens) {
     return tokens.some((t) => argv.includes(t));
 }
@@ -81,8 +86,64 @@ function dockerPlatformArg(value) {
     }
     return platform;
 }
+function formatDownloadStageFailure(stage) {
+    return [
+        downloadTranslatedText(`failures.${stage}.title`),
+        downloadTranslatedText(`failures.${stage}.body`),
+        downloadTranslatedText(`failures.${stage}.hint`),
+    ].join('\n');
+}
+function formatDownloadFailure(message, verbose) {
+    if (verbose) {
+        return message;
+    }
+    const lower = message.toLowerCase();
+    if (lower.includes('yarn install')) {
+        return formatDownloadStageFailure('dependencyInstall');
+    }
+    if (lower.includes('git clone')) {
+        return formatDownloadStageFailure('gitClone');
+    }
+    if (lower.includes('docker pull')) {
+        return formatDownloadStageFailure('dockerPull');
+    }
+    if (lower.includes('docker save')) {
+        return formatDownloadStageFailure('dockerSave');
+    }
+    if (lower.includes('create-nocobase-app') || lower.includes('npx create-nocobase-app')) {
+        return formatDownloadStageFailure('scaffold');
+    }
+    if (lower.includes('nocobase command')) {
+        return formatDownloadStageFailure('build');
+    }
+    if (lower.includes('exited with code') || lower.includes('exited due to signal')) {
+        return formatDownloadStageFailure('generic');
+    }
+    return message;
+}
 const EXTERNAL_COMMAND_LOADING_DELAY_MS = 8_000;
 const EXTERNAL_COMMAND_LOADING_UPDATE_MS = 15_000;
+function normalizeVersionPreset(value) {
+    const text = String(value ?? '').trim();
+    if (text === 'latest' || text === 'beta' || text === 'alpha') {
+        return text;
+    }
+    return 'other';
+}
+function versionPresetForValue(value) {
+    return normalizeVersionPreset(value);
+}
+function otherVersionValue(value) {
+    const text = String(value ?? '').trim();
+    return normalizeVersionPreset(text) === 'other' ? text : '';
+}
+function resolveVersionFromResults(results, fallback) {
+    const preset = normalizeVersionPreset(results.version ?? fallback);
+    if (preset === 'other') {
+        return String(results.otherVersion ?? fallback ?? '').trim();
+    }
+    return preset;
+}
 export default class Download extends Command {
     _flags;
     preparationTaskActive = false;
@@ -176,30 +237,72 @@ export default class Download extends Command {
     static prompts = {
         source: {
             type: 'select',
+            variant: 'radio',
             message: downloadText('prompts.source.message'),
             options: [
-                { value: 'npm', label: downloadText('prompts.source.npmLabel') },
-                { value: 'git', label: downloadText('prompts.source.gitLabel') },
-                { value: 'docker', label: downloadText('prompts.source.dockerLabel') },
+                {
+                    value: 'docker',
+                    label: downloadText('prompts.source.dockerLabel'),
+                    hint: downloadText('prompts.source.dockerHint'),
+                },
+                {
+                    value: 'npm',
+                    label: downloadText('prompts.source.npmLabel'),
+                    hint: downloadText('prompts.source.npmHint'),
+                },
+                {
+                    value: 'git',
+                    label: downloadText('prompts.source.gitLabel'),
+                    hint: downloadText('prompts.source.gitHint'),
+                },
             ],
             yesInitialValue: 'docker',
             initialValue: 'docker',
             required: true,
         },
         version: {
-            type: 'text',
+            type: 'select',
+            variant: 'radio',
             message: downloadText('prompts.version.message'),
-            placeholder: downloadText('prompts.version.placeholder'),
-            initialValue: 'alpha',
-            yesInitialValue: 'alpha',
+            options: [
+                {
+                    value: 'latest',
+                    label: downloadText('prompts.version.latestLabel'),
+                    hint: downloadText('prompts.version.latestHint'),
+                    disabled: true,
+                },
+                {
+                    value: 'beta',
+                    label: downloadText('prompts.version.betaLabel'),
+                    hint: downloadText('prompts.version.betaHint'),
+                },
+                {
+                    value: 'alpha',
+                    label: downloadText('prompts.version.alphaLabel'),
+                    hint: downloadText('prompts.version.alphaHint'),
+                },
+                {
+                    value: 'other',
+                    label: downloadText('prompts.version.otherLabel'),
+                    hint: downloadText('prompts.version.otherHint'),
+                },
+            ],
+            initialValue: DEFAULT_DOWNLOAD_VERSION,
+            yesInitialValue: DEFAULT_DOWNLOAD_VERSION,
+            required: true,
+        },
+        otherVersion: {
+            type: 'text',
+            message: downloadText('prompts.otherVersion.message'),
+            placeholder: downloadText('prompts.otherVersion.placeholder'),
             required: true,
+            hidden: (values) => normalizeVersionPreset(values.version) !== 'other',
         },
         dockerRegistry: {
             type: 'text',
             message: downloadText('prompts.dockerRegistry.message'),
             placeholder: downloadText('prompts.dockerRegistry.placeholder'),
-            initialValue: (values) => defaultDockerRegistryForLang(values.lang),
-            yesInitialValue: DEFAULT_DOCKER_REGISTRY,
+            initialValue: defaultDockerRegistryForPromptValues,
             required: true,
             hidden: (values) => values.source !== 'docker',
         },
@@ -239,7 +342,10 @@ export default class Download extends Command {
             type: 'text',
             message: downloadText('prompts.outputDir.message'),
             placeholder: downloadText('prompts.outputDir.placeholder'),
-            initialValue: (values) => defaultOutputDirForVersion(String(values.version ?? 'latest').trim() || 'latest'),
+            initialValue: (values) => {
+                const version = resolveVersionFromResults(values, DEFAULT_DOWNLOAD_VERSION) || DEFAULT_DOWNLOAD_VERSION;
+                return defaultOutputDirForVersion(version);
+            },
             required: true,
             hidden: (values) => {
                 const s = values.source;
@@ -315,7 +421,7 @@ export default class Download extends Command {
         return outputAbs;
     }
     dockerTarPath(flags, outputAbs) {
-        const image = flags['docker-registry'] ?? DEFAULT_DOCKER_REGISTRY;
+        const image = String(flags['docker-registry'] ?? '').trim() || defaultDockerRegistryForLang(process.env.NB_LOCALE);
         const tag = flags.version ?? 'latest';
         const safeBase = `${image.replace(/[/:]/g, '-')}-${tag.replace(/[/\\]/g, '-')}`;
         return path.join(outputAbs, `${safeBase}.tar`);
@@ -326,12 +432,15 @@ export default class Download extends Command {
      */
     buildInitialValuesFromParsed(flags, preset) {
         const initialValues = {};
+        const localeDefaultDockerRegistry = defaultDockerRegistryForLang(flags.locale ?? process.env.NB_LOCALE);
         const source = flags.source?.trim();
         if (source) {
             initialValues.source = source;
         }
         if (flags.version !== undefined) {
-            initialValues.version = flags.version.trim() || 'latest';
+            const version = flags.version.trim() || 'latest';
+            initialValues.version = versionPresetForValue(version);
+            initialValues.otherVersion = otherVersionValue(version);
         }
         initialValues.replace = flags.replace;
         initialValues.devDependencies = flags['dev-dependencies'];
@@ -346,6 +455,9 @@ export default class Download extends Command {
         if (flags['docker-registry'] !== undefined) {
             initialValues.dockerRegistry = String(flags['docker-registry'] ?? '').trim();
         }
+        else {
+            initialValues.dockerRegistry = localeDefaultDockerRegistry;
+        }
         initialValues.dockerPlatform = normalizeDockerPlatform(flags['docker-platform']);
         initialValues.dockerSave = flags['docker-save'];
         if (flags['npm-registry'] !== undefined) {
@@ -370,7 +482,11 @@ export default class Download extends Command {
             preset.source = String(flags.source).trim();
         }
         if (flags.version !== undefined) {
-            preset.version = String(flags.version).trim() || 'latest';
+            const version = String(flags.version).trim() || 'latest';
+            preset.version = versionPresetForValue(version);
+            if (normalizeVersionPreset(version) === 'other') {
+                preset.otherVersion = version;
+            }
         }
         if (flags['docker-registry'] !== undefined) {
             const v = String(flags['docker-registry'] ?? '').trim();
@@ -424,7 +540,7 @@ export default class Download extends Command {
     }
     mapCatalogResultsToResolved(results, flags) {
         const source = String(results.source);
-        const version = String(results.version ?? '').trim() || 'latest';
+        const version = resolveVersionFromResults(results, flags.version) || 'latest';
         const devDependencies = source === 'npm' ? Boolean(results.devDependencies) : undefined;
         const effectiveBuild = this.resolveEffectiveBuild(source, results, flags);
         const buildDtsWant = results.buildDts !== undefined ? Boolean(results.buildDts) : flags['build-dts'];
@@ -435,9 +551,11 @@ export default class Download extends Command {
         const gitUrl = results.gitUrl !== undefined
             ? String(results.gitUrl).trim() || undefined
             : flags['git-url']?.trim() || undefined;
-        const dockerRegistry = results.dockerRegistry !== undefined
-            ? String(results.dockerRegistry).trim() || undefined
-            : flags['docker-registry']?.trim() || undefined;
+        const dockerRegistry = source === 'docker'
+            ? (results.dockerRegistry !== undefined
+                ? String(results.dockerRegistry).trim() || undefined
+                : flags['docker-registry']?.trim() || defaultDockerRegistryForLang(flags.locale ?? process.env.NB_LOCALE))
+            : undefined;
         const dockerPlatform = source === 'docker'
             ? normalizeDockerPlatform(results.dockerPlatform !== undefined
                 ? results.dockerPlatform
@@ -490,9 +608,13 @@ export default class Download extends Command {
             },
         });
         const source = String(results.source ?? '').trim();
+        const version = resolveVersionFromResults(results, flags.version);
         if (!source || !['docker', 'npm', 'git'].includes(source)) {
             this.error('Download source is required. Choose npm, git, or docker.');
         }
+        if (!version) {
+            this.error('Version is required. Choose alpha, beta, latest, or enter another version.');
+        }
         if (flags['docker-save'] && source !== 'docker') {
             this.error('--docker-save is only available when --source docker is selected.');
         }
@@ -586,7 +708,7 @@ export default class Download extends Command {
         return argv;
     }
     async downloadFromDocker(flags) {
-        const image = flags['docker-registry'] ?? DEFAULT_DOCKER_REGISTRY;
+        const image = String(flags['docker-registry'] ?? '').trim() || defaultDockerRegistryForLang(process.env.NB_LOCALE);
         const tag = flags.version ?? 'latest';
         const imageRef = `${image}:${tag}`;
         const platform = dockerPlatformArg(flags['docker-platform']);
@@ -737,7 +859,7 @@ export default class Download extends Command {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            this.error(message);
+            this.error(formatDownloadFailure(message, this.isVerbose()));
         }
     }
 }

package/dist/commands/init.js

@@ -48,6 +48,13 @@ function downloadInNewInstallOnly(def) {
 function argvHasToken(argv, tokens) {
     return tokens.some((token) => argv.includes(token));
 }
+function resolveInitDownloadVersion(results) {
+    const preset = String(results.version ?? '').trim();
+    if (preset === 'other') {
+        return String(results.otherVersion ?? '').trim();
+    }
+    return preset;
+}
 function shouldAllowExistingInitEnv() {
     return argvHasToken(process.argv.slice(2), ['--force', '-f']);
 }
@@ -177,6 +184,7 @@ Prompt modes:
         fetchSource: newInstallOnly(Install.appPrompts.fetchSource),
         source: downloadInNewInstallOnly(Download.prompts.source),
         version: downloadInNewInstallOnly(Download.prompts.version),
+        otherVersion: downloadInNewInstallOnly(Download.prompts.otherVersion),
         dockerRegistry: downloadInNewInstallOnly(Download.prompts.dockerRegistry),
         dockerPlatform: downloadInNewInstallOnly(Download.prompts.dockerPlatform),
         dockerSave: downloadInNewInstallOnly(Download.prompts.dockerSave),
@@ -238,6 +246,10 @@ Prompt modes:
             description: 'Open the guided setup flow in a local browser form (not valid with --yes)',
             default: false,
         }),
+        verbose: Flags.boolean({
+            description: 'Show detailed command output',
+            default: false,
+        }),
         'ui-host': Flags.string({
             description: 'Host for the local --ui setup server (default: 127.0.0.1)',
         }),
@@ -468,6 +480,7 @@ Prompt modes:
                 catalog: {
                     source: c.source,
                     version: c.version,
+                    otherVersion: c.otherVersion,
                     dockerRegistry: c.dockerRegistry,
                     dockerPlatform: c.dockerPlatform,
                     dockerSave: c.dockerSave,
@@ -614,7 +627,7 @@ Prompt modes:
         const envName = String(results.appName ?? DEFAULT_INIT_APP_NAME).trim() || DEFAULT_INIT_APP_NAME;
         const appPort = String(results.appPort ?? '').trim();
         const source = String(results.source ?? '').trim();
-        const version = String(results.version ?? '').trim();
+        const version = resolveInitDownloadVersion(results);
         const dockerRegistry = String(results.dockerRegistry ?? '').trim();
         const dockerPlatform = String(results.dockerPlatform ?? '').trim();
         const gitUrl = String(results.gitUrl ?? '').trim();
@@ -675,6 +688,9 @@ Prompt modes:
         if (options?.resume) {
             argv.push('--resume');
         }
+        if (Boolean(flags.verbose)) {
+            argv.push('--verbose');
+        }
         const lang = String(results.lang ?? '').trim();
         if (lang) {
             argv.push('--lang', lang);
@@ -699,7 +715,7 @@ Prompt modes:
             if (source) {
                 argv.push('--source', source);
             }
-            const version = String(results.version ?? '').trim();
+            const version = resolveInitDownloadVersion(results);
             if (version) {
                 argv.push('--version', version);
             }

package/dist/commands/install.js

@@ -15,7 +15,7 @@ import { mkdir } from 'node:fs/promises';
 import path from 'node:path';
 import { exit } from 'node:process';
 import { runPromptCatalog, } from "../lib/prompt-catalog.js";
-import { applyCliLocale, localeText, translateCli, } from "../lib/cli-locale.js";
+import { applyCliLocale, localeText, resolveCliLocale, translateCli, } from "../lib/cli-locale.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';
@@ -40,6 +40,12 @@ const DEFAULT_INSTALL_BUILTIN_DB_IMAGES = {
     mariadb: 'mariadb:11',
     kingbase: 'registry.cn-shanghai.aliyuncs.com/nocobase/kingbase:v009r001c001b0030_single_x86',
 };
+const DEFAULT_INSTALL_BUILTIN_DB_IMAGES_ZH_CN = {
+    postgres: 'registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16',
+    mysql: 'registry.cn-shanghai.aliyuncs.com/nocobase/mysql:8',
+    mariadb: 'registry.cn-shanghai.aliyuncs.com/nocobase/mariadb:11',
+    kingbase: 'registry.cn-shanghai.aliyuncs.com/nocobase/kingbase:v009r001c001b0030_single_x86',
+};
 const DEFAULT_INSTALL_DB_DATABASE = 'nocobase';
 const DEFAULT_INSTALL_DB_USER = 'nocobase';
 const DEFAULT_INSTALL_DB_PASSWORD = 'nocobase';
@@ -141,9 +147,12 @@ export function defaultDbPortForDialect(value) {
 }
 function defaultBuiltinDbImageForDialect(value) {
     const dialect = String(value ?? 'postgres').trim();
+    const defaults = resolveCliLocale(process.env.NB_LOCALE) === 'zh-CN'
+        ? DEFAULT_INSTALL_BUILTIN_DB_IMAGES_ZH_CN
+        : DEFAULT_INSTALL_BUILTIN_DB_IMAGES;
     return supportsBuiltinDbDialect(dialect)
-        ? DEFAULT_INSTALL_BUILTIN_DB_IMAGES[dialect]
-        : DEFAULT_INSTALL_BUILTIN_DB_IMAGES.postgres;
+        ? defaults[dialect]
+        : defaults.postgres;
 }
 function defaultDbDatabaseForDialect(value) {
     return String(value ?? '').trim() === 'kingbase'
@@ -254,6 +263,10 @@ export default class Install extends Command {
             description: 'Resume a previous unfinished setup for this env using the saved workspace env config',
             default: false,
         }),
+        verbose: Flags.boolean({
+            description: 'Show detailed command output',
+            default: false,
+        }),
         env: Flags.string({
             char: 'e',
             description: 'App/env name to create or update. Defaults app paths to ./<envName>/source/ and ./<envName>/storage/.',
@@ -804,15 +817,15 @@ export default class Install extends Command {
         };
     }
     /**
-     * When install runs {@link Download.prompts} after app prompts, align language and
-     * output directory defaults with the app settings collected earlier in the flow.
+     * When install runs {@link Download.prompts} after app prompts, align the download
+     * output directory with app settings, while Docker registry defaults follow the CLI locale.
      */
     static buildDownloadPromptOptionsForInstall(appResults, envName) {
         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),
+            dockerRegistry: defaultDockerRegistryForLang(process.env.NB_LOCALE),
             outputDir: appRoot,
         };
         const values = {
@@ -970,7 +983,7 @@ export default class Install extends Command {
                 ? dbHostInput
                 : containerName);
         if (dbDialect === 'postgres') {
-            const image = String(params.builtinDbImage ?? '').trim() || DEFAULT_INSTALL_BUILTIN_DB_IMAGES.postgres;
+            const image = String(params.builtinDbImage ?? '').trim() || defaultBuiltinDbImageForDialect(dbDialect);
             const dataDir = path.resolve(params.storagePath, 'db', 'postgres');
             const args = [
                 'run',
@@ -1014,7 +1027,7 @@ export default class Install extends Command {
             };
         }
         if (dbDialect === 'mysql') {
-            const image = String(params.builtinDbImage ?? '').trim() || DEFAULT_INSTALL_BUILTIN_DB_IMAGES.mysql;
+            const image = String(params.builtinDbImage ?? '').trim() || defaultBuiltinDbImageForDialect(dbDialect);
             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 ?? defaultDbDatabase).trim() || defaultDbDatabase;
@@ -1060,7 +1073,7 @@ export default class Install extends Command {
             };
         }
         if (dbDialect === 'mariadb') {
-            const image = String(params.builtinDbImage ?? '').trim() || DEFAULT_INSTALL_BUILTIN_DB_IMAGES.mariadb;
+            const image = String(params.builtinDbImage ?? '').trim() || defaultBuiltinDbImageForDialect(dbDialect);
             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 ?? defaultDbDatabase).trim() || defaultDbDatabase;
@@ -1106,7 +1119,7 @@ export default class Install extends Command {
             };
         }
         if (dbDialect === 'kingbase') {
-            const image = String(params.builtinDbImage ?? '').trim() || DEFAULT_INSTALL_BUILTIN_DB_IMAGES.kingbase;
+            const image = String(params.builtinDbImage ?? '').trim() || defaultBuiltinDbImageForDialect(dbDialect);
             const dataDir = path.resolve(params.storagePath, 'db', 'kingbase');
             const dbUser = String(params.dbUser ?? DEFAULT_INSTALL_DB_USER).trim() || DEFAULT_INSTALL_DB_USER;
             const dbDatabase = String(params.dbDatabase ?? defaultDbDatabase).trim() || defaultDbDatabase;
@@ -1271,7 +1284,7 @@ export default class Install extends Command {
     }
     static buildDockerAppPlan(params) {
         const dockerRegistry = String(downloadResultsValue(params.downloadResults, 'dockerRegistry') ?? '').trim()
-            || defaultDockerRegistryForLang(params.appResults.lang);
+            || defaultDockerRegistryForLang(process.env.NB_LOCALE);
         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()
@@ -1365,8 +1378,11 @@ export default class Install extends Command {
             argv.push(flag, text);
         }
     }
-    static buildDownloadArgvFromResults(results) {
+    static buildDownloadArgvFromResults(results, options) {
         const argv = ['-y', '--no-intro'];
+        if (options?.verbose) {
+            argv.push('--verbose');
+        }
         Install.pushDownloadArgIfValue(argv, '--source', results.source);
         Install.pushDownloadArgIfValue(argv, '--version', results.version);
         Install.pushDownloadArgIfValue(argv, '--output-dir', results.outputDir);
@@ -1402,7 +1418,9 @@ export default class Install extends Command {
         return path.resolve(process.cwd(), outputDir);
     }
     async downloadLocalApp(params) {
-        const argv = Install.buildDownloadArgvFromResults(params.downloadResults);
+        const argv = Install.buildDownloadArgvFromResults(params.downloadResults, {
+            verbose: params.verbose,
+        });
         p.log.step('Downloading local NocoBase app files');
         const result = await this.config.runCommand('download', argv);
         const projectRoot = Install.resolveLocalProjectRoot({
@@ -1799,6 +1817,7 @@ export default class Install extends Command {
                     envName,
                     appResults,
                     downloadResults,
+                    verbose: parsed.verbose,
                 });
                 localAppPlan = await this.startLocalApp({
                     envName,

package/dist/lib/prompt-catalog.js

@@ -22,8 +22,14 @@ function clackSelectOptions(options, locale) {
             value: o.value,
             label: resolvePromptText(o.label, locale, o.value),
             ...(o.hint !== undefined ? { hint: resolvePromptText(o.hint, locale) } : {}),
+            ...(o.disabled !== undefined ? { disabled: o.disabled } : {}),
         });
 }
+function enabledSelectOptionValues(options) {
+    return options
+        .filter((o) => typeof o === 'string' || o.disabled !== true)
+        .map((o) => (typeof o === 'string' ? o : o.value));
+}
 function defaultOnCancel(locale) {
     p.cancel(createCliTranslate(locale)('promptCatalog.common.cancelled'));
     exit(0);
@@ -63,21 +69,22 @@ function mergedBoolean(key, def, iv, useYesInitial) {
 }
 function mergedSelect(key, def, iv, useYesInitial) {
     const valueList = selectOptionValues(def.options);
+    const enabledValueList = enabledSelectOptionValues(def.options);
     if (hasIvKey(iv, key)) {
         const s = String(iv[key]);
-        if (valueList.includes(s)) {
+        if (enabledValueList.includes(s)) {
             return s;
         }
         return undefined;
     }
-    if (useYesInitial && def.yesInitialValue !== undefined && valueList.includes(def.yesInitialValue)) {
+    if (useYesInitial && def.yesInitialValue !== undefined && enabledValueList.includes(def.yesInitialValue)) {
         return def.yesInitialValue;
     }
     const d = def.initialValue;
-    if (d !== undefined && valueList.includes(d)) {
+    if (d !== undefined && enabledValueList.includes(d)) {
         return d;
     }
-    return valueList[0];
+    return enabledValueList[0];
 }
 function mergedInteger(key, def, iv, useYesInitial) {
     if (hasIvKey(iv, key)) {

package/dist/lib/prompt-web-ui.js

@@ -9,7 +9,7 @@
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:http';
 import { createCliTranslate, resolveCliLocale, resolveLocalizedText, } from "./cli-locale.js";
-import { isPromptBlockSkipped, runPromptFieldValidate, selectOptionValues, } from "./prompt-catalog.js";
+import { isPromptBlockSkipped, runPromptFieldValidate, } from "./prompt-catalog.js";
 const DEFAULT_SUBMIT = '/__pwc_ui_submit';
 const DEFAULT_REFLOW = '/__pwc_ui_reflow';
 const DEFAULT_VALIDATE_STEP = '/__pwc_ui_validate_step';
@@ -76,12 +76,17 @@ function defaultValueForInput(key, def, out) {
         case 'boolean':
             return def.initialValue !== undefined ? Boolean(def.initialValue) : true;
         case 'select': {
-            const first = selectOptionValues(def.options)[0];
+            const first = def.options
+                .find((o) => typeof o === 'string' || o.disabled !== true);
+            const firstValue = typeof first === 'string' ? first : first?.value;
             const i = def.initialValue;
-            if (i !== undefined && selectOptionValues(def.options).includes(i)) {
+            const enabledValues = def.options
+                .filter((o) => typeof o === 'string' || o.disabled !== true)
+                .map((o) => (typeof o === 'string' ? o : o.value));
+            if (i !== undefined && enabledValues.includes(i)) {
                 return i;
             }
-            return first ?? '';
+            return firstValue ?? '';
         }
         case 'password':
             return def.initialValue ?? '';
@@ -147,7 +152,9 @@ function normalizeWebRawForBlock(def, raw, key) {
         }
         case 'select': {
             const s = String(raw ?? '');
-            const list = selectOptionValues(def.options);
+            const list = def.options
+                .filter((o) => typeof o === 'string' || o.disabled !== true)
+                .map((o) => (typeof o === 'string' ? o : o.value));
             if (list.includes(s)) {
                 return s;
             }
@@ -298,11 +305,15 @@ function renderPwcRadioOptions(key, def, defaults, hidden, locale) {
             : o.hint
                 ? `<div class="pwc-radio-option-hint">${escapeHtml(resolveUiText(o.hint, locale))}</div>`
                 : '';
+        const optionDisabled = typeof o !== 'string' && o.disabled === true;
         const checked = String(defaults[key] ?? '') === val ? ' checked' : '';
         const required = def.required && index === 0 ? ' required' : '';
-        const disabled = hidden ? ' disabled' : '';
-        return (`<label class="pwc-radio-option">` +
-            `<input class="pwc-radio-input" name="${escapeHtml(key)}" type="radio" value="${escapeHtml(String(val))}"${checked}${required}${disabled} />` +
+        const disabled = hidden || optionDisabled ? ' disabled' : '';
+        const optionClass = optionDisabled ? 'pwc-radio-option pwc-radio-option--disabled' : 'pwc-radio-option';
+        const ariaDisabled = optionDisabled ? ' aria-disabled="true"' : '';
+        const staticDisabled = optionDisabled ? ' data-pwc-static-disabled="1"' : '';
+        return (`<label class="${optionClass}"${ariaDisabled}>` +
+            `<input class="pwc-radio-input" name="${escapeHtml(key)}" type="radio" value="${escapeHtml(String(val))}"${checked}${required}${disabled}${staticDisabled} />` +
             `<span class="pwc-radio-option-body">` +
             `<span class="pwc-radio-option-label">${escapeHtml(String(lab))}</span>` +
             hint +
@@ -361,7 +372,8 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
             const val = typeof o === 'string' ? o : o.value;
             const lab = typeof o === 'string' ? o : resolveUiText(o.label, locale, o.value);
             const sel = String(defaults[key] ?? '') === val ? ' selected' : '';
-            return `<option value="${escapeHtml(String(val))}"${sel}>${escapeHtml(String(lab))}</option>`;
+            const disabledOpt = typeof o !== 'string' && o.disabled === true ? ' disabled' : '';
+            return `<option value="${escapeHtml(String(val))}"${sel}${disabledOpt}>${escapeHtml(String(lab))}</option>`;
         })
             .join('');
         const req = def.required ? ' required' : '';
@@ -1132,6 +1144,15 @@ function runPromptCatalogWebUIImpl(options) {
       box-shadow: 0 0 0 2px color-mix(in srgb, var(--pwc-ad-color-primary) 8%, transparent);
       background: color-mix(in srgb, var(--pwc-ad-color-primary) 2%, var(--pwc-ad-color-container));
     }
+    .pwc-radio-option--disabled {
+      cursor: not-allowed;
+      background: var(--pwc-ad-color-fill-alter);
+    }
+    .pwc-radio-option--disabled:hover {
+      border-color: var(--pwc-ad-color-border);
+      box-shadow: none;
+      background: var(--pwc-ad-color-fill-alter);
+    }
     .pwc-radio-input {
       margin: 3px 0 0;
       width: 16px;
@@ -1140,6 +1161,9 @@ function runPromptCatalogWebUIImpl(options) {
       accent-color: var(--pwc-ad-color-primary);
       cursor: pointer;
     }
+    .pwc-radio-option--disabled .pwc-radio-input {
+      cursor: not-allowed;
+    }
     .pwc-radio-option-body { min-width: 0; }
     .pwc-radio-option-label {
       display: block;
@@ -1147,12 +1171,18 @@ function runPromptCatalogWebUIImpl(options) {
       line-height: 1.5715;
       color: var(--pwc-ad-color-text);
     }
+    .pwc-radio-option--disabled .pwc-radio-option-label {
+      color: color-mix(in srgb, var(--pwc-ad-color-text) 55%, transparent);
+    }
     .pwc-radio-option-hint {
       margin-top: 2px;
       font-size: 12px;
       line-height: 1.5;
       color: var(--pwc-ad-color-text-description);
     }
+    .pwc-radio-option--disabled .pwc-radio-option-hint {
+      color: color-mix(in srgb, var(--pwc-ad-color-text-description) 70%, transparent);
+    }
     .pwc-radio-input:focus-visible {
       outline: none;
       box-shadow: 0 0 0 2px color-mix(in srgb, var(--pwc-ad-color-primary) 20%, transparent);
@@ -1163,6 +1193,11 @@ function runPromptCatalogWebUIImpl(options) {
       box-shadow: 0 0 0 2px color-mix(in srgb, var(--pwc-ad-color-primary) 12%, transparent);
       background: color-mix(in srgb, var(--pwc-ad-color-primary) 5%, var(--pwc-ad-color-container));
     }
+    .pwc-radio-option--disabled:has(.pwc-radio-input:checked) {
+      border-color: var(--pwc-ad-color-border);
+      box-shadow: none;
+      background: var(--pwc-ad-color-fill-alter);
+    }
     .pwc-form-item-has-error .pwc-radio-option {
       border-color: var(--pwc-form-color-error);
     }
@@ -1570,7 +1605,7 @@ function runPromptCatalogWebUIImpl(options) {
             w.style.display = hidden ? 'none' : 'block';
             var ctrls = w.querySelectorAll('input, select, textarea');
             for (var i = 0; i < ctrls.length; i++) {
-              ctrls[i].disabled = hidden;
+              ctrls[i].disabled = hidden || ctrls[i].getAttribute('data-pwc-static-disabled') === '1';
             }
             if (!hidden && k && !pwcIsFieldDirty(k) && Object.prototype.hasOwnProperty.call(vals, k)) {
               setControlValue(form, k, vals[k]);

package/dist/lib/run-npm.js

@@ -6,15 +6,9 @@
  * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
-import { spawn } from 'node:child_process';
 import path from 'node:path';
+import spawn from 'cross-spawn';
 function resolveCommandName(name) {
-    if (process.platform !== 'win32' || path.extname(name) || name.includes(path.sep)) {
-        return name;
-    }
-    if (['npm', 'npx', 'pnpm', 'yarn'].includes(name)) {
-        return `${name}.cmd`;
-    }
     return name;
 }
 function resolveCwd(cwd) {
@@ -27,14 +21,16 @@ function resolveCwd(cwd) {
 export function run(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
     const label = options?.errorName ?? name;
+    const command = resolveCommandName(name);
     return new Promise((resolve, reject) => {
-        const child = spawn(resolveCommandName(name), [...args], {
+        const child = spawn(command, [...args], {
             stdio: options?.stdio ?? 'inherit',
             cwd,
             env: {
                 ...process.env,
                 ...options?.env,
             },
+            windowsHide: process.platform === 'win32',
         });
         child.once('error', reject);
         child.once('close', (code, signal) => {
@@ -52,14 +48,16 @@ export function run(name, args, options) {
 }
 export function commandSucceeds(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
+    const command = resolveCommandName(name);
     return new Promise((resolve) => {
-        const child = spawn(resolveCommandName(name), [...args], {
+        const child = spawn(command, [...args], {
             cwd,
             env: {
                 ...process.env,
                 ...options?.env,
             },
             stdio: 'ignore',
+            windowsHide: process.platform === 'win32',
         });
         child.once('error', () => resolve(false));
         child.once('close', (code) => resolve(code === 0));
@@ -68,14 +66,16 @@ export function commandSucceeds(name, args, options) {
 export function commandOutput(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
     const label = options?.errorName ?? name;
+    const command = resolveCommandName(name);
     return new Promise((resolve, reject) => {
-        const child = spawn(resolveCommandName(name), [...args], {
+        const child = spawn(command, [...args], {
             cwd,
             env: {
                 ...process.env,
                 ...options?.env,
             },
             stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: process.platform === 'win32',
         });
         let stdout = '';
         let stderr = '';

package/dist/locale/en-US.json

@@ -95,16 +95,67 @@
       }
     },
     "download": {
+      "failures": {
+        "dependencyInstall": {
+          "title": "Couldn't finish preparing the local NocoBase app.",
+          "body": "The download completed, but dependency installation did not finish successfully.",
+          "hint": "Run the same command again with `--verbose` to see the full install logs."
+        },
+        "gitClone": {
+          "title": "Couldn't download NocoBase from Git.",
+          "body": "The CLI was not able to clone the selected NocoBase repository.",
+          "hint": "Run the same command again with `--verbose` to see the full clone logs."
+        },
+        "dockerPull": {
+          "title": "Couldn't download the Docker image.",
+          "body": "The CLI was not able to pull the selected NocoBase image.",
+          "hint": "Run the same command again with `--verbose` to see the full Docker pull logs."
+        },
+        "dockerSave": {
+          "title": "The Docker image was pulled, but saving the tar file failed.",
+          "body": "The CLI could not finish exporting the image to the target tarball path.",
+          "hint": "Run the same command again with `--verbose` to see the full Docker save logs."
+        },
+        "scaffold": {
+          "title": "Couldn't create the local NocoBase app scaffold.",
+          "body": "The CLI was not able to finish generating the initial app files.",
+          "hint": "Run the same command again with `--verbose` to see the full scaffold logs."
+        },
+        "build": {
+          "title": "The local NocoBase app was downloaded, but the build step failed.",
+          "body": "The CLI could not finish building the downloaded source code.",
+          "hint": "Run the same command again with `--verbose` to see the full build logs."
+        },
+        "generic": {
+          "title": "Couldn't finish downloading NocoBase.",
+          "body": "The CLI hit an unexpected command failure while preparing the download.",
+          "hint": "Run the same command again with `--verbose` to see the full command logs."
+        }
+      },
       "prompts": {
         "source": {
           "message": "How would you like to get NocoBase?",
-          "npmLabel": "npm package",
-          "gitLabel": "Git repository",
-          "dockerLabel": "Docker image"
+          "dockerLabel": "Docker install (Recommended)",
+          "dockerHint": "Best for no-code and low-maintenance setups. You can upgrade later by pulling a newer image and restarting the app.",
+          "npmLabel": "create-nocobase-app install",
+          "npmHint": "Best when you want an app project with business code kept separate from the NocoBase framework, while still supporting low-code development.",
+          "gitLabel": "Git source install",
+          "gitHint": "Best when you want to try the latest unreleased changes, contribute code, or debug and modify NocoBase source directly. This option is more developer-oriented."
         },
         "version": {
-          "message": "Which version would you like to use? You can enter a package version, Docker image tag, or Git ref such as a branch name.",
-          "placeholder": "alpha"
+          "message": "Which version would you like to use?",
+          "latestLabel": "latest",
+          "latestHint": "Stable release. Best for production use and the most predictable experience. Currently unavailable.",
+          "betaLabel": "beta",
+          "betaHint": "Preview release. Good for trying upcoming features before general release.",
+          "alphaLabel": "alpha",
+          "alphaHint": "Development release. Includes the newest changes, but may be incomplete or unstable.",
+          "otherLabel": "Other",
+          "otherHint": "Enter another package version, Docker tag, or Git ref manually, such as a branch name."
+        },
+        "otherVersion": {
+          "message": "Enter the version, Docker tag, or Git ref you want to use.",
+          "placeholder": "For example: fix/cli-v2"
         },
         "dockerRegistry": {
           "message": "Which Docker registry would you like to use? The image tag is set separately in Version.",

package/dist/locale/zh-CN.json

@@ -95,20 +95,71 @@
       }
     },
     "download": {
+      "failures": {
+        "dependencyInstall": {
+          "title": "本地 NocoBase 应用还没有准备完成。",
+          "body": "下载已经完成，但依赖安装没有成功结束。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整安装日志。"
+        },
+        "gitClone": {
+          "title": "无法通过 Git 下载 NocoBase。",
+          "body": "CLI 没有成功克隆你选择的 NocoBase 仓库。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整克隆日志。"
+        },
+        "dockerPull": {
+          "title": "无法下载 Docker 镜像。",
+          "body": "CLI 没有成功拉取你选择的 NocoBase 镜像。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整 Docker pull 日志。"
+        },
+        "dockerSave": {
+          "title": "Docker 镜像已经拉取完成，但导出 tar 文件失败了。",
+          "body": "CLI 没有成功将镜像导出到目标 tar 包路径。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整 Docker save 日志。"
+        },
+        "scaffold": {
+          "title": "无法创建本地 NocoBase 应用骨架。",
+          "body": "CLI 没有成功生成初始应用文件。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整 scaffold 日志。"
+        },
+        "build": {
+          "title": "本地 NocoBase 应用已经下载完成，但构建步骤失败了。",
+          "body": "CLI 没有成功完成已下载源码的构建。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整构建日志。"
+        },
+        "generic": {
+          "title": "无法完成 NocoBase 下载。",
+          "body": "CLI 在准备下载内容时遇到了未预期的命令失败。",
+          "hint": "请使用相同命令加上 `--verbose` 重试，以查看完整命令日志。"
+        }
+      },
       "prompts": {
         "source": {
           "message": "你想通过哪种方式获取 NocoBase？",
-          "npmLabel": "npm 包",
-          "gitLabel": "Git 仓库",
-          "dockerLabel": "Docker 镜像"
+          "dockerLabel": "Docker 安装（推荐）",
+          "dockerHint": "适合无代码或低维护成本场景。后续升级时，拉取新镜像并重启应用即可。",
+          "npmLabel": "create-nocobase-app 安装",
+          "npmHint": "适合希望将业务代码与 NocoBase 框架保持独立的场景，同时仍然支持低代码开发。",
+          "gitLabel": "Git 源码安装",
+          "gitHint": "适合体验最新未发布版本、参与贡献，或直接修改和调试 NocoBase 源码。这个方式更偏向开发者使用。"
         },
         "version": {
-          "message": "你想使用哪个版本？这里可以填写 npm 版本号、Docker tag，或 Git ref（例如分支名）。",
-          "placeholder": "alpha"
+          "message": "你想使用哪个版本？",
+          "latestLabel": "latest",
+          "latestHint": "稳定版。适合生产环境和希望获得稳定体验的场景。当前暂不可用。",
+          "betaLabel": "beta",
+          "betaHint": "测试版。包含即将发布的新功能，适合提前体验和反馈。",
+          "alphaLabel": "alpha",
+          "alphaHint": "开发版。功能更新最快，但可能不完整或不稳定。",
+          "otherLabel": "其他",
+          "otherHint": "手动填写其他版本号、Docker tag 或 Git ref，例如分支名。"
+        },
+        "otherVersion": {
+          "message": "请输入你想使用的版本号、Docker tag 或 Git ref。",
+          "placeholder": "例如：fix/cli-v2"
         },
         "dockerRegistry": {
           "message": "你想使用哪个 Docker registry？镜像 tag 请单独在 Version 中填写。",
-          "placeholder": "nocobase/nocobase"
+          "placeholder": "registry.cn-shanghai.aliyuncs.com/nocobase/nocobase"
         },
         "dockerPlatform": {
           "message": "要使用哪个 Docker 镜像平台？",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/cli",
-  "version": "2.1.0-alpha.22",
+  "version": "2.1.0-alpha.23",
   "description": "NocoBase Command Line Tool",
   "type": "module",
   "main": "dist/generated/command-registry.js",
@@ -47,6 +47,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "@oclif/core": "^4.10.4",
+    "cross-spawn": "^7.0.6",
     "lodash": "^4.17.21",
     "openapi-types": "^12.1.3",
     "ora": "^8.2.0",
@@ -61,5 +62,5 @@
     "type": "git",
     "url": "git+https://github.com/nocobase/nocobase.git"
   },
-  "gitHead": "81ed83f158f172cca607b36beaf8428b14ba16ad"
+  "gitHead": "baa19dafe25e85b680b2fea7451f202831930c1c"
 }